Superstruct 入门指南：JavaScript 数据验证库快速上手

Superstruct 入门指南：JavaScript 数据验证库快速上手

superstruct A simple and composable way to validate data in JavaScript (and TypeScript). 项目地址: https://gitcode.com/gh_mirrors/su/superstruct

什么是 Superstruct

Superstruct 是一个轻量级但功能强大的 JavaScript 数据验证库，它通过定义数据结构（struct）来验证输入数据是否符合预期格式。与同类库相比，Superstruct 具有简洁的 API 设计和出色的错误信息反馈，非常适合用于表单验证、API 数据校验等场景。

安装 Superstruct

通过 npm 安装

对于使用 npm 包管理器的项目，可以通过以下命令安装 Superstruct：

npm install --save superstruct

安装完成后，你可以在项目中这样引入：

import { object, string, number } from 'superstruct'

替代引入方式

如果你更喜欢使用命名空间导入：

import * as s from 'superstruct'

const User = s.object({
  id: s.number(),
  name: s.string(),
})

浏览器直接使用

对于不使用构建工具的项目，可以通过 script 标签直接引入 UMD 版本：

<script src="https://unpkg.com/superstruct/lib/index.cjs"></script>

引入后，全局将暴露 Superstruct 对象供使用。

定义数据结构

Superstruct 的核心概念是"struct"（数据结构），它定义了数据的形状和类型约束。让我们从一个用户数据示例开始：

const data = {
  id: 42,
  name: 'Jane Smith',
  email: 'jane@example.com',
}

创建对象结构

要为上述数据创建验证结构：

import { object, number, string } from 'superstruct'

const User = object({
  id: number(),
  name: string(),
  email: string(),
})

这个 User 结构定义了：

• id 必须是数字类型
• name 必须是字符串类型
• email 必须是字符串类型

数据验证方法

Superstruct 提供了多种验证方式，适合不同场景：

1. 断言验证 (assert)

最直接的方式是使用 assert 方法，当数据无效时会抛出错误：

import { assert } from 'superstruct'

assert(data, User)  // 如果数据有效，不会抛出异常

对于无效数据：

const invalidData = {
  id: 43,
  name: false,  // 不符合字符串类型
  email: 'jane@example.com',
}

assert(invalidData, User)
// 将抛出包含详细信息的 StructError

2. 验证并返回错误 (validate)

如果不想抛出异常，可以使用 validate 方法返回验证结果：

import { validate } from 'superstruct'

const [error, validatedData] = validate(data, User)
if (error) {
  // 处理错误
}

3. 布尔验证 (is)

只需要知道数据是否有效时，使用 is 方法：

import { is } from 'superstruct'

if (is(data, User)) {
  // 数据有效
}

验证错误详解

当验证失败时，Superstruct 会提供详细的错误信息，包括：

• 期望的类型 (type)
• 实际接收的值 (value)
• 错误路径 (path)
• 完整的错误分支 (branch)

例如上面的无效数据示例中，错误信息明确指出 name 字段期望是字符串但收到了布尔值。

最佳实践建议

1. 尽早验证：在数据进入系统时就进行验证
2. 复用结构：将常用结构定义为常量复用
3. 组合结构：可以通过组合简单结构创建复杂验证
4. 处理错误：为用户提供友好的错误信息反馈

Superstruct 的简单性和强大功能使其成为 JavaScript 数据验证的优秀选择。通过本指南，你应该已经掌握了基本用法，可以开始在项目中实践了。

superstruct A simple and composable way to validate data in JavaScript (and TypeScript). 项目地址: https://gitcode.com/gh_mirrors/su/superstruct