openapi-typescript 中如何为转换类型注入导入语句

在 TypeScript 开发中，使用 openapi-typescript 工具从 OpenAPI 规范生成类型定义时，我们经常需要对某些特殊格式的类型进行自定义转换。一个常见的需求是将 OpenAPI 中的日期时间格式映射到第三方库提供的类型，如使用 luxon 的 DateTime 类型替代原生 Date 类型。

类型转换的基本实现

openapi-typescript 提供了 transform 选项，允许开发者自定义类型转换逻辑。例如，我们可以这样将 date-time 和 date 格式映射到自定义类型：

const DATE_TIME = ts.factory.createTypeReferenceNode(ts.factory.createIdentifier("DateTime"));
const DATE = ts.factory.createTypeReferenceNode(ts.factory.createIdentifier("Date")); 
const NULL = ts.factory.createLiteralTypeNode(ts.factory.createNull());

const output = await openapiTS(localPath, {
    transform(schemaObject, metadata) {
     if (["date-time", "date"].includes(schemaObject.format)) {
        return schemaObject.nullable
          ? ts.factory.createUnionTypeNode([DATE_TIME, NULL])
          : DATE_TIME;
      }
    },
});

这段代码会将 OpenAPI 规范中的 date-time 和 date 格式字段转换为 DateTime 类型，并处理可空(nullable)情况。然而，生成的类型定义文件中缺少必要的导入语句，导致 DateTime 类型无法解析。

解决方案：动态注入导入语句

openapi-typescript 提供了几种方式来解决导入语句的问题：

1. 使用 inject 选项

最简单的方法是使用 inject 选项在生成文件的开头注入静态文本：

const output = await openapiTS(localPath, {
    inject: "import { DateTime } from 'luxon';\n\n",
    // ...其他配置
});

这种方法适用于确定需要导入的情况，但当转换的类型可能不会出现在所有生成的类型定义中时，会导致不必要的导入。

2. 动态检测并注入导入

更优雅的解决方案是在转换过程中跟踪是否使用了特定类型，然后根据使用情况动态添加导入语句：

let hasDateTime = false;

const typesOutput = await openapiTS(localPath, {
    transform(schemaObject) {
        if (["date-time", "date"].includes(schemaObject.format)) {
            hasDateTime = true;
            return ts.factory.createTypeReferenceNode("DateTime");
        }
    },
});

const finalOutput = `${hasDateTime ? "import { DateTime } from 'luxon';\n\n" : ""}${astToString(typesOutput)}`;

fs.writeFileSync("interfaces.d.ts", finalOutput);

这种方法通过 hasDateTime 标志位跟踪是否使用了 DateTime 类型，只有在实际使用时才会添加对应的导入语句，避免了不必要的依赖。

高级应用场景

在实际项目中，我们可能需要处理更复杂的转换场景：

1. 多类型转换：同时处理多种自定义类型转换，如 ObjectId、Decimal 等
2. 多源导入：从不同模块导入多种类型
3. 条件导入：根据环境或配置选择不同的实现类型

对于这些场景，可以扩展上述模式，使用对象或 Map 来跟踪多种类型的引用情况：

const usedTypes = new Set<string>();

const typesOutput = await openapiTS(localPath, {
    transform(schemaObject) {
        if (schemaObject.format === "date-time") {
            usedTypes.add("DateTime");
            return ts.factory.createTypeReferenceNode("DateTime");
        }
        if (schemaObject.format === "decimal") {
            usedTypes.add("Decimal");
            return ts.factory.createTypeReferenceNode("Decimal");
        }
    },
});

const imports = [];
if (usedTypes.has("DateTime")) imports.push("import { DateTime } from 'luxon'");
if (usedTypes.has("Decimal")) imports.push("import { Decimal } from 'decimal.js'");

const finalOutput = `${imports.join("\n")}\n\n${astToString(typesOutput)}`;

最佳实践建议

1. 保持一致性：在整个项目中统一使用相同的类型转换规则
2. 文档化：为自定义转换规则添加文档说明，方便团队协作
3. 测试验证：编写测试确保生成的类型定义符合预期
4. 性能考虑：对于大型 OpenAPI 规范，注意转换逻辑的性能影响

通过合理使用 openapi-typescript 的类型转换和导入注入功能，我们可以生成更加符合项目需求的类型定义，同时保持代码的整洁和高效。