# 使用 z 模式验证 JSON 数据 z-schema 根据 JSON Schema 验证 JSON 数据（draft-04、draft-06、draft-07、draft-2019-09、draft-2020-12）。默认草稿：**draft-2020-12**。 ## 快速开始从“z-schema”导入 ZSchema； const 验证器 = ZSchema.create(); 常量架构 = { 类型：'对象'，属性：{ 名称: { 类型: '字符串' }, 年龄: { 类型: '整数', 最小值: 0 }, }, 必填：['姓名'], }; // 抛出无效数据 validator.validate({ name: 'Alice', 年龄: 30 }, schema); 安装：`npm install z-schema` ## 选择验证模式 z-schema 有四种基于两个切换的模式：“异步”和“安全”。选择适合用例的一个。模式|工厂来电 |返回|使用时 ---|---|---|--- 同步投掷| `ZSchema.create()` | `true` 或抛出 `ValidateError` |默认 — 简单脚本和中间件同步安全 | `ZSchema.create({ safe: true })` | `{ 有效，错误吗？ }` |需要在不使用 try/catch 的情况下检查错误异步抛出 | `ZSchema.create({ async: true })` | `Promise` 或拒绝 |使用异步格式验证器异步安全 | `ZSchema.create({ async: true, safe: true })` | `Promise<{ 有效，呃？ }>` |异步+非抛出 ### 同步抛出（默认）从“z-schema”导入 ZSchema； const 验证器 = ZSchema.create(); 尝试{ validator.validate（数据，模式）； } 捕获（错误）{ // err 是 ValidateError console.log(错误.详细信息); // 模式错误详细信息[] } ### 同步安全 const 验证器 = ZSchema.create({ safe: true }); const 结果 = validator.validate(数据, 模式); if (!result.valid) { console.log(结果.err?.details); } 或者在常规（抛出）验证器上调用“.validateSafe()”以获得相同的结果形状： const 验证器 = ZSchema.create(); const { valid, err } = validator.validateSafe(数据, schema); ### 异步抛出使用异步格式验证器时必需的。 const 验证器 = ZSchema.create({ async: true }); 尝试{ 等待验证器.validate（数据，模式）； } 捕获（错误）{ console.log(错误.详细信息); } ### 异步安全 const validator = ZSchema.create({ async: true, safe: true }); const { valid, err } =等待 validator.validate(数据, schema); ## 检查错误 `ValidateError` 有 `.details` — 一个 `SchemaErrorDetail` 数组：接口 SchemaErrorDetail { 消息：字符串； //“预期类型为字符串，但发现类型为数字” 代码：字符串； //“无效类型” 参数：(字符串|数字|数组<字符串|数字>)[]; 路径：字符串|数组<字符串|数量>; // "#/age" 或 ["age"] 关键字？：字符串； //“类型”、“必需”、“最小长度”等内部？：SchemaErrorDetail[]； //来自anyOf/oneOf/not的子错误 schemaPath？：数组<字符串|数量>; schemaId？：字符串； } ### 示例：遍历嵌套错误组合器（`anyOf`、`oneOf`、`not`）会产生嵌套的 `inner` 错误： const { valid, err } = validator.validateSafe(数据, schema); 如果（！有效&&错误）{ for (err.details 的常量详细信息) { console.log(`${detail.path}: [${detail.code}] ${detail.message}`); if (detail.inner) { for (detail.inner 的 const sub) { console.log(` └─ ${sub.path}: [${sub.code}] ${sub.message}`); } } } } ### 过滤错误将“ValidateOptions”作为第三个参数传递以包含或排除特定的错误代码： // 只报告类型错误 validator.validate(data, schema, { includeErrors: ['INVALID_TYPE'] }); // 抑制字符串长度错误 validator.validate(data, schema, { exceptErrors: ['MIN_LENGTH', 'MAX_LENGTH'] }); 有关完整的错误代码列表，请参阅 [references/error-codes.md]()。 ## 模式预编译在启动时编译模式以获得更好的运行时性能并解决交叉引用： const 验证器 = ZSchema.create(); const 模式 = [ { id: '地址', 类型：'对象'，属性：{ 城市：{ 类型：'字符串' }，邮政编码：{ 类型：'字符串' } }，必填：['城市'], }, { id: '人', 类型：'对象'，属性：{ 名称: { 类型: '字符串' }, 家: { $ref: '地址' }, }, 必填：['姓名'], }, ]; // 编译所有模式（验证它们并注册引用） validator.validateSchema(schemas); // 使用编译的模式 ID 验证数据 validator.validate({ name: 'Alice', home: { city: '巴黎' } }, 'person'); ## 远程引用 ### 手动注册 ZSchema.setRemoteReference('http://example.com/schemas/address.json', addressSchema); // 或每个实例： validator.setRemoteReference('http://example.com/schemas/person.json', personSchema); ### 通过模式读取器自动加载从“节点：fs”导入 fs；从“节点：路径”导入路径； ZSchema.setSchemaReader((uri) => { const filePath = path.resolve(__dirname, 'schemas', uri + '.json'); 返回 JSON.parse(fs.readFileSync(filePath, 'utf8')); }); ### 诊断缺失的参考文献 const { valid, err } = validator.validateSafe(数据, schema); 如果（！有效&&错误）{ const Missing = validator.getMissingReferences(err); const Remote = validator.getMissingRemoteReferences(err); } ## 自定义格式验证器 ### 全局（在所有验证器实例之间共享） ZSchema.registerFormat('邮政编码', (value) => { return typeof value === 'string' && /^\d{5}(-\d{4})?$/.test(value); }); ### 实例范围 const 验证器 = ZSchema.create(); validator.registerFormat('邮政编码', (value) => { return typeof value === 'string' && /^\d{5}(-\d{4})?$/.test(value); }); ### 通过创建时的选项 const 验证器 = ZSchema.create({ 自定义格式：{ '邮政编码': (value) => typeof value === 'string' && /^\d{5}(-\d{4})?$/.test(value), }, }); ### 异步格式验证器返回 `Promise`。需要 `{ async: true }`。 const 验证器 = ZSchema.create({ async: true }); validator.registerFormat('用户存在', async (value) => { if (typeof value !== 'number') return false; const user = wait db.findUser(value); 返回用户！= null； }); ### 列出注册格式 const 格式 = ZSchema.getRegisteredFormats(); ## 选择草稿版本如果架构针对特定版本，则显式设置草稿： const validator = ZSchema.create({ 版本: 'draft-07' }); 有效值：“draft-04”、“draft-06”、“draft-07”、“draft2019-09”、“draft2020-12”（默认）、“none”。有关草稿之间的功能比较，请参阅 [references/draft-comparison.md]()。 ## 常用选项选项 |默认 |目的 ---|---|--- `breakOnFirstError` | `假` |在出现第一个错误时停止验证 `noEmptyStrings` | `假` |拒绝空字符串作为“string”类型 `noEmptyArrays` | `假` |拒绝空数组作为“array”类型 `严格模式` | `假` |立即启用所有严格检查 `忽略未知格式` | `假` |抑制未知的格式错误（现代草稿总是忽略） `formatAssertions` | `空` | `null`=总是断言，`true`=尊重词汇，`false`=仅注释 `reportPathAsArray` | | `reportPathAsArray` `假` |将错误路径报告为数组而不是 JSON 指针字符串有关完整选项参考，请参阅 [references/options.md]()。 ## 验证子模式以模式中的特定路径为目标： validator.validate(carData, fullSchema, { schemaPath: 'definitions.car' }); ## 浏览器使用（UMD） <脚本> var 验证器 = ZSchema.create(); 尝试{ validator.validate({ name: 'test' }, { type: 'object' }); } 捕获（错误）{ console.log(错误.详细信息); } ## TypeScript 类型所有类型均从包中导出：导入类型{ JsonSchema, // 模式类型（所有草稿联合） ZSchemaOptions, // 配置选项 ValidateOptions, // 每次调用选项（schemaPath、includeErrors、exclusiveErrors） ValidateResponse, // { valid: boolean, err?: ValidateError } SchemaErrorDetail, // 单个错误详细信息 ErrorCode, // 错误代码字符串文字类型 FormatValidatorFn, // (输入：未知) => boolean |承诺<布尔值> SchemaReader, // (uri: string) => JsonSchema } 来自 'z 模式'；从 'z-schema' 导入 { ValidateError }; ## 参考文件 * [references/error-codes.md]() — 包含描述和示例的完整错误代码列表 * [references/options.md]() — 带默认值的完整选项参考 * [references/draft-comparison.md]() — JSON Schema 草稿之间的功能比较 ## 重要约定 * 始终使用 `ZSchema.create(options?)` — 切勿使用 `new ZSchema()`。工厂返回正确类型的变体。 * 错误详细信息位于“.details”（而不是“.errors”）。 * 使用“import type { ... }”导入类型，使用“import { ValidateError }”导入值。 * 默认草稿为“draft2020-12”。如果针对较旧的草稿，请明确指定。

验证 Json 数据

包含技能