TSExpress：类型安全的Express风格Web框架，实现路由契约与强类型推导

一个TypeScript优先的Express风格Web框架，提供路由契约、中间件支持和强大的类型推导能力，为Node.js开发带来完整的类型安全体验。

在Node.js生态中，Express长期占据主导地位，但其对TypeScript的支持始终是开发者心中的痛点。虽然可以通过类型定义文件获得基本的类型提示，但路由参数、中间件上下文、响应格式等关键环节仍然缺乏严格的类型约束，导致许多错误只能在运行时发现。

TSExpress 项目正是为了解决这一问题而生。它从头开始构建了一个Express风格的Web框架，将TypeScript的类型系统作为一等公民，实现了路由契约、中间件链和响应格式的完整类型推导。

TSExpress的设计哲学可以概括为"类型即契约"。这意味着：

1. 路由定义即接口文档：通过类型定义自动推导出API的输入输出规范
2. 编译时错误检测：参数类型不匹配、缺失必填字段等问题在编译阶段暴露
3. IDE智能提示：完整的自动补全和类型提示，提升开发效率
4. 重构安全保障：修改类型定义后，所有相关代码的兼容性问题会立即显现

TSExpress引入了"路由契约"的概念，允许开发者在定义路由时同时声明其类型规范：

// 定义请求和响应的类型契约
interface CreateUserRequest {
  body: {
    name: string;
    email: string;
    age?: number;
  };
  params: {};
  query: {};
}

interface CreateUserResponse {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}

// 路由定义与类型契约绑定
app.post<CreateUserRequest, CreateUserResponse>(
  '/users',
  (req, res) => {
    // req.body 自动推导为 { name: string; email: string; age?: number }
    // res.json() 要求传入 CreateUserResponse 类型的数据
    const user = createUser(req.body);
    res.json(user);
  }
);

这种方式的好处显而易见：

• 请求数据安全：req.body、req.params、req.query都有精确类型
• 响应格式约束：确保返回的数据结构符合预期
• 自动文档生成：类型定义可直接用于生成OpenAPI/Swagger文档

中间件是Express架构的核心，TSExpress对其进行了完善的类型支持：

// 自定义中间件可以精确声明其对请求对象的扩展
interface AuthMiddleware extends Middleware {
  req: {
    user: {
      id: string;
      role: 'admin' | 'user';
    };
  };
}

const authMiddleware: AuthMiddleware = (req, res, next) => {
  // 验证token并附加用户信息
  req.user = verifyToken(req.headers.authorization);
  next();
};

// 使用中间件后的路由自动获得类型扩展
app.get('/admin', authMiddleware, (req, res) => {
  // req.user 自动可用，类型为 { id: string; role: 'admin' | 'user' }
  if (req.user.role !== 'admin') {
    return res.status(403).json({ error: 'Forbidden' });
  }
  // ...
});

这种设计解决了传统Express中中间件修改请求对象后类型丢失的问题。

URL路径参数的类型安全是Web框架的关键：

// 路径参数自动推导
app.get('/users/:userId/posts/:postId', (req, res) => {
  // req.params 类型为 { userId: string; postId: string }
  const { userId, postId } = req.params;
  // TypeScript 会确保你不能访问不存在的参数
  // req.params.nonExistent // 编译错误
});

// 支持自定义参数转换器
app.get('/items/:id(number)', (req, res) => {
  // req.params.id 类型为 number，自动完成字符串到数字的转换
});

统一的错误处理是生产级应用的必备能力：

// 定义错误响应结构
interface ApiError {
  code: string;
  message: string;
  details?: Record<string, unknown>;
}

// 错误处理中间件拥有完整类型
app.use((err: ApiError, req, res, next) => {
  res.status(500).json({
    error: err.code,
    message: err.message
  });
});

TSExpress在设计时充分考虑了与Express生态的兼容性：