RESTful API 设计规范：字段命名、状态码和错误处理的最佳实践

背景介绍

API 是前后端交互的桥梁，一个好的 API 设计可以极大提升开发效率和维护性。反之，糟糕的 API 设计会导致混乱和技术债务。

基于多个项目的经验，我们总结了以下 API 设计规范。

一、字段命名规范

1. URL 路径命名：

• 使用小写字母
• 使用连字符（-）分隔单词
• 使用复数形式表示资源集合
• 避免使用动词，使用 HTTP 方法表示动作

正确示例：

/api/v1/users
/api/v1/users/123/orders
/api/v1/products/search

2. 请求参数命名：

• 使用 snake_case（小写蛇形命名）
• 保持语义清晰
• 避免使用缩写

正确示例：

GET /api/v1/users?page=1&page_size=10&sort_by=created_at&sort_order=desc

3. 响应字段命名：

• 使用 camelCase（驼峰命名）
• 保持与前端一致
• 布尔字段使用 is_ 或 has_ 前缀

二、HTTP 方法使用

方法	用途	幂等性
GET	获取资源	是
POST	创建资源	否
PUT	更新资源（全部字段）	是
PATCH	更新资源（部分字段）	否
DELETE	删除资源	是

三、HTTP 状态码使用

2xx 成功：

• 200 OK：成功获取或更新资源
• 201 Created：成功创建资源，返回 Location 头
• 204 No Content：成功删除资源，无响应体

4xx 客户端错误：

• 400 Bad Request：请求参数错误
• 401 Unauthorized：未认证，需要登录
• 403 Forbidden：已认证，但无权限
• 404 Not Found：资源不存在
• 409 Conflict：资源冲突（如重复创建）

5xx 服务器错误：

• 500 Internal Server Error：服务器内部错误
• 502 Bad Gateway：网关错误
• 503 Service Unavailable：服务不可用

四、统一响应格式

成功响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com"
  },
  "meta": {
    "page": 1,
    "pageSize": 10,
    "total": 100
  }
}

错误响应：

{
  "code": 4001,
  "message": "参数错误",
  "detail": "邮箱格式不正确",
  "field": "email"
}

五、错误处理规范

错误码设计：

• 0：成功
• 1000-1999：通用错误
• 2000-2999：认证授权错误
• 3000-3999：参数验证错误
• 4000-4999：业务逻辑错误
• 5000-5999：系统错误

错误信息要求：

• message：简短描述错误
• detail：详细说明（可选）
• field：错误字段（可选，参数错误时使用）

六、API 版本控制

方案一：URL 版本（推荐）

/api/v1/users
/api/v2/users

方案二：请求头版本

Accept: application/vnd.example.v1+json

版本管理策略：

• 新增接口不加版本号（向后兼容）
• 修改接口增加新版本
• 旧版本标记为 deprecated
• 定期清理废弃版本

七、API 文档

使用 OpenAPI/Swagger：

• 自动生成文档
• 支持在线测试
• 生成客户端 SDK

文档内容要求：

• 接口说明
• 请求参数
• 响应示例
• 错误码说明

八、安全性考虑

• 认证：使用 JWT 或 OAuth2
• 授权：基于角色的访问控制
• 限流：防止 API 滥用
• HTTPS：强制使用 HTTPS
• 输入验证：所有输入都要验证

九、设计检查清单

1. URL 是否使用小写和连字符？
2. HTTP 方法是否正确使用？
3. 状态码是否符合规范？
4. 响应格式是否统一？
5. 是否考虑了版本控制？
6. 是否有完整的文档？

总结

API 设计是一个团队协作的过程，需要前后端开发人员共同参与。

1. 保持一致性：命名、格式、风格统一
2. 注重语义：让 API 易于理解
3. 考虑扩展性：预留扩展空间
4. 文档即代码：保持文档与代码同步

一个好的 API 设计可以提升团队效率，减少沟通成本。