AI Agent / 系统课时
定义稳定的 API 契约
定义稳定的 API 契约
API 契约用于明确客户端和服务端之间如何通信。本篇将建立请求、响应、错误、分页和版本兼容规则,让接口在多人协作和持续迭代中保持稳定。
学习目标
- 理解 API 契约需要约束的核心内容。
- 能够设计清晰统一的请求与响应结构。
- 掌握接口演进中的兼容策略。
API 契约包含哪些内容
一个稳定 API 不只是定义 URL 和参数,还需要约定数据结构、状态码和异常表达方式。客户端依赖这些规则处理页面展示、重试逻辑和错误提示,因此契约越清晰,后续修改成本越低。常见契约内容包括:
- 请求方法与路径,例如 GET 查询、POST 创建。
- 请求参数名称、类型、必填条件。
- 响应字段结构和字段含义。
- HTTP 状态码与业务错误码。
- 分页、排序和过滤规则。
- 版本兼容策略。
设计统一的请求与响应结构
推荐让接口返回结构保持一致,避免每个接口使用完全不同的格式。下面是一个创建用户接口的响应示例。
json
{
"data": {
"id": "u_1001",
"name": "Alice"
},
"requestId": "req_001"
}预期结果
text
客户端可以稳定读取 data.id 和 data.name 字段。错误响应也应保持统一,例如:
json
{
"error": {
"code": "INVALID_ARGUMENT",
"message": "email 格式错误"
},
"requestId": "req_002"
}这样客户端无需针对每个接口编写不同错误处理逻辑。
处理分页和版本兼容
列表接口通常需要提前定义分页方式。常见方案包括页码分页和游标分页,选择后应保持长期稳定。例如页码分页可以约定:
json
{
"items": [],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 200
}
}接口升级时,应优先采用增加字段而不是删除字段的方式。删除已有字段会直接影响旧客户端,增加可选字段通常具有更好的兼容性。
契约验证与协作方式
在团队开发中,可以使用 OpenAPI 等格式保存接口定义,让前后端根据同一份契约开发。接口变更前需要确认影响范围,并通过自动化测试验证旧客户端是否仍然可用。
按自己的节奏,确认真正理解。