企业官网建设流程全解析

• 后端
• 前端
• 金融科技
• 数据可视化

导读

本文围绕 Ghostfolio 仓库内.agents/skills/nestjs-best-practices/rules/error-use-exception-filters.md这条高阶错误处理规则展开，系统讲解如何在 NestJS 应用中用 Exception Filters（异常过滤器）取代控制器里的手写 try/catch 响应，实现全应用一致的错误处理。文章先讲清"为什么不该在控制器里手动拼 JSON"，再给出内置异常、自定义领域异常、局部过滤器、全局过滤器的完整写法，最后以 Ghostfolio 真实代码（组合快照计算过滤器、MCP 工具过滤器、CallerFacingError 体系）印证这套模式在生产项目中的落地方式。读完你将掌握一套可直接复制的异常处理骨架，并理解 Ghostfolio 如何在 REST 与 MCP 两条链路上分别收敛错误。

一、反模式：控制器里手写错误响应

许多 NestJS 项目最初会把错误处理写成"在每个控制器里捕获、再手动构造 JSON"。下面这种写法虽然能工作，却是规则明确反对的典型反模式：

// Manual error handling in controllers @Controller('users') export class UsersController { @Get(':id') async findOne(@Param('id') id: string, @Res() res: Response) { try { const user = await this.usersService.findById(id); if (!user) { return res.status(404).json({ statusCode: 404, message: 'User not found', }); } return res.json(user); } catch (error) { console.error(error); return res.status(500).json({ statusCode: 500, message: 'Internal server error', }); } } }

它的弊端显而易见：

• 响应格式不统一：每个控制器各写各的{ statusCode, message }，字段名、错误码、时间戳都可能不一致；
• 控制器职责膨胀：业务逻辑里混入 HTTP 状态码决策与响应序列化，控制器无法保持"薄"；
• 重复代码爆炸：404/500 的处理逻辑在几十个控制器里复制粘贴，改一处格式就要全局搜索替换；
• 遗漏风险：并非所有路径都被 try/catch 覆盖，异步错误、管道校验错误、守卫抛出的错误都可能绕过手工处理，直接落到框架默认行为上。

规则给出的结论是：永远不要在控制器中 catch 异常并手工格式化错误响应，而应使用 NestJS 的 Exception Filters 统一处理。

二、正确做法：抛异常，让过滤器接管

NestJS 本身自带异常层：只要抛出HttpException（或其子类），框架默认就会把它转换为 JSON 响应。因此控制器只需要"抛"，不需要"接"：

// Use built-in and custom exceptions @Controller('users') export class UsersController { @Get(':id') async findOne(@Param('id') id: string): Promise<User> { const user = await this.usersService.findById(id); if (!user) { throw new NotFoundException(`User #${id} not found`); } return user; } }

与之配套的规则.agents/skills/nestjs-best-practices/rules/error-throw-http-exceptions.md进一步强调：在 HTTP 应用中，服务层直接抛HttpException子类是被允许且更优的——它让控制器保持薄、让服务层直接表达错误状态；而对于需要跨层复用的服务，则应定义领域异常（domain exception），再在过滤器里映射到 HTTP 状态码。这正是"抛异常 + 过滤器映射"两条腿走路的核心思想。

自定义领域异常：给错误附上业务语义

内置的NotFoundException只能表达"没找到"，但业务上往往需要携带错误码（code）、上下文等结构化信息。为此可以派生领域异常：

// Custom domain exception export class UserNotFoundException extends NotFoundException { constructor(userId: string) { super({ statusCode: 404, error: 'Not Found', message: `User with ID "${userId}" not found`, code: 'USER_NOT_FOUND', }); } }

这样调用方只需要throw new UserNotFoundException(id)，状态码、错误码、人类可读信息都在一处定义，语义集中、可复用、可测试。

三、自定义 Exception Filter：接管领域异常的序列化

@Catch(DomainException)可以把特定异常类型从框架默认行为中接管过来，让你完全控制响应体结构（加入timestamp、path等字段）：

