es-toolkit 兼容 Lodash 的 wrap 函数：函数包装与高阶封装的完整实战指南-酒店常州论坛

es-toolkit 兼容 Lodash 的 wrap 函数：函数包装与高阶封装的完整实战指南

【免费下载链接】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

导读

wrap是 es-toolkit 在 compat（Lodash 兼容）模块中提供的函数包装工具，它允许你创建一个新函数，将原始值或函数作为第一个参数传给自定义的包装函数（wrapper），从而在原逻辑前后附加日志、性能测量、HTML 渲染等额外行为。本文以日文版兼容文档为核心骨架，结合 wrap 源码实现与 wrap 测试用例，带你掌握wrap的调用签名、三种典型用法（包装函数、包装非函数值、复杂包装）、参数/返回值语义，以及其底层this绑定与空值回退等实现细节，并给出与原生闭包方案的取舍建议。

一、`wrap`是什么：签名与定位

wrap(value, wrapper)会创建一个包装后的新函数。其 TypeScript 签名如下：

const wrappedFunc = wrap(value, wrapper);

完整的类型签名（见 wrap.ts 源码）：

export function wrap<T, U, V>( value: T, wrapper: (value: T, ...args: U[]) => V ): (...args: U[]) => V;

第一个参数value：被包装的值或函数（类型T）；
第二个参数wrapper：包装函数，它接收原始值作为第一个参数，并应用附加逻辑（类型(value: T, ...args: U[]) => V）；
返回值：一个应用了包装函数的新函数(...args: U[]) => V。

从 es-toolkit 源码结构看，wrap属于 compat（Lodash 兼容）层，与_.wrap行为对齐，通过 compat 模块入口导出：

export { wrap } from './function/wrap.ts';

使用时可从es-toolkit/compat导入：

import { wrap } from 'es-toolkit/compat';

使用建议：优先考虑高阶函数

原文档在开头给出了重要警示：wrap只是简单地将函数包装起来，在大多数场景下，使用更简洁的高阶函数（higher-order function）或闭包（closure）反而更清晰、更快速。它主要面向从 lodash 迁移到 es-toolkit 时保持行为一致的兼容场景。如果你正在编写新代码，请优先考虑直接定义闭包或高阶函数；只有需要与 Lodash 代码库保持等价语义时才选用wrap。

二、核心用法一：包装函数以附加额外逻辑

当你希望对一个已有函数追加"执行前/执行后"的额外行为时，可以把该函数作为value传入，包装函数将收到原始函数作为第一个参数。

示例：为函数添加日志功能

import { wrap } from 'es-toolkit/compat'; // 包装函数以添加日志功能 const greet = (name: string) => `Hi, ${name}`; const loggedGreet = wrap(greet, (originalFunc, name) => { const result = originalFunc(name); console.log(`[LOG] ${result}`); return result; }); loggedGreet('Alice'); // 控制台输出 "[LOG] Hi, Alice" 并返回 "Hi, Alice"

在这个例子中，originalFunc就是被包装的greet函数，包装函数在其调用前后插入了日志逻辑，同时保留原始返回值。

示例：为函数添加性能测量

原文档给出了更复杂的包装示例——在执行前后记录耗时：

import { wrap } from 'es-toolkit/compat'; const add = (a: number, b: number) => a + b; // 创建带性能测量功能的函数 const timedAdd = wrap(add, (originalAdd, a, b) => { const start = Date.now(); const result = originalAdd(a, b); const end = Date.now(); console.log(`执行时间: ${end - start}ms`); return result; }); timedAdd(3, 7); // 控制台输出执行时间，并返回 10

注意这里add是多参数函数（a、b），调用timedAdd(3, 7)时，除原始函数外的其余参数3、7会依次传给包装函数——这正是wrapper: (value: T, ...args: U[]) => V中...args的语义。

三、核心用法二：包装非函数值

wrap不仅支持函数，也支持包装任意值。此时该值会作为包装函数的第一个参数被传入，返回的函数则用于接收后续参数。

示例：用 HTML 标签包裹字符串

import { wrap } from 'es-toolkit/compat'; // 创建将字符串包裹进 HTML 标签的函数 const htmlWrapper = wrap('Hello World', (text, tag) => `<${tag}>${text}</${tag}>`); console.log(htmlWrapper('h1')); // "<h1>Hello World</h1>"

