ts-rest 项目中路由中间件与错误处理机制解析

前言

在基于 Express 框架的 Node.js 开发中，中间件机制是核心功能之一。ts-rest 作为一个类型安全的 API 契约库，为 Express 应用提供了优雅的路由定义方式。本文将深入探讨 ts-rest 中的中间件工作机制，特别是关于路由后置处理和错误处理的最佳实践。

ts-rest 的前置中间件机制

ts-rest 允许开发者为特定路由定义前置中间件，这些中间件会在路由处理器执行前被调用。这种机制非常适合用于以下场景：

1. 请求日志记录
2. 身份验证检查
3. 请求参数预处理
4. 权限验证

示例代码展示了如何为 getPost 路由添加前置中间件：

const router = s.router(contract, {
  getPost: {
    middleware: [
      (req, res, next) => {
        console.log('Called: ', req.tsRestRoute.method, req.tsRestRoute.path);
        next();
      }
    ],
    handler: async ({ params: { id } }) => {
      // 路由处理逻辑
    }
  },
});

关于后置中间件的技术考量

在 Express 生态中，严格意义上的"后置中间件"概念并不存在，因为一旦响应被发送，后续的中间件就无法修改响应内容。但这并不意味着我们不能实现类似后置处理的功能。

实现后置处理的替代方案

1. 响应结束事件监听：通过监听 res 对象的 'finish' 事件来实现后置逻辑

(req, res, next) => {
  res.on('finish', () => {
    // 响应结束后执行的逻辑
    console.log('请求处理完成');
  });
  next();
}

2. 路由处理器内部后处理：在路由处理器最后添加处理逻辑

handler: async ({ params: { id } }) => {
  const result = await someAsyncOperation();
  
  // 后处理逻辑
  logOperationComplete();
  
  return result;
}

ts-rest 的错误处理机制

ts-rest 内置了错误处理机制，会自动捕获路由处理器中抛出的异常并将其传递给 Express 的错误处理中间件。

自定义错误处理

虽然 ts-rest 不直接提供错误处理中间件配置，但可以通过 Express 的标准机制来实现：

1. 全局错误处理中间件

app.use((err, req, res, next) => {
  // 自定义错误响应
  res.status(500).json({
    error: err.message,
    timestamp: new Date().toISOString()
  });
});

2. 请求验证错误处理

ts-rest 会自动验证请求是否符合契约定义，验证失败时会抛出特定错误，可以通过以下方式自定义响应：

const { requestValidationErrorHandler } = require('@ts-rest/express');

app.use(requestValidationErrorHandler({
  body: (err) => ({ message: '请求体验证失败', details: err }),
  params: (err) => ({ message: '参数验证失败', details: err }),
  query: (err) => ({ message: '查询参数验证失败', details: err }),
  headers: (err) => ({ message: '请求头验证失败', details: err }),
}));

最佳实践建议

1. 日志记录：建议在前置中间件中记录请求开始，在响应结束事件中记录请求完成
2. 错误分类处理：根据错误类型返回不同的状态码和错误格式
3. 性能监控：可以在前置中间件记录开始时间，在响应结束时计算处理耗时
4. 资源清理：利用响应结束事件进行资源释放等清理工作

总结

ts-rest 提供了灵活的前置中间件机制，结合 Express 原生功能可以实现完整的请求生命周期管理。虽然不直接支持后置中间件概念，但通过事件监听和合理的架构设计，开发者仍然可以实现各种后处理需求。错误处理方面，ts-rest 与 Express 的错误处理机制无缝集成，开发者可以充分利用这一特性构建健壮的 API 服务。