1. 为什么选择 routing-controllers 来简化 Express 项目在传统的 Express 项目中我们通常需要手动编写大量的路由定义和中间件处理逻辑。比如一个典型的用户控制器可能会这样写import express from express; const router express.Router(); router.get(/users, (req, res) { res.json(userRepository.findAll()); }); router.get(/users/:id, (req, res) { const id parseInt(req.params.id); res.json(userRepository.findById(id)); }); // 其他路由...这种方式虽然直接但随着项目规模扩大会出现几个明显问题路由定义分散在各个文件中难以统一管理参数解析和验证逻辑重复编写缺乏类型安全容易出错代码组织不够直观routing-controllers 通过装饰器模式解决了这些问题。它允许我们使用类和方法装饰器来定义路由将路由逻辑自然地组织在控制器类中。这种方式与 Spring MVC、ASP.NET Core 等主流框架的设计理念相似提供了更结构化的代码组织方式。2. 快速搭建 routing-controllers 环境2.1 基础依赖安装首先需要安装必要的依赖包npm install express reflect-metadata routing-controllers npm install -D typescript types/expressreflect-metadata 是 TypeScript 装饰器运行时必需的反射库必须确保在项目入口文件的最顶部引入import reflect-metadata;2.2 TypeScript 配置在 tsconfig.json 中启用装饰器支持{ compilerOptions: { emitDecoratorMetadata: true, experimentalDecorators: true, target: ES6, module: commonjs } }这两个配置项缺一不可experimentalDecorators启用装饰器语法emitDecoratorMetadata为装饰器生成类型元数据2.3 可选依赖根据项目需要还可以安装以下增强功能包npm install class-validator class-transformer这些包提供了强大的参数验证和转换能力我们后面会详细介绍。3. 创建第一个控制器3.1 基本控制器结构创建一个用户控制器 UserController.tsimport { Controller, Get, Post, Put, Delete, Param, Body } from routing-controllers; Controller() export class UserController { private users [ { id: 1, name: Alice }, { id: 2, name: Bob } ]; Get(/users) getAll() { return this.users; } Get(/users/:id) getOne(Param(id) id: number) { const user this.users.find(u u.id id); if (!user) throw new Error(User not found); return user; } Post(/users) create(Body() user: any) { this.users.push(user); return user; } Put(/users/:id) update(Param(id) id: number, Body() user: any) { const index this.users.findIndex(u u.id id); if (index -1) throw new Error(User not found); this.users[index] user; return user; } Delete(/users/:id) delete(Param(id) id: number) { this.users this.users.filter(u u.id ! id); return { message: User deleted }; } }3.2 启动应用创建应用入口文件 app.tsimport { createExpressServer } from routing-controllers; import { UserController } from ./UserController; const app createExpressServer({ controllers: [UserController] }); app.listen(3000, () { console.log(Server running on port 3000); });现在你已经拥有了一个完整的 REST API支持对用户资源的 CRUD 操作。4. 高级功能详解4.1 参数绑定与验证routing-controllers 提供了多种参数装饰器来自动解析请求数据import { QueryParam, BodyParam, HeaderParam, CookieParam } from routing-controllers; Get(/search) search( QueryParam(keyword) keyword: string, QueryParam(page, { required: false }) page: number 1, HeaderParam(authorization) token: string, CookieParam(sessionId) sessionId: string ) { // 使用参数进行查询 }结合 class-validator 可以实现强大的参数验证import { IsString, IsInt, Min, Max } from class-validator; class SearchQuery { IsString() keyword: string; IsInt() Min(1) Max(100) page: number 1; } Get(/search) search(QueryParams() query: SearchQuery) { // query 已经过验证 }4.2 响应处理routing-controllers 提供了多种装饰器来控制响应行为import { HttpCode, Header, ContentType } from routing-controllers; Post(/users) HttpCode(201) // 设置状态码 Header(Cache-Control, no-store) // 添加响应头 ContentType(application/json) // 设置Content-Type createUser(Body() user: User) { return userService.create(user); }4.3 异常处理可以自定义错误类和错误处理import { HttpError } from routing-controllers; class UserNotFoundError extends HttpError { constructor() { super(404, User not found); } } Get(/users/:id) getUser(Param(id) id: number) { const user userService.findById(id); if (!user) throw new UserNotFoundError(); return user; }4.4 文件上传使用UploadedFile和UploadedFiles处理文件上传import { Post, UploadedFile, UploadedFiles } from routing-controllers; Post(/upload) uploadFile(UploadedFile(file) file: any) { // 处理单个文件 } Post(/uploads) uploadFiles(UploadedFiles(files) files: any[]) { // 处理多个文件 }需要先配置 multer 选项const uploadOptions { storage: multer.diskStorage({ destination: (req, file, cb) { cb(null, uploads/); }, filename: (req, file, cb) { cb(null, Date.now() - file.originalname); } }), limits: { fileSize: 1024 * 1024 * 5 // 5MB } }; Post(/upload) uploadFile( UploadedFile(file, { options: uploadOptions }) file: any ) { // ... }5. 项目组织最佳实践5.1 目录结构建议一个良好的项目结构可以提高代码可维护性src/ ├── controllers/ # 控制器 │ ├── UserController.ts │ ├── ProductController.ts │ └── ... ├── middlewares/ # 中间件 │ ├── AuthMiddleware.ts │ └── ... ├── services/ # 业务逻辑 │ ├── UserService.ts │ └── ... ├── entities/ # 数据实体 │ ├── User.ts │ └── ... ├── dtos/ # 数据传输对象 │ ├── CreateUser.dto.ts │ └── ... └── app.ts # 应用入口5.2 自动加载控制器可以使用 glob 模式自动加载控制器createExpressServer({ controllers: [__dirname /controllers/*.ts] }).listen(3000);5.3 全局路由前缀为所有路由添加统一前缀createExpressServer({ routePrefix: /api, controllers: [UserController] }).listen(3000);5.4 控制器级路由前缀在控制器装饰器中指定前缀Controller(/users) export class UserController { Get(/) // 实际路径: /users getAll() { /* ... */ } Get(/:id) // 实际路径: /users/:id getOne() { /* ... */ } }6. 常见问题与解决方案6.1 装饰器不生效如果装饰器没有生效检查以下问题确保 tsconfig.json 中启用了装饰器支持确保在入口文件最顶部引入了reflect-metadata确保没有错误的装饰器语法6.2 参数解析失败参数解析常见问题类型声明错误确保装饰器参数类型与实际类型匹配验证失败检查 class-validator 的验证规则必填参数缺失使用{ required: true }选项标记必填参数6.3 性能优化建议对于大型项目考虑按功能模块拆分控制器使用JsonController替代Controller可以减少手动 JSON 转换合理使用全局中间件处理通用逻辑如日志、鉴权7. 实际项目中的经验分享在实际项目中使用 routing-controllers 几年后我总结了一些有价值的经验保持控制器精简控制器应该只负责路由和参数处理业务逻辑应该放在 Service 层充分利用依赖注入结合 typedi 等 DI 容器可以更好地管理依赖关系import { Container } from typedi; import { UserService } from ../services/UserService; Controller() export class UserController { constructor(private userService: UserService) { this.userService Container.get(UserService); } }统一错误处理创建自定义错误中间件统一处理业务异常Middleware({ type: after }) export class ErrorHandlerMiddleware implements ExpressErrorMiddlewareInterface { error(error: any, req: any, res: any, next: (err?: any) any) { if (error instanceof BusinessError) { res.status(400).json({ error: error.message }); } else { next(error); } } }接口文档生成结合 tsoa 或 swagger-express-ts 可以自动生成 API 文档测试策略控制器测试应该关注路由和参数绑定业务逻辑测试放在 Service 层import supertest from supertest; import { createExpressServer } from routing-controllers; describe(UserController, () { let app: Express; beforeAll(() { app createExpressServer({ controllers: [UserController] }); }); it(GET /users should return 200, async () { const response await supertest(app).get(/users); expect(response.status).toBe(200); }); });routing-controllers 为 Express 项目提供了一种更结构化、更类型安全的开发方式。通过合理利用其各种特性可以显著提高开发效率和代码质量。虽然有一定的学习曲线但一旦掌握你会发现它能让你的 Express 项目更加易于维护和扩展。
1. 为什么选择 routing-controllers 来简化 Express 项目在传统的 Express 项目中我们通常需要手动编写大量的路由定义和中间件处理逻辑。比如一个典型的用户控制器可能会这样写import express from express; const router express.Router(); router.get(/users, (req, res) { res.json(userRepository.findAll()); }); router.get(/users/:id, (req, res) { const id parseInt(req.params.id); res.json(userRepository.findById(id)); }); // 其他路由...这种方式虽然直接但随着项目规模扩大会出现几个明显问题路由定义分散在各个文件中难以统一管理参数解析和验证逻辑重复编写缺乏类型安全容易出错代码组织不够直观routing-controllers 通过装饰器模式解决了这些问题。它允许我们使用类和方法装饰器来定义路由将路由逻辑自然地组织在控制器类中。这种方式与 Spring MVC、ASP.NET Core 等主流框架的设计理念相似提供了更结构化的代码组织方式。2. 快速搭建 routing-controllers 环境2.1 基础依赖安装首先需要安装必要的依赖包npm install express reflect-metadata routing-controllers npm install -D typescript types/expressreflect-metadata 是 TypeScript 装饰器运行时必需的反射库必须确保在项目入口文件的最顶部引入import reflect-metadata;2.2 TypeScript 配置在 tsconfig.json 中启用装饰器支持{ compilerOptions: { emitDecoratorMetadata: true, experimentalDecorators: true, target: ES6, module: commonjs } }这两个配置项缺一不可experimentalDecorators启用装饰器语法emitDecoratorMetadata为装饰器生成类型元数据2.3 可选依赖根据项目需要还可以安装以下增强功能包npm install class-validator class-transformer这些包提供了强大的参数验证和转换能力我们后面会详细介绍。3. 创建第一个控制器3.1 基本控制器结构创建一个用户控制器 UserController.tsimport { Controller, Get, Post, Put, Delete, Param, Body } from routing-controllers; Controller() export class UserController { private users [ { id: 1, name: Alice }, { id: 2, name: Bob } ]; Get(/users) getAll() { return this.users; } Get(/users/:id) getOne(Param(id) id: number) { const user this.users.find(u u.id id); if (!user) throw new Error(User not found); return user; } Post(/users) create(Body() user: any) { this.users.push(user); return user; } Put(/users/:id) update(Param(id) id: number, Body() user: any) { const index this.users.findIndex(u u.id id); if (index -1) throw new Error(User not found); this.users[index] user; return user; } Delete(/users/:id) delete(Param(id) id: number) { this.users this.users.filter(u u.id ! id); return { message: User deleted }; } }3.2 启动应用创建应用入口文件 app.tsimport { createExpressServer } from routing-controllers; import { UserController } from ./UserController; const app createExpressServer({ controllers: [UserController] }); app.listen(3000, () { console.log(Server running on port 3000); });现在你已经拥有了一个完整的 REST API支持对用户资源的 CRUD 操作。4. 高级功能详解4.1 参数绑定与验证routing-controllers 提供了多种参数装饰器来自动解析请求数据import { QueryParam, BodyParam, HeaderParam, CookieParam } from routing-controllers; Get(/search) search( QueryParam(keyword) keyword: string, QueryParam(page, { required: false }) page: number 1, HeaderParam(authorization) token: string, CookieParam(sessionId) sessionId: string ) { // 使用参数进行查询 }结合 class-validator 可以实现强大的参数验证import { IsString, IsInt, Min, Max } from class-validator; class SearchQuery { IsString() keyword: string; IsInt() Min(1) Max(100) page: number 1; } Get(/search) search(QueryParams() query: SearchQuery) { // query 已经过验证 }4.2 响应处理routing-controllers 提供了多种装饰器来控制响应行为import { HttpCode, Header, ContentType } from routing-controllers; Post(/users) HttpCode(201) // 设置状态码 Header(Cache-Control, no-store) // 添加响应头 ContentType(application/json) // 设置Content-Type createUser(Body() user: User) { return userService.create(user); }4.3 异常处理可以自定义错误类和错误处理import { HttpError } from routing-controllers; class UserNotFoundError extends HttpError { constructor() { super(404, User not found); } } Get(/users/:id) getUser(Param(id) id: number) { const user userService.findById(id); if (!user) throw new UserNotFoundError(); return user; }4.4 文件上传使用UploadedFile和UploadedFiles处理文件上传import { Post, UploadedFile, UploadedFiles } from routing-controllers; Post(/upload) uploadFile(UploadedFile(file) file: any) { // 处理单个文件 } Post(/uploads) uploadFiles(UploadedFiles(files) files: any[]) { // 处理多个文件 }需要先配置 multer 选项const uploadOptions { storage: multer.diskStorage({ destination: (req, file, cb) { cb(null, uploads/); }, filename: (req, file, cb) { cb(null, Date.now() - file.originalname); } }), limits: { fileSize: 1024 * 1024 * 5 // 5MB } }; Post(/upload) uploadFile( UploadedFile(file, { options: uploadOptions }) file: any ) { // ... }5. 项目组织最佳实践5.1 目录结构建议一个良好的项目结构可以提高代码可维护性src/ ├── controllers/ # 控制器 │ ├── UserController.ts │ ├── ProductController.ts │ └── ... ├── middlewares/ # 中间件 │ ├── AuthMiddleware.ts │ └── ... ├── services/ # 业务逻辑 │ ├── UserService.ts │ └── ... ├── entities/ # 数据实体 │ ├── User.ts │ └── ... ├── dtos/ # 数据传输对象 │ ├── CreateUser.dto.ts │ └── ... └── app.ts # 应用入口5.2 自动加载控制器可以使用 glob 模式自动加载控制器createExpressServer({ controllers: [__dirname /controllers/*.ts] }).listen(3000);5.3 全局路由前缀为所有路由添加统一前缀createExpressServer({ routePrefix: /api, controllers: [UserController] }).listen(3000);5.4 控制器级路由前缀在控制器装饰器中指定前缀Controller(/users) export class UserController { Get(/) // 实际路径: /users getAll() { /* ... */ } Get(/:id) // 实际路径: /users/:id getOne() { /* ... */ } }6. 常见问题与解决方案6.1 装饰器不生效如果装饰器没有生效检查以下问题确保 tsconfig.json 中启用了装饰器支持确保在入口文件最顶部引入了reflect-metadata确保没有错误的装饰器语法6.2 参数解析失败参数解析常见问题类型声明错误确保装饰器参数类型与实际类型匹配验证失败检查 class-validator 的验证规则必填参数缺失使用{ required: true }选项标记必填参数6.3 性能优化建议对于大型项目考虑按功能模块拆分控制器使用JsonController替代Controller可以减少手动 JSON 转换合理使用全局中间件处理通用逻辑如日志、鉴权7. 实际项目中的经验分享在实际项目中使用 routing-controllers 几年后我总结了一些有价值的经验保持控制器精简控制器应该只负责路由和参数处理业务逻辑应该放在 Service 层充分利用依赖注入结合 typedi 等 DI 容器可以更好地管理依赖关系import { Container } from typedi; import { UserService } from ../services/UserService; Controller() export class UserController { constructor(private userService: UserService) { this.userService Container.get(UserService); } }统一错误处理创建自定义错误中间件统一处理业务异常Middleware({ type: after }) export class ErrorHandlerMiddleware implements ExpressErrorMiddlewareInterface { error(error: any, req: any, res: any, next: (err?: any) any) { if (error instanceof BusinessError) { res.status(400).json({ error: error.message }); } else { next(error); } } }接口文档生成结合 tsoa 或 swagger-express-ts 可以自动生成 API 文档测试策略控制器测试应该关注路由和参数绑定业务逻辑测试放在 Service 层import supertest from supertest; import { createExpressServer } from routing-controllers; describe(UserController, () { let app: Express; beforeAll(() { app createExpressServer({ controllers: [UserController] }); }); it(GET /users should return 200, async () { const response await supertest(app).get(/users); expect(response.status).toBe(200); }); });routing-controllers 为 Express 项目提供了一种更结构化、更类型安全的开发方式。通过合理利用其各种特性可以显著提高开发效率和代码质量。虽然有一定的学习曲线但一旦掌握你会发现它能让你的 Express 项目更加易于维护和扩展。
