深入理解 API 设计中的 Content Negotiation：从 Accept 头到多格式响应实战

导读

Content Negotiation（内容协商）是 HTTP 协议赋予 API 设计的一项核心能力：它让客户端与服务端在同一个 URL 上就"返回什么格式的数据"进行协商，从而让一套接口同时服务 JSON、XML、HTML 等多种消费场景。在 api-design 这条技术路线中，内容协商是与 HTTP 头、RESTful API、版本化策略 紧密衔接的基础知识点。读完本文，你将掌握内容协商的四种机制、三类核心协商头（Accept / Accept-Language / Accept-Encoding）、服务端协商决策流程，并能通过 curl 与真实请求/响应示例在项目中落地多格式 API。

什么是内容协商：客户端与服务端的"格式对话"

在 API 设计语境下，内容协商指的是 客户端与服务端就双方都能接受的数据表示形式（data representation）进行沟通的过程。它允许客户端声明自己偏好的响应格式——例如 JSON、XML 或 HTML——服务端据此返回最合适的表示。这一机制让 API 变得灵活、可适配，显著提升其可用性，是掌握 API 设计基础不可或缺的一环。

理解内容协商的关键在于区分两个概念：

• 资源（Resource）：URL 所指向的抽象实体，例如 /users/42 代表的"用户 42"。
• 表示（Representation）：资源在特定时刻、特定格式下的具体形态，例如 {"id": 42, "name": "Alice"} 是 JSON 表示，<user id="42"><name>Alice</name></user> 是 XML 表示。

内容协商解决的正是在"资源"与"表示"之间做选择的问题：同一个 URL，客户端想要什么格式，服务端就给什么格式。这也解释了为什么内容协商天然契合 REST 的"资源 + 表示（Representation）"理念——RESTful API 本质上就是 围绕资源及其表示展开的，而内容协商正是决定"表示"如何被挑选的机制。

HTTP 中的三类内容协商机制

HTTP 标准定义了三种内容协商形式，它们在 API 设计中的适用场景各不相同。

服务端驱动协商（Server-driven / Proactive Negotiation）

由客户端在请求头中携带偏好，服务端根据这些偏好选择最佳表示并返回。这是 API 设计中最常见、最实用的一类，也是本指南的重点。

代理驱动协商（Agent-driven / Reactive Negotiation）

服务端先返回一个默认表示，并在响应中列出所有可用表示的地址（例如通过 Alternates 头或 HTML 页面内的链接），客户端再从中挑选并二次请求。这种方式会引入额外往返，实际 API 中较少直接使用。

透明协商（Transparent Negotiation）

由中间代理（如缓存服务器、CDN）代表客户端与服务端协商，客户端和服务端都认为对方就是直接通信方。透明协商将协商逻辑抽离到基础设施层，是代理驱动协商的一种变体。

对于绝大多数 REST/JSON API 而言，服务端驱动协商就是全部答案：客户端通过 Accept 系列请求头表达偏好，服务端按 q 权重排序后选择表示，并用 Content-Type 说明实际返回格式。

核心协商头：Accept 家族

Accept：声明可接受的媒体类型

Accept 请求头告诉服务端客户端能够理解哪些媒体类型（MIME type），服务端据此选择响应格式。一个典型的多格式 API 请求如下：

GET /users/42 HTTP/1.1
Host: api.example.com
Accept: application/json

如果客户端更偏好 JSON 但也接受 XML，可以这样声明：

Accept: application/json, application/xml

服务端应返回其中一种格式，并在响应头中标注实际使用的媒体类型：

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "name": "Alice"}

这里体现了 Accept（客户端偏好）与 Content-Type（服务端实际返回）的分工：Accept 描述"我想要什么"，Content-Type 描述"我给的是什么"。

q 权重：表达偏好优先级

当列表中出现多种格式时，客户端可以用 q 参数（0 到 1 的权重，默认 1）表达相对优先级。例如"最想要 JSON，其次 XML，HTML 也可以但不理想"：

Accept: application/json;q=1.0, application/xml;q=0.8, text/html;q=0.5

服务端按权重降序尝试匹配自身能力，选择权重最高的可提供格式。q=0 表示明确拒绝该格式。这一机制让客户端能以精确的"偏好梯度"参与协商，而不是简单的二选一。

Accept-Language：协商自然语言

Accept-Language 负责协商响应的语言表示，对面向多语言用户的 API 尤为重要：

Accept-Language: zh-CN, zh;q=0.9, en;q=0.8

服务端可据此返回中文或英文版本的消息文本、错误提示等。若无法满足任何语言，应返回 406 Not Acceptable 或按默认语言降级返回。

Accept-Encoding：协商压缩编码

Accept-Encoding 用于协商传输层的压缩方式，直接关系 API 的传输体积与性能：

Accept-Encoding: gzip, deflate, br

服务端选择支持的一种编码压缩响应体，并在 Content-Encoding 头中声明。这是内容协商中与 API 性能 关系最密切的一类协商——合理的压缩协商可以显著降低带宽消耗与响应延迟。

服务端协商决策流程

一次完整的服务端驱动内容协商，在 API 内部大致遵循以下决策链条：

