为何http.IncomingMessage的headers属性是非可枚举的？

问题背景 #

假设我们通过以下代码创建Node.js HTTP服务器：

const server = http.createServer((req, res) => {
  // req 是 IncomingMessage 的实例
});

根据Node.js官方文档，req是IncomingMessage的实例，它拥有headers属性，但执行Object.keys(req)时无法看到headers这个键，说明该属性是非可枚举的；而rawHeaders属性却能被枚举出来。

核心问题：为什么headers是非可枚举的，而rawHeaders是可枚举的？这是既定规则还是有特定原因？

具体原因 #

• 设计意图的明确区分：
  headers是Node.js对原始请求头加工后的结构化对象（比如合并重复的Set-Cookie头、将头名转换为小写格式），属于给开发者提供的易用访问接口。将其设为非枚举，是为了引导开发者通过属性直接访问（req.headers），而非通过枚举遍历的方式获取；而rawHeaders是接收到的原始请求头数组（按接收顺序存储，保留原始大小写和重复项），属于原始数据载体，枚举它能让开发者直接看到所有原始请求头内容，符合其作为原始数据的定位。

• 避免遍历逻辑干扰：
  如果headers设为可枚举，当开发者用Object.keys(req)或for...in遍历req实例时，会把这个结构化的headers对象也纳入结果中，这可能干扰开发者对req本身核心属性/方法的遍历需求——大多数情况下，开发者遍历req是为了查找实例的原生方法或状态属性，而非这个加工后的头信息结构。

• 匹配属性的动态特性：
  headers并非实例创建时就存在的静态属性，而是通过getter动态生成的（每次访问时可能根据原始头重新计算）。将动态生成的访问器属性设为非枚举，是JavaScript中常见的设计方式，能区分“静态存储的原始数据”和“动态计算的派生属性”，rawHeaders作为静态存储的原始数据，设为可枚举更合理。

• API稳定性与兼容性考量：
  Node.js早期版本就确立了这种设计，后续版本保持该规则以保证API一致性。如果允许枚举headers，可能会让开发者依赖这种遍历行为，而当Node.js调整headers的生成逻辑（比如新增头处理规则）时，就可能破坏这类依赖代码，非枚举设计能避免这种情况。

内容的提问来源于stack exchange，提问作者Aaron Parisi