Nock项目从v10升级到v11的完整迁移指南

Nock项目从v10升级到v11的完整迁移指南

nock HTTP server mocking and expectations library for Node.js 项目地址: https://gitcode.com/gh_mirrors/no/nock

前言

Nock作为Node.js生态中广泛使用的HTTP测试辅助工具，在v11版本中带来了多项重要改进和变化。本文将全面解析从v10升级到v11需要注意的关键点，帮助开发者顺利完成迁移。

核心改进概述

基础架构升级

• 代码库全面转向ES6语法
• 采用Prettier统一代码风格
• 实现了100%测试覆盖率
• 测试套件支持完全离线运行

开发者体验增强

1. 内置TypeScript类型定义（v11.3新增）
2. 完整支持Node 10.9新增的http.request签名
3. 新增条件过滤功能：.conditionally(() => true)
4. 请求头修改现在会被正确保留
5. 录制功能增强：afterRecord()钩子支持自定义字符串化
6. .reply()现在支持async/await函数
7. 响应头设置方式统一：支持对象、Map和平铺数组

重大变更详解

运行环境要求

• 最低Node版本：必须使用Node 8或更高版本
• 官方测试覆盖Node 8、10和12三个LTS版本

响应处理逻辑重构

响应函数返回值处理

v10版本对.reply()函数返回值存在歧义处理，v11进行了规范化：

// v10问题示例
.reply(200, () => [500, 'hello world']) 
// 200被忽略，500作为状态码

// v11正确写法
.reply(500, 'hello world')
.reply(500, () => 'hello world')

错误处理机制变更

v10会自动捕获错误并返回500响应，v11改为透传错误：

// v11正确错误处理
.reply((uri, body, cb) => {
  fs.readFile('file.txt', (err, data) => {
    if(err) cb([500, err.stack]) 
    else cb([201, data])
  })
})

查询参数处理变更

1. .query()回调现在接收querystring.parse结果而非qs.parse
2. 禁止重复定义查询参数，会抛出Query parameters have already been defined错误

路径规范强化

• 路径必须以斜杠开头，否则抛出错误
• 旧版本会静默忽略此错误导致匹配失败

请求头规范

• reqheaders必须为纯对象格式
• 错误格式会抛出Headers must be provided as an object

其他重要变更

1. request.once现在真正只触发一次
2. nock.define()必须显式指定HTTP方法
3. 响应状态码必须为数字
4. 新增完善的错误类型检查

测试行为改进

请求处理增强

1. 完整支持request.end()所有重载形式
2. .destroy()错误现在能正确传播
3. 响应完成时设置.complete属性
4. 测试Socket添加unref()方法

迁移建议

1. 逐步升级：先在开发环境测试，确认无兼容问题再部署到CI
2. 错误处理：检查所有自定义响应函数的错误处理逻辑
3. 类型检查：利用新增的类型检查发现潜在问题
4. 查询参数：检查重复定义查询参数的情况
5. 路径规范：确保所有路径以斜杠开头

结语

Nock v11通过更严格的API规范和更完善的错误处理，提供了更可靠的HTTP测试能力。虽然需要一些迁移成本，但这些改进将显著提升测试代码的健壮性。建议开发者参考本文列出的变更点，逐步完成升级工作。

nock HTTP server mocking and expectations library for Node.js 项目地址: https://gitcode.com/gh_mirrors/no/nock