JSON 到强类型代码生成器

目标与适用范围

从 JSON 或 schema 证据生成 TypeScript、Go、Rust、Kotlin、Java、C# 与 Zod 校验模型。
本指南将当前任务范围转化为可复核的交付结果。请保留源文件、中间产物和关键判断，让后续协作者能够理解检查了什么以及为什么这样处理。

准备证据并作出选择

• 收集有代表性的 JSON 样例或已批准的 JSON Schema，覆盖可选字段、null、嵌套数组和真实边界情况。

• 明确目标语言、命名风格、包或命名空间位置，以及生成代码是临时脚手架还是需要纳入版本管理的契约。

• 记录运行时校验方式，尤其是 TypeScript 类型是否还需要 Zod schema 来解析外部输入。

• 决策点: 你已有 schema，还是只有样例？. 如果样例需要先沉淀为共享契约，用 JSON Schema Generator；如果样例已经足够稳定且只服务单一代码库，可以直接从目标语言生成器开始。

• 决策点: 哪个运行时拥有这个模型？. 选择服务端或 SDK 实际运行语言对应的生成器，这样命名、可空字段、枚举和集合类型能在真实运行环境里审查。

• 决策点: 你需要编译期类型、运行时校验，还是两者都要？. 语言模型提供编译期安全；当 TypeScript 边界必须解析并拒绝非法输入时，再把 JSON Schema 转成 Zod。

按步骤完成工作流

1. 规范化源契约

从代表性 JSON 样例开始；当契约仍隐含在样例中时生成 JSON Schema；如果数据来自 XLSX，则先从表格列结构推导 schema。 使用 json-schema-generator, xlsx-sheet-to-json-schema.

2. 生成主运行时模型

为拥有数据边界的运行时生成模型，并在复制到项目之前审查字段名、可选性、嵌套对象命名和序列化行为。 使用 json-to-typescript, json-to-go, json-to-rust.

3. 创建辅助 SDK 模型

同一载荷跨平台或 SDK 传递时，生成 Kotlin、Java 或 C# 模型，并对比各语言中的可空字段和集合类型。 使用 json-to-kotlin, json-to-java, json-to-csharp.

4. 补充必要的运行时校验

当 TypeScript API、表单、worker 或导入边界处理不可信输入时，把共享 JSON Schema 转成 Zod，而不是只依赖类型。 使用 json-schema-to-zod-schema-converter.

5. 复核采用证据

把生成代码与原始样例对照，记录可空和命名假设，并保留未来重新生成时应使用的 schema 或样例。 使用 json-to-typescript, json-schema-generator.

交付前验收结果

• 生成模型覆盖下游代码需要的全部代表字段、可选值、嵌套结构、数组形状和类似枚举的取值。
• 采用前已审查语言特定的命名、包路径、可见性、可空类型和序列化注解。
• 如果使用 schema 或表格来源，最终产物记录源样例、生成假设和后续更新时的校验路径。

常见问题

• 应该直接从 JSON 样例生成代码，还是先生成 JSON Schema？ 快速脚手架可以直接用样例。多个服务或多种语言需要共享稳定契约时，先使用 JSON Schema 更适合后续再生成和校验。
• 生成的 TypeScript 类型可以替代运行时校验吗？ 不可以。TypeScript 类型只帮助开发期检查，外部输入仍需要运行时解析；需要拒绝非法数据时，应把 JSON Schema 转成 Zod。
• 为什么强类型代码工作流里包含表格转 schema？ 很多导入项目最初只有 XLSX 列而不是 API schema。先把表格形状转成 JSON Schema，可以给各语言生成器一个更清晰的契约。