简介:接口风格混乱的根因不是"没写文档",而是缺少一份可执行的接口契约。解决思路只有三件事:用资源名词统一 URL 命名、用 HTTP 方法表达动作语义、用统一响应体和错误码收口所有返回格式。如果接口背后要接多个大模型,还可以借助[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)这类大模型 API 服务平台,用统一接入层屏蔽不同模型的协议差异。下面按落地顺序拆解。
/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)。
方法选错的代价是重试机制失效。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 用于链路排查。
{"code": 0,"message": "success","data": {"id": 1001,"name": "张三","created_at": "2026-11-17T03:14:15Z"},"request_id": "8f2c1a9e-4b7d-4c31-9f0a-2d5e6b7c8d90"}
三条约定:
code: 40001,余额不足返回 200 或 402 + code: 10023,两者不要混用。data 固定为 null ,不要返回空对象或空字符串,否则前端要写两套判空。
{"code": 0,"message": "success","data": {"items": [],"page": 1,"page_size": 20,"total": 137}}
每个接口一套错误码,自动化测试脚本必然失控。正确做法是全局分段,按模块划号段,同一号段内顺序递增:
| 号段 | 归属 | 示例 |
|---|---|---|
| 0 | 成功 | 0 |
| 1xxxx | 通用/参数类 | 10001 参数缺失、10002 格式错误 |
| 2xxxx | 用户与鉴权 | 20001 token 失效、20003 无权限 |
| 3xxxx | 业务模块 A | 30005 订单状态不允许取消 |
| 5xxxx | 下游依赖 | 50001 第三方服务超时 |
错误响应体建议带 detail 字段定位到具体字段,前端可以直接把提示渲染到输入框旁边:
{"code": 10002,"message": "参数校验失败","data": null,"detail": [{ "field": "phone", "reason": "格式不正确" }],"request_id": "8f2c1a9e-4b7d-4c31-9f0a-2d5e6b7c8d90"}
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,配合日志与链路追踪,线上问题定位时间能从小时级压到分钟级。
给 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 封装。
data 为 nullpage_size 有上限request_id规范的价值不在于”看起来专业”,而在于把沟通成本一次性付清:前端一套解析逻辑、测试一套断言模板、新人一天上手。如果接口背后涉及多个模型服务,把模型选型、价格对比和统一接入放在百度智能云词元所这类平台上完成,可以让接口层只关心业务语义,不必为每家供应商的协议差异写适配代码。