企业官网建设流程全解析

es-toolkit 兼容层ary函数详解：限制函数实参数量，彻底规避回调参数陷阱

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit

ary是 es-toolkit 兼容层（es-toolkit/compat）提供的 Lodash 兼容函数，用于创建一个限制实参接收数量的新函数。本文以 docs/compat/reference/function/ary.md 为主线，结合 src/compat/function/ary.ts、src/function/ary.ts 及配套测试源码，完整讲解ary的用法、边界行为、底层实现原理，并给出在map回调等场景下规避多余参数陷阱的实战方案。

一、ary是什么：一句话概括核心能力

ary创建的新函数会把实际接收到的实参裁剪到最多n个，超出的参数一律忽略：

const cappedFunction = ary(func, n);

它最典型的应用场景有两类：

1. 安全使用那些会接收过多实参的函数，避免多余参数污染函数内部逻辑；
2. 在回调函数中忽略不必要的参数，例如数组方法map会向回调额外传入索引和数组本身，ary可以阻止这些参数泄漏进业务函数。

在 es-toolkit 中，ary有两个入口：

本文以兼容版为主（即关联文档所述），同时会对比现代核心版的实现差异。

二、基础用法：按需裁剪实参数量

import { ary } from 'es-toolkit/compat'; // 基本用法 function greet(name, age, city) { return `Hello, ${name}! ${age} years old, from ${city}.`; } const limitedGreet = ary(greet, 2); console.log(limitedGreet('John', 30, 'Seoul', 'extraArg')); // "Hello, John! 30 years old, from undefined." // 从第 3 个实参开始全部被忽略

当limitedGreet被调用时，只有前两个参数'John'和30被传入greet，'Seoul'与'extraArg'被丢弃，因此city的值为undefined。

说明：文档示例中greet是普通函数，类型上ary兼容层接受任意(...args: any[]) => any形式的函数（见 src/compat/function/ary.ts），因此 JavaScript 场景下可直接使用。

三、实战场景一：修复map+parseInt的经典陷阱

数组方法map的回调会收到三个参数：当前元素、当前索引、整个数组。而parseInt的第二个参数是进制基数（radix），于是直接写numbers.map(parseInt)时，索引值会被当作进制基数传入，产生匪夷所思的结果：

import { ary } from 'es-toolkit/compat'; const numbers = ['1', '2', '3', '4', '5']; // 错误用法——parseInt 把索引当作进制基数接收 console.log(numbers.map(parseInt)); // [1, NaN, NaN, NaN, NaN] // 用 ary 只传第一个参数 console.log(numbers.map(ary(parseInt, 1))); // [1, 2, 3, 4, 5]

这是因为parseInt('2', 1)、parseInt('3', 2)等调用中的第二个参数（索引1、2……）并非合法进制，导致解析结果为NaN。用ary(parseInt, 1)包一层后，map传入的多余参数全部被裁剪，parseInt只会收到字符串本身，结果回归正确。

这一场景同样出现在现代核心版文档 docs/reference/function/ary.md 中，也是ary在函数式编程里最经典的价值体现：防止回调函数接收到预期之外的参数。

四、实战场景二：精确控制可变参数函数的入参个数

对于使用剩余参数（rest parameters）收集所有实参的函数，ary可以精确限定其实际能“看见”的参数个数：

import { ary } from 'es-toolkit/compat'; function sum(...args) { return args.reduce((total, num) => total + num, 0); } const sum0 = ary(sum, 0); const sum1 = ary(sum, 1); const sum2 = ary(sum, 2); const sum3 = ary(sum, 3); console.log(sum0(1, 2, 3, 4, 5)); // 0（一个参数都不接收） console.log(sum1(1, 2, 3, 4, 5)); // 1（只接收第一个参数） console.log(sum2(1, 2, 3, 4, 5)); // 3（只接收前两个参数） console.log(sum3(1, 2, 3, 4, 5)); // 6（只接收前三个参数）

注意sum通过...args收集的是实际传入的参数，因此ary(sum, 2)调用后，args只有[1, 2]，求和结果为3。

五、边界行为：负数与NaN一律按 0 处理

兼容版ary遵循 Lodash 语义：当传入的n是负数或NaN时，会被当作0处理，即所有实参都被忽略：

import { ary } from 'es-toolkit/compat'; const func = (a, b, c) => [a, b, c]; console.log(ary(func, -1)(1, 2, 3)); // [undefined, undefined, undefined]（负数按 0 处理） console.log(ary(func, NaN)(1, 2, 3)); // [undefined, undefined, undefined]（NaN 按 0 处理）

上述行为可以在源码中找到直接依据。兼容版实现 src/compat/function/ary.ts 中：

if (Number.isNaN(n) || n < 0) { n = 0; }

