使用 Zod 和 OpenAPI 在单个合约中实现类型安全的快速 API

本指南旨在为“使用 Zod 和 OpenAPI 构建类型安全的 Express API”这一目标重建可操作的实现路径。重点在于契约定义、校验机制，以及那些无需猜测意图即可直接放入代码库的代码片段。在开始修改代码之前，应先明确输入参数、该步骤的负责人以及完成标准；这样操作人员就能从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。相比冗长的脚本，更应优先使用小型且易于测试的单元。当某个步骤失败时，故障原因应当指向单一责任模块，而非复杂的流程链。

核心理念

在修改代码之前，先明确该功能的输入参数、负责执行该步骤的人员以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏的状态。 将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，杜绝默默完成部分任务的情况。 利用能够自动生成文档的架构在边界处进行验证。拥有唯一的真实数据源，可避免 OpenAPI 定义与实际处理逻辑之间的偏差。

const CreateUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
});

api.post("/users", {
  body: CreateUserSchema,
  response: {
    201: UserSchema,
  },
  handler: async (req) => {
    const user = await createUser(req.body);
    return {
      status: 201,
      body: user,
    };
  },
});

为何要构建另一个 Express 库？

在探讨“为何要构建另一个 Express 库？”时，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间和成本。提前了解这些信息可以避免在从演示环境过渡到共享环境时出现意外费用。可使用同时能生成文档的架构规范在边界处进行验证，这样就能避免 OpenAPI 定义与实际处理逻辑之间的不一致。

目前的现状

对于“当前状态”方案，应在修改代码之前明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个流程即可进行审计。 利用能自动生成文档的架构规范在边界处进行验证。统一的真实数据源可避免OpenAPI描述与实际处理逻辑之间的偏差。 对于“当前状态”方案，应在修改代码之前明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 相比庞大的脚本，更应优先使用小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向某个特定功能模块，而非整个复杂的流程。

您会非常希望获得开发者的反馈

如果您希望获得开发者的反馈，那么在修改代码之前就必须明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏的状态。应将此阶段视为输入与已验证输出之间的契约：为相关成果命名，定义成功判定标准，并拒绝默许的半完成状态。需返回结构化的错误信息，以便客户端能够据此做出决策；严格的类型检查能避免不必要的猜测。

操作检查清单

对于操作检查清单，同样需要在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏的状态。

应将正常流程和恢复流程一并记录下来。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续才添加的完善措施。

应返回结构化的错误信息，以便客户端据此进行分支处理。过于宽泛的类型错误描述会迫使人们猜测问题所在。

与其展示巧妙但仅一次性的演示，不如追求扎实可靠的性能。

相比庞大的脚本，应优先选择小型且易于测试的单元。当某个步骤出现故障时，故障点应指向单一责任模块，而非复杂的处理流程。

应返回结构化的错误信息，以便客户端据此进行分支处理。过于宽泛的类型错误描述会迫使人们猜测问题所在。

在推广该技术栈之前，需冻结版本、为关键流程记录标准操作日志，并确认回滚步骤。共享环境需要设置速率限制、进行租户身份验证，同时明确密钥轮换的负责人。与其展示巧妙但仅一次性的演示，不如追求扎实可靠的性能。