周三下午,移动端同事在群里贴了一张截图:订单列表是空的,接口返回 200,data 是空数组。后端翻日志,请求是 GET /api/order/list?status=3。问题不在查询,而在 status 的取值:服务端这一版只认 paid,Web 端传的是 paid,移动端传的是 3,报表脚本传的是 PAY_SUCCESS。三个客户端各维护一份映射表,谁也不知道哪份是准的。

这不是谁写错了代码,而是接口从来没有约定过参数的取值边界。服务端觉得「我文档里写了」,客户端觉得「我照着上个版本抄的」,中间没有任何机制能拦住第三种写法。

接口设计最容易被当成「给字段起个名字」,真正难的是三件事:同一个概念在所有端只有一种表达;改动一个字段时知道谁会受影响;出了问题能从请求本身定位,而不是靠猜。这篇按这三件事往下讲。

接口出问题,通常不是代码写错

先看一组真实出现过的现象。它们看起来分散,根子都在「边界没定」。

现象真实原因第一步查什么
三个端传同一个状态,服务端只认一种枚举没有唯一来源,客户端各自维护映射查服务端枚举定义,再抓三个端的实际请求参数
新增一个可选参数后,老客户端报错服务端把可选参数做成了必填,或校验规则变严对比新旧版本的请求体与校验规则
返回体多了一个字段,某个端白屏客户端把响应当固定结构解析,遇到未知字段就崩看客户端反序列化配置是否忽略未知字段
列表越翻越慢,越往后超时用了大偏移量的 offset 分页,数据库每次都要扫前面所有行看慢查询里的 offset 值和扫描行数
同一时刻两个版本接口,监控错误率混在一起版本只改了路径,日志和指标没有版本维度查网关日志是否记录了路由版本
文档写着可选,线上却拒绝空值文档和校验代码是两份,没人保证同步用文档示例直接发一次请求,看实际返回

这六条里,只有第二条和第六条是「实现问题」,其余都是设计问题。设计问题的代价不会当天出现,而是在第三个客户端接入、第五次字段改名、第十次线上排障时一起结账。

先把资源和动作分开

REST 这个词第一次出现时,可以先把它理解成一句话:用 URL 表示「东西」,用 HTTP 方法表示「对这个东西做什么」。订单是一个东西,/orders 是订单集合,/orders/123 是其中一单;查用 GET,建用 POST,整体改用 PUT,局部改用 PATCH,删用 DELETE。

这套约定的价值不在「好看」,而在中间层能读懂。网关、缓存、浏览器、监控工具都认识 GET 和 POST 的差别:GET 可以被缓存、可以重试,POST 默认不行。你把所有操作都塞进 POST,这些能力就全丢了。

但资源模型不是所有业务都能套。取消订单、确认收货、发起退款,这些是动作,不是对资源的增删改查。硬套的结果是出现 POST /orders/123/cancel 这种路径,那也没问题,业界一直在用。真正要避免的是 POST /api/doOrderAction?action=cancel 这种把所有动作塞进一个入口的写法:路由没法分流,权限没法按动作配置,监控也看不出哪个动作慢。

一个订单接口的最小资源划分
/orders 集合
/orders/{id} 单个订单
/orders/{id}/items 订单明细
/orders/{id}/refunds 退款动作

判断标准很简单:这个路径下面,能不能再挂子资源。能挂,说明它表达的是「东西」;只能接一个动词,说明它是动作。动作路径单独列出来,权限和审计反而更清楚。

路径、查询参数、请求体,各放什么

这三层的分工建议固定下来,团队里不再逐个项目讨论。

路径只放「是谁」:资源类型和唯一标识。订单 ID、用户 ID、租户标识放这里。路径里出现 status、type、page 这类筛选条件,说明分层已经乱了。
查询参数放「怎么选、怎么排、取多少」:筛选、排序、分页、字段裁剪、语言。它们不影响资源身份,只影响这一次读取的结果。
请求体放「写成什么」:创建和更新的字段。请求体不参与路由,也不该承担筛选职责,否则缓存和日志都没法按 URL 归类。

