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 表示查询某个用户的订单。但层级不要无限向下嵌套;当路径需要连续表达三层以上关系时,通常应该重新检查资源边界。

让 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 会随环境变化。
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 为动态值。
HTTP/1.1 201 Created
Location: /orders/<ID>
Content-Type: application/json
{"id":"<ID>","productId":"<ID>","quantity":2,"status":"CREATED"}如果请求字段错误,则应返回 4xx,而不是继续返回 200。
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 不追求形式上的绝对纯粹,而是让资源、方法、状态码和错误模型长期保持一致,让调用方不看实现也能推断接口行为。