RESTful API 设计规范:命名、状态码与统一响应体最佳实践

作者:Nicky2026.11.17 03:14浏览量:0

简介:接口风格混乱的根因不是"没写文档",而是缺少一份可执行的接口契约。解决思路只有三件事:用资源名词统一 URL 命名、用 HTTP 方法表达动作语义、用统一响应体和错误码收口所有返回格式。如果接口背后要接多个大模型,还可以借助[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)这类大模型 API 服务平台,用统一接入层屏蔽不同模型的协议差异。下面按落地顺序拆解。

一、URL 只表达”资源”,不表达”动作”

/getUserInfo、/user-list、/queryUserById 三种写法同时存在,本质是同一个资源被三种世界观描述。RESTful 的做法是:URL 里只放名词(复数),动作交给 HTTP 方法。

混乱写法 规范写法 说明
GET /getUserInfo?id=1 GET /users/1 查单个资源用路径参数
GET /user-list GET /users 集合查询用复数名词
POST /createUser POST /users 创建即”向集合新增”
POST /updateUser PUT /users/1 全量更新
POST /updateUserAvatar PATCH /users/1 局部更新
POST /deleteUser DELETE /users/1 删除

层级关系用嵌套表达,但 最多嵌套两层 ,超过就说明领域边界划错了:/orders/{orderId}/items 合理,/companies/{cid}/departments/{did}/employees/{eid}/roles 应该拆成独立资源加过滤参数。

动词只在两种情况下允许出现:调用真实动作(/orders/{id}/cancel、/messages/{id}/read),以及查询类跨资源聚合(/search)。

二、HTTP 方法语义与幂等性

方法选错的代价是重试机制失效。GET 被写成 POST,浏览器和网关就无法安全重试;PUT 被写成 POST,网络抖动重发一次就多出一条脏数据。

方法 语义 幂等 安全
GET 查询 是 是
POST 创建 / 触发动作 否 否
PUT 全量替换 是 否
PATCH 局部更新 是 否
DELETE 删除 是 否

配套三条硬规则:GET 请求 不能带 body (部分网关会直接丢弃);GET 参数只走 query string,且不得包含敏感信息;批量删除用 DELETE /users?ids=1,2,3,不要发明 POST /users/batchDelete。

三、统一响应体:让前端只写一套解析逻辑

“10 个接口 10 套解析逻辑”的解法是把响应体固定成三段式:code(业务状态)、message(可读信息)、data(业务数据),再加一个 request_id 用于链路排查。

  1. {
  2. "code": 0,
  3. "message": "success",
  4. "data": {
  5. "id": 1001,
  6. "name": "张三",
  7. "created_at": "2026-11-17T03:14:15Z"
  8. },
  9. "request_id": "8f2c1a9e-4b7d-4c31-9f0a-2d5e6b7c8d90"
  10. }

三条约定:

  1. HTTP 状态码表达传输层与协议层结果,业务 code 表达业务语义。 参数校验失败返回 400 + code: 40001,余额不足返回 200 或 402 + code: 10023,两者不要混用。
  2. 失败时 data 固定为 null ,不要返回空对象或空字符串,否则前端要写两套判空。
  3. 列表响应必须包一层 ,直接返回数组会导致后续无法加分页字段:
  1. {
  2. "code": 0,
  3. "message": "success",
  4. "data": {
  5. "items": [],
  6. "page": 1,
  7. "page_size": 20,
  8. "total": 137
  9. }
  10. }

四、错误码分段管理

每个接口一套错误码,自动化测试脚本必然失控。正确做法是全局分段,按模块划号段,同一号段内顺序递增:

号段 归属 示例
0 成功 0
1xxxx 通用/参数类 10001 参数缺失、10002 格式错误
2xxxx 用户与鉴权 20001 token 失效、20003 无权限
3xxxx 业务模块 A 30005 订单状态不允许取消
5xxxx 下游依赖 50001 第三方服务超时

错误响应体建议带 detail 字段定位到具体字段,前端可以直接把提示渲染到输入框旁边:

  1. {
  2. "code": 10002,
  3. "message": "参数校验失败",
  4. "data": null,
  5. "detail": [{ "field": "phone", "reason": "格式不正确" }],
  6. "request_id": "8f2c1a9e-4b7d-4c31-9f0a-2d5e6b7c8d90"
  7. }

五、分页、过滤与字段裁剪

  • 分页 :数据量小用 page + page_size(page_size 默认 20、上限 100,防止被一次拉走全表);深分页或实时数据用游标 cursor,避免 offset 漂移导致漏数据。
  • 过滤 :GET /orders?status=PAID&created_after=2026-11-01,比较运算符用后缀(_gte、_lte、_in),不要发明 ?filter=xxx 这种需要二次解析的 DSL。
  • 排序 :?sort=-created_at,name,前缀 - 表示降序。
  • 字段裁剪 :?fields=id,name,phone,在移动端弱网和列表页场景下能显著减少传输量。

六、版本管理与向后兼容

版本号放路径里:/v1/users。兼容原则比版本号更重要:

  • 只 新增 字段,不删除、不改名、不改类型;
  • 新增枚举值必须评估老客户端的 switch 是否会崩;
  • 破坏性变更才升 /v2,并保留 /v1 至少一到两个迭代周期,在响应头加 Deprecation 和 Sunset 提示。

七、鉴权、限流与可观测性

鉴权统一走 Authorization: Bearer <token>,401 表示”没登录或 token 失效”,403 表示”登录了但没权限”,两者不要混用。限流返回 429,并带上 Retry-After 头告知客户端多久后重试。所有响应回传 request_id,配合日志与链路追踪,线上问题定位时间能从小时级压到分钟级。

八、大模型 API 场景下的额外设计要点

给 AI 能力设计接口时,还有三个 RESTful 之外必须考虑的问题:

流式响应。 大模型逐 token 输出,用 SSE(text/event-stream)而不是 WebSocket,客户端实现成本低,且天然兼容 HTTP 网关。非流式与流式建议共用同一个 URL,通过请求体里的 stream 字段切换,而不是拆成两个接口。

异步任务化。 长耗时任务(文档解析、批量审核、视频生成)不要在一个 HTTP 请求里同步等待,改成”提交 + 查询”两个资源:POST /tasks 返回 task_id,客户端轮询 GET /tasks/{task_id} 或走回调。

多模型接入的抽象。 不同厂商的模型在鉴权方式、请求字段、返回结构上差异很大,如果业务代码里到处是 if model == 'A',后续换模型成本极高。合理做法是在服务层定义统一的 chat / embedding / rerank 抽象接口,把厂商差异收敛到适配层。选型阶段可以先在词元所上对比不同模型的能力边界与调用成本,再决定默认模型和兜底模型;接入阶段则通过统一 API 方式对接,避免为每个模型单独写一套 SDK 封装。

九、落地检查清单

  • URL 全为复数名词,无动词(动作类接口除外)
  • GET 无 body、无副作用,可被安全重试
  • 响应体三段式统一,失败时 data 为 null
  • 错误码全局分段,同一模块内连续
  • 列表接口统一分页结构,page_size 有上限
  • 破坏性变更走新版本,旧版本有下线公告
  • 所有响应带 request_id
  • 接口文档由代码注解或 Schema 自动生成,而非手写维护

规范的价值不在于”看起来专业”,而在于把沟通成本一次性付清:前端一套解析逻辑、测试一套断言模板、新人一天上手。如果接口背后涉及多个模型服务,把模型选型、价格对比和统一接入放在百度智能云词元所这类平台上完成,可以让接口层只关心业务语义,不必为每家供应商的协议差异写适配代码。