接口文档写得再漂亮，如果URL命名随心所欲、状态码使用混乱，调用方的体验依然会很糟糕。比如有的接口用/getUser，有的用/user/query，错误时统一返回200再靠body里的code字段区分成败——这类做法在项目迭代中会不断积累技术债。API设计的规范性主要体现在两个层面：一是资源的命名结构，二是HTTP状态码的语义。把这两件事定好标准并严格执行，API的一致性和可维护性会有质的提升。
一、资源命名的核心原则：面向资源而非面向动作
RESTful风格的API设计的第一条铁律是：URL应该表示资源（名词），而不是动作（动词）。动作语义交给HTTP方法来表达。GET表示查询，POST表示创建，PUT表示整体更新，PATCH表示局部更新，DELETE表示删除。这样组合起来，接口路径自然就统一了。
对比一下两种风格。面向动作的写法：/createUser、/deleteUserById、/getUserList，每个操作都要造一个新URL，接口数量随业务膨胀。面向资源的写法：/users一个资源路径配合不同HTTP方法就能覆盖增删改查全部场景。后者的接口数量更少，语义更清晰，调用方学习成本更低。
GET /users 查询用户列表 POST /users 创建新用户 GET /users/123 查询id为123的用户 PUT /users/123 整体更新该用户 PATCH /users/123 局部更新该用户（如只改昵称） DELETE /users/123 删除该用户
命名细节上建议遵循以下约定，团队内部保持一致最重要：
- 资源名使用名词复数形式，如
/users、/orders，与"集合"的语义对应 - 路径一律小写，多个单词用连字符分隔，如
/order-items，不要驼峰也不要下划线 - 层级关系表达从属，如
/users/123/orders表示用户123的订单列表 - 避免层级过深，一般不超过三层，过深时可以考虑用查询参数，如
/orders?userId=123 - 过滤、排序、分页信息放在查询字符串中，如
/users?page=2&size=20&sort=created_at,desc
还有一个容易踩的坑：把版本号放进路径还是请求头。两种方案都有大厂在用，路径版本（如/v1/users）直观、便于调试和网关路由，是多数团队的选择；请求头版本对URL更友好但调试稍麻烦。无论选哪种，全项目必须统一，不要有的接口带版本有的不带。
二、HTTP状态码的正确使用：让语义自己说话
很多团队图省事，不管成功失败都返回200，然后在响应体里放一个自定义code字段判断。这种做法的问题在于：网关、监控系统、重试机制都依赖HTTP状态码工作。全返回200意味着监控无法统计错误率，CDN和浏览器缓存策略失效，调用方的通用错误处理逻辑形同虚设。正确的做法是让HTTP状态码承担第一层语义，自定义业务码作为补充。
常用的状态码可以按类别记忆。2xx表示成功，最常用的是200（请求成功）、201（创建成功，配合Location头返回新资源地址）、204（成功但无返回体，常用于DELETE）。4xx表示客户端错误：400参数错误、401未认证、403无权限、404资源不存在、409资源冲突（如重复创建）、422参数格式合法但校验不通过、429请求过于频繁。5xx表示服务端错误：500服务器内部异常、502网关错误、503服务不可用。
几个容易混淆的需要特别说明。401和403的区别在于：401是"你是谁我不知道"，缺少或提供了无效的认证凭证；403是"我知道你是谁，但你没权限"，认证已通过但授权失败。404和400的区别在于：404是路径里的资源标识找不到，400是请求参数本身不合法。用一个实例展示规范返回：
// 创建用户成功
// HTTP/1.1 201 Created
// Location: /users/123
{
"code": 0,
"message": "success",
"data": { "id": 123, "name": "张三" }
}
// 参数校验失败
// HTTP/1.1 422 Unprocessable Entity
{
"code": 10021,
"message": "邮箱格式不正确",
"data": null
}
// 未登录
// HTTP/1.1 401 Unauthorized
{
"code": 10001,
"message": "请先登录",
"data": null
}
三、落地实践：如何让规范在团队中真正执行
规范写出来只是第一步，执行才是难点。建议从三方面入手。第一，编写API设计文档模板，新增接口必须先按模板填写资源路径、方法、请求参数、响应结构和状态码约定，评审通过后再开发。第二，引入自动化检查，比如用Swagger OpenAPI定义接口契约，通过CI流水线校验URL命名是否符合小写加连字符的规则、状态码是否在允许的清单内，不合规直接打回。第三，统一错误响应结构，定义全项目通用的错误码区间划分，例如1xxxx表示通用错误、2xxxx表示用户模块、3xxxx表示订单模块，避免各模块错误码冲突。
还需要注意幂等性问题。PUT和DELETE天然幂等，重复调用结果一致；POST不幂等，重复提交会创建多条数据。对于非幂等操作，要么在前端加防重复提交，要么在后端做幂等键校验，配合409状态码提示资源冲突。另外，分页接口建议统一返回结构，携带总数、当前页和每页条数，列表字段固定命名，这样前端封装通用列表组件才有可能。
最后提醒一点：规范不是一成不变的教条。纯粹的RESTful在某些场景并不合适，比如登录这种本质上是一次性动作的场景，可以约定POST /sessions（创建会话）来表达，也可以务实一些用POST /login。关键在于全团队达成共识并写进文档，让每一个接口都有据可查，而不是靠口口相传。规范的API是最好的接口文档，它让代码不言自明，让协作成本降到最低。
API设计RESTful资源命名HTTP状态码修改时间：2026-09-11 20:08:31