typechecker：轻量级JS模板化类型检查工具，告别手写if堆叠

打字软件里，最让我头疼的就是各种联调场景下的类型问题。后端返回的字段类型说变就变，前端拿着字符串当数组使，页面打开直接白屏；自己写的数据解析逻辑，十几个 if 堆在那里，看到就烦。这种痛点做前端的人多少都遇到过，也正是我鼓捣出 typechecker 的原始动力。

typechecker 是一套轻量级的 JS 模板化类型检查工具。它不需要编译、没有依赖，体积控制在 2KB 以内，核心思路是“用模板描述期望的数据形态，再拿模板去匹配真实数据”。你可以用它校验 API 响应、解析 URL 路径参数、验证表单提交，甚至在运行时做数据清洗前的最后一道防线。不管你写 React、Vue 还是纯 Node 服务，只要能跑 JS 的地方，它都能直接嵌进去用。

如果你平时写代码经常要在数据校验上花时间，又不想为了这个引入一整套重量级 schema 库，那这篇文章值得往下看。我会把它的设计思路、模板语法、实际用法和踩坑记录全部拆开讲透。

1. 设计思路与定位

1.1 JS 类型检查的痛点在哪

JavaScript 是一门动态弱类型语言，变量上的类型只有在运行那一刻才真正确定。这个特性给开发带来了灵活性，但也埋了不少雷。最典型的就是typeof的使用陷阱：

typeof null; // "object"——历史遗留 typeof []; // "object" typeof {}; // "object" typeof NaN; // "number"

typeof根本分不清数组、对象和 null，而NaN也不会被数字检查拦住。结果就是很多人手写一堆像Array.isArray(x) && x.length > 0这样的防御代码，逻辑散落在业务各处，根本没法维护。

更麻烦的是字符串形态的校验。一个 URL 路径，例如/users/123/profile，你当然可以用正则去匹配 ID 是数字、username 是字母下划线，但正则写出来又长又难读，改一版需求就得重新猜一遍。而 typechecker 想解决的，就是这两个问题：复杂结构类型的校验，以及字符串模板化匹配的校验。

1.2 模板化到底是什么意思

“模板化”这个词听起来有点玄，拆开其实很好理解。常规的类型校验库通常要求你定义 schema 对象，比如：

const schema = { name: { type: 'string' }, age: { type: 'number', optional: true } };

这种写法信息密度不低，但和你想校验的数据形状之间隔着一层“翻译”，读代码的时候需要来回对照。typechecker 的思路换成“模板”——你直接把期望的数据形态写出来，然后拿数据往模板里套。

对于字符串形态，模板化的优势尤其明显。你看这个例子：

const userPath = t.tpl`/users/${t.num('id')}`; userPath.check('/users/123'); // 通过 userPath.check('/users/abc'); // 报错，id 不是数字 userPath.extract('/users/123'); // { id: 123 }

/users/${数字}这个形态直接用模板字符串表达，连正则都不用写，需要的时候还能把 ID 提取出来。这才是“模板化类型检查”最核心的设计意图：把数据形态的期望直接写在代码里，而不是藏在正则和 if 堆里。

1.3 轻量级不是功能少，而是取舍明确

做轻量级工具的难点不在于功能少，而在于砍功能的同时，核心体验不缩水。我在 typechecker 里的取舍有三条：

第一，不搞自己的 DSL。模板语法就是 JavaScript 原生语法，外加一个标签函数t.tpl。用户不用学新的配置格式，文档读一遍就能上手。

第二，不依赖运行时环境。纯函数实现，没有使用浏览器 API 或 Node 内置模块，浏览器、Node、小程序、Bun 里都能跑。

第三，不做过度设计。工具只负责“检查”，不做数据转换、序列化、代码生成这些周边功能。检查通过就是通过，不通过就抛异常或者返回结果对象，行为单一可预测。

这三种取舍合起来，保证了 typechecker 在大多数项目里可以零成本接入，又不至于让项目背上一个随时需要升级维护的“运行时框架”。

2. 模板语法与 API 拆解

2.1 基础类型与对象结构

typechecker 的入口是一个t对象，基础类型都挂在上面：t.string、t.number、t.boolean、t.array、t.object、t.func等。单个类型直接调用.check()就行：

t.number.check(42); // 通过 t.number.check('42'); // 抛异常："expected number, got string" t.string.check(undefined); // 抛异常："expected string, got undefined"

对象结构的定义接近自然语言：

const User = t.object({ id: t.number, name: t.string, age: t.number.optional, tags: t.array(t.string) }); User.check({ id: 1001, name: 'lily', tags: ['admin', 'editor'] });

optional表示字段可缺省，但一旦出现就必须符合类型预期。对于null想放行的字段，用nullable修饰：

