路由与控制器

# 路由与控制器 - 最佳实践 关于整洁路由定义和控制器模式的完整指南。 ## 目录 - [路由：仅负责路由](#routes-routing-only) - [BaseController 模式](#basecontroller-pattern) - [良好示例](#good-examples) - [反模式](#anti-patterns) - [重构指南](#refactoring-guide) - [错误处理](#error-handling) - [HTTP 状态码](#http-status-codes) --- ## 路由：仅负责路由 ### 黄金法则 **路由应该仅做以下事情：** - ✅ 定义路由路径 - ✅ 注册中间件 - ✅ 委托给控制器 **路由绝不应该：** - ❌ 包含业务逻辑 - ❌ 直接访问数据库 - ❌ 实现验证逻辑（使用 Zod + 控制器） - ❌ 格式化复杂响应 - ❌ 处理复杂的错误场景 ### 整洁的路由模式 typescript // routes/userRoutes.ts import { Router } from 'express'; import { UserController } from '../controllers/UserController'; import { SSOMiddlewareClient } from '../middleware/SSOMiddleware'; import { auditMiddleware } from '../middleware/auditMiddleware'; const router = Router(); const controller = new UserController(); // ✅ 整洁：仅定义路由 router.get('/:id', SSOMiddlewareClient.verifyLoginStatus, auditMiddleware, async (req, res) => controller.getUser(req, res) ); router.post('/', SSOMiddlewareClient.verifyLoginStatus, auditMiddleware, async (req, res) => controller.createUser(req, res) ); router.put('/:id', SSOMiddlewareClient.verifyLoginStatus, auditMiddleware, async (req, res) => controller.updateUser(req, res) ); export default router; **关键点：** - 每个路由：方法、路径、中间件链、控制器委托 - 无需 try-catch（由控制器处理错误） - 整洁、可读、易于维护 - 一目了然地查看所有端点 --- ## BaseController 模式 ### 为什么使用 BaseController？ **优势：** - 所有控制器中一致的错误处理 - 自动集成 Sentry - 标准化的响应格式 - 可重用的辅助方法 - 性能跟踪工具 - 日志记录和面包屑辅助工具 ### BaseController 模式（模板） **文件：** `/email/src/controllers/BaseController.ts` typescript import * as Sentry from '@sentry/node'; import { Response } from 'express'; export abstract class BaseController { /** * 使用 Sentry 集成处理错误 */ protected handleError( error: unknown, res: Response, context: string, stat