具体到字段格式,有几条约定能省掉大量扯皮。时间统一用 ISO 8601 带时区的 UTC 字符串,比如 2026-11-07T08:30:00Z,不要混用时间戳和本地时间;金额统一用最小货币单位的整数,比如 1299 表示 12.99 元,不要用浮点;枚举统一用字符串,且客户端必须容忍未知值;布尔值不要用 0、1、yes、no 混传。

参数命名也要一次定死。同一套接口里不要一半 user_id 一半 userId;数组参数要么统一重复键 tag=a&tag=b,要么统一逗号分隔,不要两种都支持。这些细节看起来琐碎,但它们决定了客户端能不能用一套代码生成工具。

「不传」和「传空」也要区分清楚。更新接口里,字段缺省通常表示「不改」,字段传 null 表示「清空」,传空字符串则是业务上的另一个值。这三种语义如果不写进契约,客户端就会用「传空字符串」来尝试清空,服务端却当成「不修改」,最后两边都认为对方理解错了。建议在文档里对每个可选字段标注默认行为和空值行为,校验层也按这个规则实现,不要依赖各语言对 undefined 和 null 的不同处理。

最危险的一种「兼容」是:服务端同时接受数字和字符串两种枚举,还接受大小写不敏感。看起来宽容,实际是把错误悄悄吞掉。三个月后没人知道线上到底在传什么,也没法收紧迫使客户端改。输入边界应该窄,而且写进校验里。

REST 还是 RPC,看调用方是谁

RPC 指远程过程调用,翻成大白话就是「像调本地函数一样调远端服务」,常见实现有 gRPC、JSON-RPC、Thrift。它和 REST 不是新旧关系,是两种组织方式:REST 围绕资源,RPC 围绕动作和强类型契约。

REST 更适合的场景

对外开放、调用方不受控、需要经过浏览器和通用网关、资源模型清楚、读多写少。好处是任何语言都能上手,缓存和调试工具现成;代价是契约偏弱,字段含义靠文档,复杂动作容易写成四不像。

RPC 更适合的场景

内部服务之间、动作密集、对延迟和吞吐敏感、需要代码生成和强类型校验。好处是契约由 schema 固定,改字段编译期就能发现;代价是调用方必须用对应工具链,跨团队接入成本高,浏览器直连也麻烦。

一个常见的折中是:对外提供 REST,内部服务之间用 RPC,中间加一层适配。适配层不要做成「万能转换器」,只转换真正需要的字段和错误码,否则两边模型会越漂越远。

还有一类接口不适合硬套 REST:批量操作、复杂查询、长耗时任务。批量删除可以用 POST /orders/batch-delete,复杂报表查询可以用 POST /reports/query,长任务用「创建任务再轮询结果」的两步式接口。判断依据不是「纯不纯」,而是调用方能不能理解、中间层能不能处理。

版本化:别让兼容靠自觉

版本化的目的不是「每隔一段时间升一版」,而是让不兼容的改动有一个明确的落点。先分清哪些改动兼容、哪些不兼容。

改动是否兼容做法
响应体新增字段兼容客户端必须忽略未知字段,直接发
新增可选请求参数兼容默认值写清楚,老请求行为不变
删除响应字段不兼容先标记弃用并观察调用量,再下线
修改字段类型或含义不兼容新增字段并行写,迁移完再删旧字段
把可选参数改成必填不兼容新版本接口,或先放宽再收紧
新增枚举值视客户端而定客户端必须能处理未知值,否则算不兼容

版本放在哪,有三种常见做法。URL 里加 /v1/ 最直观,网关和日志一眼能分,缺点是同一资源的多版路径会长期并存;请求头加版本号更干净,但调试时容易忘带,缓存键也要额外处理;不显式分版本、靠兼容演进最省事,但遇到真正的不兼容改动时会很被动。