// Custom exception filter for domain errors @Catch(DomainException) export class DomainExceptionFilter implements ExceptionFilter { catch(exception: DomainException, host: ArgumentsHost) { const ctx = host.switchToHttp(); const response = ctx.getResponse<Response>(); const request = ctx.getRequest<Request>(); const status = exception.getStatus?.() || 400; response.status(status).json({ statusCode: status, code: exception.code, message: exception.message, timestamp: new Date().toISOString(), path: request.url, }); } }

要点：

• 过滤器必须实现ExceptionFilter接口，即catch(exception, host)方法；
• 通过host.switchToHttp()拿到 Express 的Request/Response，从而写入状态码、响应体，并读取当前请求路径；
• 响应体中同时携带timestamp与path，便于调用方与日志侧对齐排查；业务错误码code让客户端可以做程序化处理，而不是解析人类语言消息。

四、全局过滤器：兜底一切未处理异常

仅有针对领域异常的过滤器还不够——未预期的Error、数据库约束冲突、未知异常仍会穿透。此时需要一个@Catch()的全量兜底过滤器：

// Global exception filter for unhandled errors @Catch() export class AllExceptionsFilter implements ExceptionFilter { constructor(private readonly logger: Logger) {} catch(exception: unknown, host: ArgumentsHost) { const ctx = host.switchToHttp(); const response = ctx.getResponse<Response>(); const request = ctx.getRequest<Request>(); const status = exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR; const message = exception instanceof HttpException ? exception.message : 'Internal server error'; this.logger.error( `${request.method} ${request.url}`, exception instanceof Error ? exception.stack : exception, ); response.status(status).json({ statusCode: status, message, timestamp: new Date().toISOString(), path: request.url, }); } }

这个兜底过滤器做了三件事：

1. 分类：HttpException取其状态码，其他一切异常统一映射为500 Internal Server Error；
2. 记录：把METHOD URL与堆栈写入 Logger，保证线上可观测；
3. 收敛：对外只暴露statusCode / message / timestamp / path，不把堆栈、内部字段名泄露给调用方。

注册方式一：useGlobalFilters（main.ts）

// Register globally in main.ts app.useGlobalFilters( new AllExceptionsFilter(app.get(Logger)), new DomainExceptionFilter(), );

注意：useGlobalFilters在NestFactory.create()之后调用即可生效，适用于在引导阶段一次性挂载所有全局过滤器。

注册方式二：APP_FILTER 依赖注入（模块级）

更符合 NestJS 依赖注入习惯、且能被测试框架感知的是APP_FILTER令牌：

// Or via module @Module({ providers: [ { provide: APP_FILTER, useClass: AllExceptionsFilter, }, ], }) export class AppModule {}

APP_FILTER注册的过滤器会作为全局过滤器挂载，同时仍可注入Logger等依赖，是生产项目中最常用的方式。规则还提醒：对特定控制器/模块只起作用的异常，用@UseFilters(...)在控制器或方法上局部挂载即可，避免全局过滤器过度集中。

五、Ghostfolio 源码印证：过滤器如何落地到生产仓库

Ghostfolio 的apps/api（NestJS）把这条规则落成了两套真实实现，分别覆盖 REST 与 MCP 两条错误链路，是理解"领域异常 + 局部过滤器 + 全局过滤器"组合拳的最佳案例。

5.1 领域异常定义：分层清晰的错误类型

仓库在apps/api/src/errors/caller-facing.error.ts定义了"面向调用方"的基础错误：

/** * An error whose message is written for the caller. A filter passes such a * message on, while it hides the message of every other error, because that * message can carry internals of the application. */ export class CallerFacingError extends Error { public constructor(message: string) { super(message); this.name = 'CallerFacingError'; } }

