RESTful API 作为主流接口设计风格，核心在于以资源为中心，利用 HTTP 协议本身的语义完成通信。许多团队虽声称遵循 REST 规范，却常陷入命名混乱、动词误用、状态码随意等问题，导致可维护性下降。本文从工程实践角度梳理一套切实可用的设计规范。
资源建模与 URI 命名
资源是 REST 架构的基本单元。好的资源建模应做到名词化、层级清晰、含义明确。URI 中只出现名词，通过路径表达层级关系，例如「/users/123/orders」表示用户 123 的订单集合。避免在 URI 中混入动词，动作应由 HTTP 方法表达。
命名统一使用小写字母和连字符分隔，复数形式代表集合资源，单数形式通过路径参数定位实例。嵌套层级控制在三层以内，过深会增加前端理解成本和路由复杂度。
HTTP 动词的语义化使用
GET 用于获取资源不产生副作用，POST 用于创建新资源，PUT 用于整体更新且要求幂等，PATCH 用于局部修改，DELETE 用于删除。这套语义约定是 REST 的基石，严格遵循能降低沟通成本。切忌用 GET 执行写操作。
批量操作可通过集合端点配合 POST 实现，例如向「/orders/batch」提交批量创建请求。复杂非 CRUD 操作可建模为子资源，如「/orders/123/cancel」表示取消订单。
状态码与错误处理
HTTP 状态码是接口语义的重要组成。2xx 表示成功，4xx 表示客户端错误，5xx 表示服务端异常。创建成功返回 201，参数校验失败返回 400，未认证返回 401，无权限返回 403，资源不存在返回 404，冲突返回 409。不要所有错误都返回 200 再在 body 中标明错误码。
错误响应体应包含统一结构：错误码、错误描述和字段级错误详情。返回 JSON 对象，code 字段标识业务错误类型，message 字段给出可读说明，errors 数组列出字段校验信息，让前端能统一处理异常。
分页与排序设计
列表接口必须支持分页，常见有偏移分页和游标分页。偏移分页通过 page 和 page_size 参数实现，适合数据量不大的场景；游标分页通过上一页最后记录标识获取下一页，在数据频繁变动时更稳定。排序通过 sort 参数指定字段和方向。
过滤参数直接拼在查询字符串上，字段名与资源属性保持一致。务必对过滤参数做白名单校验，防止注入风险。复杂多条件过滤可引入 RSQL 查询语言，但多数场景简单字段级过滤已够用。
版本管理与协同
接口版本控制是保障向后兼容的关键。常见策略包括 URI 版本（「/v1/users」）、查询参数版本和 Header 版本。URI 版本最直观，推荐公开 API 使用。版本升级时保留旧端点，通过废弃标记引导迁移。
设计规范的形成需要团队不断讨论迭代。建议将规范文档化，配合代码审查确保落地，借助 Swagger 自动生成文档，让规范从纸面走向代码，真正发挥约束和指导价值。