io-ts运行时类型检查完全指南：TypeScript数据验证最佳实践

三、安装与基本配置

3.1 安装

npm  io-ts fp-ts

> io-ts依赖fp-ts的函数式编程工具，必须同时安装fp-ts。

> 来源：官方

3.2 配置要求

确保.json中启用严格模式，特别是和：

{
  "": {
    "": true
  }
}

四、核心概念详解

4.1 编解码器（Codec）

io-ts中的所有类型校验器都称为“编解码器”，它们实现了t.Type<A, O, I>接口：

A：静态类型（编译时类型）

O：输出类型（解码后的类型，通常与A相同）

I：输入类型（接受的数据类型，通常是）

常用内置编解码器：

> 完整列表见官方文档：

4.2 解码与编码

解码（）：将未知输入转换为已验证类型，返回<, A>。

编码（）：将已验证类型编码为原始输出格式（通常与输入相同），用于序列化。

const  = t.type({ value: t. })
// 解码
const  = .({ value: 42 }) // Right({ value: 42 })
const  = .({ value: '42' }) // Left([...])
// 编码
const  = .({ value: 42 }) // { value: 42 }

4.3 错误处理

解码失败时返回Left，其中包含数组，每个错误包含：

value：引发错误的值

：错误上下文（路径）

：错误描述

实用工具：

t..map(e => e..map(c => c.key).join('.')) 可获取错误路径。

推荐使用fp-ts的fold或进行错误处理。

 { pipe } from 'fp-ts/'
 { fold } from 'fp-ts/'
const  = pipe(
  .(input),
  fold(
     => {
      // 处理错误，返回默认值或抛出异常
      .error()
       null
    },
    value => value
  )
)

五、进阶用法与最佳实践

5.1 自定义编解码器

通过t.type、t.或t.可自定义校验逻辑。

5.1.1 自定义基础类型（）

// 定义正整数类型
const  = t.(t., n => n > 0 && .(n), '')
// 使用
const  = t.type({ port:  })

5.1.2 完全自定义编解码器

实现t.Type接口：

const  = new t.Type<Date, , >(
  '',
  (input): input is Date => input  Date,
  (input, ) => {
    if ( input === '') {
      const date = new Date(input)
      if (!isNaN(date.())) {
         t.(date)
      }
    }
     t.(input, )
  },
  date => date.()
)

5.2 组合与复用

io-ts编解码器可以像普通值一样组合和复用：

const  = t.type({
  : t.,
  city: t.,
  zip: t.
})
const  = t.type({
  name: t.,
  age: t.,
  : 
})
// 导出类型
type  = t.< >

5.3 与API响应集成（全链路示例）