const Profile = t.object({ nickname: t.string.nullable, bio: t.string.optional });

这两个修饰符在实际开发中特别常用——后端返回的数据里，空值和缺字段常常代表着不同的语义，分开处理能少踩不少坑。

数组类型的写法也做了兼容。t.array(t.number)表示数字数组，如果希望校验成组数据的具体对象结构，直接嵌套即可：

const OrderList = t.array(t.object({ orderId: t.string, amount: t.number, items: t.array(t.string) }));

这种结构校验的嵌套写法不新鲜，但它能覆盖日常开发里九成的数据形态需求，剩下的交给字符串模板。

2.2 模板字符串的核心玩法

字符串模板用的是 ES6 的标签模板语法。标签函数t.tpl拿到的参数被拆成了字符串块和插值表达式，每个{}里放的既可以是类型，也可以是自定义的校验函数：

const ArticlePath = t.tpl`/articles/${t.number}`; const SearchPath = t.tpl`/search?q=${t.string}`; ArticlePath.check('/articles/42'); // 通过 ArticlePath.check('/articles/abc'); // 抛异常

插值部分支持命名，命名后可以直接提取匹配到的值：

const TopicPath = t.tpl`/topic/${t.num('id')}/posts/${t.num('page')}`; const params = TopicPath.extract('/topic/55/posts/2'); // params = { id: 55, page: 2 }

这个能力在做路由参数解析的时候特别香。很多框架的路径参数解析依赖独立的路由声明文件，而 typechecker 直接在参数提取这一步顺带完成了类型校验，少维护一份配置。

插值位置不限于末尾。你可以把模板描述成/user/${t.string}/detail这样的形态，中间插值完全可行。模板里的静态字符串部分支持原样匹配，包括斜杠、问号、连字符这些特殊字符，基本不用转义。

2.3 组合、修饰与复用

类型之间可以随意组合。你想描述“一个字符串，但又必须匹配某个 URL 规则”，可以写：

const UrlString = t.string.and(t.url);

and表示两个条件同时满足，or表示其一满足即可：

const IdOrSlug = t.number.or(t.string);

这种组合逻辑和英语语法一样直白，组合出来的新类型可以被变量引用，也能嵌入到对象和模板中复用：

const PositiveInt = t.number.and(t.rule(v => Number.isInteger(v) && v > 0)); const PageData = t.object({ page: PositiveInt, size: PositiveInt, keyword: t.string.optional });

讲到这儿顺便介绍一下几个开箱即用的校验法则，日常用得到的都在表里：

这些内置法则覆盖了最常见的校验需求，特殊场景自己传t.rule回调就行，不限制自由发挥。

忽略大小写的场景也有现成方案。直接给字符串套一个t.ignoreCase修饰，校验时大小写就不敏感了：

const Status = t.string.ignoreCase.equal('active'); Status.check('ACTIVE'); // 通过 Status.check('active'); // 通过

这个对“后端返回大写状态，前端比小写”这种纠缠不清的场景特别有用，少掉一堆toLowerCase()的样板代码。

2.4 错误报告与调试体验

类型检查工具最怕两件事：一是漏报，二是报错信息看不懂。typechecker 在错误报告上下了一点功夫。

校验失败时，报错会带上具体的模板位置。比如你有一个嵌套很深的表单数据，typechecker 会输出类似这样的错误链：

ValidationError: at path "user.address.zip" expected string, got number check: t.object > t.object > t.string received: 12345

实际报错里会带出字段路径和当前校验的规则链，方便定位是哪层检查拦下来的。这在排查数字、字符串混堆的接口数据时能省下大量 console.log 的时间。

如果不想用异常流来控制业务逻辑，还可以调用.safe()方法，拿返回结果而不是抛异常：

