1schema 中文文档教程

Question

1schema

1schema 为 TypeScript 的运行时检查提供了友好的开发人员工具 模式。 它使用强大而有效的 ts-json-schema-generator 来 生成 JSON Schema 可以在运行时使用 1schema 进行验证 内置支持 Ajv 或 任何其他 JSON 模式验证器。 例如，在我们的 Python 项目中，我们使用 jsonschema。

这比手工编写和维护 JSON Schema 要好得多，如果你 使用 TypeScript，您还可以获得编译时检查的好处。

由于模式是用 TypeScript 编写的，因此非常适合 TypeScript 项目， 但是它在 JavaScript 项目中很容易使用，并且可以在非 JavaScript 项目中使用 项目也是。

我没有写这篇博文，但是 它很好地解释了这个想法。

我们在 Metabolize–Curvewise 中已经使用这种模式一段时间了，两者都是为了 验证用户上传和跨接口边界验证。 这 开源工具是新的并且被认为是 alpha。 开发者反馈和 欢迎投稿！

Why not use ts-json-schema-generator directly?

你可以！ 但是，为了提供流畅的开发体验，1schema 提供了一个 一些细节：

1. Globbing
2. Formatting
3. Checking that the schema are up to date
4. Pruning JSON schemas when their corresponding source files are removed

How it works

• In your project, create a schema.ts file:

  export type ContactMethodType = 'mobile' | 'home' | 'work' | 'other'

  export interface Address {
    streetAddress: string
    locality: string
    region: string
    postalCode: string
    country: string
  }

  export interface Contact {
    familyName: string
    givenName: string
    honorificPrefix?: string
    honorificSuffix?: string
    nickname?: string
    url?: string
    imageUrl?: string
    email: {
      address: string
      type: ContactMethodType
    }[]
    phone: {
      phoneNumber: string
      type: ContactMethodType
    }[]
    address: Array<Address & { type: ContactMethodType }>
    birthdate: Date
    gender?: string
  }

• Run 1schema update to generate generated/schema.json with all exported types and their dependents. Check in this file.
• COMING SOON: At runtime, import { validate } from '1schema' and validate(inputData).
• If you're using TypeScript, cast the validated input to the appropriate type from your schema (e.g. const contact = inputData as Contact) to get compile-time checking.
• In CI, run 1schema check to verify the generated schema are up to date.

您的模式文件只是普通的 TypeScript 文件，因此它们可以导入和 扩展其他 TypeScript 类型和模式，只要 ts-json-schema-validator 支持这些类型。

如果你有一个 tsconfig.json 它将被使用，如果没有提供 你。

您可以将模式分布在多个文件中：如果您创建：this.schema.ts， that.schema.ts, the-other/schema.ts。 运行 1schema update 将生成 generated/this.schema.json, generated/that.schema.json 和 the-other/schema.json。

Related projects

我们将 1schema 与 Werkit 一起使用，这是一个用于封装 Python 函数的工具包 AWS 拉姆达。

Acknowledgements

非常感谢 Dominik Moritz 维护精彩 ts-json-schema-validator 工具。 感谢 Jacob Beard 让我回头 首先放在 JSON Schema 上。