HTTP API 概述

什么是 HTTP API

HTTP API(HTTP Application Programming Interface)是指基于 HTTP 协议构建的应用程序接口。它允许两个系统(比如前端和后端、服务 A 和服务 B)通过 HTTP 请求进行通信和数据交换。

为什么用 HTTP 做 API

HTTP 是 Web 的基石,具有以下天然优势:

  • 广泛支持:所有编程语言、设备、平台都内置 HTTP 客户端
  • 简单易用:使用 URL、方法(GET/POST 等)、状态码等标准机制
  • 可调试:可用浏览器、Postman、curl 等工具直接测试
  • 防火墙友好:通常走 80/443 端口,无需额外开放端口
  • 生态成熟:缓存、代理、认证、日志等基础设施完善

因此,即使不是做网页,很多系统也选择用 HTTP 来暴露接口。

HTTP API 的基本组成

一个典型的 HTTP API 包含以下要素:

  1. URL(端点 / Endpoint) — 标识要操作的资源或功能,例如 https://api.example.com/v1/orders

  2. HTTP 方法(Verb) — 表示操作类型:

  • GET:获取数据
  • POST:创建数据
  • PUT / PATCH:更新数据
  • DELETE:删除数据
  1. 请求头(Headers) — 传递元信息,如 Content-Type: application/json、Authorization: Bearer xxx

  2. 请求体(Body) — 发送数据(通常用于 POST/PUT),如 JSON:

{ "name": "张三", "email": "zhang@example.com" }
  1. 响应状态码(Status Code) — 表示结果状态:
  • 200 OK:成功
  • 201 Created:创建成功
  • 400 Bad Request:参数错误
  • 401 Unauthorized:未认证
  • 404 Not Found:资源不存在
  • 500 Internal Server Error:服务器出错
  1. 响应体(Response Body) — 返回的数据,通常是 JSON:
{
  "id": 101,
  "name": "张三",
  "created_at": "2026-01-30T10:00:00Z"
}

HTTP API 的常见风格

RESTful、RPC、GraphQL、gRPC、SOAP 属于接口设计范式;Webhook 是事件推送通信模式,并非接口范式,底层一般基于 HTTP API 实现。

风格 数据格式 协议 典型用途 是否资源导向
RESTful JSON/XML HTTP/1.1 Web 应用、公开 API 是
RPC JSON/XML HTTP/1.1 内部服务、简单接口 否(动词)
GraphQL JSON HTTP/1.1 多端数据需求灵活的场景 混合
gRPC Protobuf HTTP/2 高性能微服务,不使用 HTTP 语义 否
SOAP XML HTTP(理论支持 SMTP) 企业级系统、金融旧系统 否
Webhook JSON/XML HTTP/1.1 事件通知、异步回调(通信模式,非 API 范式) 否

RESTful API

在现代 Web 开发中,RESTful API 是一种被广泛采用的接口设计风格。无论是移动应用、前后端分离的网站,还是微服务架构,几乎都会遇到 RESTful API 的身影。

REST 是什么

REST(Representational State Transfer)中文译为"表述性状态转移",是由 Roy Fielding 在 2000 年博士论文中提出的一种软件架构风格。它并不是一个协议或标准,而是一组设计原则和约束条件。当一个 Web API 遵循这些原则时,就称为 RESTful API。

REST 的核心原则