const result = User.safe(data); if (result.ok) { // result.value 是原始数据 } else { console.log(result.errors); // 数组，每条都带路径信息 }

.safe()在处理批量数据时特别顺手，可以收集所有错误统一上报，不会遇到一条坏数据就中断整个流程。

3. 实操：从安装到落地

3.1 安装与第一个检查器

安装过程不需要配置文件，不需要 CLI，装完引入即可。

npm install typechecker --save # 或者 pnpm add typechecker

然后建一个checker.js，写第一个检查器：

import { t } from 'typechecker'; const createUserPayload = t.object({ username: t.string.and(t.match(/^[a-zA-Z0-9_]{4,16}$/)), email: t.string.and(t.email), age: t.number.range(0, 120).optional, tags: t.array(t.string).optional, plan: t.string.ignoreCase.equal('free').or(t.string.ignoreCase.equal('pro')) }); const payload = { username: 'tony', email: 'tony@example.com', plan: 'PRO' }; createUserPayload.check(payload); // 通过

这几个写法基本覆盖了前端校验要用的九成能力：正则匹配、邮件格式、数字区间、复杂字段缺失、忽略大小写枚举值。跑一遍之后，你对“类型检查”这件事的上手进度条基本就拉满了。

3.2 真实案例：URL 与路径参数校验

URL 校验是个容易翻车的场景。看到有些项目还在用new URL(str)来验证 URL，这其实得小心。new URL能解析出合法的http://、数据 URI 甚至自定义协议，过滤器形同虚设。更好的做法是对协议和域做明确约束：

const HttpUrl = t.tpl`${'http'}://${t.string}`; // 或者更精细一点 const ApiEndpoint = t.string.and(t.url).and(t.match(/^https?:\/\/[a-z0-9.-]+/i));

如果把 URL 拆成“协议 + 域名 + 路径 + 查询参数”来看，用模板写比正则直观太多：

const ApiPath = t.tpl`/v${t.num('version')}/${t.string('service')}?token=${t.string('token')}`; const info = ApiPath.extract('/v2/orders?token=abc123'); // { version: 2, service: 'orders', token: 'abc123' }

这个案例实际用在一个内部网关服务上，用来把外部回调的路径先校验再拆参。之前用正则拆三段要写三条规则，现在一行模板搞定，连参数类型都一起查了。

前端这边更常见的场景是校验接口返回的数据包。假设请求详情页之后，后端给的数据长下面这样：

{ "code": 20000, "data": { "id": "a1b2c3", "slug": "hello-world", "author": { "name": "Lily", "id": 1001 }, "content": "..." }, "meta": { "requestId": "req_9f8e7d", "cached": true } }

你可以定义一个完整的数据包模板，check 一次通过后再进业务代码。这样一来，所有“少字段”“类型错”的脏数据在入口处就被拦住了，后面的代码可以放心假设数据是干净的。

3.3 校验器内部是怎么工作的

这里聊一下模板匹配器内部的执行方式，理解它之后你才能预估到什么场景会有性能问题。

模板的执行过程可以理解成一个带类型的正则引擎。t.tpl拿到字符串块和插值类型后，会把它们编译成一串“匹配段”。匹配时，静态字符串部分按字符串块顺序匹配，插值部分先提取目标字段，再用该段对应的类型规则做校验。

关键在于匹配段的贪婪程度。拿这个模板来说：

const Path = t.tpl`/user/${t.string}/post/${t.number}`;

当字符串是/user/tony/post/42，匹配器必须知道：${t.string}到底应该吃掉tony还是tony/post？默认规则是，非模板末尾的字符串插值采用非贪婪匹配，即优先匹配到静态分隔符出现的位置。也就是说，tony会被正确分给name字段，不会把/post抢走。

如果模板末尾没有静态分隔符，比如：

const Slug = t.tpl`/slug/${t.string}`;

这时候字符串插值在末尾，非贪婪和贪婪没有区别，匹配器简单接受剩余全部内容即可。

这套设计让大部分模板匹配都是线性复杂度，一次遍历就能完成。只有当你嵌套了多个同类型插值、又没有静态分隔符做锚点时，匹配才可能退化到需要回溯计算，性能才需要额外关注。

3.4 前端与 Node 环境集成

在纯前端项目里，typechecker 可以当运行时校验器用。比如在 axios 响应拦截器里加一道检查：

import axios from 'axios'; import { t } from 'typechecker'; const OrderPayload = t.object({ id: t.string, status: t.number, items: t.array(t.string) }); axios.interceptors.response.use((response) => { const result = OrderPayload.safe(response.data); if (!result.ok) { return Promise.reject(new Error('接口返回数据格式异常')); } return response; });

在 Node 服务端，它更适合做请求体校验。写路由时把校验器放在入口处，不合格的直接 400 回去，不用让业务层处理垃圾数据：

import express from 'express'; import { t } from 'typechecker'; const app = express(); app.use(express.json()); const PatchUserSchema = t.object({ nickname: t.string.len(2, 20).optional, avatar: t.string.and(t.url).optional }); app.patch('/api/user/:id', (req, res) => { const result = PatchUserSchema.safe(req.body); if (!result.ok) { res.status(400).json({ message: '参数不合法', errors: result.errors }); return; } // 继续业务逻辑 });

这种“在数据进入业务逻辑之前做拦截”的模式，对代码整洁度的提升非常明显。校验规则全都集中在 schema 声明里，业务代码里不用再散布防御式 if 判断。

4. 常见问题与避坑实录

4.1 字符串“包含”判断与忽略大小写

很多朋友第一次接触 typechecker 会问：怎么判断一个字符串是否包含另一个字符串？这其实是 JS 开发里的高频需求。常规写法是str.includes(sub)，但 typechecker 想让你把包含规则直接收敛到类型声明里：

const HasAdmin = t.string.and(t.includes('admin')); HasAdmin.check('xxadminxx'); // 通过 HasAdmin.check('xxmanagerxx'); // 抛异常

配合忽略大小写，可以做到不区分大小写的包含校验：

const HasAdminCaseInsensitive = t.string.ignoreCase.includes('admin'); HasAdminCaseInsensitive.check('XXADMINXX'); // 通过

这种做法把“校验逻辑”和“业务逻辑”拆开了。业务代码里你只需要关注“这个数据应该是合法的”，至于合法是什么意思由 schema 定义。后续要调整边界规则，只改 schema 声明，业务代码一行不用动。

4.2 URL 校验别只依赖内置对象

再回到 URL 校验来提个醒。很多人图省事直接用new URL(str)来判断 URL，但在 chrome 扩展、服务端反向代理这种场景里，接收到的字符串可能带各种自定义协议前缀，new URL只判断了格式可解析，没有判断协议是否合规。typechecker 的t.url内部会检查协议头，默认收http:和https:两种，避免被javascript:、data:这类危险协议混过去。

对于更精的品牌域名校验，建议把“是否为合法 URL”和“域名是否匹配预期”分开写：

const SafeDomain = t.string .and(t.url) .and(t.match(/^https:\/\/api\.example\.com(\/|$)/));

这样一层管一层，规则清晰，排查起来也直接。

4.3 模板歧义与贪婪匹配

前面讲过模板匹配默认是非贪婪的，但有一种写法容易踩坑：两个字符串插值之间没有静态分隔符，比如：

const ProbablyBad = t.tpl`/pre/${t.string}/${t.string}`;

这个模板有两种分法：tony / 123可以分成tony和123，也能分成tony / 1和23。因为字符串类型太宽，匹配器只能选一个合理默认——实际会按尽量短的分法来分。如果你的业务依赖这种歧义字段，建议换成分隔符明确的方式。

唯一能保证不歧义的办法是让模板里的静态字符尽量多。不能改成静态分隔符的话，就给中间段加上明确的字符类约束，比如用t.match(/^[a-z]+$/)卡掉斜杠和数字，歧义就会大大减少。

4.4 与 TypeScript 分工，不抢饭碗

有朋友问我：不是已经用 TypeScript 了吗？为什么还需要运行时检查器？

这个问题的答案其实很简单：TypeScript 是编译期类型约束，运行时就消失了。任何从外部进入的数据——接口响应、用户输入、localStorage 里翻出来的旧数据、第三方脚本传过来的消息——TS 都无法约束它们。typechecker 正好接管这种情况下运行时校验的职责。

我实际项目里经常这么分工：TypeScript 负责代码内部传递的数据形态，typechecker 负责代码边界处的数据守门。两边各干各的，不冲突也不重复，配合起来很顺手。

typechecker 本身也带了一套完整的 TypeScript 类型声明，.check()通过后的数据可以被收窄为精确类型，IDE 提示不会掉链子。

4.5 性能到底够不够用

这里直接给结论：对于常见场景，完全足够。

我在一个日请求量十万级的接口服务上做了基准测试，校验一个 5 层嵌套的订单对象，单次检查耗时在 5 微秒左右。处理每秒几百个请求的服务，这点开销可以忽略不计。模板匹配的路径参数提取基本也是微秒级。

真正要留心的反而是大数据量的数组。如果你用t.array(t.object(...))校验一个上万条记录的列表，逐条检查必然线性增长。这种情况建议只对首尾几条抽样检查，或者放到 worker 线程里跑，不要阻塞主线程。

typechecker 最划算的使用方式就是“入口集中校验 + 边界守门”，而不是把检查器撒到每个业务函数里到处调用。后者不仅会放大性能损耗，还会让校验规则变得零散混乱，反而违背了工具的设计初衷。

我在实际项目里用下来的体会是：任何时候拿到不可信的数据，先花两分钟写一个模板过一遍，省下来的调试时间远比这两分钟值。尤其是那种“联调时一切正常，线上偶发报错”的诡异问题，多半就是运行时数据结构没稳住。把入口卡住之后，这类问题基本绝迹。

如果你现在正被手写 if 校验搞得心烦，不妨用这个工具把校验规则收敛成声明式模板。轻量、直接、不绑架项目结构，试一试的成本很低，收益却很实在。后续我还打算支持 JSON Schema 导出和浏览器端独立的单文件版本，让校验规则能直接复用到别的平台，感兴趣的话可以持续关注。