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

Question

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

我想要这三件事：

但我想要一个单一的事实来源，以避免这三个组件不同步。所以我只想手动维护其中之一（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-静态类型语言。或者您使用像io-ts这样的库。

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