TypeBox TypeScript：方法、示例、安装

什么是 TypeBox，为什么需要它？

\n\n

TypeBox 是一个强大的 TypeScript 库，它允许您定义与 JSON Schema 标准兼容的数据模式，并同时从中推导出正确的 TypeScript 静态类型。简单来说，它是运行时数据验证（当您的应用程序运行并实时检查数据时）和编译时类型（当 TypeScript 在代码执行前检查其正确性时）之间的桥梁。

\n\n

为什么需要它？在现代 Web 开发中，数据通常来自不可靠的来源：API 请求、网站表单、配置文件。如果没有验证，您可能会遇到难以捕获的运行时错误。TypeBox 优雅地解决了这个问题：您只需描述一次模式，就能获得：

运行时验证器 — 在程序运行时检查对象是否符合模式。
静态类型 — TypeScript 自动推导出可用于注解的类型。
JSON Schema — 模式可以序列化为 JSON，并用于其他工具（例如，用于生成 UI 表单或文档）。

\n\n

TypeBox 非常适合：创建带有请求体验证的 API 端点、处理配置文件、构建具有字段检查的复杂表单，以及任何在各个环节都重视类型安全的场景。

\n\n

安装 TypeBox

\n\n

TypeBox 是一个用于 Node.js/TypeScript 的库，因此通过 npm（或 yarn/pnpm）安装。

\n\n

npm install @sinclair/typebox

\n\n

安装后，您可以将其导入到您的项目中：

\n\n

import { Type } from '@sinclair/typebox';

\n\n

为了进行验证，您还需要一个验证器本身。TypeBox 默认不包含它，以便将选择权留给开发者。建议使用 @sinclair/typebox/compiler（内置编译器）或 ajv（流行的 JSON Schema 验证器）。让我们安装编译器：

\n\n

npm install @sinclair/typebox-compiler

\n\n

或者，如果您更喜欢 AJV：

\n\n

npm install ajv ajv-formats

\n\n

请注意：该库名为 @sinclair/typebox，而不仅仅是 typebox。这对于正确安装很重要。

\n\n

快速入门及代码示例

\n\n

让我们创建一个简单的用户模式并对其进行验证。

\n\n

import { Type } from '@sinclair/typebox';\nimport { TypeCompiler } from '@sinclair/typebox/compiler';\n\n// 1. 定义用户模式\nconst UserSchema = Type.Object({\n    id: Type.Number(),\n    name: Type.String({ minLength: 2 }),\n    email: Type.String({ format: 'email' }),\n    age: Type.Optional(Type.Number({ minimum: 0, maximum: 120 })),\n});\n\n// 2. 创建用于验证的编译器\nconst validator = TypeCompiler.Compile(UserSchema);\n\n// 3. 测试数据\nconst validUser = {\n    id: 1,\n    name: 'Alice',\n    email: 'alice@example.com',\n    age: 30,\n};\n\nconst invalidUser = {\n    id: 'not-a-number',\n    name: 'A',\n    email: 'invalid-email',\n};\n\n// 4. 验证\nconsole.log(validator.Check(validUser));   // true\nconsole.log(validator.Check(invalidUser)); // false\n\n// 5. 获取静态类型\ntype UserType = Static<typeof UserSchema>;\n// 现在 UserType 是 { id: number; name: string; email: string; age?: number; }\n

\n\n

在这个示例中，我们定义了一个模式，将其编译成验证器，并检查了两个对象。请注意对 age 字段使用了 Type.Optional — 它可能不存在。我们还使用了 format: 'email' 来检查电子邮件格式。

\n\n