REST 完整六大约束:客户端-服务器、无状态、可缓存、统一接口、分层系统、按需代码(Code-on-Demand,可选约束,工业实现极少)。

  1. 无状态(Stateless)
    每次客户端请求都必须包含服务器处理该请求所需的全部信息。服务器不会保存客户端的状态(比如会话),这使得系统更容易扩展和维护。例如,每次访问 RESTful 接口都要带上认证 Token,而非依赖服务器记住会话。

  2. 统一接口(Uniform Interface)
    所有资源通过统一的方式进行操作:

  • 每个资源都有唯一的标识(URI)
  • 使用标准 HTTP 方法(GET、POST、PUT、DELETE 等)表示操作类型
  • 资源的表现形式(如 JSON、XML)与资源本身分离
  1. 资源导向(Resource-Based)
    REST 将一切视为"资源"(Resource),比如用户、订单、文章等。每个资源都有一个唯一的 URL。例如:
  • GET /users 获取所有用户
  • GET /users/123 获取 ID 为 123 的用户
  • POST /users 创建一个新用户
  1. 使用标准 HTTP 方法
    RESTful API 充分利用 HTTP 协议的语义:
HTTP 方法 含义 幂等性 安全性
GET 获取资源 是 是
POST 创建资源 否 否
PUT 更新整个资源 是 否
PATCH 部分更新资源 视请求内容 否
DELETE 删除资源 是 否

> - 幂等性:多次执行同一操作,服务端最终结果保持不变。PATCH 是否幂等取决于传入的业务逻辑。
> - 安全性:请求不会修改服务端业务状态。

  1. 可缓存(Cacheable)
    响应应明确标明是否可以被缓存,以提升性能。例如,GET 请求的响应通常可以被浏览器或代理缓存。

  2. 分层系统(Layered System)
    客户端无需知道是否直接连接到最终服务器,中间可以有代理、网关、负载均衡等层级,增强系统的可扩展性和安全性。

补充:完全严格的 RESTful API 在国内项目并不多见,大量是 REST-like(类REST):底层 HTTP+JSON,借鉴 REST 资源命名,但业务错误码统一包装 {code, msg, data},不完全依赖 HTTP Status Code。

RESTful API 示例

假设有一个博客系统,典型的 RESTful 接口设计如下:

GET    /api/posts      → 获取所有文章
GET    /api/posts/1    → 获取 ID 为 1 的文章
POST   /api/posts      → 创建一篇新文章
PUT    /api/posts/1    → 替换 ID 为 1 的整篇文章
PATCH  /api/posts/1    → 更新 ID 为 1 的文章的部分字段
DELETE /api/posts/1    → 删除 ID 为 1 的文章

响应通常使用 JSON 格式:

{
  "id": 1,
  "title": "什么是 RESTful API?",
  "author": "xx",
  "published": true
}

接口设计规范

资源与 URL 命名

约定依据是"URL 标识资源,方法表达动作"。

做法 推荐写法 不推荐写法 原因
集合用复数 /orders /order 集合与单条资源可区分
单条用路径变量 /orders/{id} /getOrder?id= 资源标识而非操作
层级用路径 /orders/{id}/items /orderItems?orderId= 从属关系表达清晰
筛选用查询参数 /orders?status=paid /orders/paid 状态是筛选条件而非资源层级
命名风格 /order-items /order_items、/orderItems 路径段统一小写连字符
动词不进入 URL POST /orders /createOrder 动作由方法表达

补充约定:

  • 路径层级控制在两层以内,更深的关联通过查询参数或子资源接口获取,避免 URL 随业务不断加长。
  • 需要执行无法映射到增删改查的操作时(如审批、重试),使用子资源加动作段的例外写法,例如 POST /orders/{id}/actions/retry,并限制使用范围。

HTTP 状态码的使用边界

状态码 含义 使用场景
200 成功 查询、更新成功并返回内容
201 已创建 创建成功,响应头返回 Location
202 已接受 请求已受理但未处理完,返回任务标识供查询
204 无内容 操作成功且无需返回内容,如删除
400 请求错误 参数缺失、格式错误、无法解析
401 未认证 缺少或无效凭证,响应头带 WWW-Authenticate
403 无权限 身份有效但无权访问该资源
404 不存在 资源不存在
405 方法不允许 路径存在但方法不支持,响应头返回 Allow
406 不可接受 无法按 Accept 声明的内容类型响应
409 冲突 状态冲突,如重复创建、版本冲突
412 前置条件失败 If-Match 校验未通过
415 媒体类型不支持 请求体类型不被支持
422 语义错误 格式正确但业务规则校验失败
429 请求过多 触发限流或配额,响应头带 Retry-After
500 服务内部错误 未预期异常
502 网关错误 上游返回无效响应
503 服务不可用 依赖不可用或正在发布
504 网关超时 上游响应超时

