ZenStack项目中TRPC插件生成代码的类型导入问题解析

在ZenStack项目中使用TRPC插件时，开发者可能会遇到一个与TypeScript严格模式相关的类型导入问题。本文将深入分析该问题的成因、影响及解决方案。

问题现象

当启用TypeScript的verbatimModuleSyntax选项时，TRPC插件生成的routers/index.ts文件中会出现类型导入错误。具体表现为：

import {
    unsetMarker,
    type AnyRootConfig,
    type CreateRouterInner,
    type ProcedureBuilder,
    type ProcedureParams,
    type ProcedureRouterRecord,
} from "@trpc/server"

系统会报错提示："'unsetMarker' resolves to a type-only declaration and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled."

问题根源

这个问题源于TypeScript的严格类型检查机制。当启用verbatimModuleSyntax选项时，TypeScript要求：

1. 纯类型声明必须使用import type语法明确标注
2. 不能将类型和常规导入混合在同一导入语句中

在TRPC的@trpc/server模块中，unsetMarker实际上是一个类型声明，而非运行时值。因此，按照TypeScript的严格规则，它必须被明确标记为类型导入。

解决方案

正确的导入方式应该是：

import type {
    AnyRootConfig,
    CreateRouterInner,
    ProcedureBuilder,
    ProcedureParams,
    ProcedureRouterRecord,
    unsetMarker,
} from "@trpc/server"

这种写法将所有类型相关的导入统一放在import type语句中，完全符合TypeScript的严格类型检查要求。

技术背景

verbatimModuleSyntax是TypeScript的一项重要特性，它：

1. 强制区分类型导入和值导入
2. 防止类型被错误地包含在JavaScript输出中
3. 提高代码的明确性和可维护性

在大型项目中，这种严格的区分有助于：

• 避免意外的运行时依赖
• 使构建输出更加精简
• 提高类型系统的可靠性

最佳实践

对于使用ZenStack和TRPC的开发者，建议：

1. 在项目中统一使用import type来导入所有类型声明
2. 保持类型导入和值导入分离
3. 定期检查生成的代码是否符合TypeScript严格模式要求

未来展望

值得注意的是，TRPC团队计划在未来的版本中重构这些类型声明，可能会将它们移动到专门的"unstable"目录中。这意味着：

1. 当前的导入路径可能会发生变化
2. 开发者需要关注TRPC的版本更新
3. 类型系统的稳定性将得到进一步提升

通过理解并应用这些类型导入的最佳实践，开发者可以确保项目在TypeScript严格模式下平稳运行，同时为未来的升级做好准备。