node.js - API 请求/响应形状(包括 JSON 架构、TypeScript 类型和运行时验证器)的单一事实来源？

Question

我正在编写一个典型的 Node.js REST 服务，其端点接收 JSON 输入(作为 POST 正文)并返回 JSON 响应。

我想要这三件事:

1. 定义端点的请求正文和响应正文的形状的 JSON 架构。 (或 Swagger 文件，或任何适合为客户定义契约(Contract)的文件。)
2. TypeScript 类型/接口(interface)完美反射(reflect) JSON 架构。
3. 我可以从处理程序中调用运行时验证函数，以确保对象处于正确的形状。 (一旦输入对象经过验证，我的 TypeScript 代码就应该知道它的接口(interface)。)

但我想要一个单一的事实来源，以避免这三个组件不同步。所以我只想手动维护其中一个(JSON 模式或 TypeScript 类型)。另外两个组件应该从手写组件生成，并且不应该提交到版本控制。

我觉得这一定是当今相当普遍的一组要求，但我在网上找不到太多相关信息。也许我使用了错误的搜索词来研究它。是否有任何框架或传统模式可以解决此目标，即定义具有严格输入验证、标准化模式文档以及 TypeScript 中完全类型化对象的所有便利性的 JSON API 的目标？

Answer 1

我假设您在前端和后端使用 TypeScript。

自定义类型重用

假设我们有一个项目存储库，其中包含三个主要文件夹:client、server 和 shared。

在shared中，您有一个Types.ts文件，其中包含所有自定义类型定义。 例如:

export interface Person {
  name: string;
  age: number;
}

现在您可以从任何子文件夹导入这些类型，例如 .\client\src\components\SomeComponent.ts 或服务器 .\server\src\api\SomeRoute.ts 与:

import { Person } from `..\..\..\..\shared\Types.ts`;

通过这种方式，您可以在服务器和客户端的项目范围内使用类型定义。

JSON 模型和文档生成

您可以使用ts-doc记录您的 api 和 ts-docs-gen 的评论生成 Markdown 文档。

替代方案是 typedoc 。 TypeDoc 将 TypeScript 源代码中的注释转换为呈现的 HTML 文档或 JSON 模型。您可以以仅考虑相关 api 文件的方式对其进行配置。

运行时验证

关于输入和输出的运行时验证，您可以为每种类型编写自己的验证函数，本文中的 Stereobooster 对此进行了解释:pragmatic-types-io-validation-or-how-to-handle-json-based-apis-in-statically-typed-language 。或者您使用像 io-ts 这样的库.

可能没有一个适合所有情况的工具，因为它在很大程度上取决于您想要完成的确切要求。因此，由不同的工具组成你的工具集应该会引导你走向正确的方向。如果您找到了适合您的设置，请随时自行发布答案。