用途:在各类数据边界(API 请求、表单提交、数据库写入、服务间契约)使用 JSON Schema 配合 AJV 做运行时校验,保证数据完整性。
主要能力:schema 统一放在 /schemas/ 目录,按 common、entities、api 分层;命名遵循 {entity}.schema.json、{entity}.create.schema.json、{entity}.update.schema.json、{context}.schema.json 等约定。支持字符串、数字、枚举、可空字段等常用校验关键字,以及 email、uri、uuid、date、date-time、time、ipv4、ipv6、hostname 等格式,并可自定义 phone、slug 格式。
使用方式:通过中间件调用 validateBody、validateQuery、validateParams 校验请求体、查询参数和路径参数,例如 validateBody('entities/user.create');也可在 service 层调用 validate(data, 'entities/user.create') 做纵深防御。查询字符串会自动强制转换类型(如 integer、boolean、array)。校验失败返回 VALIDATION_ERROR 及 details 数组,body 失败返回 422,query/params 失败返回 400。
类型生成:运行 npm run generate:types,用 json-schema-to-typescript 把 schema 转为 .d.ts,置于 src/types/generated/,可在 JSDoc 中导入使用;类型检查运行 npm run typecheck。schema 约束应与数据库 CHECK 约束对齐,并可从 OpenAPI 规范中以 $ref 引用。
限制:资料未提供安装命令、具体价格、平台支持范围;部分细节(如自定义格式的完整定义)暂未提供。