es-toolkit 兼容层 matches 深度指南用 Lodash 风格谓词实现结构化部分匹配【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkitmatches是 es-toolkitcompat兼容层提供的一个高阶函数它根据一个给定的模式pattern创建谓词函数用于判断目标对象是否与该模式在结构与取值上部分匹配。本文以 matches 官方参考文档 为主体结合 matches 源码实现、其底层 isMatch / isMatchWith 实现 以及 matches 测试用例完整讲解该函数的 API、匹配规则、边界行为与实战用法帮助你在数组过滤、对象检索、数据校验等场景中写出声明式、可复用的匹配逻辑。一、matches是什么一行代码创建可复用匹配器matches(pattern)接收一个模式source返回一个类型为(target: unknown) boolean的谓词函数。之后你只需把任意目标值传给该谓词即可得知目标值是否部分匹配这个模式——即模式中的所有键值对都能在目标中找到对应的匹配而目标中额外的属性不会影响结果。const matcher matches(pattern);这一工厂函数的形态让它天然适合与Array.prototype.filter、find、some、every等需要回调的 API 组合使用避免了在每次回调中重复编写匹配逻辑。从源码层面看matches.ts 的实现极其简洁export function matchesT, V(source: T): (target: V) boolean { source cloneDeep(source); return (target?: unknown): boolean { return isMatch(target as object, source as object); }; }其中有两个关键设计调用时立即cloneDeep深拷贝模式匹配器创建后即使后续修改原始模式对象也不会影响匹配行为测试用例 matches.spec.ts 专门验证了这一点。委托给isMatch做深度比较真正的匹配逻辑在底层的 isMatch.ts 中而isMatch又进一步委托给支持自定义比较器的 isMatchWith.ts。二、基本用法对象、嵌套对象与数组匹配matches的核心价值在于对任意嵌套结构做部分匹配。以下是官方文档中的三类典型场景。1. 对象模式匹配import { matches } from es-toolkit/compat; // Object pattern matching const userMatcher matches({ age: 25, department: Engineering }); const users [ { name: Alice, age: 25, department: Engineering }, { name: Bob, age: 30, department: Marketing }, { name: Charlie, age: 25, department: Engineering }, ]; const engineeringUsers users.filter(userMatcher); // [{ name: Alice, age: 25, department: Engineering }, // { name: Charlie, age: 25, department: Engineering }]注意Alice和Charlie都带有模式中没有的name属性但依然被匹配——这正是部分匹配的含义模式是目标的子集即视为匹配。2. 嵌套对象模式匹配// Nested object pattern const profileMatcher matches({ profile: { city: Seoul, verified: true }, }); const profiles [ { name: Kim, profile: { city: Seoul, verified: true, score: 100 } }, { name: Lee, profile: { city: Busan, verified: true } }, { name: Park, profile: { city: Seoul, verified: false } }, ]; const seoulVerifiedUsers profiles.filter(profileMatcher); // [{ name: Kim, profile: { city: Seoul, verified: true, score: 100 } }]嵌套匹配会递归进行Kim的profile中多出的score不影响匹配而Lee的城市不符、Park的verified为false均被排除。3. 数组模式匹配// Array pattern matching const arrayMatcher matches([2, 4]); const arrays [ [1, 2, 3, 4, 5], [2, 4, 6], [1, 3, 5], ]; const matchingArrays arrays.filter(arrayMatcher); // [[1, 2, 3, 4, 5], [2, 4, 6]]数组匹配是顺序无关的部分匹配[1, 2, 3, 4, 5]中包含了 2 和 4 因此命中[2, 4, 6]本身就以 2、4 开头同样命中而[1, 3, 5]缺少这两个元素被排除。4. 空模式匹配一切// Empty pattern matches all values const emptyMatcher matches({}); emptyMatcher({ anything: value }); // true emptyMatcher([]); // true emptyMatcher(null); // true空对象模式对任意目标包括null和undefined都返回true。源码层面isMatchWithInternal 中对source null直接返回true对象匹配分支中keys.length 0也返回true空数组、空 Map、空 Set 同理详见 isObjectMatch 与 isMapMatch。参数与返回值参数sourceunknown——作为匹配模式的对象或值。返回值(target: unknown) boolean——判断给定值是否部分匹配该模式的函数。三、类型签名两个泛型重载matches.ts 提供了两组重载分别适用于已知目标类型与未知目标类型两种场景// 目标类型未知默认为 any export function matchesT(source: T): (value: any) boolean; // 目标类型由调用方指定 export function matchesT, V(source: T): (value: V) boolean;// 显式指定模式类型 T 与目标类型 V const matcher matches{ a: number }, { a: number; b?: number }({ a: 1 }); matcher({ a: 1, b: 2 }); // true matcher({ a: 2 }); // false第二组重载让 TypeScript 能够对匹配目标做类型约束适合在类型严格的项目中使用。四、底层原理matches→isMatch→isMatchWith的调用链matches本身只做深拷贝 委托真正负责深度比较的是 isMatch.tsexport function isMatch(target: object, source: object): boolean { return isMatchWith(target, source, () undefined); }传入() undefined作为默认比较器表示不进行自定义比较全部走默认逻辑。默认逻辑位于 isMatchWith.ts 的isMatchWithInternal其按数据类型分派对象Object模式中所有键必须存在于目标中且对应值递归匹配key in target判断同时支持目标继承的字符串键属性测试用例见 matches.spec.ts而模式自身的继承属性不参与匹配matches.spec.ts。数组Array模式数组中的每个元素都要能在目标数组中找到匹配项且已匹配的下标不会被重复使用countedIndex集合保证见 isArrayMatch因此[2, 2]无法匹配只有单个 2 的数组。Map模式 Map 中每个键值对都必须存在于目标 MapisMapMatch。Set模式 Set 的每个元素都必须在目标 Set 中isSetMatch内部转为数组匹配实现。函数Function无自有属性的函数按引用严格相等比较带自有属性的函数则展开为对象进行属性匹配isMatchWithInternal。原始值Primitive使用eq做严格比较其中-0与0视为相等matches.spec.ts。此外还内置了两项健壮性设计循环引用防护通过内部stack: Map记录源对象 → 目标对象的映射遇到重复引用时直接复用比较结果避免无限递归isObjectMatch。根级与嵌套级行为差异嵌套的空对象模式只匹配对象类目标不匹配字符串等原始值——测试用例matches({ value: {} })({ value: bar })返回false而matches({ value: {} })({ value: { b: 1 } })返回truematches.spec.ts。五、特殊值语义undefined、null与原始值目标matches对undefined和null的处理非常精细测试用例 matches.spec.ts 给出了完整行为// 模式中的 undefined 要求目标对应键存在且值为 undefined const objects1 [{ a: 1 }, { a: 1, b: 1 }, { a: 1, b: undefined }]; objects1.map(matches({ b: undefined })); // [false, false, true]即模式中b: undefined只有在目标真的拥有b且其值为undefined时才命中目标缺少该键{ a: 1 }或值为其他{ a: 1, b: 1 }都不匹配。null的语义同理。这一规则由 isObjectMatch 中的显式检查实现。另外模式非空时目标为null/undefined一律返回falsematches.spec.ts。模式为空{}时目标即使为null/undefined也返回truematches.spec.ts。在根级原始值目标会被包装为对象后再匹配isPrimitive(target)时target Object(target)因此matches({ a: 1, b: undefined })(1)这类调用不会抛错matches.spec.ts。六、实战场景从筛选到数据校验matches的返回值是标准谓词可以无缝嵌入各类数据处理管线。1. 声明式数组过滤import { matches } from es-toolkit/compat; // 组合多个条件年龄 25 且部门为 Engineering const users [...]; const result users.filter(matches({ age: 25, department: Engineering }));2. 对象检索与条件判断// 在配置列表中查找目标配置 const configs [{ env: dev, features: { darkMode: true, beta: false } }, /* ... */]; const devConfig configs.find(matches({ env: dev, features: { darkMode: true } }));3. 与isMatch的直接比较如果你只需要一次性判断不必创建匹配器可以直接使用底层的isMatch(target, source)它接收两个对象而非返回谓词isMatch.ts。两者的匹配语义完全一致matches相当于isMatch的柯里化形态。4. 与matchesProperty的分工同目录下的 matchesProperty.ts 提供更窄的用途只检查目标对象某个属性路径上的值是否匹配。它支持点路径字符串如address.city或数组路径如[address, city]适合按单个字段筛选import { matchesProperty } from es-toolkit/compat; const checkNested matchesProperty([address, city], New York); checkNested({ address: { city: New York } }); // true checkNested({ address: { city: Los Angeles } }); // false当需要整体结构部分匹配时用matches当只需要某个属性等于某值时用matchesProperty。七、总结matches是 es-toolkitcompat层为 Lodash 兼容提供的结构化匹配工具其核心价值在于工厂化一次创建、多处复用天然适配filter/find/some等回调式 API深度部分匹配支持对象、嵌套对象、数组、Map、Set 以及函数属性模式为目标的子集即命中语义严谨undefined/null显式区分、-0与0相等、数组顺序无关且不重复消费下标、循环引用安全快照语义创建时深拷贝模式避免外部修改影响匹配结果类型友好双泛型重载可为目标值提供类型约束。如需进一步了解底层匹配的完整规则可深入阅读 isMatchWith.ts 及其配套测试 matches.spec.ts与其他compat谓词函数如matchesProperty、isMatch组合使用可以构建出灵活且可读的数据筛选与校验体系。【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考