容易混淆的三组:

  • 401 与 403:401 表示身份未确认,客户端应重新认证;403 表示身份已确认但被拒绝,重复认证无意义。
  • 400 与 422:400 表示请求本身无法解析或结构不合法;422 表示结构合法但业务校验不通过。
  • 404 与 403:无权限访问某资源时返回 404 还是 403,取决于是否允许通过状态码判断资源是否存在,对外接口通常统一返回 404 以避免探测。

请求与响应头约定

头 方向 用途
Content-Type 请求 声明请求体类型,通常为 application/json; charset=utf-8
Accept 请求 客户端可接受的内容类型,服务端据此协商
Accept-Language 请求 期望的响应语言,用于错误消息本地化
Authorization 请求 凭证,通常为 Bearer <token>
X-Request-Id 或 traceparent 双向 链路标识,服务端应接受并回传,缺失时生成
Idempotency-Key 请求 幂等键,用于写操作的重复提交控制
Retry-After 响应 限流或不可用时建议的重试等待时间
Deprecation、Sunset 响应 接口废弃声明与下线时间
X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 响应 配额与剩余量

约定要点:链路标识由网关或入口服务生成并回传,业务代码只做透传与日志记录,不自行生成;错误响应应回传链路标识,使客户端报错时可据此定位服务端日志。

版本管理

三种策略对比

策略 示例 优点 代价
路径版本 /api/v1/orders 直观、易在网关与日志中区分、缓存友好 URL 变化,资源标识不稳定
查询参数 /api/orders?version=1 URL 路径不变 容易被客户端遗漏,网关路由复杂,缓存键处理麻烦
媒体类型或自定义头 Accept: application/vnd.example.v1+json 符合内容协商语义,URL 干净 调试与手动调用不便,前端与网关支持成本高

落地建议

  1. 主版本号放入路径,次版本号不进入 URL,通过兼容方式演进。
  2. 只有当变更无法兼容时才升主版本,升级前先确认是否可以用新增字段或新增接口替代。
  3. 同一路径上不要长期并行维护多个主版本,版本数量应受控,旧版本需有明确下线时间。

弃用与下线流程

  • 在响应头声明 Deprecation: true 与 Sunset: <HTTP 日期>,同时在文档与变更记录中标注。
  • 下线前按调用方维度统计旧版本流量,逐个通知并确认迁移完成,不能仅依赖声明头。
  • 保留短期双版本并行窗口,窗口长度由调用方改造周期决定,而不是由服务端实现便利决定。

统一响应与错误码

两种风格

风格 表现 优点 缺点
状态码语义化 HTTP 状态码表达结果,响应体直接是资源 符合协议语义,中间件与监控天然可用,缓存与重试策略易统一 业务错误需映射到有限的状态码,表达力有限
业务码包装 状态码多为 200,响应体为 {code, message, data} 业务错误表达自由,前端处理逻辑单一 与协议语义脱节,监控与缓存无法按状态码区分,错误易被中间件当作成功

实践中常见折中方案:传输与协议层错误使用状态码,业务规则错误使用统一结构并在状态码上给出对应值,避免全部返回 200。

响应结构示例

{
  "code": "ORDER_STOCK_INSUFFICIENT",
  "message": "库存不足",
  "data": null,
  "requestId": "b7f2c1d4-5a6e-4f3b-9c2d-1e8a7b6c5d4e",
  "timestamp": "2026-09-21T10:20:30Z"
}

