API 设计最佳实践：从 REST 到健壮接口的工程准则
API 是软件系统的”门面”——它决定了调用方是否愿意继续使用你的服务，也决定了系统能否在频繁迭代中保持稳定。一个糟糕的 API 会让团队陷入无休止的兼容性修复，而一个设计良好的 API 则能显著降低协作成本。本文不谈抽象理论，而是从命名、版本、错误处理、分页、幂等性等维度，给出一套可直接落地的工程准则。
一、命名与资源建模：动词与名词的边界
RESTful 设计的核心是把”资源”当作一等公民，用名词表达资源、用 HTTP 方法表达动作。一个常见的反模式是把动词塞进 URL：
✗ GET /getUserList
✗ POST /createOrder
✗ GET /api/v1/user/delete?id=1
正确做法是让资源路径保持清晰、可预测：
✓ GET /users # 获取用户列表
✓ GET /users/{id} # 获取单个用户
✓ POST /users # 创建用户
✓ PUT /users/{id} # 全量更新用户
✓ PATCH /users/{id} # 部分更新用户
✓ DELETE /users/{id} # 删除用户
几个关键约定：
- 资源名用复数，如
/users、/orders、/articles，保持一致性； - 路径用小写 + 连字符，避免驼峰或下划线：
/blog-posts而非/blogPosts； - 嵌套资源要有节制：超过两级就应及时打住。
/users/{id}/orders/{orderId}/items/{itemId}这种深层嵌套会带来严重的路由耦合，可以改用/order-items?orderId=xxx的扁平方式； - 标量过滤、排序用查询参数，不要设计成路径：
/articles?status=published&sort=-createdAt。
二、版本控制：给变更留一扇门
API 一旦发布，就存在大量无法强制的调用方。版本控制不是为了炫技，而是为了在”破坏性变更”发生时给双方缓冲。常见方案有三种：
1. URL 路径版本（最主流）
https://api.example.com/v1/users
优点是直观、易缓存、易调试，缺点是 URL 不够”纯粹”，且可能导致大量重复路由。
2. 请求头版本
GET /users
Accept: application/vnd.example.v1+json
优点是 URL 干净，缺点是对调用方不友好、调试成本高、缓存策略复杂。
3. 查询参数版本
GET /users?version=1
实现简单，但容易被忽略，也污染了业务参数。
实践建议：对外公开的 API 优先使用路径版本，内部服务可以结合语义化版本 + 兼容性原则，尽量避免破坏性变更，能新增就新增，能不删就不删。
三、统一响应结构：让调用方一眼看懂
无论成功还是失败，响应体都应该遵循统一的外壳结构。这样前端和 SDK 可以写一套通用的解析逻辑，而不是每个接口都特判：
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"name": "Alice"
},
"requestId": "9f4b1e2a-xxxx"
}
错误时同样使用该结构，只是 code 非零、data 为空或包含错误详情：
{
"code": 40401,
"message": "user not found",
"data": null,
"requestId": "9f4b1e2a-xxxx"
}
其中两个细节值得强调：
- requestId：每次请求生成唯一标识，写入日志，出问题时可直接按 id 检索，大幅缩短排障时间；
- 错误码分段：用区间区分错误类型，例如
40000~40999表示请求参数错误、50000~50999表示服务内部错误，避免一个笼统的-1打天下。
四、HTTP 状态码：语义要诚实
状态码是 API 的语言，用错了会让调用方误判。至少掌握以下高频场景：
| 状态码 | 含义 | 典型场景 |
|---|---|---|
| 200 | OK | 请求成功 |
| 201 | Created | 资源创建成功 |
| 204 | No Content | 删除成功、无返回体 |
| 400 | Bad Request | 参数校验失败 |
| 401 | Unauthorized | 未认证或凭证失效 |
| 403 | Forbidden | 已认证但无权限 |
| 404 | Not Found | 资源不存在 |
| 409 | Conflict | 状态冲突、重复提交 |
| 422 | Unprocessable Entity | 语义错误（参数格式对但业务不合法） |
| 429 | Too Many Requests | 触发限流 |
| 500 | Internal Server Error | 意料之外的异常 |
一个常见错误是”业务失败也返回 200″。例如登录失败却返回 200 + {code:1001}。更推荐在有明确语义时用对应状态码（登录失败用 401），让网关、监控、缓存都能正确理解。
五、分页、排序与过滤：大数据集的基本功
返回全量数据是大忌。一个稳定、可扩展的列表接口应至少支持分页，并约定清晰的约定：
基于偏移量的分页：
GET /articles?page=1&pageSize=20
响应中应明确返回总数和分页元信息：
{
"code": 0,
"message": "success",
"data": {
"items": [ /* ... */ ],
"page": 1,
"pageSize": 20,
"total": 328,
"hasMore": true
}
}
基于游标的分页（数据量大、实时性要求高时更优）：
GET /feed?cursor=eyJpZCI6MzQ1fQ&limit=50
游标分页避免了深分页的性能问题，但代价是无法直接跳页。二者可并存：page/pageSize 用于管理后台，cursor 用于移动端 Feed 流。
过滤与排序统一走查询参数，并支持常用操作符：
GET /articles?status=published&category=tech&sort=-createdAt
GET /articles?price_gte=100&price_lte=500
六、幂等性：防止重复提交的兜底
网络是不可靠的——重试是常态，而重试带来的”重复执行”必须被妥善处理。写操作应尽量设计成幂等，尤其是支付、下单、发消息这类敏感场景。
推荐做法是为关键写操作引入幂等键：
POST /orders
Idempotency-Key: 8f4a2c1e-9b3d-4c5e-8f4a-2c1e9b3d4c5e
服务端以 Idempotency-Key 为唯一索引，首次请求记录结果，后续相同 key 的请求直接返回首次结果，而不是重复执行。对于天然幂等的 PUT /users/{id}、DELETE /users/{id}，即便重试也不会产生副作用；而 POST 这类非幂等操作则必须借助幂等键或业务唯一约束来兜底。
七、文档与可调试性：好 API 是”自解释”的
再规范的设计，如果没人看得懂也等于白做。以下几点能极大提升 API 的可用性：
- 使用 OpenAPI / Swagger 作为唯一真源，从定义生成文档、Mock 与客户端 SDK，避免文档与实现脱节；
- 给出可直接复制的示例，包括请求、响应和 curl 命令，减少调用方试错；
- 错误信息要可操作，不要只抛
"error"，而是说清”缺什么、该怎么修”； - 记录关键日志，把 requestId、耗时、来源 IP、关键参数写入日志，配合链路追踪快速定位问题。
八、安全底线：永远不要信任输入
以下几点属于”必须做”而非”可选”：
- 强制 HTTPS，不传输明文凭证；
- 做输入校验与边界限制，防止 SQL 注入、XSS、越权访问；
- 限流与防刷，保护接口不被恶意打爆，429 + 退避重试是标准组合；
- 鉴权分层，公开接口与需登录接口严格区分，敏感数据脱敏后再返回；
- 最小权限原则，返回字段裁剪，避免把密码散列、密钥等内部信息泄露给调用方。
结语
API 设计是一个”约束与克制”的活儿——克制住把动词塞进 URL 的冲动，克制住随手返回全量数据的习惯，克制住用一个笼统 -1 应付所有错误的懒惰。当你开始认真对待命名、版本、状态码、分页、幂等和文档这些细节时，你的 API 就从”能用”迈向了”好用、耐用、可维护”。希望这些准则能成为你下一个项目的默认约定。