入门

¥Getting started

• 安装
• 基础数据校验
• 解析和序列化 JSON

安装

¥Install

节点 REPL

你可以尝试 Ajv，而无需将其安装在 Node.js REPL 中：https://runkit.com/npm/ajv (opens new window)

¥You can try Ajv without installing it in the Node.js REPL: https://runkit.com/npm/ajv (opens new window)

要安装 Ajv 版本 8：

¥To install Ajv version 8:

npm install ajv

如果需要将 Ajv 与 JSON 结构草案 04 一起使用，则需要安装 Ajv 版本 6：

¥If you need to use Ajv with JSON Schema draft-04, you need to install Ajv version 6:

npm install ajv@6

请参阅 Contributing 了解如何在本地运行测试

¥See Contributing on how to run the tests locally

基础数据校验

¥Basic data validation

Ajv 获取 JSON 数据的结构，并将其转换为非常高效的 JavaScript 代码，根据该结构校验你的数据。要创建模式，你可以使用 JSON 结构 或 JSON 类型定义 - 看看 选择结构语言，它们有不同的优点和缺点。

¥Ajv takes a schema for your JSON data and converts it into a very efficient JavaScript code that validates your data according to the schema. To create a schema you can use either JSON Schema or JSON Type Definition - check out Choosing schema language, they have different advantages and disadvantages.

例如，要校验具有必需属性 "foo"（整数）、可选属性 "bar"（字符串）并且没有其他属性的对象：

¥For example, to validate an object that has a required property "foo" (an integer number), an optional property "bar" (a string) and no other properties:

Ajv 将结构编译为函数并在所有情况下缓存它们（使用结构本身作为 Map 中的键），以便下次使用相同的结构对象时不会再次编译。

¥Ajv compiles schemas to functions and caches them in all cases (using the schema itself as a key in a Map), so that the next time the same schema object is used it won't be compiled again.

Best performance:compile and getSchema methods

使用 compile 或 getSchema 方法返回的编译函数时可以获得最佳性能。

¥The best performance is achieved when using compiled functions returned by compile or getSchema methods.

虽然编译后的校验函数的执行速度非常快，但其编译速度相对较慢，因此你需要确保仅编译结构一次并重复使用编译后的校验函数。参见 管理多个结构。

¥While execution of the compiled validation function is very fast, its compilation is relatively slow, so you need to make sure that you compile schemas only once and re-use compiled validation functions. See Managing multiple schemas.

保存错误属性

每次调用校验函数（或 ajv.validate）时，errors 属性都会被覆盖。如果你想稍后使用它（例如在回调中），你需要将 errors 数组引用复制到另一个变量。参见 校验错误。

¥Every time a validation function (or ajv.validate) is called the errors property is overwritten. You need to copy the errors array reference to another variable if you want to use it later (e.g. in the callback). See Validation errors.

解析和序列化 JSON

¥Parsing and serializing JSON

New

Ajv 可以从 JSON 类型定义 结构编译高效的解析器和序列化器。

¥Ajv can compile efficient parsers and serializers from JSON Type Definition schemas.

与 JSON.stringify 相比，使用专门针对你的数据形状的函数来序列化数据可以提高 10 倍以上。

¥Serializing the data with a function specialized to your data shape can be more than 10x compared with JSON.stringify.

解析数据取代了使用 JSON.parse 进行通用解析后单独校验的需要（尽管校验本身通常比解析快得多）。如果你的 JSON 字符串有效，则专门的解析大约与 JSON.parse 一样快，但如果你的 JSON 无效，则专门的解析会失败得更快 - 所以在某些场景下它可以非常有效。

¥Parsing the data replaces the need for separate validation after generic parsing with JSON.parse (although validation itself is usually much faster than parsing). In case your JSON string is valid, the specialized parsing is approximately as fast as JSON.parse, but in case your JSON is invalid, the specialized parsing would fail much faster - so it can be very efficient in some scenarios.

对于相同的数据结构，可以这样编译解析器和序列化器：

¥For the same data structure, you can compile parser and serializer in this way:

Lower parsing performance of empty schemas

You would have smaller performance benefits in case your schema contains some properties or other parts that are empty schemas ({}) - parser would call JSON.parse in this case.

JTD discriminator schema

The performance of parsing discriminator schemas depends on the position of discriminator tag in the schema - the best parsing performance will be achieved if the tag is the first property - this is how compiled JTD serializers generate JSON in case of discriminator schemas.

Also, if discriminator tag were to be repeated in JSON, the second value would be ignored and the object still validated according to the first tag.

Compiled parsers do NOT throw exceptions

Compiled parsers, unlike JSON.parse, do not throw the exception in case JSON string is not a valid JSON or in case data is invalid according to the schema. As soon as the parser determines that either JSON or data is invalid, it returns undefined and reports error and position via parsers properties message and position.