错误码设计

  • 分段:按模块划分号段或使用带前缀的字符串码,模块段固定不变,便于定位归属。
  • 稳定:已发布的错误码不复用、不改语义,语义变化时新增错误码。
  • 可定位:错误码与消息分离,消息可随语言与上下文变化,错误码不变;客户端按错误码分支处理,不依赖消息文本。
  • 边界:对外只暴露可预期的业务错误码与固定文案,系统异常的堆栈、SQL、类名等信息只写入服务端日志,响应中仅返回链路标识。

错误码与状态码的映射原则:先确定客户端应采取的动作(重新认证、修正参数、等待重试、联系支持),再据此选择状态码,而不是先选状态码再拼凑错误码。

分页、排序与过滤

分页方式对比

方式 参数示例 随机跳页 深度分页性能 数据变动时是否稳定 适用场景
偏移分页 limit=20&offset=100 支持 随偏移量增大而下降 不稳定,可能重复或漏项 后台管理、数据量可控
页码分页 page=1&size=20 支持 同上 同上 需要展示总页数的界面
游标分页 cursor=xxx&limit=20 不支持 稳定 稳定 信息流、导出、大数据量遍历

偏移分页在数据频繁写入时会出现重复与漏项,因为两次查询之间插入的数据会改变后续页的边界;游标分页以"上一页最后一条的排序键"为起点,不受插入影响,但无法直接跳到任意页。

参数约定

  • 全站统一一种参数命名,不同时支持 page/size 与 limit/offset。
  • 单页条数设上限,避免客户端请求过大导致数据库压力。
  • 是否需要返回总数取决于界面需求:总数查询本身是一次聚合,数据量大时应避免默认返回,或改为异步统计。

排序与过滤

  • 排序参数形如 sort=createdAt,desc,多字段用逗号分隔。
  • 可排序与可过滤字段使用白名单校验,禁止将客户端字段名直接拼入查询,避免注入与索引失效。
  • 过滤参数与权限绑定:能过滤的字段与能返回的字段范围一致,避免通过过滤结果反推无权限数据。

幂等设计

需要幂等的场景

  • 客户端超时重试:请求已到达服务端并成功处理,但响应丢失,客户端重试会造成重复写入。
  • 用户重复点击或前端未做提交按钮互斥。
  • 消息重投、定时补偿与人工补单。

三种实现方式

方式 机制 适用 限制
唯一索引 业务唯一键(如订单号)建唯一索引,重复插入报冲突 有天然唯一业务键的创建操作 仅覆盖插入,更新与删除不适用
幂等键加去重表 以客户端提供的幂等键为唯一键,记录处理状态与结果 通用写操作,尤其是无天然唯一键的场景 需要额外的存储与过期清理
状态机 通过状态流转约束重复操作(已支付不能再次支付) 有明确状态流转的业务 只对状态敏感的操作有效

幂等键的使用

  • 由客户端生成并放入 Idempotency-Key 请求头,同一业务动作的重试使用同一个键。
  • 服务端以该键作为唯一约束存储"处理中、已完成、结果"三部分信息。
  • 重复请求的处理策略:处理中返回处理中状态,已完成返回首次结果,而不是重新执行。
  • 需要设置有效期,过期后键可被回收,避免存储无限增长。

与重试的配合

超时重试必须与幂等键配合才有意义:没有幂等键的重试会把"网络超时"变成"重复业务",可能的表现为重复扣款、重复发货与库存重复扣减。

条件请求与并发更新

同一组请求头在有缓存与并发控制两种用途,容易混用。

请求头 对应响应头 用途 不匹配时的结果
If-None-Match ETag 读取时的缓存校验 内容未变化返回 304,无响应体
If-Match ETag 写入时的乐观锁 版本不一致返回 412,拒绝写入
If-Modified-Since Last-Modified 读取时的缓存校验(时间粒度) 未修改返回 304
If-Unmodified-Since Last-Modified 写入时的乐观锁(时间粒度) 已修改返回 412

