2. API基础回顾：RESTful API设计原则、HTTP协议与状态码、API版本管理策略
在进入可解释评分与低延迟保障的实战之前，必须夯实API设计的基础。本章聚焦三个核心支柱：RESTful设计原则、HTTP协议与状态码、API版本管理策略。这三者共同决定了API的可理解性、可维护性与可演化性，是后续所有高级特性的基石。
2.1 RESTful API设计原则
REST（Representational State Transfer）是一种架构风格，而非协议。其核心约束包括：
- 资源导向：一切皆资源（Resource），通过URI唯一标识。
- 无状态：每个请求包含所有必要信息，服务器不保存客户端上下文。
- 统一接口：使用标准HTTP方法操作资源。
- 自描述消息：资源表示应包含足够元数据（如Content-Type、Link关系）。
- 超媒体驱动（HATEOAS）：响应中提供链接引导客户端下一步操作。
设计黄金法则：URI描述资源（名词复数），HTTP方法描述动作（动词）。
正确：
错误：
正确：
GET /users/123、POST /orders错误：
GET /getUser?id=123、POST /createOrder
下表对比了常见HTTP方法在RESTful设计中的语义与幂等性：
| HTTP方法 | CRUD语义 | 幂等 | 安全（只读） | 请求体 | 响应体 |
|---|---|---|---|---|---|
| GET | 读取资源 | 是 | 是 | 无 | 资源表示 |
| POST | 创建资源 | 否 | 否 | 资源数据 | 新资源URI |
| PUT | 整体替换 | 是 | 否 | 完整资源 | 更新后资源 |
| PATCH | 部分更新 | 否 | 否 | 差异数据 | 更新后资源 |
| DELETE | 删除资源 | 是 | 否 | 无 | 空/确认消息 |
实践建议：对于集合资源（如
/users），GET返回列表，POST创建新项；对于单例资源（如 /users/123），GET/PUT/DELETE操作特定项。避免在URI中使用动词或版本号（如 /v1/getUsers）。
2.2 HTTP协议与状态码
HTTP是API的传输载体。状态码是服务器对请求处理结果的标准化信号，正确使用状态码能极大提升API的可解释性。状态码按类别分为五类：
- 1xx（信息）：请求已接收，继续处理。如
101 Switching Protocols（WebSocket升级）。 - 2xx（成功）：请求成功接收并处理。最常用：
200 OK、201 Created、204 No Content。 - 3xx（重定向）：需要客户端进一步操作。如
301 Moved Permanently、304 Not Modified（缓存）。 - 4xx（客户端错误）：请求包含错误。如
400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、409 Conflict、422 Unprocessable Entity。 - 5xx（服务器错误）：服务器处理失败。如
500 Internal Server Error、502 Bad Gateway、503 Service Unavailable。
常见误区：不要将所有错误都返回
400 或 500。例如，认证失败应返回 401，权限不足应返回 403，资源不存在应返回 404，数据校验失败应返回 422。精确的状态码是API可解释性的第一道防线。
下表列出了API设计中最高频使用的状态码及其语义：
| 状态码 | 名称 | 典型场景 | 响应体建议 |
|---|---|---|---|
| 200 | OK | GET/PUT/PATCH成功 | 资源表示 |
| 201 | Created | POST创建成功 | 新资源URI + 表示 |
| 204 | No Content | DELETE成功、批量操作 | 空 |
| 400 | Bad Request | 请求格式错误、参数缺失 | 错误详情 |
| 401 | Unauthorized | 未提供或无效认证凭证 | 认证方式提示 |
| 403 | Forbidden | 已认证但无权限 | 权限说明 |
| 404 | Not Found | 资源不存在 | 资源标识 |
| 409 | Conflict | 资源冲突（如重复创建、版本冲突） | 冲突详情 |
| 422 | Unprocessable Entity | 语义校验失败 | 字段级错误列表 |
| 429 | Too Many Requests | 限流触发 | Retry-After头 |
| 500 | Internal Server Error | 未预期服务器异常 | 错误ID（不暴露堆栈） |
| 503 | Service Unavailable | 服务过载或维护 | 预计恢复时间 |
可解释性增强：在4xx/5xx响应体中，统一使用
{"error": {"code": "VALIDATION_ERROR", "message": "邮箱格式无效", "details": [...]}} 结构，而非仅返回状态码。这能让客户端快速定位问题。
2.3 API版本管理策略
API发布后必然面临演化。版本管理策略决定了向后兼容性与迁移成本之间的平衡。主流策略有三种：
- URI路径版本（/v1/users）：最直观，易于路由和缓存，但会污染URI结构，且难以强制废弃旧版本。
- 请求头版本（Accept: application/vnd.myapi.v1+json）：符合RESTful理念，URI保持纯净，但调试和文档复杂度增加。
- 查询参数版本（/users?version=1）：实现简单，但容易被缓存忽略，且参数污染。
推荐策略：对于公开API，优先使用URI路径版本（如
/v1/orders），配合响应头（如 X-API-Version: 1.2.3）提供细粒度版本信息。内部微服务间可使用请求头版本以保持URI整洁。
下表对比三种策略的优劣：
| 策略 | 可读性 | 缓存友好 | 客户端迁移成本 | 强制废弃难度 | 典型场景 |
|---|---|---|---|---|---|
| URI路径 | 高 | 高 | 低（显式修改URL） | 中（可监控路径访问） | 公开REST API |
| 请求头 | 低（需文档） | 中（需Vary头） | 中（需修改请求头） | 高（难以追踪） | 内部微服务 |
| 查询参数 | 中 | 低（参数易被忽略） | 低 | 低（易被绕过） | 快速原型 |
版本管理避坑：
- 不要将版本号放在域名中（如
- 不要承诺永久支持旧版本。建议制定版本生命周期：如v1发布后支持18个月，提前6个月公告废弃。
- 版本号应遵循语义化版本（MAJOR.MINOR.PATCH），仅MAJOR变更代表不兼容改动。
- 不要将版本号放在域名中（如
v1.api.example.com），这会增加DNS和证书管理复杂度。- 不要承诺永久支持旧版本。建议制定版本生命周期：如v1发布后支持18个月，提前6个月公告废弃。
- 版本号应遵循语义化版本（MAJOR.MINOR.PATCH），仅MAJOR变更代表不兼容改动。
2.4 小结：基础决定可解释性
RESTful原则、HTTP状态码、版本管理策略共同构成了API的可解释性基础设施：
- RESTful原则确保API的URI和操作语义清晰，客户端无需额外文档即可理解资源关系。
- 精确的状态码让客户端能自动区分错误类型，无需解析响应体即可做出决策。
- 合理的版本策略让API在演化过程中保持向后兼容，降低客户端迁移成本。