先说一个我观察了很久的现象：绝大多数后端项目的接口，“能用”和“好用”之间隔着的不是代码能力，而是一套从第一天就定死的约定。功能都做出来了，功能是真的在跑；可一旦进入前后端联调、版本迭代、新人接手这些环节，各种问题就全冒出来：字段一会儿下划线一会儿驼峰、错误信息中英文混合、同一个“删除”操作有的用 DELETE 有的用 POST、文档和真实行为对不上……我不是在说教，这些坑我自己都踩过，而且是反复踩。今天这篇文章，就是把我在多个项目里沉淀下来的后端 API 接口设计和文档编写经验整理成一份可以抄作业的规范参考。适合后端开发、前端同学以及正在搭项目骨架的技术负责人，内容不绑定任何语言和框架，但会给出常见落地方案。
1. 接口规范先定“契约边界”，而不是先争命名风格
很多人一提到接口规范，第一反应就是 URL 怎么拼、字段用驼峰还是下划线。这些当然重要，但都不是最核心的。接口规范最先要解决的是契约边界问题——即前后端各自认什么、接口的承诺是什么、接口在什么情况下给你什么东西。这个边界不划清，后面所有细节规范都是空中楼阁。
1.1 一套规范到底要覆盖哪些范围
我在项目启动阶段一般会要求团队先把下面这六件事书面定下来，而不是写个几十页的文档应付事：
- URL 与资源命名规则，包括版本号放哪、集合和单资源怎么区分。
- 请求参数的摆放位置：哪些走 path、哪些走 query、哪些走 body、哪些走 header。
- 响应体结构，成功时返什么、失败时返什么，不能两套样子。
- HTTP 状态码和业务错误码的使用边界。
- 列表类接口的分页、排序、过滤、字段裁剪规则。
- 鉴权方式与幂等策略（这一条最容易被忽略）。
这六件事只要成文，哪怕只有三页纸，也比“按网上的 RESTful 最佳实践来”有价值得多。因为“最佳实践”往往是从别人的业务场景里长出来的，直接抄会是四不像。规范的价值是让一个十人团队在写代码时不用反复开会确认同一个问题，而不是让你背出一堆标准来显得专业。
1.2 我理解的四个核心原则
十几年项目经验总结下来，我发现做得顺的接口规范都有四个共性原则：
第一是一致性。同一个语义在不同接口里必须长一个样，比如用户 ID 在用户接口里叫userId，在订单接口里就不能变成uid。错误码的格式、分页参数的命名、日期的时区处理，都要全局统一。一致性是降低认知成本的最有效手段。
第二是可预测性。前端拿到一个接口，应该能根据已有经验猜到它的行为。看到GET /api/v1/users就猜到是拉用户列表，看到DELETE /api/v1/users/123就猜到是删用户。如果每个接口都需要翻文档才知道干什么，那接口设计一定出了问题。
第三是自描述性。返回的数据要能自己说明自己。比如枚举字段返回OrderStatus.PAID而不是1，错误信息里带上可读的描述而不是只有一串500。前端拿到数据不需要再找后端要一份“状态码对照表”。
第四是可演进性。接口一旦上线，就可能被无数客户端依赖。设计时要留出版本管理、字段附加、废弃机制的空间，而不是把接口写成一锤子买卖。
这四个原则里，一致性和可预测性是给前端省时间，自描述性和可演进性是给未来的自己省命。谁优先、谁牺牲，每个团队侧重点不一样，但至少要明说，不能在 Code Review 时才吵。
2. URL与资源建模：把“动作”留给HTTP方法
URL 设计是接口规范里讨论最多、也最容易跑偏的地方。跑偏的核心原因只有一个：把 URL 当作“功能清单”在写，而不是当作“资源定位符”在写。我看到过太多/api/getUserList、/api/deleteOrder、/api/userManager/add这种写法，这种接口在业务逻辑上没什么错，但从长期维护的角度看，它把接口变成了一个巨大的、无规则的函数名集合，前端根本没法预测下一个接口长什么样。
2.1 资源、子资源和集合的边界怎么划
资源建模第一件事：把系统中的名词先列出来。用户、订单、商品、评论、支付单，这些都是资源。资源之间的关系用路径层级表达：
- 集合资源用复数名词：
/api/v1/users - 单个资源用 ID 标识：
/api/v1/users/{userId} - 子资源挂在父资源下面：
/api/v1/users/{userId}/orders
这个orders子资源表达的是“某个用户的订单列表”，而不是全局订单列表。注意，子资源的层级不要嵌套超过两层，超过两层的路径前端理解起来就开始吃力了，后端写起来也容易迷。比如GET /api/v1/orders/{orderId}/items/{itemId}/logs这种，我建议拆分成顶层资源GET /api/v1/order-items/{itemId}/logs，或者直接让前端通过查询参数过滤。
资源的命名统一用英文复数名词，单词之间用连字符分隔。不要用下划线，不要混用大小写，比如/user_profile、/userProfile都会造成混乱。既然大多数 Web 框架路由默认对大小写不敏感或强制小写，直接用lowercase-with-hyphen是成本最低的选择。
2.2 HTTP方法映射表与常用约定
HTTP 方法本身已经很好地定义了“动作”的语义，接口设计者需要做的只是让方法、URL 和资源状态变化完全对应。下面这张表是我在团队里反复贴的基准约定：
| 方法 | 语义 | 请求体 | 成功响应 | 典型场景 |
|---|---|---|---|---|
| GET | 查询资源 | 无 | 200 OK | 获取列表 / 详情 |
| POST | 创建资源 或 触发特定动作 | 有 | 201 Created（创建） / 200 OK（动作） | 新建订单 / 取消订单 |
| PUT | 整体替换资源 | 有 | 200 OK | 全量更新用户资料 |
| PATCH | 部分更新资源 | 有 | 200 OK | 只修改用户昵称 |
| DELETE | 删除资源 | 一般无 | 204 No Content | 删除评论 |
这里有个容易混淆的点：POST既承担“创建”也承担“动作出发”，两者并不矛盾。POST /api/v1/orders创建订单是标准 REST 风格，而POST /api/v1/orders/{orderId}/cancel则是对“取消订单”这个业务动作的合理表达。因为取消订单不是一个简单的资源 CRUD，它涉及到订单状态机的流转、库存回滚、可能的退款操作，用标准的PUT /api/v1/orders/{orderId}传一个status=CANCELLED反而会把状态机的复杂度暴露给调用方。
2.3 处理“不像增删改查”的业务动作
处理业务动作时，我的经验是三步走：
- 能不能用现有的资源字段表达？比如“下架商品”，如果商品有
status字段，可以PATCH /api/v1/products/{productId}传{"status": "OFF_SHELF"}。 - 如果不能，就设计成一个“动作子资源”，用
POST触发，例如POST /api/v1/products/{productId}/off-shelf。 - 如果涉及多个资源的联动操作，不要放在某个资源的子路径下，而是创建一个独立的“任务资源”或者“操作资源”，例如
POST /api/v1/batch-operations。
最后一种情况经常出现在后台管理系统中，比如“批量审核通过”“批量导出”。你当然可以做POST /api/v1/orders/batch-approve，但更好的做法是把这个操作建模成一个任务：POST /api/v1/batch-jobs，请求体里写明操作类型和目标 ID 列表，后端立即返回一个jobId，前端轮询任务结果。这样既符合资源化思想，又解决了批量操作的超时和进度问题。
3. 请求和响应：方案落地，看起来最简单，其实最容易各自为战
URL 规则定完，真正决定联调效率的是请求和响应的“标准格式”。如果团队里每个后端都按自己习惯写 Response，前端就要为每个接口写不同版本的封装逻辑，这事我见得太多。所以请求和响应这件事，必须在所有接口开发前就达成一致。
3.1 参数放哪里：path、query、body、header
每个位置的参数都有它该干的活，让参数待在该待的位置，接口的可读性会大幅提升。
- path 参数用来定位资源：
/api/v1/users/{userId}，只放资源 ID 或资源标识。 - query 参数用来筛选、排序、分页和投影：
GET /api/v1/users?status=ACTIVE&page=1&pageSize=20。 - body 参数用来承载创建和更新操作的数据，对象结构放在 JSON 里：
POST /api/v1/usersbody 里放头像、昵称。 - header 参数用来携带与业务数据无关的元信息：
Authorization、X-Request-Id、Idempotency-Key、Accept-Language。
最忌讳的是把业务数据塞进 header，把分页参数塞进 body。比如POST /api/v1/orders的 body 里写分页参数，这就完全乱了套。还有团队喜欢把所有字段都放 query，包括创建用户这种明显应该是结构化的操作，结果 URL 长到几十个参数还容易触发网关限制，这类问题尽早统一约定能避免。
3.2 响应体结构：用状态码说话，用 data 携带数据
我推荐的响应体结构其实非常简单：
{ "data": { "id": 123, "name": "张三" }, "error": null }失败时:
{ "data": null, "error": { "code": "USER_NOT_FOUND", "message": "用户不存在", "details": { "userId": 999 }, "traceId": "a1b2c3d4-5678-90ab-cdef-1234567890ab" } }这里最关键的一点：HTTP 状态码必须真实反映请求结果。成功就是 2xx，业务规则不满足用 4xx，服务异常用 5xx。而error是业务层面的错误详情，code是给程序判断的业务错误码，message是给人看的提示信息，traceId用于把前端报错和后端日志关联起来。
很多老项目喜欢“永远返回 200，然后在 body 里放code=0表示成功”，这种设计对调用网关、监控告警极不友好。你的运维同学想看 5xx 比例监控，结果所有错误全部混在 200 里，监控完全失效。接口的 HTTP 状态码应该让基础设施层（网关、负载均衡、监控系统）一看就能理解，而不是还要展开 body 做二次判断。
3.3 错误响应与错误码的三层设计
错误码体系我建议分三层，这三层各司其职：
第一层是HTTP 状态码，表达“这个请求有没有被正确完成”。我在团队里只允许用下面这几个状态码：
| 状态码 | 含义 | 使用场景 |
|---|---|---|
| 400 | 请求参数错误 | 缺少必填参数、参数格式错误 |
| 401 | 未认证 | 没有 token 或 token 过期 |
| 403 | 无权限 | 已认证但无权访问该资源 |
| 404 | 资源不存在 | URL 错误或资源已被删除 |
| 409 | 状态冲突 | 重复创建、订单状态不允许取消 |
| 422 | 语义校验失败 | 手机号格式错、用户名被占用 |
| 429 | 请求过于频繁 | 触发限流 |
| 500 | 服务端内部错误 | 未捕获异常 |
| 503 | 服务不可用 | 依赖服务熔断、降级 |
第二层是业务错误码，用短横线大写下划线分隔，例如USER_NOT_FOUND、ORDER_ALREADY_CANCELLED。这个码应保持稳定，程序设计时根据它做分支判断，而不是去 parsemessage字符串。
第三层是错误详情字段details。用于携带结构化上下文，比如哪个字段校验失败、期望的最大长度是多少。前端可以利用它在表单校验里直接定位到输入框并提示。注意，details不要放异常堆栈，堆栈应该进日志系统而不是返回给客户端，泄露内部调用细节有安全风险。
4. 列表接口：分页、排序、过滤、字段裁剪的通用解法
列表接口是后台系统里数量最多的一类接口，也是最容易做得千奇百怪的一类。前端往往要被三种分页参数换着调。做一次统一的列表接口约定，能省下前后端大量联调时间。
4.1 分页：page/pageSize 还是 cursor
分页模式主要两种，适用场景完全不同。
第一种是page/pageSize（页码分页），适合数据量不大、需要跳页的运营后台。接口响应的格式:
{ "data": { "items": [ {"id": 1, "name": "张三"} ], "pagination": { "page": 1, "pageSize": 20, "totalItems": 103, "totalPages": 6 } }, "error": null }页码分页默认参数名可以约定为page（从 1 开始）和pageSize（默认 20，最大上限 100）。返回体里totalItems是数据总量。
第二种是cursor游标分页，适合移动端信息流、聊天记录这类数据量大且高频写入的场景。游标分页不返回totalItems，而是返回nextCursor，客户端拿这个值请求下一页。示例:
{ "data": { "items": [...], "nextCursor": "eyJpZCI6MTAwfQ==" }, "error": null }它比页码分页稳的地方在于：插入新数据不会导致页码偏移，重复读到的问题也基本不存在。但缺点是前端不能直接跳页。比较适合动态 feed 流。
这里有个分页相关的细节经验：页码分页的
pageSize必须设置上限。如果前端传pageSize=100000，后台直接把全表捞出来，很容易把数据库打爆。我一般默认 20、上限 100，超了直接返回 400。
4.2 排序、过滤与字段裁剪的约定
排序参数我推荐用sort表达，多个排序字段用逗号分隔，降序用-前缀：
GET /api/v1/orders?sort=created_at,-total_amount这个表达的意思是先按created_at升序，再按total_amount降序。后端拿到这个参数后，绝不能直接拼到 SQL 里，而是要做映射白名单校验。比如created_at映射到数据库真实列，白名单外的字段直接拒绝。否则一旦允许sort=id;drop table...这种参数，被注入的风险是实打实的。
过滤参数，简单的等值过滤直接平铺在 query 上：
GET /api/v1/orders?status=PAID&paymentMethod=WECHAT范围过滤推荐用两个显式参数表达，比filter[created_at][gte]=2024-01-01这种括号语法更直观，写起来也更安全：
GET /api/v1/orders?createdAtFrom=2024-01-01T00:00:00+08:00&createdAtTo=2024-12-31T23:59:59+08:00关键在于团队要统一，不能今天用from，明天用gte。我个人习惯是xxxFrom/xxxTo只表示范围过滤，分词过滤用keyword或者q。
字段裁剪是很多团队忽略的能力，但对移动端低流量场景非常有用：
GET /api/v1/users/{userId}?fields=id,name,avatar&include=recentOrdersfields告诉后端只返回这几个字段，include可以表示需要额外关联的信息。这个机制在后端实现起来不算难，但能显著减少网络传输体积。当然它也会带来 N+1 查询风险，后端做的时候要小心，不是每个资源都适合动态字段裁剪。
5. 安全与幂等：前后端分离项目里最容易漏掉的设计
接口安全和幂等性设计比 URL 规范更容易被拖延，因为它们不像命名风格那样一眼看得见。但只要线上出过一次重复下单事故，你就能理解为什么一开始就要把这类设计写进规范。
5.1 认证、鉴权与密钥管理的实操建议
前后端分离项目最常见的认证方式是Authorization: Bearer <token>，token 通常是 JWT。这个约定要写死在规范和文档里，而不是让前端开发猜应该把 token 放哪。我的建议是:
- 用户端认证：JWT Access Token + Refresh Token 组合，Access Token 短期有效。
- 服务端到服务端认证：API Key 或更严格的 mTLS，API Key 放入
X-API-Key请求头，不能放到 URL 里（网关日志会记 URL 导致泄露）。 - 权限控制：不要只做“登录就能访问”，要在后端做基于 RBAC 的细粒度鉴权，比如普通用户不能调用管理员接口。
在密钥管理方面，我要特别提醒：API 密钥不能硬编码在代码里，更不能提交进 Git 仓库。应该放在环境变量或配置中心，并且按环境隔离（开发、测试、生产三套）。如果你已经在代码仓库里提交过密钥，立刻去后台吊销重新生成，然后查一下提交历史，考虑是否需要让团队知晓这个风险。风险评估这点写进规范，比事后补救强得多。
5.2 幂等性设计：从“快速双击下单”说起
幂等性讲的是同一个请求重复执行多次，和只执行一次，产生的结果是一样的。这个属性在支付、下单、转账这类场景里是刚需。
前端用户在弱网环境下经常手滑点两次“提交订单”，如果不做幂等处理，后端就会创建两条一模一样的订单。解决方案是幂等键机制：前端在创建类请求的 header 里带上一个唯一标识：
POST /api/v1/orders Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000后端拿到这个 key 之后，先去缓存或存储里查有没有处理过相同 key 的请求。如果有，直接返回第一次的结果，不再重复创建；如果没有，执行业务逻辑，把结果和 key 绑定存储。需要注意，Idempotency-Key 要在客户端生成，服务端负责校验。
从语义上说，GET、PUT、DELETE 本身应该是幂等的。同一个 GET 请求发多少次都一样，PUT 整体替换和 DELETE 重复删除也不应该改变资源状态。真正需要额外加幂等键保护的是 POST 创建和那些“动作型”接口。做接口设计时，可以在文档里明确标注哪些接口是幂等的，哪些不是，这对调用方是很大的信息量。
5.3 重放防护与并发控制
重放攻击指的是攻击者把截获的请求原封不动地再发一次。常见的做法是请求签名 + 时间戳 + nonce（一次性随机数）。客户端发起请求时带上timestamp、nonce和signature，服务端校验 signature 之后，检查 timestamp 是否在允许的偏差窗口内（比如 5 分钟），然后把nonce存到 Redis 里并设置同样的过期时间，相同的 nonce 再次出现就拒绝。
这套机制主要用在开放平台这类对安全性要求很高的场景。内部系统如果强行全量启用签名机制，会大幅增加开发成本，我的经验是分场景处理：涉及钱、批量数据导出、授权信息修改的接口必须做幂等和防重放；只读类接口做好鉴权和限流就够了。
并发控制上，ETag配合If-Match是处理并发编辑的标准姿势。客户端先 GET 拿到资源版本号ETag，提交更新时带上If-Match: "v1"，服务端比对版本不匹配就返回 412 Precondition Failed。很多团队在数据库层面用version字段做乐观锁，效果一样，但注意要把版本号暴露给前端才能形成闭环。
6. 版本管理与兼容性：接口也不可能永远不变
有些团队在项目初期觉得“就我们前后端自己用，不用管版本”，结果三个月后需求变化，接口改得不兼容，前端十几个页面全部报错，只能连夜加班。做版本管理越早越好，哪怕你只是简单的/v1/前缀，也能给未来留下调整空间。
6.1 三种常见的版本策略怎么选
版本策略无非三种，我按实际体验排一下优先级：
| 策略 | 实现方式 | 优点 | 缺点 |
|---|---|---|---|
| URL 路径版本 | /api/v1/users | 直观、路由明确、容易联调 | 路径冗余、语义不够纯粹 |
| Header 版本 | Accept: application/json; version=2 | 路径干净、代理友好 | 调试麻烦、容易漏配 |
| Query 参数版本 | /users?version=2 | 实现简单 | 容易被缓存污染、不直观、不规范 |
我个人的选择是优先使用 URL 路径版本。原因很简单：直观，在浏览器地址栏里一眼就能看到调的是哪个版本，也方便用同一个网关做灰度分流。虽然它会让资源路径多一层，但对团队协作和问题排查带来的收益远大于这点“不优雅”。Header版本适合已经上线很久、因为历史原因不能改 URL 的项目。Query 参数版本我基本不推荐，缓存系统会把不同的 version 参数当成不同的 URL 缓存，容易把 v1 的数据返回给 v2。
6.2 兼容性维护和字段废弃流程
版本不是用来逃避代码修改的，而是用来隔离破坏性变更的。下面这些向后兼容的行一条也不能碰：
- 不能改变已有字段的类型，比如把
id从整数改成字符串。 - 不能删除已有字段，即使你觉得前端没用这个字段。
- 不能改变字段语义，比如原来
status表示订单状态，现在又想拿它表示支付状态。 - 不能修改分页默认值到影响前端分页逻辑的程度，比如 page 从 1 开始改成从 0 开始，前端数量直接错位。
需要新增字段的时候，直接在响应里加就行，客户端通常忽略未知字段，这是 JSON 的天然优势。需要废弃字段的时候，先标记deprecated，在文档里写明替代字段和废弃时间，至少保留一个完整的发布周期。可以在响应头里带上Deprecation: true和Sunset: 2025-06-30，客户端看到这些头就能提前感知迁移。
如果不得不做破坏性变更，就走v2。发布v2之后，v1还需要存活一段时间，通过网关按客户端版本或渠道逐步切流。关于“存活多久”，建议至少一个季度起步，真实情况里很多第三方客户接入很慢，半年以上的超长废弃周期一点不夸张。
7. 用OpenAPI让文档真正成为可执行契约
接口文档这件事，很多团队把它当“事后总结”来做：代码写完，再根据代码补一篇 Swagger 文档，甚至还有人手工维护 Word 文档。这种做法的问题在于文档必然过期。代码在演进，文档停留在昨天。我的建议是采用“代码即文档”或“设计优先”的方式，把 OpenAPI 文件当作契约来维护，并且让它在 CI 里承担校验工作。
7.1 写接口文档时最值得投入精力的三件事
首先，schema 必须统一引用。一个用户模型不要在十个路径里复制粘贴一份 JSON 结构，应该在 OpenAPI 的components.schemas.User里定义一次，路径里用$ref引用。这样模型一改，所有引用同步生效，不会出现用户详情接口有email而用户列表接口没有这种诡异差异。
其次，每个字段都要有 description 和 example。description 里写清边界条件，比如“用户 ID，UUID 格式”“订单状态，枚举值：PENDING/PAID/CANCELLED”“创建时间，ISO 8601 带时区”。example 里给真实的脱敏数据，不要给"string"、"0"这种占位符。真实示例的价值是让前端可以直接照着 Mock，减少无效沟通。我见过太多接口文档，字段清了，示例是string，前端根本不知道真实数据长什么样。
最后，为错误响应补文档。不要只写成功返回，OpenAPI 里可以给每个路径都声明 400、401、403、404、500 的error结构引用。这样做第一个好处是前端知道每个接口会抛什么错，第二个好处是后端在写测试时可以对着文档做契约校验。
7.2 把文档放进CI/CD，防止接口悄悄跑偏
自动化是防止文档漂移的唯一可靠手段。具体来说，用 OpenAPI 文件（无论是手写的还是代码生成的）作为基准，在 CI 里做下面三件事：
- 格式校验：保证 OpenAPI 文件本身是合法有效的，没有语法错误。
- 破坏性变更检测：比较当前分支和主干上的 OpenAPI 文件，如果发现接口路径被删除、响应必填字段被去掉、参数类型被改变，CI 直接失败，要求开发者评审过后才允许合并。
- 请求响应契约测试：对核心接口编写基于 OpenAPI 的契约测试，让测试请求按文档定义生成，断言响应结构完全匹配。一般可以用 Postman/Schemathesis 或专门的契约测试工具来做，不用很重的框架，先把核心交易链路覆盖住。
我在团队里实际用的工具链是：Java 项目用 springdoc-openapi 自动生成，前端把生成的 OpenAPI JSON 接入代码生成器直接产出 TypeScript client。这样接口一改，前端类型同步更新，编译期就能发现字段引用错误。对非 Java 项目，我也尽量要求至少维护一份手写的 OpenAPI YAML 并纳入 CI 校验。文档一旦可以从 CI 管道里自动校验，它的可信度就会高很多，前端同学也才敢真正把它当成参照。
另外一个很值得养成的习惯：每次接口发布，把 OpenAPI 文档的快照和版本号绑定，比如发布包里带上openapi-1.0.0.json。出了问题可以快速对比线上实际行为和当时约定的行为差在哪里。这个快照放到对象存储或制品库都行，关键是它必须和发布版本一一对应。
最后分享一个我自己的操作习惯。接口规范这种文档，我的做法是放在代码仓库里而不是 Wiki 里，命名为docs/api-contract.md，让每个开发者提交代码时都看得到。内容不用太长，把 URL 规则、响应结构、错误码体系、分页幂等策略写清楚就够了，十来页算多，三页正常。规范文件离代码越近，维护的人越多，真正执行的概率也越高。接口设计的最终目标不是写出一个完美的规范，而是让团队里任何一个后端写出来的接口，前端不看签名都能猜个八九不离十。做到这一点，你的接口设计就已经赢了。