这里value = 'Hello World'被作为text传入包装函数，调用htmlWrapper('h1')时'h1'作为第二个参数tag传入。

示例：将数字用于计算

import { wrap } from 'es-toolkit/compat'; // 创建将数字用于计算的函数 const calculate = wrap(10, (baseValue, multiplier) => baseValue * multiplier); console.log(calculate(5)); // 50

10作为基数baseValue被固定下来，calculate(5)中5作为乘数传入，得到10 * 5 = 50。这种"值 + 参数"的组合方式，本质上是把一部分状态提前固化在闭包中。

四、参数与返回值详解

原文档对参数与返回值给出了明确说明，这里结合源码进一步展开：

参数

value（T）：要包装的值或函数。源码将其作为包装函数的第一个参数固定传入（见 wrap.ts：wrapFn.apply(this, [value, ...args])）。
wrapper（(value: T, ...args: U[]) => V)）：接收原始值作为第一个参数并应用附加逻辑的函数。调用wrapped(...args)时，...args会紧随value之后传递给wrapper。

返回值

(...args: U[]) => V：应用了包装函数的新函数。每次调用该新函数时，都会把固定的value与本次调用的参数合并，再调用wrapper。

源码中的两个关键实现细节

this绑定透传：源码中返回的函数声明为function (this: unknown, ...args: any[])，并通过wrapFn.apply(this, [value, ...args])调用包装函数（见 wrap.ts）。这意味着包装函数内的this与调用者保持一致，原文档与测试用例均验证了这一行为（详见下文第五节的this绑定测试）。
空值回退到 identity：源码使用isFunction(wrapper)（实现见 isFunction.ts，即typeof value === 'function'）判断包装函数是否有效；若wrapper为null、undefined等非函数值，则回退到identity（见 identity.ts，原样返回输入）。这一设计与 Lodash 中"wrapper 为空时使用_.identity"的语义保持一致，兼容性测试也专门覆盖了该分支。

五、源码与测试验证：从测试用例理解行为边界

wrap.spec.ts 使用 Vitest 编写，共 5 组用例，完整覆盖了wrap的行为边界，可作为理解该函数语义的权威依据：

创建包装函数：wrap(escape, (func, text) => ...)对 HTML 转义函数escape进行包装，验证输出为fred, barney & pebbles，即包装逻辑在原始函数之外生效。
wrapper 参数顺序：通过slice.call(arguments)捕获包装函数收到的全部参数，断言结果为[noop, 1, 2, 3]——原始函数noop永远排在第一，随后才是调用时传入的参数。
wrapper 为空值时使用 identity：对null、undefined等值，wrap('a', value)返回的函数直接透传参数（期望结果与stubA一致），印证了源码中的 identity 回退逻辑。
this绑定：wrap(escape, function (func) { return '' + func(this.text) + ''; })挂载到对象{ p, text: 'fred, barney & pebbles' }上后，object.p()能正确读取this.text，验证了this透传行为。
原始值包装：wrap('value', v => '' + v + '')直接返回value，验证了包装非函数值的能力。

这些测试与日文版参考文档中的示例互为印证，也说明wrap的设计目标是与 Lodash 兼容语义完全对齐。

六、实战场景小结与最佳实践

wrap在 es-toolkit 中的典型应用场景包括：

横切关注点注入：为既有函数统一附加日志、计时、鉴权等逻辑，且无需修改原函数实现；
渲染/序列化扩展：将基础值（字符串、数字、对象）包装成带格式的输出（如 HTML 标签、模板结构）；
Lodash 代码迁移：将_.wrap调用平滑迁移到es-toolkit/compat，保持行为不变。

需要再次强调的是原文档的核心建议：若编写全新代码，优先使用更快的现代闭包或直接函数定义，例如：

// 用闭包替代 wrap 的等价写法 const loggedGreet = (name: string) => { const result = `Hi, ${name}`; console.log(`[LOG] ${result}`); return result; };

只有在需要与 Lodash 语义严格兼容、或需要以"值 + 动态包装函数"方式抽象逻辑时，才选择wrap。把握这一边界，就能在代码可读性、性能与兼容性之间做出正确取舍。

企业官网建设流程全解析