Superstruct for TypeScript: 完整指南及示例

Superstruct 简介

\n\n

Superstruct 是一个轻量级但功能强大的库，用于在 TypeScript 和 JavaScript 中验证和解析数据结构。它允许您使用简单且富有表现力的“模式”（structs）来描述预期的数据形状（对象、数组、字符串、数字等），然后检查实际数据是否符合这些模式。

\n\n

与其他验证库（如 Zod 或 Yup）不同，Superstruct 专注于简单性、性能和极简主义。它不会自动生成复杂的 TypeScript 类型（尽管与它们兼容），而是提供灵活且直观的 API 来描述结构。

\n\n

为什么需要 Superstruct？

\n

\n
• 验证外部来源的数据： API 响应、表单数据、配置文件、localStorage——任何数据可能以意外格式出现的地方。
\n
• 创建安全的 DTO（数据传输对象）： 确保在应用程序层之间传输的数据符合预期的结构。
\n
• 解析和转换： Superstruct 不仅可以检查，还可以转换数据（例如，将字符串转换为数字）。
\n
• 可读的文档： Superstruct 模式本身就是关于数据外观的极佳文档。
\n

\n\n

安装

\n\n

Superstruct 是一个 npm 包，因此通过 Node.js 包管理器安装：

\n\n

npm install superstruct

\n\n

或者，如果您使用 Yarn：

\n\n

yarn add superstruct

\n\n

安装后，您可以将该库导入到您的 TypeScript 文件中：

\n\n

import { struct, string, number, object, array, optional, union, literal, enums, size, refine, assert, is, validate } from 'superstruct';

\n\n

快速入门

\n\n

让我们为用户创建一个简单的模式并验证数据。

\n\n

import { object, string, number, assert } from 'superstruct';\n\n// 1. 定义模式 (struct)\nconst User = object({\n    id: number(),\n    name: string(),\n    email: string(),\n});\n\n// 2. 我们要验证的数据\nconst userData = {\n    id: 1,\n    name: 'Alice',\n    email: 'alice@example.com',\n};\n\n// 3. 验证\ntry {\n    assert(userData, User);\n    console.log('数据有效！');\n} catch (e) {\n    console.error('验证错误：', e.message);\n}\n\n// 4. 如果数据无效，assert 将抛出异常\nconst badData = { id: '不是数字', name: 'Bob' };\ntry {\n    assert(badData, User);\n} catch (e) {\n    console.error('错误：', e.message);\n    // 输出：Expected a number for `id`, but received: "不是数字"\n}

\n\n

主要方法和函数

\n\n

Superstruct 提供了一组用于创建模式的工厂函数。以下是 10 个主要函数：

\n\n

1. string()

\n

描述： 创建一个检查值是否为字符串的模式。

\n

参数： 无。

\n

import { string, assert } from 'superstruct';\n\nconst NameSchema = string();\nassert('Hello', NameSchema); // OK\n// assert(123, NameSchema); // 错误：Expected a string, but received: 123

\n\n

2. number()

\n

描述： 检查值是否为数字（除非另有指定，否则包括 NaN）。

\n

参数： 无。

\n

import { number, assert } from 'superstruct';\n\nconst AgeSchema = number();\nassert(30, AgeSchema); // OK\n// assert('30', AgeSchema); // 错误

\n\n

3. boolean()

\n

描述： 检查值是否为布尔值（true 或 false）。

\n

参数： 无。

\n

import { boolean, assert } from 'superstruct';\n\nconst IsActiveSch