API 设计 / 技术文章

REST API 到底应该怎么设计

这篇文章解决 REST API 最常见的设计失控问题:路径像 RPC、方法乱用、状态码和错误结构不统一。适合正在设计 Java / 后端接口的开发者,读完后你会得到一套可直接用于项目评审的资源建模、请求语义、响应规范和演进原则。

先从资源建模,而不是接口动作开始

REST API 的第一步不是给接口起名字,而是确认系统里有哪些“资源”。用户、订单、商品、支付记录都可以成为资源;创建、查询、修改、删除则由 HTTP 方法表达,而不是继续塞进路径。

例如,订单接口优先设计成 /orders 与 /orders/<ID>,而不是 /createOrder、/queryOrderDetail、/cancelOrder。路径应该表达“你正在操作什么”,方法才表达“你想对它做什么”。

业务意图 推荐设计 不推荐设计
查询订单列表 GET /orders GET /getOrderList
查询单个订单 GET /orders/<ID> GET /queryOrderDetail?id=<ID>
创建订单 POST /orders POST /createOrder
更新订单 PATCH /orders/<ID> POST /updateOrder
删除订单 DELETE /orders/<ID> POST /deleteOrder

资源之间存在从属关系时,可以使用层级路径,例如 GET /users/<ID>/orders 表示查询某个用户的订单。但层级不要无限向下嵌套;当路径需要连续表达三层以上关系时,通常应该重新检查资源边界。

REST API 资源建模与请求语义关系

让 HTTP 方法保持语义一致

同一类业务动作应该长期保持一致的 HTTP 语义,否则调用方很难仅凭接口定义判断是否安全、是否可重试、是否会改变服务端状态。

GET 用于读取资源,不应该产生业务副作用;POST 通常用于创建资源或提交无法自然映射为幂等更新的动作;PUT 更适合整体替换;PATCH 更适合局部更新;DELETE 用于删除资源。

需要特别关注幂等性。GET、PUT、DELETE 按语义应当是幂等的:同一个请求重复执行多次,最终资源状态应与执行一次一致。POST 通常不保证幂等,因此创建订单、支付等场景如果允许客户端重试,应该额外设计幂等键,而不是依赖“调用方不要重复提交”。

用查询参数表达筛选、分页和排序

集合资源的筛选条件放在查询参数里,不要把所有过滤维度扩展成新的路径。以订单列表为例,状态、分页、排序都属于“如何查询订单集合”,而不是新的资源。

推荐形式类似:GET /orders?status=PAID&page=1&pageSize=20&sort=createdAt,desc。这样路径保持稳定,新增筛选条件时也不会持续制造新接口。

分页字段需要在整个系统内统一,例如固定使用 page、pageSize,或者统一使用游标 cursor、limit。同一项目里不要同时出现 pageNo、pageNum、currentPage 等多个同义字段。

对于大数据量、实时流式列表,游标分页通常比页码分页更稳定,因为它不会因为前面新增或删除数据而频繁导致重复或遗漏;普通后台管理列表则可以继续使用页码分页,优先保证简单和可维护。

状态码和响应体分别表达什么

HTTP 状态码应该先表达请求的协议级结果,响应体再补充业务细节。不要所有成功都返回 200,所有失败也返回 200 再靠业务字段判断。

常见约定可以保持简单:创建资源返回 201 Created;成功但没有响应体返回 204 No Content;请求参数不合法返回 400 Bad Request;未认证返回 401 Unauthorized;已认证但无权限返回 403 Forbidden;资源不存在返回 404 Not Found;资源状态冲突返回 409 Conflict。

下面是一个创建订单的完整请求示例。实际域名、端口和资源 ID 会随环境变化。

bash
curl -i -X POST "https://api.example.com:<PORT>/orders" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <ID>" \
  -d '{"productId":"<ID>","quantity":2}'

预期结果:服务端创建订单后返回 201 Created,并通过 Location 告诉客户端新资源地址;订单 ID 为动态值。

text
HTTP/1.1 201 Created
Location: /orders/<ID>
Content-Type: application/json

{"id":"<ID>","productId":"<ID>","quantity":2,"status":"CREATED"}

如果请求字段错误,则应返回 4xx,而不是继续返回 200。

text
HTTP/1.1 400 Bad Request
Content-Type: application/json

{"code":"INVALID_ARGUMENT","message":"quantity must be greater than 0"}

code 用于程序判断,message 用于人类阅读。不要让客户端依赖中文或英文提示文本来分支业务逻辑。

错误模型要稳定,不要把异常直接透传

接口一旦被多个客户端使用,错误结构比成功结构更需要稳定。推荐固定保留机器可识别的错误码、可读消息,以及可选的定位信息;不要直接把 Java 异常类名、SQL、堆栈或内部服务名称暴露给外部客户端。

错误码应该表达业务语义,例如 ORDER_NOT_FOUND、ORDER_STATUS_CONFLICT,而不是 RuntimeException、ERROR_001 这种无法直接理解含义的编码。对于参数校验错误,可以增加 field 或 details,但字段结构要统一。

日志里可以保存完整异常、traceId 和调用链,响应里只返回调用方真正需要的信息。这样既便于排障,也能降低内部实现细节泄露风险。

版本、兼容性和删除策略要提前设计

REST API 最难的不是写出第一版,而是第二版上线后如何不破坏旧客户端。新增可选字段通常可以保持兼容;删除字段、修改字段类型、改变枚举含义、改变默认行为则属于高风险变更。

对外 API 可以使用 /v1/orders 这样的路径版本;内部服务如果已有统一网关,也可以通过 Header 或网关路由管理版本,但同一套系统要保持单一策略。版本号只在出现不兼容变更时升级,不要把每次普通发布都变成新 API 版本。

删除字段或接口时,先进入废弃期:文档标记 deprecated、监控实际调用量、通知调用方迁移、达到约定窗口后再移除。对移动端尤其要谨慎,因为旧版本 App 可能长期存在,服务端不能假设所有客户端会同步升级。

用一组规则完成接口评审

设计完成后,可以用一组固定问题快速检查:路径是否只描述资源;HTTP 方法是否符合语义;集合查询是否使用统一筛选和分页;状态码是否真实反映结果;错误结构是否稳定;重试场景是否考虑幂等;变更是否兼容旧客户端。

如果一个接口必须写很长的说明才能解释“为什么这个 POST 其实只是查询”“为什么 200 其实代表失败”,通常说明设计已经偏离了协议语义。好的 REST API 不追求形式上的绝对纯粹,而是让资源、方法、状态码和错误模型长期保持一致,让调用方不看实现也能推断接口行为。

目录与阅读设置

记录一个想法

REST API 到底应该怎么设计

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通