Zod 项目新增 example 参数支持详解

在 API 开发中，Schema 定义和文档生成是至关重要的环节。Zod 作为一个强大的 TypeScript Schema 声明和验证库，近期在 v4 版本中新增了对 example 参数的支持，这为开发者提供了更完善的 API 文档生成能力。

功能背景

在实际开发中，我们经常需要为 API 参数提供示例值，这在生成 OpenAPI/Swagger 文档时尤为重要。示例值能够帮助前端开发者更直观地理解 API 的使用方式，也能让测试人员更容易构造测试数据。

使用方式

在 Zod v4 中，我们可以通过 metadata 功能为字段添加示例值。具体实现方式如下：

const apiSchema = {
  params: z.object({
    id: z.string().describe('An identifier for the resource.')
      .meta({ example: '9c235211-6834-11ea-a78c-6feb38a34414' })
  })
};

这种写法比直接传递参数更加灵活，因为 metadata 可以承载各种附加信息，而不仅仅是示例值。

转换效果

当使用 zod-to-json-schema 等工具将上述 Schema 转换为 JSON Schema 时，会生成如下结构：

{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "example": "9c235211-6834-11ea-a78c-6feb38a34414"
  },
  "description": "An identifier for the resource."
}

最终在 Swagger UI 等文档工具中，这些示例值会直观地展示出来，极大提升了 API 文档的可读性和实用性。

技术实现原理

Zod v4 通过引入 metadata 的概念，为 Schema 提供了扩展能力。metadata 本质上是一个键值对集合，可以附加到任何 Zod Schema 上。当使用转换工具时，这些 metadata 会被提取并转换为目标格式（如 OpenAPI）对应的字段。

这种设计有几个优势：

1. 扩展性强：可以添加任意类型的附加信息
2. 类型安全：TypeScript 可以正确推断 metadata 的类型
3. 非侵入式：不影响原有的 Schema 验证逻辑

最佳实践

在实际项目中，建议为重要的 API 参数都添加示例值，特别是：

• ID 类参数
• 枚举值参数
• 复杂格式参数（如日期时间、正则表达式等）
• 业务特定格式的参数

同时，示例值应该：

1. 具有代表性，能展示参数的典型用法
2. 格式正确，能通过 Schema 验证
3. 不包含敏感信息

总结

Zod 对 example 参数的支持，进一步完善了其作为全栈 TypeScript 开发工具链中重要一环的角色。通过 metadata 机制实现的这一功能，既保持了 Zod 原有的简洁性，又提供了足够的灵活性，是 API 开发工作流中值得采用的新特性。