小团队、接口主要对内,建议先用「兼容演进 + 少量 URL 版本」:能加字段解决的就不开新版本,确实要改语义才开 /v2/。不要一开始就设计 v1/v2/v3 的宏大体系,多数项目活不到需要第三版的那天。

文档和实现必须是同一份事实。手写 Markdown 文档一定会和代码漂移,比较稳的做法是从代码里的 schema 生成文档,或者反过来用 schema 文件驱动校验。无论哪种,都要有一个「用文档示例发请求」的自动检查:示例里的每个请求至少能跑通一次,字段名和类型对不上就报错。这个检查比每周人工核对文档有效得多,也能防止「文档写着可选、线上却必填」这类低级但高频的问题。

弃用一个字段或接口,要有可执行的流程:先在文档和响应里标记弃用,最好带一个 Deprecation 响应头;然后按调用方维度统计流量,逐个通知;最后设一个下线日期。没有调用量数据就下线,等于赌没人用,通常赌输。

版本号要进日志和指标。否则线上同时跑着两个版本,错误率一涨,你连是哪个版本涨的都说不清。路由模板里带上版本,是最便宜的做法。

错误码、分页和幂等:三个最容易各写各的

错误响应建议固定成四个字段:code 给机器看,message 给人看,request_id 给排障用,details 放字段级错误。HTTP 状态码表达大类,业务 code 表达细分。比如参数校验失败返回 400,业务码是 INVALID_ARGUMENT,details 里指出是哪个字段。

不要让所有错误都返回 200 再在 body 里写 success:false。网关、监控、客户端重试策略都依赖状态码,全返 200 等于把这些能力关掉。也不要把内部异常堆栈直接返回给调用方,那既是安全问题,也让客户端养成解析堆栈的坏习惯。

分页先定上限。offset 分页写起来简单,但翻到第 100 页时数据库要跳过大量行,越翻越慢。数据量大、又要求稳定排序时,用游标分页:上一页最后一条的排序键作为下一页的起点。代价是不能随机跳页,产品要接受这个限制。

GET /v1/orders?status=paid&limit=20&cursor=2026-11-07T08:30:00Z,ord_1024

{
  "items": [ ... ],
  "next_cursor": "2026-11-07T08:29:12Z,ord_1004",
  "has_more": true
}

写接口要考虑重试。客户端超时后并不知道服务端到底成没成功,最安全的做法是让客户端带一个 Idempotency-Key,服务端用这个键去重:第一次正常处理,重复请求返回第一次的结果。键的范围要按「用户 + 操作 + 业务对象」组合,不能只用一个随机字符串,否则不同请求会互相覆盖。

与之配套的是超时约定。服务端处理时间超过客户端超时,客户端会重试,但服务端可能还在跑,于是同一次操作被并发执行两次。接口文档里应该写明服务端的最大处理时间,客户端超时不要短于它;确实需要长耗时的操作,改成「提交任务、返回任务 ID、轮询结果」的异步接口,而不是让 HTTP 连接一直挂着。把这些约定写进契约,比事后在代码里加各种补丁更省事。

一套能落地的骨架

目录按业务模块分,不按 controller、service、dao 三层分。三层分法在项目变大后,改一个业务要横穿三个目录;按模块分,改订单只动 orders/。

src/
  modules/
    orders/
      orders.route.js       路由与参数解析
      orders.schema.js      请求与响应校验
      orders.service.js     业务规则
      orders.repo.js        数据访问
    users/
      ...
  shared/
    errors.js             统一错误结构与业务码
    pagination.js         分页参数解析
  app.js

校验放在路由之后、业务之前,别散落在 service 里。下面是一个不依赖框架的最小例子,用 Node 自带的 http 模块也能跑。它做三件事:只接受白名单里的查询参数;把 limit 限制在 1 到 100;把非法枚举直接拒绝。

const ALLOWED_STATUS = new Set(["pending", "paid", "cancelled"]);

