Nestia项目中TypedException装饰器处理对象联合类型的缺陷分析

问题背景

在Nestia项目(一个用于NestJS框架的Swagger文档生成工具)中，开发者发现当使用@TypedException装饰器处理对象联合类型时，Swagger文档无法正确生成异常描述信息。这个问题特别出现在需要为同一HTTP状态码定义多种不同错误消息的场景下。

问题复现

开发者尝试了两种典型的使用方式：

第一种方式是直接使用对象联合类型：

interface A {
  code: 1;
  message: 'hi';
}
interface B {
  code: 2;
  message: 'hello';
}

@TypedException<A | B>(200)
async func() {
  // ...
}

第二种方式是通过命名空间组织错误类型：

namespace ERROR_MESSAGE {
  export interface USER_NOT_FOUND {
    code: 404;
    message: "Can not find user";
  }

  export interface USER_INFO_NOT_FOUND {
    code: 404;
    message: "No User info";
  }
}

@TypedException<ERROR_MESSAGE.USER_NOT_FOUND | ERROR_MESSAGE.USER_INFO_NOT_FOUND>(404)
@Get('user-info')
async getUserInfo() {
  return userInfo;
}

这两种方式都无法在生成的Swagger文档中正确显示异常信息。

技术分析

根本原因

问题主要出现在ExceptionAnalyzer模块的"DO ASSIGN"处理过程中：

1. 类型名称匹配问题：当异常模式是联合类型且每个子类型都是使用层级类型名称的对象类型时，类型名称的表示方式可能存在差异。例如，ErrorCode.NotFound在元组中会被完整表示，而在func.exceptions中可能只显示NotFound，导致匹配失败。

2. 泛型处理问题：当异常模式是泛型形式时，类型名称没有正确分割。当前实现只是简单地基于" | "分隔符对整个字符串进行分割和排序。如果遇到类似Gen<101 | 202>的类型，会被错误地分割为"Gen<101"和"202>"，导致类型名称比较失败。

3. 命名空间类型处理：当使用命名空间组织的类型时，类型引用路径处理不当，导致类型识别失败。

预期行为

开发者期望能够：

1. 为同一状态码定义多种不同的错误响应结构
2. 在Swagger文档中使用"oneOf"结构展示这些可能的错误响应
3. 通过命名空间组织相关的错误类型，保持代码整洁性

解决方案

根据仓库所有者的回复，此问题已被标记为bug并承诺尽快修复。修复方向可能包括：

1. 改进类型名称的解析逻辑，正确处理命名空间路径
2. 增强联合类型的处理能力，确保能识别所有子类型
3. 完善泛型类型的解析，避免错误分割
4. 在Swagger文档生成时，为同一状态码的多种错误响应使用"oneOf"结构

最佳实践建议

在问题修复前，开发者可以考虑以下临时解决方案：

1. 使用单一错误类型，通过额外字段区分不同错误场景
2. 将不同错误类型提升到全局命名空间，避免命名空间引用
3. 暂时使用@ApiResponse等原生装饰器手动定义错误响应

总结

这个问题揭示了Nestia在处理复杂类型系统时的局限性，特别是当涉及命名空间、联合类型和泛型等高级TypeScript特性时。对于需要精细控制API错误响应的项目，理解这些限制并寻找合适的变通方案非常重要。随着项目的持续维护，这类类型系统处理问题有望得到根本性解决。