` 到 `toSpliced()` 的安全迁移)
eslint-plugin-unicorn no-array-splice 规则深度解析基于 AVA 快照测试还原splice()到toSpliced()的安全迁移【免费下载链接】eslint-plugin-unicornMore than 300 powerful ESLint rules项目地址: https://gitcode.com/GitHub_Trending/es/eslint-plugin-unicorn导读本文以 eslint-plugin-unicorn 仓库中的规则测试快照 test/snapshots/no-array-splice.js.md 为核心素材结合规则源码 rules/no-array-splice.js、完整测试用例 test/no-array-splice.js 与官方规则文档 docs/rules/no-array-splice.md系统还原no-array-splice规则的完整行为它在什么条件下报告、如何生成编辑器建议suggestion、如何逐字符保留注释与转义、如何处理 TypeScript 类型标注以及为了避免破坏外部引用而设计的逃逸分析防线。读完本文你将能准确理解该规则的误报边界并能在自己的 ESLint 配置中正确启用、验证和运用它。一、规则背景为什么鼓励用toSpliced()代替splice()Array#splice()会原地修改原数组并返回被移除的元素而Array#toSpliced()是 ES2023 引入的不可变方法它返回修改后的新副本原数组保持不变。二者参数签名完全一致(start, deleteCount, ...items)因此当splice()的返回值未被使用时替换成toSpliced()再赋回语义几乎等价却能让代码走向不可变风格避免共享引用被意外修改。规则文档给出的最简示例见 docs/rules/no-array-splice.md// ❌ 错误返回值未被使用却原地改动了 array let array [1, 2, 3]; array.splice(1, 1); // ✅ 推荐生成新数组并赋回 array array.toSpliced(1, 1);需要特别强调的是只有在splice()的返回值没有被使用时这种替换才是合理的。如果代码依赖返回值例如const removed array.splice(1, 1);规则不会报告——快照测试与测试用例 test/no-array-splice.js 均将其列为合法代码。二、快照测试文件解析一篇可执行的规则行为说明书test/snapshots/no-array-splice.js.md 是 AVA 测试框架为test/no-array-splice.js自动生成的快照报告记录了全部27 个 invalid应报错用例的输入、报错消息和修复建议。每个用例的结构固定为 Input被测试的源代码 Error 1/N报错位置^^^^^^标记指向splice属性、消息Use \Array#toSpliced() instead of Array#splice().Suggestion 1/1一条以Assign the \.toSpliced() result back to the array.为标题的自动建议即把.splice(...)改写为array array.toSpliced(...)。这一消息与建议文案在规则源码 rules/no-array-splice.js 中定义const MESSAGE_ID_ERROR error; const MESSAGE_ID_SUGGESTION suggestion; const messages { [MESSAGE_ID_ERROR]: Use Array#toSpliced() instead of Array#splice()., [MESSAGE_ID_SUGGESTION]: Assign the .toSpliced() result back to the array., };下面的章节将把这 27 个用例按接收者来源和语言特性两个维度分组解读。三、快照用例分组解读什么情况下会被报告3.1 基础场景let/var声明的数组字面量快照invalid(1)invalid(2)是最基础的场景——用数组字面量初始化、且使用let或var而非const声明的变量let array []; array.splice(index, deleteCount); // invalid(1) var array []; array.splice(index, deleteCount, item); // invalid(2)两个用例分别验证了仅删除与删除并插入新元素含第三个及更多参数两种形态修复建议均为array array.toSpliced(...)。注意var也被纳入报告范围但仅限声明次数唯一的情况见下文安全边界。3.2 新鲜数组来源new Array()、Array.from()、Array.of()与数组返回方法快照invalid(3)invalid(13)系统验证了变量初始化的值确定是全新数组的各种来源。规则源码中通过isFreshLocalArrayInit函数rules/no-array-splice.js逐一判定const newArrayMethods [ filter, flat, flatMap, map, toReversed, toSorted, toSpliced, with, ];判定逻辑为初始化表达式是数组字面量、Array()/new Array()调用、Array.from()/Array.of()静态方法调用或上述任一必定返回新数组的实例方法调用。快照中对应的用例快照用例初始化来源说明invalid(3)new Array()空数组构造invalid(4)new Array(5)带长度参数invalid(5)Array.from(iterable)静态工厂方法invalid(6)Array.of(1, 2, 3)静态工厂方法invalid(7)items.filter(Boolean)数组方法invalid(8)items.map(String)数组方法invalid(9)items.flat()数组方法invalid(10)items.toSorted()数组方法invalid(11)items.with(0, item)数组方法invalid(12)original.toSpliced(0, 1)数组方法invalid(13)object.items.filter(Boolean)成员链上的数组方法其中invalid(13)验证了通过成员链获取的新数组同样成立只要array变量本身被初始化为一个全新的、作用域独占的数组无论这个数组是通过多长的属性链计算出来的都可以安全地改写成toSpliced()赋回。源码注释rules/no-array-splice.js特别说明了这一白名单的取舍原地修改方法reverse、sort、fill、copyWithin、splice和有歧义的方法slice/concat也可能是String的方法被有意排除在外避免误报。3.3 非逃逸读取数组仍在作用域内被使用invalid(14)invalid(17)验证了数组虽然被后续代码读取但这些读取方式不会让数组对象逃出当前作用域的场景let array []; array.forEach(foo); array.splice(1, 1); // invalid(14) let array []; foo(...array); array.splice(1, 1); // invalid(15) let array []; const first array[0]; array.splice(1, 1); // invalid(16) let array []; for (const element of array) {} array.splice(1, 1); // invalid(17)对应的逃逸判定函数isEscapingArrayReferencerules/no-array-splice.js规定以下读取方式不构成逃逸成员访问parent.type MemberExpression且标识符是object展开语法parent.type SpreadElementfor...of的右侧迭代对象parent.type ForOfStatement。原因在于这些读取只把数组当作值在本地消费外部无法因此获得对同一数组对象的引用所以把原地splice()换成toSpliced()赋回对任何外部观察者都不可见。3.4 多次调用与注释、转义等边界细节快照后半部分集中验证了容易出错的语法细节同一数组上的多次splice()调用invalid(18)每一处调用都被独立报告快照显示Error 1/2与Error 2/2两条消息且两处建议互不干扰——第一处改为array array.toSpliced(1, 1)第二处改为array array.toSpliced(2, 1)。参数中的注释与展开invalid(19)array.splice(1, 1, /* comment */ item, ...items)改写后注释原样保留array array.toSpliced(1, 1, /* comment */ item, ...items)。成员运算符两侧的注释invalid(20)、invalid(23)array /* comment */ .splice(1, 1)与array. /* comment */ splice(1, 1)均被正确识别且建议会原样保留注释位置。Unicode 转义标识符invalid(21)\u0061rray.splice(1, 1)即array.splice(1, 1)同样被报告建议文本中的变量名也以转义形式写出说明规则基于 AST 而非文本匹配。带括号的接收者invalid(22)(array).splice(1, 1)被识别为同一变量改写为array (array).toSpliced(1, 1)括号得以保留。从实现看建议通过两个 fixer 组合完成rules/no-array-splice.jsinsertTextBefore(callExpression,${receiverText} )在调用前插入receiver replaceText(property, toSpliced)只替换property节点因此所有其他文本注释、括号、参数都不会被触碰这解释了快照中注释和转义被完整保留的现象。3.5 TypeScript 场景类型标注、as断言与非空断言快照invalid(24)invalid(27)验证了规则对 TypeScript 语法的支持let array: string[] []; array.splice(1, 1); // invalid(24) let array: Arraystring []; array.splice(1, 1); // invalid(25) let array: string[] []; (array as string[]).splice(1, 1); // invalid(26) let array: string[] []; array!.splice(1, 1); // invalid(27)invalid(26)和invalid(27)体现了规则的类型包装剥离能力as string[]类型断言和!非空断言包裹的接收者经unwrapTypeScriptExpressionrules/utils/unwrap-typescript-expression.js递归解包后依然能被识别为同一局部变量并给出建议。四、反向验证合法用例揭示的不报告边界快照只记录了 invalid 用例但测试文件 test/no-array-splice.js 中的 valid 用例同样是理解规则行为的关键。它们完整勾勒出绝对不报告的边界条件1. 返回值被使用const removed array.splice(1, 1);、return array.splice(1, 1);、foo(array.splice(1, 1));均不报告。实现上规则入口首先调用isValueNotUsablerules/utils/is-value-not-usable.js它只判断调用是否是独立的表达式语句isExpressionStatement(node.parent)。2. 非let/var可重赋值局部变量const array []; array.splice(1, 1);不报告const无法重新赋值函数参数、catch绑定、解构绑定、先声明后赋值let array; array [];不报告重复声明的var可能被重新初始化为非新鲜数组不报告全局作用域中的变量不报告。3. 数组来源不确定或可能共享let array otherArray;、let structures getStructures();不报告——外部来源的数组可能是共享引用必须保留原地修改语义初始化时带类型断言的外部来源let array otherArray as string[];、satisfies、!不报告using array acquire();显式资源管理声明不报告。4. 数组逃逸出作用域外部持有者可能观察到原地修改作为实参传递foo(array);、new Set(array);别名赋值const alias array;、let alias; alias array;存入外部容器obj.property array;、const wrapper [array];、const wrapper {array};被闭包捕获后返回function getArray() { return array; }作为函数返回值function foo() { let array []; array.splice(1, 1); return array; }for...in迭代与for...of不同它会读取数组作为值源码注释明确指出这一差异。5. 已知非数组接收者rules/utils/should-skip-known-non-array-receiver.jsSet等已知非索引集合即使恰好声明了同名方法也不报告new Foo()非new Array()不报告包括继承Array的自定义类——源码注释明确这是有意为之的边界。6. 参数形态splice()无参调用、splice(index, 0)、splice(0)、splice(0, 1)、splice(0, 0, item)、splice(array.length - 1, 1)、splice(array.length, 0, item)均不报告——它们被交给另一条规则no-unnecessary-splice处理见第六节。7. 可选链与计算属性array?.splice(1, 1)、array.splice?.(1, 1)、arraysplice、arraysplice不报告源码中optionalCall、optionalMember、computed均要求为false。8. 非数组同名标识符function array() {} array.splice(1, 1);、class array {} array.splice(1, 1);不报告——findVariable找到的变量不是变量声明isFreshLocalArrayInit会因definition.type ! Variable拒绝。五、TypeScript 类型层面的三重防线除快照展示的语法层处理外规则还在类型层设置了额外的防线防止在类型上不安全的改写上误报类型注解检查shouldSkipReceiverrules/no-array-splice.js当声明带类型注解且不是普通数组类型TSArrayType或ArrayT类型引用时跳过。因此元组类型[string, string]、readonly数组、类型别名type Pair [string, string]均不报告。泛型类型参数function fooT extends string[](array: T) { array.splice(1, 1); }不报告——类型参数可能是元组或只读数组赋回普通数组在类型上不安全。类型信息检查isTypeParameterOrTuplerules/no-array-splice.js当启用类型感知解析parserOptions.projectService时利用 TypeScript 的getTypeAtLocation与类型检查器判断接收者的实际类型是否包含类型参数或元组此类类型断言、联合/交叉类型也需要类型信息才能可靠跳过。测试文件中以typeAware(...)包装的用例test/no-array-splice.js专门验证了这条路径例如as const as [string, string]与联合元组condition ? first : second场景。六、与no-unnecessary-splice规则的职责划分no-array-splice只处理应改为不可变风格的场景而那些有更简单的原地替代方案的splice()形态如splice(0, 1)等价于shift()、splice(array.length, 0, item)等价于push()由另一条规则 no-unnecessary-splice 负责其替换判定集中在共享模块 rules/shared/splice-replacements.js。no-array-splice在入口处通过getUnnecessarySpliceReplacement(callExpression)rules/no-array-splice.js主动让位一旦识别出shift/unshift/pop/push/no-op/empty等可由no-unnecessary-splice处理的形态立即返回不报告避免两条规则对同一调用重复报告。因此快照中所有被报告的用例其参数形态都是无法化简为单方法调用的一般形式。七、为什么只提供建议而非自动修复规则元数据rules/no-array-splice.js声明为type: suggestion且hasSuggestions: true即只生成编辑器可一键应用的建议editor suggestions不提供--fix自动修复。文档对此给出了明确理由docs/rules/no-array-splice.md该规则仅提供建议因为把Array#toSpliced()的结果赋回会改变别名行为——任何仍然引用原数组对象的代码在重新赋值后都会观察到不同的行为。这正是规则内置逃逸分析的原因只有证明数组没有别名、没有逃逸、来源全新赋值回写才在语义上等价。即便如此只要存在任何超出静态分析能力的模糊性就交给开发者通过建议手动确认。八、如何启用与验证该规则默认在recommended配置中启用在unopinionated配置中禁用见 docs/rules/no-array-splice.md。可手动在 ESLint 配置中显式开启// eslint.config.jsflat config 风格 export default [ { rules: { unicon/no-array-splice: error, }, }, ];运行测试生成或更新快照npx ava test/no-array-splice.js # 运行该规则的测试 npx ava test/no-array-splice.js --update-snapshots # 更新快照新生成的快照会写入test/snapshots/no-array-splice.js.snap而 test/snapshots/no-array-splice.js.md 是它的可读 Markdown 呈现。理解这份快照就等于掌握了这条规则在全部 27 个代表性输入上的精确行为——从数组来源判定、逃逸分析到注释保留、Unicode 转义和 TypeScript 类型防线一条规则的安全边界完整可见。小结no-array-splice是 eslint-plugin-unicorn 中推动不可变数组编程的代表性规则它只在作用域独占、来源全新、无别名逃逸的let/var数组上将未使用返回值的splice()建议改写为toSpliced()赋回并通过源码级分析rules/no-array-splice.js、完整的正反用例test/no-array-splice.js与逐用例快照test/snapshots/no-array-splice.js.md把何时可安全迁移这一复杂问题变成了可验证、可复现的确定行为。理解其判定管线与快照结构既能帮助你正确配置规则、规避误报也能作为阅读这类安全分析型 ESLint 规则的通用方法论。【免费下载链接】eslint-plugin-unicornMore than 300 powerful ESLint rules项目地址: https://gitcode.com/GitHub_Trending/es/eslint-plugin-unicorn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