function parseListQuery(url) {
  const q = new URL(url, "http://localhost").searchParams;
  for (const key of q.keys()) {
    if (!["status", "limit", "cursor"].includes(key)) {
      throw Object.assign(new Error("unknown query: " + key), { status: 400 });
    }
  }
  const status = q.get("status");
  if (status !== null && !ALLOWED_STATUS.has(status)) {
    throw Object.assign(new Error("invalid status"), { status: 400 });
  }
  const raw = Number(q.get("limit") || 20);
  const limit = Number.isFinite(raw) ? Math.min(100, Math.max(1, Math.floor(raw))) : 20;
  return { status, limit, cursor: q.get("cursor") };
}

验证方式不用等客户端接入,直接在本机发请求,看四种情况:正常请求返回 200 和列表;status=3 返回 400 且 code 是 INVALID_ARGUMENT;limit=9999 被压到 100;多传一个 foo=1 被拒绝。四种都符合,边界才算真的写进了代码,而不是只写在文档里。

curl -i "http://localhost:8080/v1/orders?status=3"
curl -i "http://localhost:8080/v1/orders?limit=9999"
curl -i "http://localhost:8080/v1/orders?foo=1"

换语言时,这一层要改的是「校验库和路由写法」,不是设计本身。Java 用 Bean Validation,Go 用结构体标签加校验器,Python 用 Pydantic,规则表可以原样搬过去。

边界与代价

REST 的优雅是有成本的。资源划分、版本管理、错误码规范,都需要团队先达成一致并持续维护。三五个人、接口只给自己用的小服务,把这些全上齐,维护成本可能超过收益。先定参数格式和错误结构,就够用很久。

版本化不是越多越好。每多一个版本,就多一套测试、一份监控、一段兼容代码。真正该做的是把「不兼容改动」拖到不得不做时再开新版本,而不是每次需求变更都升一版。

RPC 的强类型也不是免费的。schema 变更需要重新生成代码、重新发版,跨语言时还要维护多套生成配置。服务数量少、调用链短的时候,HTTP 加 JSON 往往更快落地。

开放平台的接口设计要更保守。一旦有外部调用方,任何字段删除都可能变成事故。内部接口可以靠一起发版解决,外部接口只能靠版本和弃用流程。两者的标准不该一样。

重构接口的时机也要算成本。当同一个接口承载了三种调用方的不同诉求,参数开始互相冲突,文档需要写大段「如果 A 则 B」的说明时,继续打补丁的维护成本往往已经超过新开一个专用接口。判断标准不是「路径好不好看」,而是「新增一个调用方需要改几处、测几轮」。如果答案是三处以上,就该考虑拆分,而不是继续在旧接口上叠条件。

过度设计的典型信号:接口还没上线,先做了三级版本、五种鉴权方式、一套自动生成 SDK。真实需求往往只用到其中一种。先让一个端完整跑通,再按第二个调用方的实际诉求扩展,比提前设计十个扩展点靠谱。

当天可以自验的五件事

  1. 把你负责的一个列表接口的查询参数全列出来,标出哪些其实是资源身份、应该放进路径。
  2. 用 curl 给现有接口发一个非法枚举、一个超大分页、一个未知参数,记录它实际返回什么;如果都返回 200,先补校验。
  3. 挑一个准备改名的字段,按「新增并行字段、双写、迁移调用方、删旧字段」写一份四步计划,估算需要多久。
  4. 把接口的错误响应抓下来,检查是否包含 code、message、request_id 三项;缺哪项补哪项。
  5. 找两个调用方,问他们各自把状态值写成了什么;如果答案不一样,当天就把枚举收敛成一份共享定义。

下一篇讲鉴权。接口边界定清楚之后,紧接着要回答的是「这个请求是谁发的、他能做什么」。Session、JWT、OAuth2 经常被当成三选一,实际上它们解决的是不同层次的问题,选错的代价往往在半年后才显现。