Meteor check 包深度实战指南：轻量级参数校验与模式匹配

• 后端
• 前端
• 开发工具
• 移动开发

check是 Meteor 平台内置的轻量级参数校验与通用模式匹配包，专门用于在Meteor.publish、Meteor.methods等入口对传入参数做严格的类型与结构校验，防止任意对象（如 MongoDB selector）被当作参数传入。读完本文，你将掌握check()的全部用法、Match命名空间下所有匹配模式的语义差异、底层匹配引擎的实现原理，以及如何借助Match.Error、throwAllErrors和参数审计机制写出安全可靠的 Meteor 应用代码。

check 包是什么：一句话定位与适用场景

根据 packages/check/README.md 的定义：check是一个用于参数检查（argument checking）和通用模式匹配（pattern matching）的轻量级包。它的核心目标是"在运行时断言一个值是否符合某个模式"，如果不符合，立即抛出Match.Error。

它在当前仓库中的实现位于 packages/check/match.js，包描述为"Check whether a value matches a pattern"，当前版本为 1.5.0（见 packages/check/package.js）。该包依赖ecmascript与ejson，对外导出check和Match两个全局符号，可在客户端与服务端同时使用（locus: Anywhere）。

典型应用场景非常明确：

• Method 方法入口：校验客户端传来的参数类型与结构，防止脏数据进入业务逻辑；
• Publication 发布入口：例如确保roomId是字符串，而不是一个任意的 Mongo selector 对象，避免订阅接口被滥用；
• 任何函数边界的防御式校验：作为轻量级的运行时断言工具。

快速上手：来自官方 README 的典型用法

原文档给出的示例完整展现了该包的两个经典使用场景，这里原样继承并补充说明：