写入流程:

  1. 客户端先读取资源,服务端返回内容与 ETag。
  2. 客户端修改后提交,请求头带 If-Match: <etag>。
  3. 服务端比对当前版本,一致则写入并返回新的 ETag,不一致返回 412 并提示重新获取。

ETag 的生成需要满足两个条件:同一内容在多个实例上生成相同的值,以及内容变化时值随之变化。使用包含节点标识或随机数的生成方式会导致校验永远失败,表现为客户端反复重新获取。

接口演进与兼容性

变更类型 是否兼容 说明
新增响应字段 兼容 前提是客户端忽略未知字段
新增可选请求参数 兼容 服务端必须提供默认行为
新增接口或路径 兼容 无影响
新增枚举值 视客户端而定 客户端需对未知枚举容错,否则视为破坏性
修改字段语义但类型不变 破坏性 类型相同无法被编译期发现,风险最高
修改字段类型或格式 破坏性 如时间格式由时间戳改为字符串
删除字段或接口 破坏性 需先废弃并确认无调用后再移除
修改字段默认值 可能破坏 依赖默认值的调用方行为会变化
收紧参数校验 破坏性 原本通过的请求会被拒绝

扩展原则:

  • 客户端必须忽略未知字段,服务端不得依赖"客户端认识所有字段"这一假设。
  • 字段只增不删,废弃字段先标记为不再返回、再停止写入、最后移除,各阶段之间留出观测窗口。
  • 枚举新增值属于高风险变更,需要在客户端版本覆盖足够后才能启用。

契约与文档

  • 以 OpenAPI 描述文件作为接口的唯一事实来源,文档、客户端 SDK、测试用例与 Mock 服务都从契约生成,避免多份描述互相不一致。
  • 契约先行:先提交契约变更并评审,再实现服务端代码,使前后端可以并行开发。
  • 一致性校验:在构建阶段校验实现与契约是否一致,把不一致暴露在流水线中而不是上线后。
  • 变更记录需要与版本策略对应,明确标注每个版本的兼容变更与破坏性变更。

限流与配额

  • 触发限流时返回 429,并通过 Retry-After 告知建议等待时间,客户端据此退避而不是立即重试。
  • 配额类接口通过 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 暴露剩余量与重置时间,使客户端可以主动限速。
  • 限流维度需要在契约中明确(按调用方、按接口、按 IP),否则调用方无法预期被限制的原因。
  • 限流参数与网关配置应与文档保持一致,避免文档声明的阈值与实际生效值不同。

总结

  1. URL 标识资源、方法表达动作、查询参数表达筛选,路径层级保持浅而稳定。
  2. 状态码表达传输与协议层结果,需要先确定客户端应执行的动作,再选择状态码;401 与 403、400 与 422、404 与 403 的区分依据是语义而非习惯。
  3. 版本策略以路径版本为主,只有无法兼容时才升主版本,并且旧版本必须有明确的下线与观测流程。
  4. 统一响应结构需要在协议语义与业务表达力之间取舍,业务错误不宜全部返回 200。
  5. 分页方式的选择依据是数据是否频繁变动以及是否必须支持随机跳页,游标分页在稳定性与深度分页性能上更优。
  6. 幂等依赖唯一约束或状态记录,超时重试若无幂等键必然产生重复业务。
  7. If-None-Match 用于读缓存、If-Match 用于写并发控制,二者的失败结果分别是 304 与 412。
  8. 接口演进的判断标准是"旧客户端是否仍能正确工作",字段语义变更比字段增删更危险,因为无法被类型系统发现。
  9. 契约先行与构建期一致性校验,是避免文档与实现偏离的唯一有效手段。
  10. 限流与配额需要通过响应头让调用方可预期地退避,而不是让调用方在失败中猜测。