深入理解 io-ts 运行时类型系统-优快云博客

深入理解 io-ts 运行时类型系统

io-ts Runtime type system for IO decoding/encoding 项目地址: https://gitcode.com/gh_mirrors/io/io-ts

什么是 io-ts

io-ts 是一个强大的 TypeScript 运行时类型系统库，主要用于数据的编解码和验证。它巧妙地将静态类型系统与运行时类型检查结合起来，解决了 TypeScript 类型只在编译时存在而运行时无法检查的问题。

核心概念：编解码器（Codec）

io-ts 的核心是 Type<A, O, I> 类，我们称之为"编解码器"或"codec"。它包含四个关键部分：

名称(name)：编解码器的唯一标识符
类型守卫(is)：判断一个值是否符合类型A
验证函数(validate)：将输入类型I解码为类型A
编码函数(encode)：将类型A编码为输出类型O

class Type<A, O, I> {
  constructor(
    readonly name: string,
    readonly is: (u: unknown) => u is A,
    readonly validate: (input: I, context: Context) => Either<Errors, A>,
    readonly encode: (a: A) => O
  ) {}
}

解码过程

decode 方法会返回一个 Either 类型的结果，这是函数式编程中常用的代数数据类型：

Left 表示失败，包含错误信息
Right 表示成功，包含解码后的值

type Either<E, A> =
  | { readonly _tag: 'Left'; readonly left: E }
  | { readonly _tag: 'Right'; readonly right: A };

基础类型示例

让我们看一个最简单的字符串类型编解码器实现：

const string = new t.Type<string, string, unknown>(
  'string',
  (input: unknown): input is string => typeof input === 'string',
  (input, context) => 
    typeof input === 'string' ? t.success(input) : t.failure(input, context),
  t.identity
);

使用方式：

isRight(string.decode('a string')) // true
isRight(string.decode(null)) // false

组合类型

io-ts 的真正强大之处在于可以组合简单类型来构建复杂类型：

const User = t.type({
  userId: t.number,
  name: t.string
});

这相当于定义了以下 TypeScript 类型：

type User = {
  userId: number
  name: string
}

类型提取

io-ts 提供了 TypeOf 工具类型，可以从编解码器提取对应的静态类型：

type User = t.TypeOf<typeof User>;
// 等同于
type User = {
  userId: number
  name: string
}

这种方法实现了"单一真实来源"原则，避免了类型定义的重复。

错误处理

io-ts 提供了灵活的错误报告机制。默认的 PathReporter 可以生成人类可读的错误信息：

const result = User.decode({ name: 'Giulio' });
console.log(PathReporter.report(result));
// 输出: [ 'Invalid value undefined supplied to : { userId: number, name: string }/userId: number' ]

高级用法

对于更复杂的场景，可以使用 fold 函数来处理解码结果：

import { pipe } from 'fp-ts/lib/pipeable';
import { fold } from 'fp-ts/lib/Either';

const onLeft = (errors: t.Errors): string => `${errors.length} error(s) found`;
const onRight = (s: string) => `No errors: ${s}`;

pipe(t.string.decode('a string'), fold(onLeft, onRight));
// => "No errors: a string"

pipe(t.string.decode(null), fold(onLeft, onRight));
// => "1 error(s) found"