Meteor.publish("chats-in-room", function (roomId) { // 确保 roomId 是字符串，而不是一个任意的 mongo selector 对象。 check(roomId, String); return Chats.find({room: roomId}); }); Meteor.methods({addChat: function (roomId, message) { check(roomId, String); check(message, { text: String, timestamp: Date, // 可选字段：如果存在则必须是字符串数组。 tags: Match.Optional([String]) }); // ... do something with the message ... }});

要点拆解：

1. check(roomId, String)：断言roomId是原始字符串类型。若客户端传入{room: "xxx"}这类对象，check会立即抛出Match.Error，发布逻辑不会继续执行；
2. check(message, {...})：断言message是一个普通对象，其中text必须是字符串、timestamp必须是Date实例、tags若存在则必须是字符串数组；
3. Match.Optional([String])：声明tags为可选字段——对象中缺少该键时不报错，一旦出现则该值必须匹配[String]模式。

这正是本包与手写if (typeof x !== 'string')的最大区别：一个声明式模式即可表达"对象 + 必填键 + 可选键 + 嵌套数组 + 元素类型"的完整结构约束。

check() 函数签名与行为

check的函数签名定义在 packages/check/match.js：

export function check(value, pattern, options = { throwAllErrors: false }) { // ... const result = testSubtree(value, pattern, options.throwAllErrors); if (result) { if (options.throwAllErrors) { throw Array.isArray(result) ? result.map(r => format(r)) : [format(result)] } else { throw format(result) } } }

参数说明：

行为要点：

• 匹配成功：静默返回，无副作用；
• 匹配失败：抛出Match.Error（默认模式），错误对象上带有描述性的message与定位失败字段的path；
• throwAllErrors: true：抛出的是一个Match.Error数组，数组中每个元素对应一个独立的失败点；
• 与Match.test()不同，check()会与内部参数审计机制（见后文）交互，记录"哪些参数已经被检查过"。

可用的匹配模式（Match Patterns）全集

所有模式都通过Match命名空间（定义于 packages/check/match.js）或直接使用 JS 原生类型构造。下面按匹配语义逐一展开。

基础类型：String / Number / Boolean / Function / undefined

String、Number、Boolean、Function、undefined五种可以直接作为模式使用，匹配规则是严格的typeof比较。注意两点：

• 模式匹配不包含装箱对象（boxed objects）：new String('foo')不能匹配String模式（源码注释 "Do not match boxed objects"，测试见 packages/check/match_test.js）；
• NaN、Infinity均属于Number类型，可以匹配Number模式（见 match_test.js）。

check('hello', String); // 通过 check(42, Number); // 通过 check(true, Boolean); // 通过 check(function(){}, Function); // 通过 check(undefined, undefined); // 通过 check(new String('x'), String); // 抛出 Match.Error

null 与字面量匹配

• null作为模式时，只匹配值为null的情况；
• 字符串、数字、布尔值作为模式时，采用字面量精确匹配（value === pattern），配合Match.OneOf可用于枚举白名单。相关实现见 match.js，测试覆盖于 match_test.js。

check(null, null); // 通过 check('asdf', 'asdf'); // 通过 check(123, 123); // 通过 check('123', 123); // 抛出 Match.Error（类型与值都不同）

Match.Any

Match.Any匹配任意值，包括undefined、null、函数等一切内容。它在源码中实现为一个特殊的数组标记['__any__']，在 testSubtree 中首先被短路判断：

if (pattern === Match.Any) { return false; // 表示匹配成功 }

Match.Integer

Match.Integer只匹配有符号 32 位整数（signed 32-bit integers），即满足(value | 0) === value的 number。源码在 match.js 中给出了选择位运算方案的原因：JS 中判断整数常用的"取余数"方案在超大浮点数（如1.348192308491824e+23）上会误判为整数，而位运算虽然会把数值强制转换为 32 位有符号整数，但行为是确定且一致的。

check(-1, Match.Integer); // 通过 check(2147483647, Match.Integer); // 通过（INT_MAX） check(123.33, Match.Integer); // 失败 check(NaN, Match.Integer); // 失败 check(Infinity, Match.Integer); // 失败 check(1.348192308491824e+23, Match.Integer); // 失败（32 位溢出场景）

边界行为（均已被 match_test.js 验证）：-2147483648（INT_MIN）与2147483647（INT_MAX）通过；NaN、±Infinity、对象、数组、函数、Date实例全部失败。

Match.NonEmptyString

Match.NonEmptyString匹配非空字符串。它在源码内部被转换为一个Match.Where条件（match.js），该条件先check(value, String)再要求value.length > 0：

function nonEmptyStringCondition(value) { check(value, String); return value.length > 0; }

check('xx', Match.NonEmptyString); // 通过 check('', Match.NonEmptyString); // 失败

数组模式：[pattern]

单个元素组成的数组[pattern]表示同构数组：要求值本身是数组（或类数组的arguments对象），且每个元素都匹配pattern。源码处理见 match.js。注意：

• 模式数组必须恰好一个元素，否则报Bad pattern: arrays must have one type element；
• 空数组[]匹配任何[pattern]（matches([], [Number])通过，match_test.js）；
• 不支持异构数组，这是源码注释中明确列出的不支持项（"Things we explicitly do NOT support: heterogenous arrays"）；
• arguments对象会被当作数组处理（通过isArguments判断，见 match.js），相关测试见 match_test.js；
• 数组模式可以嵌套：[[[String]]]表示三维字符串数组。

check([1, 2, 3], [Number]); // 通过 check([], [Number]); // 通过 check([1, '4'], [Number]); // 失败 check([1, 2, [3]], [Number]); // 失败（嵌套数组元素） check(arguments, [Number]); // 通过（函数内）

对象模式：{key: pattern}

直接传入一个普通对象字面量作为模式，表示对对象的结构校验：每个键对应一个子模式，未用Match.Optional/Match.Maybe包裹的键为必填键，缺失时报Missing key 'xxx'；而模式中未声明的键则一律报Unknown key错误（不允许有多余键）。

check({a: 1, b: 2}, {b: Number, a: Number}); // 通过（键顺序无关） check({a: 1, b: 2}, {b: Number}); // 失败（Unknown key: a） check({}, {a: Number}); // 失败（Missing key 'a'） check({foo: 42}, {}); // 失败（Unknown key: foo）

更重要的限制是：对象模式只匹配普通对象（plain object）。源码在 match.js 中通过isPlainObject判断，而该实现是 jQuery 3.1.1isPlainObject的服务端复制版（见 packages/check/isPlainObject.js）。因此：

• 类实例（new F()）即使结构完全一致也不匹配对象模式（match_test.js）；
• Date、RegExp等内置对象不匹配{}；
• 通过Object.create(parentObj)继承得到的对象不匹配（match_test.js）；
• 注意Object作为模式是Match.ObjectIncluding({})的简写，即"任意普通对象"（match.js）。

Match.ObjectIncluding

Match.ObjectIncluding(pattern)表示部分匹配：模式中声明的键必须存在且匹配，但允许值对象带有额外的未知键。源码实现将unknownKeysAllowed置为true（match.js）。

check({a: 1, b: 2}, Match.ObjectIncluding({b: Number})); // 通过（a 被忽略） check({a: 1, b: 2}, Match.ObjectIncluding({c: String})); // 失败（Missing key 'c'）

当需要"只要某个字段存在且合法"时非常有用，例如校验 MongoDB 文档的局部字段。

Match.ObjectWithValues

Match.ObjectWithValues(pattern)匹配"键任意、但所有值都必须匹配 pattern"的对象。源码将其unknownKeysAllowed置为true且设置unknownKeyPattern，pattern本身被替换为空对象（无必填键），见 match.js。

check({}, Match.ObjectWithValues(Number)); // 通过（空对象） check({x: 1, y: 2}, Match.ObjectWithValues(Number)); // 通过 check({x: 1, y: '2'}, Match.ObjectWithValues(Number)); // 失败（y 不是数字）

Match.Optional 与 Match.Maybe

这是最容易混淆的一对模式，二者语义存在微妙但关键的区别（match.js 展示了它们的展开逻辑）：

实现上，Optional被展开为Match.OneOf(undefined, p)，Maybe被展开为Match.OneOf(undefined, null, p)。测试中的关键断言（match_test.js）：

check(null, Match.Optional(String)); // 失败（Optional 不接受 null） check(undefined, Match.Optional(String)); // 通过 check(null, Match.Maybe(String)); // 通过 check({}, {a: Match.Optional(Number)}); // 通过（键缺失） check({a: undefined}, {a: Match.Optional(Number)}); // 失败（键存在但值为 undefined） check({a: undefined}, {a: Match.Maybe(Number)}); // 失败（对象内行为同 Optional）

设计动机在 packages/check/check.d.ts 的类型注释中说明：undefined参数通过 DDP 传输到服务端后会被转换成null，因此对于"客户端可能不传该参数"的字段，服务端需要使用Match.Maybe才能同时容忍缺省（undefined）与空值（null）。

Match.OneOf

Match.OneOf(...patterns)匹配"至少命中一个子模式"的情况，常与字面量、null、Boolean组合实现枚举或联合类型校验：

check(42, Match.OneOf('asc', 'desc', 42)); // 通过 check('foo', Match.OneOf(String, Number)); // 通过 check(3, Match.OneOf(null, Boolean)); // 失败（3 不是 null 也不是布尔）

注意构造约束：OneOf至少要提供一个选项，否则抛Must provide at least one choice to Match.OneOf（match.js）。此外，Optional与Maybe本质上都是OneOf的特殊形式，因此OneOf的失败错误消息中会同时提及三者（Failed Match.OneOf, Match.Maybe or Match.Optional validation）。

Match.Where

Match.Where(condition)允许传入自定义谓词函数进行任意校验。谓词有两种"通过"方式（match.js）：

1. 返回true；
2. 内部调用check()成功（即不抛错）。

若谓词返回false或抛出Match.Error，则匹配失败；若抛出其他类型错误，该错误会原样向外抛出（不会吞掉）。

check(42, Match.Where(x => x % 2 === 0)); // 通过 check(43, Match.Where(x => x % 2 === 0)); // 失败 check({}, Match.Where(EJSON.isBinary)); // 失败 // 谓词内部复用 check 的组合式写法： check('abc', Match.Where(x => { check(x, String); // 类型断言失败会以 Match.Error 形式向外传播 return x.length > 1; }));

构造函数模式（instanceof）

任意函数（非上述特例）都会被当作构造函数处理，使用instanceof判断（match.js）。因此Date、RegExp乃至自定义类都可以作为模式：

check(new Date, Date); // 通过 check(/foo/, RegExp); // 通过 check(new Date, Number); // 失败

Match.OneOf(Number, String)与自定义构造函数（如F）的组合也能正确工作，测试覆盖于 match_test.js。

Match.test：不抛异常的布尔校验

当只需要"判断而不抛错"时，使用Match.test(value, pattern)。它与check()的区别（match.js）：

• 仅返回true/false；
• 不参与参数审计机制（不会记录参数已被检查）；
• 不会把错误转换为Meteor.Error；
• 若匹配过程中抛出Match.Error以外的错误，会向上抛出。

if (Match.test(roomId, String)) { // ... }

在 match_test.js 中，测试辅助函数同时断言"check不抛错 ⇔Match.test返回 true"、"check抛Match.Error⇔Match.test返回 false"，说明二者共享同一套testSubtree匹配引擎，语义完全一致。

解析 Match.Error：消息、路径与 DDP 场景下的处理

Match.Error是通过Meteor.makeErrorType创建的错误类型（match.js），具有三个关键属性：

1. message：以Match error:为前缀，内容形如Expected string, got number、Missing key 'bar'、Expected Integer, got 3.14；
2. path：定位失败字段的路径字符串，从空字符串开始，随错误在递归中回溯逐级拼接，形如foo[1].bar、[0].$FoO["bar baz\n\"'"]、$set.people；
3. sanitizedError：一个Meteor.Error(400, 'Match failed')。这是为 DDP 场景设计的——当错误跨网络传输到客户端时，不会泄露服务端内部细节，而是给出一个干净且比"500 Internal server error"更有意义的 400 错误。

错误路径的格式化规则由_prependPath实现（match.js）：数字索引使用方括号[i]；合法标识符使用点号.key；包含空格、引号、$或 JS 关键字（如return）的键会被 JSON 序列化后放入方括号。测试中的断言示例（match_test.js）：

check({foo: [{bar: 3}, {bar: 'something'}]}, {foo: [{bar: Number}]}) // 失败路径：foo[1].bar // 失败消息：Match error: Expected number, got string in field foo[1].bar

throwAllErrors：一次性收集全部校验错误

默认情况下check在第一个错误处立即抛出（fail-fast）。传入{ throwAllErrors: true }后，testSubtree会以collectErrors模式遍历整个值结构，收集所有失败点并以Match.Error数组形式抛出（match.js）。

该模式在 match_test.js 中有一个深度嵌套的综合用例：一个包含text、emails、things、stuff、maybe、opt、int、oneOf、where、embedded等十余个字段的复杂对象，在多种模式约束下一次性收集到 40 个Match.Error，并精确断言了其中的缺键错误：

try { check(value, pattern, {throwAllErrors: true}); } catch (e) { // e 是一个 Match.Error 数组，例如： // [ // Match error: Missing key 'another' in field embedded, // Match error: Missing key 'missing1', // Match error: Missing key 'missing2', // ... // ] }

适用场景：表单提交、批量数据处理等"希望一次告诉调用方所有问题"的校验需求；而交互式 Method 调用通常更适合默认的 fail-fast 行为。

源码探秘：testSubtree 递归匹配引擎

所有模式匹配的最终执行者是内部函数testSubtree(value, pattern, collectErrors, errors, path)（match.js）。它的工作方式值得关注：

1. 短路优先：先判断Match.Any，再遍历typeofChecks表（String/Number/Boolean/Function/undefined与typeof结果的映射表，match.js）完成基础类型匹配；
2. 类型分派：按null→ 字面量 →Match.Integer→ 数组 →Where→Maybe/Optional（先展开为OneOf）→OneOf→ 构造函数 → 对象模式的顺序逐层分派。注意数组分支必须在Match.Any之后判断，因为Match.Any自身就是以数组形式编码的；
3. 对象模式两阶段：先扫描值的每个键（必填键校验、可选键校验、未知键拒绝），再检查剩余未消费的必填键并生成Missing key错误；
4. 错误收集：collectErrors为 true 时，结果对象携带完整path并入数组，最终返回整个错误数组；否则任一失败立即返回。

对象模式只接受普通对象这一约束值得再次强调——源码在 match.js 中显式报错Expected plain object，其背后的isPlainObject严格检查"由全局Object构造函数创建的、或原型为 null 的对象"（packages/check/isPlainObject.js）。

参数审计：_failIfArgumentsAreNotAllChecked 与 audit-argument-checks

check包还提供了一套"强制所有参数都被检查"的审计机制：Match._failIfArgumentsAreNotAllChecked(f, context, args, description)（match.js）。其工作原理：

• 将args做浅拷贝后压入一个ArgumentChecker（栈结构，见 match.js）；
• 通过currentArgumentChecker（一个Meteor.EnvironmentVariable）在执行函数f期间挂载该检查器；
• 每次调用check()时，被检查的值会从参数栈中"注销"；
• 函数执行完毕后，若仍有参数未被任何check()覆盖，抛出Did not check() all arguments during ${description}。

这套机制在 DDP 服务端被实际使用：packages/ddp-server/livedata_server.js 中的maybeAuditArgumentChecks会在audit-argument-checks包存在时，用Match._failIfArgumentsAreNotAllChecked包裹 Method 与 Publish 的处理函数，从而在开发阶段强制开发者对每个传入参数都做check()。这正是 packages/audit-argument-checks 包存在的意义——它本身不含业务代码，仅通过弱依赖关系激活这套审计。测试覆盖见 match_test.js，其中甚至验证了 NaN 参数、check(args, [Number])批量检查等边界场景。

在 Meteor 生态中的真实应用

check不只是独立工具包，它被 Meteor 自身的核心包广泛使用，以下是仓库内的几个真实落点：

• packages/allow-deny/allow-deny.js：allow/deny方法包装层使用check(arguments, [Match.Any])统一声明"所有参数都已被有意处理"；
• packages/allow-deny/allow-deny.js：_validatedUpdateAsync中check(mutator, Object)校验更新操作符必须是普通对象；
• packages/ddp-server/livedata_server.js：如上所述，Method/Publish 调用的参数审计入口；
• packages/accounts-base/accounts_server.js、packages/accounts-password/password_server.js、packages/constraint-solver/solver.js 等均有大量Match.*模式用于校验内部数据结构（如用户名、邮箱、密码选项）。

这些调用印证了check在 Meteor 中的定位：它是框架自身也在依赖的运行时类型系统，而不仅仅是面向应用开发者的工具。

TypeScript 支持：check.d.ts

该包同时提供完整的 TypeScript 类型声明 packages/check/check.d.ts（作为资产打包在服务端），核心是两个高级类型：

• Match.Pattern：递归定义所有合法模式类型——typeof String/Number/Boolean/Object/Function、构造函数、undefined | null | string | number | boolean、[Pattern]、{[key: string]: Pattern}以及实现了Matcher<T>接口的Match.*结果；
• Match.PatternMatch<T>：把模式类型映射为对应的值类型，例如typeof String → string、[Pattern] → PatternMatch<T>[]、对象模式 → 同构对象类型。

基于此，check被声明为类型守卫（type guard / assertion function）：

export declare function check<T extends Match.Pattern>( value: any, pattern: T, options?: { throwAllErrors?: boolean } ): asserts value is Match.PatternMatch<T>;

也就是说，在 TypeScript 项目中执行check(x, String)之后，编译器会自动把x收窄为string，实现"一次校验，运行期与编译期双重保障"。Match.test同样声明了value is PatternMatch<T>的类型谓词。

测试验证：match_test.js 关键用例

完整的测试套件位于 packages/check/match_test.js（通过 packages/check/package.js 注册到 client 与 server 两端运行），主要覆盖：

这套测试既是行为规范，也是学习check语义边界的绝佳参考：例如Optional不接受null、Maybe接受null、{a: undefined}不通过{a: Match.Maybe(Number)}等微妙规则，都能在测试中找到明文断言。

最佳实践小结

1. 在每个 Method / Publish 入口的第一行就check参数，在业务逻辑接触数据之前拦截非法输入；
2. 能用声明式模式就用手写判断：check(message, {...})的可读性与可维护性远胜一串if/else；
3. 正确区分Optional与Maybe：仅在"接受缺省"时用Optional；当字段可能以null形式经 DDP 传输时使用Maybe；
4. 对象字面量模式默认拒绝未知键，这有助于收紧接口契约；需要宽容时显式使用Match.ObjectIncluding；
5. 用Match.Where表达无法用类型组合描述的业务规则，并在谓词内复用check以获得精确的错误信息；
6. 开发期引入audit-argument-checks包，强制自己检查每一个参数，避免漏检；
7. 结合Match.test做条件判断，只在真正需要"失败即抛错"的边界处使用check；
8. 在 TypeScript 项目中使用check的类型守卫能力，让运行时校验同时完成编译期类型收窄。

check是 Meteor 体系中一个体积小、价值大的基础设施包：它把"参数校验"从零散的样板代码提升为一种可组合、可递归、可审计的声明式能力，并在框架自身的 DDP、权限校验与账户系统中被反复验证。掌握了它，你就掌握了 Meteor 应用的第一道安全防线。

• 后端
• 前端
• 开发工具
• 移动开发