1. 解析请求头：读取 Accept、Accept-Language、Accept-Encoding，解析其中的媒体类型列表与 q 权重；
2. 匹配资源表示：将客户端声明的媒体类型与服务端为该资源准备好的表示（JSON、XML、HTML 渲染模板等）进行交集匹配；
3. 按权重排序：在可提供的候选中，选择 q 值最高的表示；
4. 生成响应：按选定表示序列化响应体，设置对应的 Content-Type（以及 Content-Language、Content-Encoding）；
5. 协商失败兜底：若没有任何表示满足客户端声明（例如客户端只接受 application/yaml 而服务端不支持），返回 406 Not Acceptable，并在响应体中尽量列出可用表示。

通过 curl 验证协商行为

curl 是调试内容协商最直接的工具，可以用 -H 显式指定协商头：

# 请求 JSON 格式
curl -H "Accept: application/json" https://api.example.com/users/42

# 请求 XML 格式
curl -H "Accept: application/xml" https://api.example.com/users/42

# 声明多格式偏好及权重
curl -H "Accept: application/json;q=1.0, application/xml;q=0.8" \
     https://api.example.com/users/42

# 观察服务端实际返回的 Content-Type
curl -i -H "Accept: application/json" https://api.example.com/users/42

-i 会输出响应头，便于核对服务端选定的 Content-Type 是否与 Accept 声明一致——这是排查"为什么我请求了 JSON 却拿到 HTML"类问题的最快手段。

多格式响应实战：JSON、XML 与 HTML

内容协商的价值在于"一套 URL，多种消费形态"。以用户资源为例，同一个 GET /users/42，依据客户端的 Accept 头可以返回三种表示：

JSON 表示（面向程序化客户端，最常用）：

GET /users/42 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Alice",
  "role": "admin"
}

XML 表示（面向遗留系统或特定行业客户端）：

GET /users/42 HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<user id="42">
  <name>Alice</name>
  <role>admin</role>
</user>

HTML 表示（面向浏览器直接访问、SEO 或调试场景）：

GET /users/42 HTTP/1.1
Accept: text/html

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

<!DOCTYPE html>
<html>
  <body>
    <h1>Alice</h1>
    <p>Role: admin</p>
  </body>
</html>

在 RESTful API 语境下，JSON 以其轻量、易读、跨语言通用的特性 成为默认首选，但 HTML 表示的价值常被低估：它让 API 文档、健康检查页面、甚至"人可直接浏览的接口"免费获得，而这一切只需要在服务端为同一资源准备多套渲染模板。

请求体的协商：Content-Type 与客户端反方向协商

内容协商不仅作用于响应，也作用于请求体。当客户端向服务端发送数据（POST/PUT/PATCH）时，用 Content-Type 声明请求体的格式，服务端必须能解析该格式，否则应返回 415 Unsupported Media Type：

POST /users HTTP/1.1
Content-Type: application/json

{"name": "Bob", "role": "viewer"}

这形成了完整的双向语义：客户端用 Accept 协商"读什么"，用 Content-Type 声明"写什么"；服务端用 Content-Type 声明"返回什么"，用 406/415 兜底"协商失败"。在设计 CRUD 接口 时，这两组头的处理应作为接口契约的一部分写入文档。

内容协商与 API 版本化：Media Type Versioning

内容协商与 API 版本化策略 有天然交集：Media Type Versioning（媒体类型版本化） 正是把版本号编码进媒体类型参与协商，例如：

Accept: application/vnd.api+json;version=2
Accept: application/vnd.example.v2+json

这种方式将"格式选择"与"版本选择"统一收口到 Accept 头中，与 URI 版本化（/api/v2/users）相比，保持 URL 稳定、语义更内聚，但也会让协商头更复杂，并要求服务端具备更强的表示选择逻辑。若采用该策略，协商决策链条中需额外加入"版本匹配"步骤。

在 api-design 路线图中的位置

内容协商不是孤立知识点。它在 api-design 路线中与以下主题构成完整的能力闭环：

• HTTP 头：Accept 与 Content-Type 是 HTTP 头体系中与数据交换最直接的一对；
• HTTP 方法：GET 读、POST/PUT 写，配合双向协商头构成完整的数据语义；
• RESTful API：资源 + 表示的 REST 理念是内容协商的架构土壤；
• API 性能：Accept-Encoding 压缩协商直接服务于传输性能；
• 错误处理：406 / 415 是协商失败时必须妥善设计的错误分支。

设计建议总结如下：

1. 默认支持 JSON：绝大多数程序化客户端以 JSON 为第一格式，Accept 缺省时应默认返回 JSON；
2. 按需扩展表示：XML、HTML 等格式只在存在真实消费场景时提供，避免为"全格式"而过度设计；
3. 妥善处理 406：协商失败时返回 406 并附带可用格式清单，而非强行返回不匹配的格式；
4. 重视 Content-Type 一致性：响应 Content-Type 必须与实际响应体一致，这是客户端正确解析的前提；
5. 谨慎引入媒体类型版本化：仅在需要同时演进格式与版本时才启用，并评估对协商复杂度的代价。

掌握了内容协商，你就掌握了让同一套 API 同时服务浏览器、移动端、自动化脚本与遗留系统的基础能力——这是 API 设计 从"能用"走向"好用"的关键一步。