ArkType 用于 TypeScript：完整指南

\n\n

1. 什么是 ArkType 以及为什么需要它

ArkType 是一个用于 TypeScript 的现代数据验证库，它在类型层面工作。与传统的验证器（Zod、Yup）不同，ArkType 采用独特的方法：它在编译阶段将类型定义转换为优化的解析器和验证器。这使其能够实现高性能并与 TypeScript 类型系统完全集成。

为什么需要 ArkType？在现代 Web 应用程序中，数据通常来自外部来源：API、表单、localStorage、WebSocket。如果没有验证，您可能会遇到难以捕获的运行时错误。ArkType 通过提供声明式数据模式描述以及从这些模式自动生成 TypeScript 类型来解决此问题。该库在处理 REST API、GraphQL、表单以及任何外部数据时特别有用。

ArkType 的关键优势在于速度。得益于模式的静态编译，其验证速度比同类库快 10-100 倍。此外，ArkType 支持递归类型、循环引用、严格检查以及众多内置类型。这使其成为高负载应用程序和微服务的理想选择。

\n\n

2. 安装

ArkType 的安装通过包管理器 npm（或 yarn/pnpm）完成。该库使用 TypeScript 编写，并提供完整的类型支持。

npm install arktype

使用 TypeScript 无需额外配置——该库会自动读取 tsconfig.json 的配置。最低 TypeScript 版本要求为 5.0。

# 如果使用 yarn\nyarn add arktype\n\n# 如果使用 pnpm\npnpm add arktype

\n\n

3. 快速入门

ArkType 的最小使用示例——创建一个用于验证用户对象的模式：

import { type } from 'arktype';\n\n// 定义模式\nconst User = type({\n    name: 'string',\n    age: 'number',\n    email: 'string.email'\n});\n\n// 验证数据\nconst result = User({\n    name: '伊万',\n    age: 25,\n    email: 'ivan@example.com'\n});\n\nif (result instanceof type.errors) {\n    console.error('验证错误:', result.summary);\n} else {\n    console.log('数据有效:', result);\n    // result 自动具有类型 { name: string; age: number; email: string }\n}

在此示例中，我们创建了一个 User 模式，用于检查三个字段。如果数据未通过验证，则返回一个包含详细描述的错误对象。如果一切正常，则返回类型化的数据。

\n\n

4. 主要方法和函数

ArkType 提供了丰富的 API 用于创建、组合和转换模式。我们来看 8 个关键方法。

\n\n

4.1. type() — 创建模式

签名: type(schema: TypeSchema): Type

描述: 创建验证模式的主要方法。接受一个对象或字符串作为类型定义。

import { type } from 'arktype';\n\n// 简单模式\nconst StringType = type('string');\nconst NumberType = type('number');\n\n// 对象模式\nconst Person = type({\n    name: 'string',\n    age: 'number',\n    isActive: 'boolean'\n});\n\n// 验证\nconsole.log(StringType('hello')); // 'hello'\nconsole.log(StringType(123)); // 错误: Expected string, got number

\n\n