此外，兼容层还会把n强制转换为整数（对应测试 src/compat/function/ary.spec.ts：'1'被当作1、1.6被当作1、无法转换的'xyz'被当作0），这正是关联文档开篇警告“该函数因复杂参数校验而运行较慢”的根源所在。

六、参数与返回值说明

ary(func, n)

参数

返回值

Function：一个新函数，最多接收n个实参。

n省略时的默认值行为同样有源码佐证——兼容版在函数签名中直接声明了默认参数n: number = func.length（src/compat/function/ary.ts），测试也验证了这一点：ary(fn)后传入 4 个实参，最终只保留 3 个（因为fn声明了 3 个形参，见 src/compat/function/ary.spec.ts）。

七、源码级剖析：兼容层如何复用现代核心实现

这是理解ary的关键。兼容版并没有重新实现裁剪逻辑，而是先做 Lodash 风格的参数校验，再委托给现代核心版：

import { ary as aryToolkit } from '../../function/ary.ts'; export function ary<F extends (...args: any[]) => any>( func: F, n: number = func.length, guard?: unknown ): (...args: any[]) => ReturnType<F> { if (guard) { n = func.length; } if (Number.isNaN(n) || n < 0) { n = 0; } return aryToolkit(func, n); }

（完整实现见 src/compat/function/ary.ts）

其中值得注意的两点：

1. 第三个隐藏参数guard：这是为了兼容 Lodash 内部调用约定而保留的守卫参数。当guard为真值时，n会被强制重置为func.length。普通用户无需关心，但它是兼容层“复杂参数校验”的一部分。
2. 委托关系：校验完成后直接调用 src/function/ary.ts 中的核心实现。现代核心版极其精简，只做一件事：

export function ary<F extends (...args: any[]) => any>(func: F, n: number): (...args: any[]) => ReturnType<F> { return function (this: any, ...args: Parameters<F>) { return func.apply(this, args.slice(0, n)); }; }

核心逻辑就是args.slice(0, n)截取前n个实参后通过func.apply(this, ...)调用，同时保留了this绑定。这一点也有测试覆盖：以对象方法形式调用被裁剪的函数时，this仍然指向该对象（src/compat/function/ary.spec.ts）。

因此，两个版本的性能差异完全来自兼容层多出的类型转换、NaN/负数检查与guard判断；如果你不需要 Lodash 的这些特殊语义，直接使用es-toolkit/function的ary即可获得更快的执行速度。

八、与兄弟函数的关系：unary等

兼容层中的unary（限制为最多接收 1 个实参）就是基于ary实现的：

export function unary<T, U>(func: (arg1: T, ...args: any[]) => U): (arg1: T) => U { return ary(func, 1); }

（见 src/compat/function/unary.ts）

也就是说，unary(fn)等价于ary(fn, 1)。ary是整个“实参数量控制”家族的基础原语，unary只是它的特例；相关函数还包括rest、spread等，它们共同构成函数式编程中控制参数传递的工具集。

九、边界行为与测试验证

兼容版ary的行为在 src/compat/function/ary.spec.ts 中有系统化验证，归纳如下：

其中“嵌套使用”值得单独说明：ary(ary(fn, 1), 2)的调用结果只接收 1 个实参，因为内层裁剪已经生效，外层无法“恢复”被丢弃的参数——ary只能减少实参，不能增加。

十、如何选择：兼容版还是现代核心版

关联文档 docs/compat/reference/function/ary.md 在开篇就给出了明确建议：

兼容版的ary因复杂的参数校验而运行较慢，建议改用 es-toolkit 现代核心版 ary。

• 需要严格对齐 Lodash 语义（例如依赖n省略时取func.length、负数/NaN按 0 处理、支持隐藏guard参数等）时，使用es-toolkit/compat的ary；
• 追求性能与代码简洁、且只需“截断实参”这一核心能力时，直接使用es-toolkit/function的ary。

两种版本的导出入口可以在 src/compat/compat.ts（export { ary } from './function/ary.ts'）与 src/function/index.ts 中确认，测试用例位于 src/compat/function/ary.spec.ts，文档参考可见 docs/compat/reference/function/ary.md 与 docs/reference/function/ary.md。

总结

ary是一个小而关键的函数式编程工具：它通过裁剪实参，规避了回调参数泄漏、parseInt进制陷阱等一类经典问题。兼容层版本完整继承了 Lodash 的参数校验语义（默认取func.length、负数与NaN归零、整数强制转换、隐藏guard参数），并最终委托给现代核心版 src/function/ary.ts 完成args.slice(0, n)的轻量裁剪。理解了这一层委托关系，你就能在“Lodash 兼容”与“极致性能”之间做出正确的选择。

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit