为什么需要统一的API设计规范
在开发一个手机App时，前端工程师小李经常要和后台接口打交道。有时候他拿到的接口文档五花八门：有的返回数据叫data，有的叫result；删除操作用POST，修改却用了GET。这种混乱让他不得不反复确认文档，甚至要改好几轮代码。
这种情况在团队协作或跨部门对接中很常见。没有统一的API设计规范，接口就容易变得难以理解和维护。一套清晰的设计规范能让前后端沟通更顺畅，减少出错概率，提升整体开发效率。
使用标准HTTP方法表达操作意图
HTTP协议本身已经定义了常用的方法，合理使用它们能让接口语义更清晰：
- GET 用于获取资源
- POST 用于创建资源
- PUT 用于完整更新资源
- PATCH 用于部分更新
- DELETE 用于删除资源
比如要操作用户信息，应该这样设计：
GET /api/users # 获取用户列表
GET /api/users/123 # 获取ID为123的用户
POST /api/users # 创建新用户
PUT /api/users/123 # 替换整个用户信息
DELETE /api/users/123 # 删除用户URL路径命名要简洁直观
路径名称使用小写字母和连字符，避免大写和下划线。资源名用复数形式更通用：
/api/order-items # 推荐
/api/order_items # 不推荐
/api/OrderItem # 不推荐如果需要层级关系，按从大到小排列：
/api/projects/456/tasks/789 # 项目下的任务响应格式保持一致
无论成功还是失败，返回结构尽量统一。常见的做法是包装一层状态信息：
{
"code": 0,
"message": "success",
"data": {
"id": 123,
"name": "张三"
}
}当出现错误时，仍然保持结构一致，只改code和message：
{
"code": 404,
"message": "用户不存在",
"data": null
}合理使用状态码
除了返回自定义code，也要正确设置HTTP状态码。浏览器、网关、监控系统都会依赖这些状态码做判断：
- 200 OK - 请求成功
- 201 Created - 资源创建成功
- 400 Bad Request - 参数错误
- 401 Unauthorized - 未登录
- 403 Forbidden - 无权限
- 404 Not Found - 路径不存在
- 500 Internal Server Error - 服务端出错
比如用户提交的数据格式不对，应该返回400而不是200加一个错误码。
版本控制别忽略
API上线后难免会调整。为了不影响老用户，建议在URL或请求头中加入版本号：
/api/v1/users
/api/v2/users新功能先走新版本，老系统可以慢慢迁移。等所有客户端都升级后，再考虑废弃旧版本。
加上必要的文档说明
哪怕接口再规范，没有文档也等于零。最简单的办法是在Swagger或YAPI这类工具里写清楚每个字段含义、示例和错误码说明。前端同事不用再追着问“这个status到底有几个值”。
公司内部可以用Markdown写个接口清单，每次发布前更新一下。这点时间投入能省下后续大量沟通成本。