Restify 从 4.x 升级到 5.x 的完整迁移指南

Restify 从 4.x 升级到 5.x 的完整迁移指南

前言

Restify 5.0 版本带来了许多重要的改进和新特性，同时也引入了一些破坏性变更。本文将从技术专家的角度，全面解析从 4.x 升级到 5.x 需要注意的关键变化，帮助开发者顺利完成迁移。

核心变更解析

1. 查询参数和请求体解析器行为变更

在 5.x 版本中，queryParser 和 bodyParser 中间件默认不再将 req.query 和 req.body 映射到 req.params。如果需要保持 4.x 的行为，需要显式启用 mapParams 选项：

server.use(restify.plugins.queryParser({
  mapParams: true
}));

server.use(restify.plugins.bodyParser({
  mapParams: true
}));

2. 错误处理模块独立

错误处理相关功能已经从核心库中分离出来，形成了独立的 restify-errors 模块。这个模块可以独立使用，提供了：

• 可定制的错误类
• 错误链式处理
• 更清晰的错误分类

迁移时需要显式引入该模块：

const errors = require('restify-errors');
const server = restify.createServer();

server.get('/', (req, res, next) => {
  return next(new errors.InternalServerError('服务器错误'));
});

3. 客户端模块独立

所有客户端功能也已从核心库中分离，形成了 restify-clients 模块。这使客户端和服务器端可以独立更新和维护。

事件处理机制改进

1. 通用错误事件

5.x 引入了 restifyError 通用错误事件，它会捕获所有通过 next() 传递的错误。特定错误类型的事件会先触发，然后是通用事件：

server.on('InternalServerError', (req, res, err, cb) => {
  // 特定错误处理
  err.handled = true;
  return cb();
});

server.on('restifyError', (req, res, err, cb) => {
  // 通用错误处理
  if (!err.handled) {
    // 记录未处理的错误
  }
  return cb();
});

2. 重定向事件

新增了 redirect 事件，当调用 res.redirect() 时会触发：

server.on('redirect', (newLocation) => {
  console.log(`重定向到: ${newLocation}`);
});

3. 标准化错误事件

以下错误事件的处理方式已标准化，与其他错误事件保持一致：

• NotFound
• MethodNotAllowed
• VersionNotAllowed
• UnsupportedMediaType

现在可以通过设置错误对象的 body 属性来自定义响应：

server.on('NotFound', (req, res, err, cb) => {
  err.body = "找不到请求的资源";
  return cb();
});

其他重要变更

1. CORS 支持移除

CORS 功能已从核心库中移除，建议使用专门的 CORS 中间件。

2. 严格路由支持

新增了 strictRouting 选项，可以区分带斜杠和不带斜杠的路由：

const server = restify.createServer({
  strictRouting: true
});

// 这两个路由现在是不同的
server.get('/api', handler1);
server.get('/api/', handler2);

3. 原始内容发送

新增 res.sendRaw() 方法，允许绕过格式化器直接发送预格式化的内容：

// 直接发送预压缩的内容
res.sendRaw(200, preGzippedData, {
  'Content-Encoding': 'gzip'
});

4. 错误对象序列化

不再对 Error 对象进行特殊 JSON 序列化。建议使用 restify-errors 或为自定义错误实现 toJSON 方法：

class CustomError extends Error {
  toJSON() {
    return {
      code: this.name,
      message: this.message
    };
  }
}

废弃功能

1. 域(Domains)支持

由于 Node.js 已弃用 domains，5.x 默认关闭了 domains 支持。如需启用：

const server = restify.createServer({
  handleUncaughtExceptions: true
});

2. next.ifError()

此功能依赖于 domains，也已废弃。仅在启用 handleUncaughtExceptions 时可用。

迁移建议

1. 逐步迁移：先在开发环境测试所有变更
2. 错误处理：全面检查错误处理逻辑，确保适应新的事件机制
3. 依赖检查：确认所有依赖的插件与 5.x 兼容
4. 性能测试：验证新版本在性能方面的表现

通过遵循本指南，开发者可以顺利将应用从 Restify 4.x 迁移到 5.x，同时利用新版本提供的改进和优化。