2. API设计规范基础

RESTful API 设计规范是微服务间契约的“语法书”。一套清晰、一致的规范能大幅降低服务提供方与消费方之间的理解偏差，为后续的契约测试与 Mock 隔离奠定基础。本节将围绕四大核心维度展开：设计原则、资源命名、方法语义与状态码规范。

2.1 RESTful 六大设计原则

REST（Representational State Transfer）并非协议，而是一组架构约束。遵循这些原则的 API 才具备“RESTful”属性。

2.2 资源命名规范

资源是 RESTful API 的核心抽象。命名规范直接影响 API 的可读性与可维护性。

2.2.1 核心规则

• 使用名词复数形式：/users 而非 /user，/orders 而非 /getOrder。
• 使用小写字母与连字符：/order-items 而非 /orderItems 或 /order_items。
• 避免动词：操作由 HTTP 方法表达，路径中不应出现 /createUser、/deleteOrder。
• 层级关系用斜杠表示：/users/{userId}/orders/{orderId}。
• 查询参数用于过滤与排序：/orders?status=active&sort=created_at。

2.2.2 常见资源模式

2.3 HTTP 方法语义化

每个 HTTP 方法在 RESTful 架构中都有明确的语义。方法的选择必须与操作类型严格对应。

2.4 状态码使用规范

状态码是 API 响应语义的重要组成部分。合理使用状态码能让客户端无需解析响应体即可判断请求结果。

2.4.1 常用状态码分类

2.4.2 推荐状态码映射

2.5 规范全景图：从原则到实践

下图展示了 RESTful API 设计规范从顶层原则到底层实现的全景关系，帮助理解各要素之间的依赖与协作。

2.6 规范落地检查清单

在团队推行 API 设计规范时，可使用以下清单进行评审与自检：

1. 路径是否仅包含名词？ 检查是否有 /getUsers、/deleteOrder 等动词路径。
2. 是否使用复数形式？ 统一使用 /users 而非 /user。
3. 层级关系是否用斜杠表达？ 如 /users/{id}/orders 而非 /orders?userId={id}。
4. HTTP 方法是否与操作语义匹配？ 创建用 POST，查询用 GET，全量更新用 PUT，部分更新用 PATCH，删除用 DELETE。
5. 状态码是否准确反映结果？ 成功创建用 201，删除成功用 204，资源不存在用 404，服务故障用 500。
6. 响应体是否包含自描述信息？ 错误响应应包含 error 字段与 message 说明。
7. 是否遵循无状态约束？ 请求中是否携带了必要的认证与上下文信息？