1. 课程导入与工程全景

在开始写第一行接口代码之前，先把“我们到底在用什么、为什么用它、怎么选版本、怎么建项目”这几件事理清楚，后面的 29 章才不会走弯路。本课程面向的是用 C# 构建 HTTP 服务端接口的工程实践，核心平台是 ASP.NET Core，核心产物是 Web API。

一、ASP.NET Core Web API 的定位

ASP.NET Core 是 .NET 平台上用于构建 Web 应用的统一框架，它同时承载了 MVC、Razor Pages、Blazor、SignalR、gRPC 以及 Web API 等多种应用形态。Web API 并不是一个独立的框架，而是“用 ASP.NET Core 承载、以数据交换为主要目的、通常返回 JSON 而非 HTML 页面”的一类应用。它的典型特征是：路由映射到控制器或端点方法，请求体与响应体通过内容协商序列化，认证授权以中间件形式插入请求管道。

理解这一点很关键：Web API 与 MVC 共享同一套路由、模型绑定、过滤器、依赖注入和中间件体系。区别主要在于 MVC 默认以“返回视图”为终点，而 Web API 默认以“返回数据”为终点。因此本课程讲的路由、DI、中间件、过滤器等知识，同样适用于 MVC 项目，只是关注点不同。

二、与 MVC、Minimal API 的关系

ASP.NET Core 提供两种编写 HTTP 端点的风格。第一种是控制器风格（Controller-based），用 [ApiController] 标注的类承载一组相关端点，适合接口数量多、需要分组、需要过滤器与约定统一处理的场景。第二种是 Minimal API，直接在 Program.cs 中用 app.MapGet、app.MapPost 等扩展方法注册端点，代码量小、启动快，适合微服务、小型服务或原型验证。

两者不是替代关系，而是同一请求管道上的两种组织方式。Minimal API 同样支持依赖注入、模型绑定、过滤器（端点过滤器）和 OpenAPI。实际工程中常见的做法是：对外暴露的少量端点用 Minimal API，业务域复杂、需要统一约定的模块用控制器。本课程以控制器风格为主线，因为它更能体现分层、约定和可维护性；在涉及轻量场景时会对比 Minimal API 的写法。

三、.NET 运行时与 SDK 版本选择

初学者最容易混淆的是“运行时”和“SDK”。运行时（Runtime）只负责执行已编译好的程序，包含 Microsoft.NETCore.App 与 Microsoft.AspNetCore.App 两部分；SDK 则在运行时之上额外提供编译器、MSBuild、模板引擎和 CLI 工具。结论很直接：开发机装 SDK，生产服务器装运行时。如果服务器上只部署不编译，装 ASP.NET Core Runtime 即可，体积更小、攻击面更少。

版本选择遵循两条规则。第一，优先选 LTS（长期支持）版本，例如 .NET 8 是 LTS，支持周期长，适合生产；STS（标准期限支持）版本如 .NET 9 生命周期较短，适合尝鲜。第二，同一解决方案内所有项目应统一目标框架，避免混用导致还原失败。目标框架写在项目文件的 <TargetFramework> 中，例如 net8.0。可用以下命令确认本机环境：

dotnet --list-sdks
dotnet --list-runtimes
dotnet --info

若输出中同时存在多个 SDK，global.json 可以锁定项目使用的 SDK 版本，避免团队协作时因版本漂移产生差异：

{
  "sdk": {
    "version": "8.0.400",
    "rollForward": "latestFeature"
  }
}

四、项目模板对比与创建

执行 dotnet new list 可以看到内置模板。与 Web API 相关的常见模板有三类：webapi（控制器风格，含 WeatherForecast 示例）、webapi --use-minimal-apis（Minimal API 风格）、mvc（含视图的 MVC 应用）。此外 web 是空 Web 模板，只含最简管道，适合从零搭建。

创建第一个可运行 API 的完整过程如下。先建解决方案目录，再建项目并加入解决方案，最后运行：

dotnet new webapi -n FirstApi -o src/FirstApi
dotnet new sln -n CourseDemo
dotnet sln CourseDemo.sln add src/FirstApi/FirstApi.csproj
dotnet run --project src/FirstApi

运行后控制台会打印监听地址，例如 Now listening on: https://localhost:7198。此时打开浏览器访问 https://localhost:7198/swagger，可以看到自动生成的接口文档；访问 /weatherforecast 会返回一段 JSON 数组。判断“第一个 API 是否跑通”的标准有三条：控制台无异常堆栈、Swagger 页面能列出端点、直接请求端点返回 200 与合法 JSON。

五、调试与观察点

在 Visual Studio 或 VS Code 中按 F5 启动调试，断点建议下在控制器方法入口，观察 Request.Path、Request.Method 与模型绑定后的参数值。修改 launchSettings.json 中的 applicationUrl 可以更换端口；ASPNETCORE_ENVIRONMENT 决定加载 appsettings.Development.json 还是 appsettings.json，这是后续配置章节的基础。日志默认输出到控制台，级别由 Logging:LogLevel:Default 控制，调试时把它设为 Information 就能看到每个请求的进入与完成记录。