深入理解Restify框架：从快速入门到高级路由

2026-02-04 04:28:34作者：咎竹峻Karen

什么是Restify？

Restify是一个专注于构建严格REST API服务的Node.js框架。与Express等通用Web框架不同，Restify专为API开发优化，提供了更精细的路由控制、版本管理和错误处理机制。它特别适合需要遵循REST规范的企业级API开发。

快速搭建Restify服务器

让我们从一个简单的"Hello World"示例开始：

const restify = require('restify');

// 创建响应处理函数
function respond(req, res, next) {
  res.send(`hello ${req.params.name}`);
  next();
}

// 创建服务器实例
const server = restify.createServer();

// 定义路由
server.get('/hello/:name', respond);
server.head('/hello/:name', respond);

// 启动服务器
server.listen(8080, () => {
  console.log(`${server.name} listening at ${server.url}`);
});

这个简单的API实现了：

GET /hello/:name 返回问候语
HEAD /hello/:name 返回相同内容的头部信息

理解Restify的请求处理流程

Restify采用Sinatra风格的路由处理机制，支持三种处理链：

pre中间件：在路由匹配前执行
路由处理器：匹配特定路由后执行
use中间件：在路由匹配后执行

pre中间件的典型应用

// 在路由前去除URL中的重复斜杠
server.pre(restify.plugins.pre.dedupeSlashes());

通用中间件的使用

server.use((req, res, next) => {
  console.log('这个中间件会处理所有路由请求');
  next();
});

深入路由系统

基本路由定义

Restify支持常见的HTTP方法：

server.get('/resource', getHandler);
server.post('/resource', postHandler);
server.put('/resource', putHandler);
server.del('/resource', deleteHandler);

路由参数处理

server.get('/user/:id', (req, res, next) => {
  const userId = req.params.id; // 获取路由参数
  // 处理逻辑...
  next();
});

正则表达式路由

server.get(/^\/user\/(\d+)/, (req, res, next) => {
  const userId = req.params[0]; // 获取正则匹配结果
  // 处理逻辑...
  next();
});

高级路由特性

超媒体链接

Restify支持动态生成资源链接：

server.get({name: 'user', path: '/users/:id'}, userHandler);

// 在其他路由中生成链接
res.send({
  profile: server.router.render('user', {id: 123})
});

API版本管理

Restify内置了基于语义化版本的API版本控制：

const versionedHandlers = [
  {version: '1.0.0', handler: v1Handler},
  {version: '2.0.0', handler: v2Handler}
];

server.get('/resource', restify.plugins.conditionalHandler(versionedHandlers));

客户端可以通过Accept-Version头指定需要的API版本。

错误处理最佳实践

Restify提供了强大的错误处理机制：

const errs = require('restify-errors');

// 抛出特定错误
server.get('/protected', (req, res, next) => {
  if (!req.headers.authorization) {
    return next(new errs.UnauthorizedError('需要认证'));
  }
  next();
});

// 全局错误处理
server.on('Unauthorized', (req, res, err, callback) => {
  // 记录错误日志
  console.error(err);
  // 必须调用callback
  callback();
});

内容协商与响应格式化

Restify自动处理内容协商，支持多种响应格式：

// 自定义响应格式
server.get('/data', (req, res, next) => {
  res.send({key: 'value'}); // 自动转为JSON
  next();
});

// 添加自定义格式化器
server = restify.createServer({
  formatters: {
    'application/custom': (req, res, body) => {
      return customSerialize(body);
    }
  }
});

升级请求处理

Restify支持WebSocket等协议升级：

server.get('/websocket', (req, res, next) => {
  if (!res.claimUpgrade) {
    return next(new Error('连接需要升级'));
  }
  
  const upgrade = res.claimUpgrade();
  // 处理WebSocket逻辑...
  next(false);
});