Zod 项目新增 example 参数支持：增强 JSON Schema 转换能力

在 API 开发领域，Schema 验证和文档生成是两个至关重要的环节。Zod 作为一个强大的 TypeScript 模式验证库，近期在其 v4 版本中新增了对 example 参数的支持，这一改进显著提升了与 JSON Schema 转换工具的兼容性，特别是与 zod-to-json-schema 这样的工具配合使用时。

功能背景

在实际开发中，我们经常需要将 Zod 定义的数据结构转换为 JSON Schema 格式，以便生成 API 文档（如 Swagger/OpenAPI）。在这个过程中，示例值（example）是一个非常有用的元数据，它能够帮助 API 使用者更好地理解每个字段的预期格式和内容。

技术实现

在 Zod v4 中，开发者现在可以通过 metadata 方法为字段添加各种元数据，其中就包括 example 参数。这个功能使得我们能够直接在 Zod 模式定义中嵌入示例值，这些值会在转换为 JSON Schema 时被保留下来。

const apiSchema = {
  params: z.object({
    id: z.string().metadata({
      description: '资源标识符',
      example: '9c235211-6834-11ea-a78c-6feb38a34414'
    }),
  }),
};

上述代码经过转换后，会生成包含示例值的 JSON Schema 结构，最终在 Swagger UI 等文档工具中展示出来，为 API 使用者提供直观的参考。

实际应用价值

1. 提升开发体验：前端开发者可以直接在 API 文档中看到各个字段的示例值，减少猜测和试错时间
2. 增强文档质量：自动生成的文档包含实际示例，比纯文本描述更加直观
3. 保持一致性：示例值直接定义在 Schema 中，确保文档与实际实现保持一致
4. 减少维护成本：当 Schema 变更时，相关示例会自动同步更新

最佳实践

在使用这一功能时，建议：

1. 为所有关键字段提供有代表性的示例值
2. 示例值应该反映真实的业务场景
3. 对于枚举类型，提供最常见的用例作为示例
4. 保持示例值的格式与实际使用一致（如日期格式、UUID 格式等）

总结

Zod 对 example 参数的支持进一步完善了其作为全栈类型安全解决方案的能力。这一改进特别适合需要同时处理数据验证和 API 文档生成的团队，它帮助开发者在单一源头维护数据结构定义、验证规则和文档元数据，显著提高了开发效率和文档质量。

随着 TypeScript 生态的不断发展，Zod 这类工具正在成为现代全栈开发中不可或缺的一部分，而类似 example 支持这样的细节改进，正是其日益成熟和完善的标志。