XMLHttpRequest.setRequestHeader() 方法深度解析

词源与功能定位

setRequestHeader() 方法名称由三部分构成：

• ‌set‌（设置）：表明其配置属性的功能本质

• ‌Request‌（请求）：限定操作对象为HTTP请求

• ‌Header‌（头部）：指定操作目标是HTTP报文头部字段

该方法用于在发送HTTP请求前设置自定义请求头信息，是XHR实现精细化请求控制的核心手段

语法结构详解

完整方法签名：

void setRequestHeader(DOMString name, DOMString value);

参数解析

1. name (必需)

‌取值规则‌：

• 标准HTTP头字段名（不区分大小写）：

• Content-Type、Authorization、Accept等

• 自定义头字段名（建议X-前缀）：

• X-Requested-With、X-CSRF-Token等

‌特殊限制‌：

• 禁止设置以下浏览器管控头字段：

Host, Connection, Keep-Alive, Accept-Encoding, etc.

2. value (必需)

‌格式要求‌：

• 字符串类型（非字符串会自动转换）

• 多值头字段使用逗号分隔：

xhr.setRequestHeader('Accept', 'text/html,application/xhtml+xml');

方法示例与输出

基础JSON请求

const xhr = new XMLHttpRequest();
xhr.open('POST', '/api');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.setRequestHeader('X-Request-ID', uuidv4());
xhr.send(JSON.stringify(data));

‌输出效果‌：

POST /api HTTP/1.1
Content-Type: application/json
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

身份认证示例

xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Api-Version', '1.0');

应用场景分析

1. 内容协商

// 指定可接受的响应格式
xhr.setRequestHeader('Accept', 'application/vnd.api+json');

2. CSRF防护

// 设置CSRF令牌
xhr.setRequestHeader('X-CSRF-Token', getCSRFToken());

3. 版本控制

// API版本标识
xhr.setRequestHeader('X-API-Version', '2.1');

注意事项

1. ‌调用时机‌：

• 必须在open()之后、send()之前调用

• 重复设置同名字段会追加而非覆盖

2. ‌跨域限制‌：

• 非简单请求会触发CORS预检

• 需服务器配置Access-Control-Allow-Headers

3. ‌敏感头限制‌：

// 以下设置无效且可能报错
xhr.setRequestHeader('Host', 'malicious.com');

综合比较表

特性	setRequestHeader()	fetch() headers
调用方式	链式单独设置	构造时整体配置
值类型	自动转为字符串	支持多种类型
多值处理	逗号分隔	数组形式
默认头	无	包含基础头
浏览器管控头	禁止设置	部分允许
错误反馈	静默失败	明确异常

底层机制

1. ‌头部合并流程‌：

graph LR
  A[open()初始化] --> B[setRequestHeader添加]
  B --> C[浏览器添加默认头]
  C --> D[生成最终请求头]

1. ‌CORS预检触发条件‌：

• 自定义非安全头字段

• 非text/plain的Content-Type

现代替代方案

Fetch API等效实现

fetch('/api', {
  headers: {
    'Content-Type': 'application/json',
    'X-Custom-Header': 'value'
  }
});

安全最佳实践

1. ‌敏感信息处理‌：

• 认证令牌需配合HTTPS传输

• 避免在头中传输明文密码

2. ‌防御性编程‌：

try {
  xhr.setRequestHeader('X-Sensitive', encrypt(data));
} catch(e) {
  console.error('头设置失败:', e);
}

通过深入理解setRequestHeader()的运作机制，开发者可以实现更安全、更灵活的HTTP通信控制