而 apps/api/src/app/import/errors/import-validation.error.ts 继承它表达导入校验失败；apps/api/src/app/portfolio/errors/portfolio-snapshot-computation.error.ts 则是一个独立的纯领域异常，用于表达"组合快照多次尝试仍无法计算"。

这套命名约定本身就是过滤器策略的一部分：CallerFacingError的消息"写给调用方看"，可以原样透传；而其他异常的消息可能携带 DTO 字段名、数据库约束名等内部信息，必须被隐藏。

5.2 全局过滤器：PortfolioSnapshotComputationExceptionFilter

组合快照计算是 Ghostfolio 的 CPU 密集核心路径，apps/api/src/app/portfolio/calculator/portfolio-calculator.ts 在超过MAX_INITIALIZATION_ATTEMPTS次尝试后抛出PortfolioSnapshotComputationError。针对它，仓库实现了 apps/api/src/filters/portfolio-snapshot-computation-exception.filter.ts：

@Catch(PortfolioSnapshotComputationError) export class PortfolioSnapshotComputationExceptionFilter implements ExceptionFilter { private readonly logger = new Logger( PortfolioSnapshotComputationExceptionFilter.name ); public catch( exception: PortfolioSnapshotComputationError, host: ArgumentsHost ) { this.logger.error(exception.message); const response = host.switchToHttp().getResponse<Response>(); response.status(StatusCodes.SERVICE_UNAVAILABLE).json({ message: getReasonPhrase(StatusCodes.SERVICE_UNAVAILABLE), statusCode: StatusCodes.SERVICE_UNAVAILABLE }); } }

实现要点：

• 用@Catch(PortfolioSnapshotComputationError)精确绑定领域异常，其他异常不受影响；
• 语义映射：计算失败并非 500 而是503 Service Unavailable（上游数据未就绪导致的暂时性失败），并通过http-status-codes的getReasonPhrase生成标准原因短语，而不是暴露内部 message；
• 通过APP_FILTER注册为全局过滤器，见 apps/api/src/app/app.module.ts：

providers: [ I18nService, { provide: APP_FILTER, useClass: PortfolioSnapshotComputationExceptionFilter }, { provide: APP_GUARD, useClass: ImpersonationWriteGuard } ]

5.3 局部过滤器：McpToolExceptionFilter

Ghostfolio 通过@rekog/mcp-nest暴露 Model Context Protocol（MCP）工具端点，控制器 apps/api/src/app/endpoints/mcp/mcp.controller.ts 用@UseFilters(McpToolExceptionFilter)局部挂载过滤器：

@McpController() @UseFilters(McpToolExceptionFilter) export class GhostfolioMcpController { public constructor(private readonly mcpService: McpService) {} }

过滤器本身实现了RpcExceptionFilter（而非 HTTP 的ExceptionFilter），返回Observable<never>，把异常转换成 MCP 协议规定的{ message, status: 'error' }结构，见 apps/api/src/filters/mcp-tool-exception.filter.ts：

