Nestia中使用泛型定义异常响应类型的最佳实践

问题背景

在使用Nestia框架开发TypeScript后端服务时，开发者可能会遇到一个关于@TypedException装饰器与泛型类型结合使用的特殊场景。当尝试为不同的错误响应定义多个异常类型时，如果这些异常类型都基于同一个泛型模板ErrorResponseForm<T>，可能会遇到Swagger文档生成不准确的问题。

现象描述

具体表现为：当使用多个@TypedException装饰器，每个装饰器都使用不同的泛型参数（如ErrorResponseForm<typeof ERROR_MESSAGE.AUTH.FORBIDDEN>和ErrorResponseForm<typeof ERROR_MESSAGE.TOKEN.NOT_FOUND_TOKEN>）时，生成的Swagger文档中所有异常响应的示例值会显示为最后一个装饰器定义的错误信息，而不是各自对应的错误信息。

技术分析

这个问题源于TypeScript的装饰器处理和Nestia的类型解析机制。当多个装饰器使用相同的泛型模板但不同参数时，类型系统在编译时可能无法完全保留所有类型信息，导致最终生成的OpenAPI/Swagger规范中丢失了部分类型细节。

解决方案

方法一：使用联合类型

Nestia的创建者建议使用联合类型来定义多个可能的错误响应类型：

@TypedException<ErrorResponseForm<typeof ERROR_MESSAGE.AUTH.FORBIDDEN> | 
               ErrorResponseForm<typeof ERROR_MESSAGE.TOKEN.NOT_FOUND_TOKEN>>(
  403, // 主状态码
  "认证或令牌错误" // 主描述
)

这种方法将所有可能的错误类型合并到一个装饰器中，确保Swagger文档能正确反映所有可能的错误响应结构。

方法二：使用显式类型

如果希望保持每个错误的独立性和清晰性，可以定义显式的非泛型类型：

type ForbiddenError = ErrorResponseForm<typeof ERROR_MESSAGE.AUTH.FORBIDDEN>;
type TokenNotFoundError = ErrorResponseForm<typeof ERROR_MESSAGE.TOKEN.NOT_FOUND_TOKEN>;

@TypedException<ForbiddenError>(ERROR_MESSAGE.AUTH.FORBIDDEN.code, "禁止访问")
@TypedException<TokenNotFoundError>(ERROR_MESSAGE.TOKEN.NOT_FOUND_TOKEN.code, "令牌不存在")

这种方法虽然需要预先定义更多类型，但能确保每个错误都有独立的文档描述。

最佳实践建议

1. 保持一致性：选择一种方式并在整个项目中保持一致，要么全部使用联合类型，要么全部使用显式类型。

2. 文档注释：为每个错误类型添加详细的文档注释，帮助其他开发者理解每种错误的使用场景。

3. 错误代码管理：考虑将错误代码和消息集中管理，如示例中的ERROR_MESSAGE对象，便于维护和国际化。

4. 测试验证：生成Swagger文档后，务必验证文档中的错误示例是否符合预期，确保API消费者能获得准确的信息。

总结

在Nestia框架中处理多个错误响应类型时，理解装饰器与泛型的交互方式至关重要。通过采用联合类型或显式类型定义，开发者可以确保生成的API文档准确反映所有可能的错误情况，为API消费者提供清晰、准确的错误处理指导。