typia 用于 TypeScript：完整指南与示例

什么是 typia 以及为什么需要它？

\n\n

typia 是一个强大的 TypeScript 库，它提供运行时类型检查（runtime type validation），并具有一个独特的特点：它在编译阶段（compile-time）生成检查代码，而不是在运行时。这使其成为 TypeScript 生态系统中最快的数据验证库之一。

\n\n

typia 解决的主要问题：

\n

\n
• 性能： 与流行的库（zod、yup、io-ts）不同，typia 不使用反射或装饰器。相反，它在构建阶段生成优化的检查代码，从而带来 10–100 倍的速度提升。
\n
• 类型安全： 您可以确保来自外部来源（API、数据库、表单）的数据符合您的 TypeScript 接口。
\n
• 最少的样板代码： 您无需编写单独的验证模式——typia 直接使用您现有的 TypeScript 类型。
\n
• 支持复杂类型： Union、intersection、conditional types、mapped types——所有这些都“开箱即用”。
\n

\n\n

该库特别适用于：

\n

\n
• 使用 TypeScript 进行 Node.js 后端开发
\n
• 需要验证表单或 API 响应的前端应用程序
\n
• 对序列化/反序列化速度有要求的微服务架构
\n
• 对性能和类型安全要求严格的项目
\n

\n\n

安装

\n\n

安装 typia 包括两个步骤：库本身和 TypeScript 转换器（编译器）。

\n\n

步骤 1. 通过 npm 安装

\n

npm install typia\n# 或\nyarn add typia\n# 或\npnpm add typia

\n\n

步骤 2. 安装转换器

\n

npm install --save-dev typia-transform\n# 或\nyarn add -D typia-transform\n# 或\npnpm add -D typia-transform

\n\n

步骤 3. 配置 tsconfig.json

\n

将插件添加到您的 tsconfig.json 中：

\n

{\n  "compilerOptions": {\n    "plugins": [\n      {\n        "transform": "typia-transform"\n      }\n    ]\n  }\n}

\n\n

步骤 4. 与 ttypescript 一起使用（推荐）

\n

安装 ttypescript 以实现自动转换：

\n

npm install --save-dev ttypescript

\n

然后在您的 package.json 脚本中将 tsc 替换为 ttsc：

\n

{\n  "scripts": {\n    "build": "ttsc",\n    "start": "node dist/index.js"\n  }\n}

\n\n

重要提示： typia 需要 TypeScript 4.4 或更高版本。没有转换器，该库将无法工作。

\n\n

快速入门与代码示例

\n\n

让我们创建一个简单的用户数据验证示例。

\n\n

import typia from "typia";\n\n// 定义接口\ninterface IUser {\n  id: number;\n  name: string;\n  email: string;\n  age: number;\n  isActive: boolean;\n}\n\n// 创建验证函数\nconst validateUser = typia.createValidate<IUser>();\n\n// 测试数据\nconst testData = {\n  id: 1,\n  name: "伊万·彼得罗夫",\n  email: "ivan@example.com",\n  age: 30,\n  isActive: true,\n};\n\n// 验证\nconst result = validateUser(testData);\n\nif (result.success) {\n  console.log("数据有效:", result.data);\n} else {\n  console.log("验证错误:", result.errors);\n}\n\n// 无效数据示例\nconst badData = {\n  id: "不是数字", // 应该是 number\n  name: "伊万",\n  email: "不是邮箱",\n  age: -5,\n  isActive: "yes", // 应该是 boolean\n};\n\nconst badResult = validateUser(badData);\nconsole.log("错误:", badResult.errors);

\n\n

这个示例展示了仅使用 TypeScript 接口就能轻松验证数据。无需额外的模式或装饰器！

\n\n

主要方法和函数

\n\n

1. typia.