强大的 TypeScript 到 JSON Schema 转换器:ts-json-schema-generator
在软件开发中,JSON Schema 是一种强大的工具,用于验证 JSON 数据的结构是否符合规定。当你使用 TypeScript 编写类型定义时,你可能会想要将这些类型转换成相应的 JSON Schema,以确保数据的有效性。这就是 ts-json-schema-generator
进场的时候了。
项目简介
ts-json-schema-generator
是一个扩展版的 TypeScript 到 JSON Schema 的转换库,它的设计灵感来源于 YousefED/typescript-json-schema
和 xiag-ag/typescript-to-json-schema
。这个项目优化了类型检查和 AST 处理,避免了对 typeChecker.getTypeAtLocation()
的依赖,并将处理步骤分离,使输出的 JSON Schema 更加准确且易于定制。
项目技术分析
ts-json-schema-generator
使用 TypeScript 的抽象语法树(AST)来解析源代码,并生成符合 ECMA-262 规范的 JSON Schema 文档。它支持多种 TypeScript 特性,包括但不限于:
- 接口(
interface
) - 枚举(
enum
) - 联合类型(
union
)、元组类型(tuple
)、数组类型(type[]
) - 类型别名(type aliases)
- 泛型(generics)
- 函数(functions)
- 预定义类型(如
Date
、RegExp
、URL
) - 基本类型(
string
、boolean
、number
) - 字面量值(
"value"
、123
、true
、false
、null
、undefined
) - 关键字操作(
typeof
、keyof
、never
) - 条件类型(Conditional Types)
此外,它还提供了 JSDoc 注解支持,可以自定义配置以满足不同需求。
应用场景
ts-json-schema-generator
可广泛应用于以下场景:
- API 客户端 - 生成客户端验证 JSON 输入的 JSON Schema。
- 数据存储 - 在数据库中存储结构化数据前进行预验证。
- 前端表单验证 - 根据 JSON Schema 自动创建并验证表单输入。
- 数据交换 - 确保与其他服务或系统的数据交互遵循固定格式。
项目特点
- 高效与精确 - 不使用
typeChecker.getTypeAtLocation()
,保证类型别名正确性。 - 独立处理 - 分离 AST 解析和 JSON Schema 格式化,方便扩展和调试。
- 非导出类型过滤 - 非导出的类型、接口和枚举不会出现在
definitions
中。 - 命令行界面 (CLI) - 支持直接通过命令行快速生成 JSON Schema 文件。
- 可编程 API - 提供 JavaScript API,方便集成到自动化流程或构建脚本中。
- 强大的自定义选项 - 允许自定义格式化器和解析器,实现特殊类型的处理。
要开始使用 ts-json-schema-generator
,你可以尝试简单的 CLI 命令或者通过 API 集成到你的项目中。如果你需要进一步的控制,例如自定义函数类型或构造函数的处理,可以创建自己的子类型处理器。
总而言之,ts-json-schema-generator
是一款强大且灵活的工具,能帮助你在 TypeScript 世界中无缝地生成和验证 JSON 数据。无论你是想提高数据安全,还是寻求更高效的编码实践,都值得尝试一下这个开源项目。