1schema 中文文档教程
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 提供了一个 一些细节:
- Globbing
- Formatting
- Checking that the schema are up to date
- 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 generategenerated/schema.json
with all exported types and their dependents. Check in this file. - COMING SOON: At runtime,
import { validate } from '1schema'
andvalidate(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 上。
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:
- Globbing
- Formatting
- Checking that the schema are up to date
- 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 generategenerated/schema.json
with all exported types and their dependents. Check in this file. - COMING SOON: At runtime,
import { validate } from '1schema'
andvalidate(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.
你可能也喜欢
- 5-angular-influencer-common 中文文档教程
- @0x/contracts-tokens 中文文档教程
- @0y0/exec-http 中文文档教程
- @160over90/vue-cli-plugin-stylelint 中文文档教程
- @1ziton/react-native-baidulocation 中文文档教程
- @24hr/block-cli 中文文档教程
- @360learning/vue-pdf-viewer 中文文档教程
- @555platform/555-calendar-sdk 中文文档教程
- @55hudong/base-module 中文文档教程
- @90poe/jest-performant-warnings-stats-reporter 中文文档教程