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 等格式保存接口定义,让前后端根据同一份契约开发。接口变更前需要确认影响范围,并通过自动化测试验证旧客户端是否仍然可用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定义稳定的 API 契约

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

登录哪都通