@Catch() export class McpToolExceptionFilter implements RpcExceptionFilter { private readonly logger = new Logger(McpToolExceptionFilter.name); public catch(exception: unknown): Observable<never> { // The message of this exception is written for the caller, hence it is // passed on and is not written to the log if (exception instanceof CallerFacingError) { return throwError(() => { return { message: exception.message, status: 'error' }; }); } const statusCode = this.getStatus(exception); // An exception which the caller causes, for example a refused call, is // expected, hence only an exception of the application is written to the // log if (statusCode >= StatusCodes.INTERNAL_SERVER_ERROR) { this.logger.error(exception); } // The message of an exception can carry internals, for example the // property names of a data transfer object of a failed validation, hence // the reason phrase of the status is passed on instead return throwError(() => { return { message: this.getReasonPhraseOfStatus(statusCode), status: 'error' }; }); } private getReasonPhraseOfStatus(statusCode: number) { try { return getReasonPhrase(statusCode); } catch { return getReasonPhrase(StatusCodes.INTERNAL_SERVER_ERROR); } } private getStatus(exception: unknown) { if (exception instanceof PortfolioSnapshotComputationError) { return StatusCodes.SERVICE_UNAVAILABLE; } if (exception instanceof HttpException) { return exception.getStatus(); } return StatusCodes.INTERNAL_SERVER_ERROR; } }

它把前面所有原则浓缩进了一个过滤器：

• 白名单透传：只有CallerFacingError的消息原样返回给调用方（如导入校验的activities.0.symbol ("X") is not valid）；
• 黑名单隐藏：其余异常一律不泄露原始 message，只返回状态码对应的标准原因短语，避免 DTO 字段名、Prisma 约束信息等内部细节外泄；
• 日志分级：只有服务端内部错误（>= 500）才写 error 日志；调用方引起的 4xx（如无权限的 Forbidden）不刷日志，防止日志被垃圾请求灌满；
• 异常分类：PortfolioSnapshotComputationError→ 503，HttpException→ 其自带状态码，未知异常 → 500。

5.4 测试用例：把错误映射固化为契约

规则强调过滤器应有可验证性，apps/api/src/filters/mcp-tool-exception.filter.spec.ts 用 4 个用例把行为钉死：

测试通过firstValueFrom(filter.catch(exception))直接驱动过滤器，无需起 HTTP 服务，验证了"消息白名单、日志分级、状态码映射"三条核心契约；apps/api/src/app/endpoints/mcp/mcp.controller.spec.ts 则通过反射检查EXCEPTION_FILTERS_METADATA，确认过滤器确实挂载在控制器上。

六、实践清单：把规则变成可执行的工程约束

综合规则文档与 Ghostfolio 源码，落地 Exception Filters 时应遵循以下检查清单：

1. 控制器零 try/catch：控制器只负责"取参 → 调服务 → 返回"，任何错误状态用throw表达；需要@Res()手动拼 JSON 的地方一律视为反模式。
2. 优先内置异常：NotFoundException、BadRequestException、ConflictException等能覆盖 90% 场景；需要错误码/上下文时再派生领域异常子类。
3. 领域异常与 HTTP 解耦：纯业务层（如计算、导入）抛自定义Error子类，由@Catch(DomainException)过滤器负责映射状态码与响应体（参考PortfolioSnapshotComputationError→ 503）。
4. 全局兜底 + 局部精确：用APP_FILTER注册一个@Catch()兜底过滤器处理所有未预期异常；对特定链路（如 MCP 工具）用@UseFilters局部挂载专用过滤器，避免污染全局响应格式。
5. 对外隐藏内部信息：异常 message 可能携带 DTO 字段名、数据库约束名、堆栈细节，一律用getReasonPhrase等标准短语替代；面向调用方的消息通过显式标记（如CallerFacingError）白名单透传。
6. 日志分级：服务端内部错误（>= 500）记录完整异常与堆栈；可预期的 4xx 不刷 error 日志，防止日志噪声。
7. 测试固化契约：为每个过滤器编写单元测试，验证状态码映射、消息透传/隐藏、日志行为，让错误响应成为可回归的 API 契约。
8. 继承微服务配置：Ghostfolio 在 apps/api/src/main.ts 中通过connectMicroservice(..., { inheritAppConfig: true })让全局过滤器/管道同样作用于 MCP 微服务，提示我们在接入微服务或协议端点时不要忘记错误处理的一致性继承。

结语

Exception Filters 不是"NestJS 的一个小特性"，而是一套把错误处理从"控制器里的散装代码"提升为"集中式、可测试、可观测的横切关注点"的架构手段。Ghostfolio 仓库给出了一个教科书级的组合：领域异常定义在errors目录、APP_FILTER注册全局兜底、@UseFilters局部挂载协议专用过滤器、spec 测试钉死契约。照着这套骨架迁移你的控制器，就能获得统一的响应格式、更薄的服务边界，以及不会把内部细节泄露给调用方的安全防线。

• 后端
• 前端
• 金融科技
• 数据可视化