API 是前后端沟通的桥梁，设计良好的 API 能大幅降低沟通成本、减少对接 Bug。本文结合实际项目经验，总结 RESTful API 设计中最常用的规范和最佳实践。
1. URL 设计：用名词，不用动词
RESTful 的核心思想是把一切操作视为对"资源"的操作，因此 URL 应该表示资源（名词），而 HTTP 方法表示动作。
// ❌ 不好的设计 POST /getUserList POST /createUser POST /deleteUser/123 // ✅ RESTful 设计 GET /api/users # 获取用户列表 POST /api/users # 创建用户 GET /api/users/123 # 获取单个用户 PUT /api/users/123 # 更新用户 DELETE /api/users/123 # 删除用户
2. HTTP 方法的正确使用
| 方法 | 语义 | 幂等性 | 示例 |
|---|---|---|---|
| GET | 获取资源 | 是 | GET /api/users |
| POST | 创建资源 | 否 | POST /api/users |
| PUT | 全量更新 | 是 | PUT /api/users/123 |
| PATCH | 部分更新 | 否 | PATCH /api/users/123 |
| DELETE | 删除资源 | 是 | DELETE /api/users/123 |
3. 统一的响应格式
所有接口返回统一的 JSON 结构，让前端可以用一套逻辑处理所有响应。推荐格式如下：
// 成功响应
{
"code": 0,
"message": "success",
"data": {
"id": 123,
"name": "张三",
"email": "zhangsan@example.com"
}
}
// 错误响应
{
"code": 40001,
"message": "用户名已存在",
"data": null
}
// 分页响应
{
"code": 0,
"message": "success",
"data": {
"list": [...],
"total": 156,
"page": 1,
"pageSize": 20
}
}
4. 合理的 HTTP 状态码
虽然业务状态码放在 body 里，但 HTTP 状态码本身也应该正确使用：
200 OK— 请求成功201 Created— 资源创建成功400 Bad Request— 请求参数有误401 Unauthorized— 未登录或 Token 过期403 Forbidden— 无权限访问404 Not Found— 资源不存在500 Internal Server Error— 服务器内部错误
5. 版本控制
API 不可避免会迭代，提前设计版本控制机制能避免很多兼容性问题。常见做法是在 URL 中加入版本号：
/api/v1/users /api/v2/users
新版本上线时，旧版本至少维护 3-6 个月的过渡期，给调用方足够的迁移时间。
6. 分页、筛选与排序
列表接口几乎都需要分页。推荐使用查询参数：
GET /api/users?page=1&pageSize=20&sort=createdAt:desc&status=active
这样设计的好处是语义清晰，前端容易拼接参数，后端也容易解析。
小结
好的 API 设计就像好的代码一样——自解释、一致、可预期。遵循 RESTful 规范不是为了教条，而是为了让团队协作更高效、让系统更易于维护。在项目初期就约定好 API 设计规范，后续的开发和对接会顺畅很多。