Superstruct 入门：轻量 TypeScript 数据校验
Superstruct 是简洁的 TS 校验库：结构即 Schema，错误信息清晰。本文讲解基础 Schema、进阶校验与错误处理。
Superstruct 用 object({ name: string(), age: number() }) 定义结构，assert(data, Schema) 校验——不符即抛出带详细路径的错误。API 极简、类型推导自动，是 Zod 之外的轻量选择。
快速上手
npm install superstruct
import { object, string, number, assert } from 'superstruct';
const User = object({
name: string(),
age: number(),
email: string(),
});
const data = { name: '张三', age: 28, email: 'zhang@example.com' };
assert(data, User); // 不符抛出 StructError，含字段路径与原因
Infer<typeof User> 从 Schema 推导 TS 类型——Schema 即类型。
进阶 Schema
import { optional, array, enums, min, pattern, defaulted } from 'superstruct';
const Order = object({
id: string(),
items: array(object({ sku: string(), qty: min(number(), 1) })),
status: enums(['pending', 'paid', 'shipped']),
coupon: optional(pattern(string(), /^[A-Z0-9]+$/)),
priority: defaulted(enums(['low', 'high']), 'low'),
});
optional可选、defaulted默认值、pattern正则、enums枚举；- 自定义校验：
define()包装任意谓词函数。
错误处理
import { validate } from 'superstruct';
const [error, value] = validate(data, Order);
if (error) {
// error.failures() 列出全部失败：path + 原因
for (const f of error.failures()) {
console.log(f.path.join('.'), f.message);
}
}
assert 抛错 / validate 返回元组 / is 返回布尔——三种消费风格按场景选。
与 Zod 的关系
Superstruct 更早、API 更简；Zod 的生态（tRPC、React Hook Form 集成）更大。功能存在重叠——存量 Superstruct 无需迁，新项目两者都试试按生态偏好选。
常见问题（FAQ）
Q：性能如何？
Superstruct 的校验是轻量函数组合，常规请求体校验开销可忽略。极端性能场景 Zod/valibot 基准略优。
Q：能复用 Schema 片段吗？
能——Schema 是值，object() 嵌套组合即可：const Address = object({...}); const User = object({ addr: Address })。
Q：校验失败的数据能部分使用吗？
不建议——校验的意义就是边界完整性。需要"尽力而为"解析时，用 mask() 明确剥离未知字段。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
