REST API 请求头规范：这些细节你真的注意了吗？

做开发时，调用第三方接口或者自己写 ref="/tag/155/" style="color:#C468A7;font-weight:bold;">API，很多人只关心传什么参数、返回什么数据，却忽略了请求头（Request Headers）的重要性。特别是在安全软件相关的系统中，一个不合规的请求头可能直接导致鉴权失败，甚至被当成攻击行为拦截。

为什么请求头不能随便写？

想象一下你去公司打卡上班，保安认的是工牌上的姓名和工号。如果工牌信息模糊不清，或者根本没有，哪怕你是真员工，也可能进不去门。API 请求头就像这张工牌，它告诉服务器“你是谁、你要干什么、数据长什么样”。

比如你在开发一款杀毒软件的云端扫描功能，客户端需要把文件特征发到后台分析。如果不带正确的 Content-Type，服务器可能无法解析上传的数据；如果缺少身份令牌，请求会被当作非法访问直接拒绝。

常见的 REST API 请求头及其作用

下面这几个请求头，在实际项目中最常出现，也最容易出错：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json
User-Agent: Antivirus-Client/2.1.0 (Windows NT 10.0)
X-Request-ID: a1b2c3d4-5678-90ef

• Authorization：用于身份认证，常见格式是 Bearer <token>，值通常由登录接口返回。安全软件频繁与后台通信，必须确保每次请求都带上有效 token。
• Content-Type：告诉服务器你发的是什么类型的数据。如果是 JSON 数据，就必须写 application/json；如果传文件，可能是 multipart/form-data。写错了，后端解析就会出问题。
• Accept：声明你能接收的响应格式。虽然很多接口默认返回 JSON，但显式声明更稳妥，避免服务端误判。
• User-Agent：标识客户端类型和版本。在安全软件中尤其重要，后台可以根据这个判断是否为合法客户端，防止模拟请求泛滥。
• X-Request-ID：用于链路追踪，方便排查问题。当某个请求出错时，运维可以通过这个 ID 快速定位日志。

自定义头部的安全建议

有些团队喜欢加自己的头部，比如 X-Device-ID 或 X-Auth-Version。这没问题，但要注意两点：

一是命名要规范，使用连字符分隔单词，不要用下划线（如 X_Device_ID），因为某些代理或网关会忽略含下划线的头部。

二是敏感信息别放头部明文传输。比如设备唯一标识，如果必须传，应先加密，避免被中间人截获后用于追踪用户。

一个真实的踩坑案例

有次我们对接某云查杀接口，始终返回 400 错误，提示“Invalid request”。检查参数没问题，抓包一看才发现，Content-Type 被自动设成了 text/plain，而对方严格校验必须是 application/json。加上正确的请求头后，问题立刻解决。

后来才明白，那个 SDK 在没有手动设置时，默认用了文本格式。这种隐式行为，最容易让人掉坑里。

如何保证请求头始终合规？

与其每次手动拼，不如在客户端封装一层 HTTP 工具类，统一设置公共头部。例如：

const defaultHeaders = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'User-Agent': `SecurityClient/${APP_VERSION}`,
  'Authorization': `Bearer ${getToken()}`
};

// 所有请求自动携带
fetch('/api/scan', {
  method: 'POST',
  headers: { ...defaultHeaders, ...customHeaders },
  body: JSON.stringify(data)
});

这样既减少出错概率，也便于集中管理，比如 token 刷新后自动更新所有后续请求。

API 接口看似简单，但细节决定成败。特别是在涉及用户隐私和系统安全的场景下，每一个请求头都不是可有可无的装饰品，而是保障通信可靠、安全的关键环节。