第6章 服务门面：Web API
文档摘要
第6章 服务门面：Web API 本章要回答的三个问题：一、什么样的 API 才称得上 RESTful，设计时到底在遵守什么原则？二、ApiController 那行特性给管线加了什么工，接口的请求与响应处理和 MVC 页面通道有何不同？三、异步编程为什么是接口的生死线，接口版本又该怎么演进才不伤客户端？ 为什么会有这一章 前五章产出的是"给人看的页面"，本章把管线重新封装成"给程序看的门面"。Web 应用迟早要对外或对前端单页应用提供数据接口——移动端、小程序、第三方集成，消费方都是代码而不是浏览器。观察哨在本章看到的变化全在管线的出站段：路由变成纯特性风格，动作返回的对象不再找视图引擎，而是经内容协商器序列化成 JSON。
第6章 服务门面：Web API
本章要回答的三个问题：一、什么样的 API 才称得上 RESTful，设计时到底在遵守什么原则？二、ApiController 那行特性给管线加了什么工，接口的请求与响应处理和 MVC 页面通道有何不同？三、异步编程为什么是接口的生死线，接口版本又该怎么演进才不伤客户端？
为什么会有这一章
前五章产出的是"给人看的页面"，本章把管线重新封装成"给程序看的门面"。Web 应用迟早要对外或对前端单页应用提供数据接口——移动端、小程序、第三方集成，消费方都是代码而不是浏览器。观察哨在本章看到的变化全在管线的出站段：路由变成纯特性风格，动作返回的对象不再找视图引擎，而是经内容协商器序列化成 JSON。
有意思的是，本章几乎不引入新管线——ApiController 是 MVC 控制器的接口装扮，模型绑定照旧（3.3 节），过滤与错误处理复用管线机制（2.2 节），数据层就是第 5 章的 LINQ。新东西只有三样：接口设计的领域素养（REST 与状态码的语义）、内容协商这一站、以及异步与版本化这两个工程生死线。
读完能解决什么
- 用资源建模、方法语义、状态码三层标准评审一段 API 设计；
- 解释 ApiController 推断与自动 400 的行为，写出返回 ProblemDetails 的规范错误响应；
- 说清内容协商器按请求头选格式的流程，以及 406 何时出现；
- 论证"接口为什么必须异步"，识别同步阻塞导致线程池饥饿的症状；
- 为一个已上线的接口设计版本演进方案，不破坏既有客户端。
本章知识点清单
- 资源建模：URL 表资源名词、方法表操作语义、请求体与响应体各司其职；
- 方法语义表：GET 安全、PUT 幂等、POST 既不安全也不幂等、DELETE 幂等；
- 状态码三层：2xx 成功族、4xx 客户端错族、5xx 服务端错族，常用码精确到 200、201、204、400、404、409；
- ApiController 推断：特性路由必填、绑定源自动推断、自动 400 响应；
- 内容协商：Accept 头与格式化器协商，返回对象默认 JSON 化；
- Produces 与响应类型标注，给文档与客户端明确的契约；
- 异步动作的线程池模型：await 让出线程，吞吐量与线程饥饿的关系；
- 版本三策略：路径版本、查询串版本、请求头版本，各自的取舍；
- 弃用流程：旧版本标识、迁移窗口、下线公告的时间线设计。
各节怎么分工
| 节 | 回答哪个问题 | 关键产出 |
|---|---|---|
| 6.1 RESTful API 设计原则 | 第一个问题 | 资源与方法语义矩阵 + 设计评审清单 |
| 6.2 Web API 控制器与请求响应处理 | 第二个问题 | ApiController 行为实验 + 内容协商流程图 |
| 6.3 异步编程与 API 版本管理 | 第三个问题 | 线程池饥饿案例 + 版本策略选型 |
6.1 是设计素养（评审别人的接口也用得上），6.2 是管线知识（ ApiController 与协商器都发生在管线里），6.3 是工程底线（异步与版本都做错会直接造成生产事故）。三节依次从"设计"到"实现"到"运营"。
接口管线与页面管线的分叉点
先决条件
- 第 3 章的路由与模型绑定是直接前置，3.3 节的绑定来源与 FromBody 必须清楚；
- 第 5 章的 LINQ 与跟踪知识——接口的分页投影全建立在它上面；
- 一个接口测试工具（任何能发 HTTP 请求的都行），本章实验需要改方法与头重发请求。
往下走到哪
接口通道架好之后，数据从页面后台走向了开放世界，下一个问题自然是"谁能进来"。第 7 章把观察哨移到管线最前排——认证与授权两站，正是 2.2 节强制次序对里的 Authentication 与 Authorization。本章 401 与 403 的语义伏笔，会在那里得到完整展开。