计算机网络 / 系统课时

设计自定义消息头

设计自定义消息头

这一课把“想塞几个自定义字段”变成可长期维护的接口约定。你会给追踪、版本和业务上下文分别选合适的字段名、值格式、长度上限与代理策略,并知道什么时候应直接采用已有标准头而不是再造一个字段。

学习目标

  • 为请求追踪、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。

bash
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):'

预期输出:

text
> 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 还禁止使用这类连接专用字段。上线前应至少做三项验收:直连服务能读到字段、经过每一层代理后仍符合覆盖策略、超长或非法值会被明确拒绝。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计自定义消息头

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

登录哪都通