API 设计规范基础：RESTful 设计原则、资源命名规范、HTTP 状态码语义
在 API 治理体系中，设计规范是质量管控的第一道防线。RESTful 风格并非严格标准，而是一组架构约束。本章聚焦三大核心支柱：设计原则、资源命名与状态码语义，为后续 Mock 隔离故障排查提供可审计的规范基线。
2.1 RESTful 六大设计原则
REST（Representational State Transfer）由 Roy Fielding 在 2000 年提出，包含以下约束。违反其中任何一条，都会导致 API 偏离 REST 风格，增加 Mock 隔离的复杂度。
| 原则 | 核心要求 | 治理检查点 |
|---|---|---|
| 客户端-服务器 | 分离关注点，客户端不关心数据存储 | Mock 层是否引入业务逻辑 |
| 无状态 | 每个请求包含全部必要信息，服务端不保存会话 | Mock 响应是否依赖请求顺序 |
| 可缓存 | 响应隐式或显式标记可缓存性 | Mock 数据是否携带 Cache-Control |
| 统一接口 | 资源标识、自描述消息、HATEOAS | 命名与状态码是否一致 |
| 分层系统 | 客户端无法区分是否直接连接终端服务器 | Mock 网关是否透明 |
| 按需代码（可选） | 服务器可传输可执行脚本（如 JavaScript） | Mock 是否支持动态扩展 |
治理提示： 在 Mock 隔离场景中，无状态与统一接口是最常被违反的原则。例如，Mock 服务依赖上一个请求的 Cookie 返回不同数据，即构成状态泄漏，应标记为故障。
2.2 资源命名规范
资源命名是统一接口原则的直接体现。命名不规范会导致 Mock 路由歧义、自动化测试脚本脆弱、治理报告误报。以下规范适用于生产级 API 设计。
2.2.1 核心规则
- 使用名词复数：
/users而非/getUser或/user。 - 层级关系用斜杠：
/users/{userId}/orders，深度不超过 3 层。 - 查询参数用于过滤：
/orders?status=active&page=1，不在路径中编码过滤条件。 - 小写字母 + 连字符：
/order-items而非/orderItems或/order_items。 - 动词仅用于非资源操作：
/users/{userId}/activate（特殊情况），优先用 HTTP 方法表达动作。
2.2.2 常见反模式与治理规则
| 反模式示例 | 问题描述 | 治理检测规则 |
|---|---|---|
/getUsers |
动词在路径中，HTTP GET 已隐含读取 | 路径包含 get/fetch/retrieve → 告警 |
/user |
单数名词，集合语义不明确 | 路径段为单数且非特殊资源 → 告警 |
/users/userId/orders |
变量名未用花括号包裹 | 路径段包含小驼峰或未标记变量 → 告警 |
/orders?page=1&size=20 |
分页参数名不统一 | 未使用 page/limit 或 offset/limit → 告警 |
/createOrder |
用路径表达创建动作 | 路径包含 create/add/new → 告警 |
治理工具集成： 在 API 规范（OpenAPI 3.x）中，通过
pattern 和 enum 约束路径参数格式。Mock 服务应直接从规范文件读取路由规则，避免硬编码路径。
2.3 HTTP 状态码语义
状态码是 API 响应语义的核心。Mock 隔离故障中，状态码误用是最隐蔽的问题之一——Mock 返回 200 但真实服务返回 201，导致客户端逻辑在集成测试中失效。
2.3.1 常用状态码分类
| 分类 | 状态码 | 语义 | Mock 使用场景 |
|---|---|---|---|
| 2xx 成功 | 200 OK | GET、PUT、PATCH 成功返回 | 标准成功响应 |
| 201 Created | POST 创建资源成功 | 创建类 Mock 必须返回 | |
| 204 No Content | DELETE 成功，无响应体 | 删除类 Mock 必须返回 | |
| 4xx 客户端错误 | 400 Bad Request | 请求格式错误 | 参数校验失败 Mock |
| 401 Unauthorized | 未认证或认证失败 | Token 缺失/过期 Mock | |
| 404 Not Found | 资源不存在 | 路径错误 Mock | |
| 5xx 服务端错误 | 500 Internal Server Error | 服务器内部错误 | 故障注入 Mock |
| 503 Service Unavailable | 服务暂时不可用 | 熔断/降级 Mock |
2.3.2 状态码治理检查清单
- 一致性检查：同一操作在所有端点中返回相同状态码（如 POST 始终返回 201 而非 200）。
- 响应体匹配：2xx 必须有响应体（204 除外），4xx/5xx 必须有错误描述结构。
- Mock 覆盖度：每个状态码至少有一个 Mock 用例，特别是 201、204、401、404、500。
- 幂等性验证：GET、PUT、DELETE 多次调用应返回相同状态码（除首次 201 外）。
故障案例： 某团队 Mock 中 POST /orders 返回 200 与空 body，真实服务返回 201 与 orderId。集成测试因无法获取 orderId 全部失败。治理规则：强制 Mock 响应状态码与 OpenAPI 规范中定义的
responses 一致，否则阻断部署。
2.4 规范治理的自动化切入点
在 Mock 隔离故障排查中，设计规范是证据报告的第一层过滤器。以下自动化检查项可直接集成到 CI/CD 流水线：
- OpenAPI 规范 lint：使用 Spectral 或 Vacuum 检查命名、状态码、路径格式。
- Mock 响应审计：对比 Mock 返回的状态码与规范中定义的 responses 是否一致。
- 命名一致性报告：扫描所有端点路径，标记违反名词复数、小写连字符规则的路由。
- 状态码覆盖矩阵：生成每个端点已 Mock 的状态码列表，标记缺失项。
证据报告示例： 某次治理扫描发现 23 个端点中 8 个 POST 操作返回 200 而非 201，5 个 DELETE 返回 200 而非 204。这些差异被标记为“Mock 隔离故障——状态码语义不一致”，直接阻断发布。