Visual Studio创建API接口项目-C++-PHP中文网

必须选择 asp.net core web api 模板而非 .net framework 的 web api，二者不兼容；创建时需勾选“使用控制器”和“启用 openapi 支持”；新建控制器类名须以 controller 结尾、加 [apicontroller] 特性、正确配置路由与参数绑定。

visual studio创建api接口项目

Visual Studio 创建 API 接口项目，关键不是“能不能”，而是“选对模板、避开旧框架陷阱”——.NET Framework 的 Web API（如 ApiController）和 ASP.NET Core Web API（基于 ControllerBase）是两套完全不兼容的体系，混用会导致路由不生效、依赖注入失败、Swagger 不加载等静默问题。

选错模板：ASP.NET Web API（.NET Framework） vs ASP.NET Core Web API

你看到的“Web API”选项在 Visual Studio 里实际对应两个不同技术栈：

旧版：ASP.NET Web Application (.NET Framework) → 选择“Web API”模板 → 生成 ApiController 类，依赖 System.Web.Http，仅支持 IIS 托管，无法跨平台
新版：ASP.NET Core Web API（推荐）→ 基于 ControllerBase，内置 DI、中间件、跨平台能力，.NET 6/7/8 默认模板

如果你目标是现代部署（Docker、Azure、Linux）、或后续要接 EF Core、JWT、OpenAPI，必须选后者。VS 2022 中搜索 “Web API” 默认优先展示的是 ASP.NET Core 模板，但若项目列表里出现 “ASP.NET Web Application (.NET Framework)”，请手动跳过。

创建时必须勾选的两项配置

在 “附加信息” 或 “其他信息” 对话框中，这两项直接影响后续开发体验：

使用控制器（Controllers）：取消勾选会进入 Minimal API 模式（无 Controller 类），适合极简场景；但多数团队仍需传统控制器结构来组织逻辑、复用过滤器、绑定模型
启用 OpenAPI 支持：勾选后自动生成 builder.Services.AddSwaggerGen() 和 app.UseSwagger()，否则 Postman 测试前得手动写文档或猜路由

注意：启用 Docker 和 配置 HTTPS 可按需选，但若本地调试时遇到 ERR_SSL_PROTOCOL_ERROR，检查是否勾选了 HTTPS 却没信任开发证书（运行 dotnet dev-certs https --trust 可修复）。

Visual Studio Professional 18.8.1

Visual Studio 18.8.1 官方固定版本安装引导程序，当前条目使用微软发布历史中的 Professional Web Installer，适合旧项目兼容、环境回退、复现特定构建链和排查版本差异等场景。

下载

创建后立刻验证的三件事

项目生成完成，别急着写业务，先确认基础链路通不通：

启动后浏览器打开 https://localhost:5001/swagger/index.html（或 http://localhost:5000），能看到 Swagger UI 页面 → 说明 OpenAPI 配置生效
点击 GET /WeatherForecast 的 Try it out → 返回 JSON 数组 → 说明控制器路由、序列化、中间件顺序都正常
把 Program.cs 中的 app.UseSwaggerUI() 移到 if (app.Environment.IsDevelopment()) 外层 → 否则发布到生产环境后 Swagger UI 消失，但定义仍存在（Azure API 管理依赖这个）

常见错误：新建控制器后 404 或参数绑定失败

自己添加的控制器返回 404，大概率是以下原因：

类名没以 Controller 结尾（如 UserAPI ❌，应为 UserController ✅），导致 MVC 路由系统不识别
没加 [ApiController] 特性 → 模型验证、自动 400 响应、FromRoute/FromBody 推断失效
路由属性写错：[Route("api/[controller]")] 是默认推荐，别手误写成 [Route("api/user")] 却忘了加 [HttpGet] 方法级路由
方法参数用了 string id 但没加 [FromRoute] 或 [FromQuery] → .NET Core 默认只从 body 绑定复杂对象，简单类型需显式指定来源

最省事的验证方式：右键 Controllers 文件夹 → “添加” → “控制器” → 选 “API 控制器 - 空”，让 VS 自动生成带正确特性和路由的骨架，再往里填逻辑。

真正容易被忽略的点是：ASP.NET Core Web API 的路由匹配严格区分大小写（尤其在 Linux 容器中），且 [Route] 和 [HttpGet] 组合时，路径拼接规则容易出错。建议初期全部用 [Route("api/[controller]/[action]")] + [HttpGet] 显式控制，等熟悉约定后再简化。