用途:定义所有进入系统的数据在信任边界处的校验模式,确保未经校验的数据不跨越信任边界。前端用 Zod 校验用户输入,后端用 Pydantic 校验 API 请求。
主要能力:前端表单校验(Zod + react-hook-form,配合 zodResolver);通过 z.infer 推导类型而非手写;模式组合(基础模式复用、refine 交叉字段校验);发送前校验 API 请求数据;澳大利亚专用校验器(ABN 含校验和、电话、4 位邮编、DD/MM/YYYY 日期);后端 Pydantic 请求模型、约束类型(PositiveInt、PageSize、ShortString)、field_validator 与路由自动校验。
使用方式:前端定义 camelCase + Schema 后缀的 Zod 模式,用 z.infer 推导 PascalCase 类型;后端定义 PascalCase + 用途后缀的 Pydantic 模型,路由参数直接声明模型由 Pydantic 自动校验。共享契约两侧字段名保持一致。模式位置:单端点用内联,多端点共享放 apps/backend/src/api/schemas/,领域模型放 apps/backend/src/models/。
适用场景:创建或修改含用户数据的表单、定义 API 请求/响应模式、新增接受 POST/PUT/PATCH 的端点、审查缺失输入校验的代码。
限制与边界:不用于认证逻辑、错误响应格式设计(用 error-taxonomy)或数据库 ORM 模型定义。校验失败应使用 DATA_VALIDATION_* 错误码。错误信息需用户友好(en-AU)。避免在路由处理器内写校验逻辑、无错误信息、未校验的类型强制转换、可选字段无默认值、手写类型而非推导。资料未提供安装命令与具体版本信息。