运行时 Schema 校验
运行时 Schema 校验（Runtime Schema Validation）是指在程序运行阶段，对数据的结构、类型和约束进行动态检查，以确保数据符合预定义的 Schema（模式/规范）。
| 维度 | 说明 |
| 什么是 Schema | 对数据结构的形式化描述，定义了字段名称、数据类型、是否必填、取值范围等规则 |
| 编译时 vs 运行时 | 编译时校验由类型系统（如 TypeScript、Java）在编译阶段完成；运行时校验则在程序实际执行时才对数据进行检查 |
| 为什么需要运行时校验 | 编译时类型系统无法覆盖所有场景——外部输入（API 请求、用户表单、文件解析、第三方数据）在编译时是未知的，只有运行时才能确认其是否合法 |
- API 请求/响应校验 — 校验客户端提交的 JSON 是否符合接口契约（如使用 JSON Schema）
- 配置文件加载 — 应用启动时验证配置文件的结构和取值是否合法
- 消息队列消费 — 消费者在反序列化消息后校验其格式
- 表单输入验证 — 前后端对用户提交的表单数据做结构和规则校验
- 数据库读写 — ORM 层在写入前校验实体对象是否满足 Schema 约束
- 跨服务通信 — 微服务之间通过 Schema 校验保证数据兼容性
JSON Schema
业界最广泛的 Schema 描述标准，通常与 REST API 配合使用：
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"age": { "type": "integer", "minimum": 0 }
},
"required": ["name", "age"]
}
各语言主流校验库
| 语言 | 库 / 工具 | 特点 |
| TypeScript/JS | zod、yup、joi、ajv | Zod 支持从 Schema 推导 TS 类型，实现编译时+运行时双重保障 |
| Python | pydantic、marshmallow、cerberus | Pydantic v2 基于 Rust 核心，性能优秀，广泛用于 FastAPI |
| Go | go-playground/validator、ozzo-validation | 基于 struct tag 或链式 API 做校验 |
| Java/Kotlin | Bean Validation (JSR 380)、jackson-schema | 注解驱动，与 Spring 生态深度集成 |
Zod 示例（TypeScript）
import { z } from "zod";
// 定义 Schema
const UserSchema = z.object({
name: z.string().min(1),
age: z.number().int().nonneg(),
email: z.string().email(),
});
// 运行时校验
const result = UserSchema.safeParse(requestBody);
if (!result.success) {
// result.error 包含详细的校验失败信息
throw new ValidationError(result.error.issues);
}
// result.data 已具备完整的类型推导
Pydantic 示例（Python）
from pydantic import BaseModel, EmailStr
class User(BaseModel):
name: str
age: int
email: EmailStr
# 运行时校验 — 数据不合法时自动抛出 ValidationError
user = User(**request_json)
运行时 Schema 校验 vs 编译时类型检查
| 对比维度 | 编译时类型检查 | 运行时 Schema 校验 |
| 检查时机 | 编写/构建阶段 | 程序执行阶段 |
| 覆盖范围 | 代码内部的类型一致性 | 外部输入、动态数据 |
| 性能开销 | 零（产物中已擦除类型信息） | 有一定开销（需遍历数据结构） |
| 典型工具 | TypeScript、Java 泛型、Go 类型系统 | Zod、Pydantic、JSON Schema |
| 互补关系 | 保证代码逻辑的类型安全 | 保证数据边界的安全 |
> 最佳实践：两者结合使用。编译时类型系统保证内部逻辑正确，运行时 Schema 校验守住数据入口，形成双重防线。
性能与工程建议
- 只在边界层校验 — 在数据进入系统的入口（API 网关、消息消费者、配置加载）做校验，内部传递时信任已校验数据，避免重复校验带来的性能损耗
- 提前失败（Fail Fast） — 校验失败立即返回清晰的错误信息，避免脏数据流入下游
- Schema 复用与版本管理 — 将 Schema 定义集中管理，支持版本演进，便于多端（前端/后端/文档）共享同一份契约
- 关注错误信息质量 — 好的校验库会返回结构化的错误路径和原因，便于调试和用户提示