1schema 中文文档教程

发布于 3年前 浏览 28 项目主页 更新于 3年前

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.tsthat.schema.ts, the-other/schema.ts。 运行 1schema update 将生成 generated/this.schema.json, generated/that.schema.jsonthe-other/schema.json

Related projects

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

Acknowledgements

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

1schema

1schema provides friendly developer tooling for runtime checking of TypeScript schemas. It uses the powerful and effective ts-json-schema-generator to generate JSON Schema which can be validated at runtime using 1schema's built-in support for Ajv or any other JSON Schema validator. For example, in our Python projects we use jsonschema.

This is way better than writing and maintaining JSON Schema by hand, and if you use TypeScript you also get the benefit of compile-time checking.

Since the schemas are written in TypeScript it's ideal for TypeScript projects, however it's easy to use in JavaScript projects, and works in non-JavaScript projects too.

I didn't write this blog post, but it explains the idea really well.

We've been using this pattern for a while at Metabolize–Curvewise, both for validating user uploads and validating across interface boundaries. This open-source tooling is new and considered alpha. Developer feedback and contributions welcome!

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

You can! However, to provide a smooth development experience, 1schema provides a few niceties:

  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.

Your schema files are just ordinary TypeScript files so they can import and extend other TypeScript types and schemas, so long as the types are supported by ts-json-schema-validator.

If you have a tsconfig.json it will be used and if not one is provided for you.

You can spread schemas across multiple files: If you create: this.schema.ts, that.schema.ts, the-other/schema.ts. Running 1schema update will generate generated/this.schema.json, generated/that.schema.json and the-other/schema.json.

Related projects

We use 1schema with Werkit, a toolkit for encapsulating Python functions on AWS Lambda.

Acknowledgements

Serious thanks to Dominik Moritz for maintaining the wonderful ts-json-schema-validator tool. And thanks to Jacob Beard who turned me back onto JSON Schema in the first place.

    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
    原文