计算机网络 / 系统课时
设计自定义消息头
设计自定义消息头
这一课把“想塞几个自定义字段”变成可长期维护的接口约定。你会给追踪、版本和业务上下文分别选合适的字段名、值格式、长度上限与代理策略,并知道什么时候应直接采用已有标准头而不是再造一个字段。
学习目标
- 为请求追踪、API 版本和业务上下文设计职责单一的消息头。
- 规定可验证的值格式、长度上限以及代理覆盖规则。
- 用 curl 验证自定义头是否按预期发出,并识别常见兼容性问题。
先把字段职责拆开
自定义字段名大小写不敏感;HTTP/2 和 HTTP/3 传输时会使用小写字段名,因此代码不能依赖原始大小写。也不建议仅因为“这是自定义字段”就机械加 X- 前缀。项目内可以采用稳定的组织前缀,降低和第三方字段冲突的概率。
下面是一组可直接落地的项目约定,数值属于工程限制而不是 HTTP 标准:
| 目的 | 推荐字段 | 值示例 | 建议上限 | 写入方 |
|---|---|---|---|---|
| 请求关联 | Acme-Request-Id |
01J9Y7M6Y7K5M4WQ3F8K2H1P0A |
64 字符 | 网关生成或重写 |
| API 版本 | Acme-Api-Version |
2026-10-01 |
32 字符 | 客户端 |
| 租户上下文 | Acme-Tenant-Id |
tenant_8f2a31 |
64 字符 | 认证网关注入 |
| 客户端能力 | Acme-Client-Capabilities |
bulk-read,delta-sync |
256 字符 | 客户端 |
字段名应描述数据含义,不要用 Info、Meta 这类万能名称。一个字段只承担一种职责;例如不要把租户、地区、版本拼成 Acme-Context: tenant=...;region=...;version=...,否则每个中间件都要理解同一套私有语法。
值格式必须能被机器严格校验
请求 ID 推荐使用固定结构的 UUID、ULID 或 16~32 字节随机值编码结果;服务端至少检查字符集和长度。版本号若用于路由,优先选稳定且可比较的格式,例如日期版本 2026-10-01 或整数 3,避免 latest、new 这类随时间变化的值。
业务上下文不要放敏感凭据。Authorization、Cookie、令牌、身份证号、完整邮箱等信息不应复制到自定义头里。对 Acme-Tenant-Id 这类字段,应用还要把它与认证结果交叉校验,不能仅凭客户端提交的值切换租户。
可采用下面的检查规则:请求 ID 1~64 个 ASCII 字符;版本 1~32 个字符且只允许数字、字母、点和短横线;租户 ID 1~64 个字符且只允许字母、数字、下划线和短横线。超过限制直接返回 400 Bad Request,不要默默截断。
代理链要规定谁覆盖谁透传
追踪 ID、租户上下文这类字段经过 CDN、API Gateway、Service Mesh 时,最容易出现“客户端伪造”和“代理误删”两类问题。应给每个字段明确三种策略之一:覆盖、透传、删除;不要依赖代理默认行为。

一个可执行的网关约定可以是:入站若有 Acme-Request-Id,先校验格式,失败则重建;Acme-Tenant-Id 一律删除客户端值并根据认证结果重新注入;Acme-Api-Version 只允许已发布版本,未知版本返回 400 或 406,由接口契约统一决定。
用 curl 验证字段是否发出
下面使用 HTTP/1.1,发送三个自定义头并只查看 curl 发出的请求行。这样可以验证字段名和值的拼写,不依赖服务端返回固定 JSON。
curl --http1.1 -sS -o /dev/null -v \
-H 'Acme-Request-Id: 01J9Y7M6Y7K5M4WQ3F8K2H1P0A' \
-H 'Acme-Api-Version: 2026-10-01' \
-H 'Acme-Tenant-Id: tenant_8f2a31' \
https://example.com/ 2>&1 \
| grep -E '^> (Acme-Request-Id|Acme-Api-Version|Acme-Tenant-Id):'预期输出:
> Acme-Request-Id: 01J9Y7M6Y7K5M4WQ3F8K2H1P0A
> Acme-Api-Version: 2026-10-01
> Acme-Tenant-Id: tenant_8f2a31如果线上链路里看不到这些字段,先查网关和反向代理是否配置了请求头白名单、重写或大小限制,再查应用框架是否把字段名统一转成小写。不要因为大小写变化就判定“头丢了”。
能用标准字段时不要自造
分布式追踪优先使用 W3C Trace Context 的 traceparent 和 tracestate,而不是自定义 Acme-Trace-Id。客户端 IP 优先使用已约定好的 Forwarded 或现有代理链规范,不要再定义 Real-Client-Ip、Source-Ip 等重复字段。
还要避免把自定义字段列入 Connection。Connection 描述逐跳连接级字段,而业务上下文通常应端到端传递;HTTP/2 还禁止使用这类连接专用字段。上线前应至少做三项验收:直连服务能读到字段、经过每一层代理后仍符合覆盖策略、超长或非法值会被明确拒绝。