ESLint function-paren-newline 规则详解:强制函数括号内换行一致性

原创2026-09-11 21:49:201,744 阅读
文章标签:Lint代码质量静态分析开发工具CLI

ESLint function-paren-newline 规则详解:强制函数括号内换行一致性

function-paren-newline 是 ESLint 内置布局(layout)类规则,用于在函数形参或实参的括号内部强制执行一致、统一的换行风格——它同时覆盖函数声明、函数表达式、箭头函数、函数调用、new 表达式以及动态 import() 这六类语法节点。读完本文,你将掌握该规则全部 5 种字符串选项与 minItems 对象选项的语义差异、每种选项下正确与错误代码的判定标准、底层源码的判定算法,以及它在当前仓库中被弃用的背景与迁移路径。

规则简介与适用场景

许多风格指南要求或禁止在函数括号内部出现换行,function-paren-newline 正是为这类需求而生:它检查函数形参(parameters)和调用实参(arguments)两侧括号内侧的换行情况,并强制整个括号对保持一致的书写风格。

从 源码定义 可以看到,该规则:

  • type 为 "layout",属于纯排版类规则,不影响代码语义;
  • fixable: "whitespace",意味着绝大多数问题都可以通过 --fix 自动修复;
  • recommended: false,不包含在 ESLint 的推荐配置中,需要用户显式开启。

规则实际检查的 AST 节点类型(见 getParenTokens 与监听器实现)包括:

节点类型 覆盖场景
FunctionDeclaration 函数声明,如 function foo(a, b) {}
FunctionExpression 函数表达式,如 var f = function(a, b) {}
ArrowFunctionExpression 箭头函数,如 (a, b) => {}
CallExpression 普通函数调用,如 foo(a, b)
NewExpression new 表达式,如 new Foo(a, b)
ImportExpression 动态导入 import(source)

对于没有括号的箭头函数(如 foo => {})以及没有实参的 new Foo,规则会直接跳过(源码中通过 getParenTokens 返回 null 处理,见 lib/rules/function-paren-newline.js#L251-L332)。

选项详解:字符串与对象两种形态

该规则只有一个选项,可以是字符串也可以是对象(对应源码 schema 定义)。字符串选项取值为枚举:"always"、"never"、"multiline"、"multiline-arguments"、"consistent";对象选项则形如 { "minItems": value }。

选项 类型 行为
"always" string 所有函数括号内部都必须有换行
"never" string 所有函数括号内部都禁止换行
"multiline" string(默认) 只要形参/实参之间存在换行,括号内就要求换行;否则禁止换行
"multiline-arguments" string 行为类似 multiline,但允许只有一个形参/实参时括号内不换行
"consistent" string 要求每一对括号两侧(( 后与 ) 前)换行状态一致:一侧有换行,另一侧也必须一致
{ "minItems": value } object 形参/实参数量达到 value 时要求括号内换行,否则禁止换行

选项如何映射为源码中的阈值

理解选项内部机制,有助于理解边界行为。在 create 函数 中,规则把选项归一化为一个 minItems 阈值:

const rawOption = context.options[0] || "multiline";
if (typeof rawOption === "object") {
    minItems = rawOption.minItems;
} else if (rawOption === "always") {
    minItems = 0;        // 数量 >= 0 恒成立 ⇒ 永远要求换行
} else if (rawOption === "never") {
    minItems = Infinity; // 数量 >= Infinity 恒不成立 ⇒ 永远禁止换行
} else {
    minItems = null;     // multiline / multiline-arguments / consistent 走专用分支
}

也就是说,"always" 等价于 { "minItems": 0 },"never" 等价于 { "minItems": Infinity },而 "multiline"、"multiline-arguments"、"consistent" 三个选项则由 shouldHaveNewlines 中的专用逻辑处理(见 lib/rules/function-paren-newline.js#L116-L132):

  • multiline / multiline-arguments:只要相邻两个形参/实参不在同一行(element.loc.end.line !== elements[index + 1].loc.start.line),就要求括号内换行;
  • multiline-arguments 的额外分支:当 elements.length === 1(只有一个参数)时,括号内是否换行完全跟随左括号当前的状态 hasLeftNewline,因此单个参数时两种风格都合法;
  • consistent:括号内是否换行直接取 hasLeftNewline(左括号后是否已有换行),即把右侧与左侧对齐。

配置示例

{
  "rules": {
    "function-paren-newline": ["error", "never"]
  }
}
{
  "rules": {
    "function-paren-newline": ["error", { "minItems": 3 }]
  }
}

对象选项的 schema 还声明了约束:minItems 必须是非负整数(type: "integer", minimum: 0),且不允许出现额外属性(additionalProperties: false),否则会触发配置校验错误(见 lib/rules/function-paren-newline.js#L65-L74)。

选项 "always":所有括号内强制换行

开启 "always" 后,只要函数声明、表达式、箭头函数或调用出现在括号中,( 之后与 ) 之前都必须有换行。

不正确的代码("always"):

/* eslint function-paren-newline: ["error", "always"] */

function foo(bar, baz) {}

var qux = function(bar, baz) {};

var qux = (bar, baz) => {};

foo(bar, baz);

正确的代码("always"):

/* eslint function-paren-newline: ["error", "always"] */

function foo(
  bar,
  baz
) {}

var qux = function(
  bar, baz
) {};

var qux = (
  bar,
  baz
) => {};

foo(
  bar,
  baz
);

注意在 "always" 下,括号内的形参之间不需要换行(如 bar, baz 写在同一行是允许的),规则只约束左右括号的内侧。这对应源码中 validateParens 只检查 ( 后与 ) 前的换行、而参数间的换行仅在 multiline-arguments 下才由 validateArguments 额外检查(见 lib/rules/function-paren-newline.js#L140-L241)。

选项 "never":所有括号内禁止换行

开启 "never" 后,函数括号内侧出现任何换行都会报错。

不正确的代码("never"):

/* eslint function-paren-newline: ["error", "never"] */

function foo(
  bar,
  baz
) {}

var qux = function(
  bar, baz
) {};

var qux = (
  bar,
  baz
) => {};

foo(
  bar,
  baz
);

正确的代码("never"):

/* eslint function-paren-newline: ["error", "never"] */

function foo(bar, baz) {}

function qux(bar,
             baz) {}

var foobar = function(bar, baz) {};

var foobar = (bar, baz) => {};

foo(bar, baz);

foo(bar,
  baz);

一个值得注意的细节:在 "never" 下,function qux(bar,\n baz) {} 是合法的——规则只检查括号内侧(( 与第一个形参之间、最后一个形参与 ) 之间)没有换行,参数之间是否换行并不属于 "never" 的管辖范围(只有在 multiline-arguments 选项下参数间换行才会被检查)。

默认选项 "multiline":跟随参数是否跨行

"multiline" 是该规则的默认选项(context.options[0] || "multiline"),核心思想是保持代码原有的多行/单行意图:只要任意两个形参/实参之间存在换行,就要求括号内部也换行;如果所有参数都在同一行,则禁止括号内换行。

不正确的代码(默认 "multiline"):

/* eslint function-paren-newline: ["error", "multiline"] */

function foo(bar,
  baz
) {}

var qux = function(
  bar, baz
) {};

var qux = (
  bar,
  baz) => {};

foo(bar,
  baz);

foo(
  function() {
    return baz;
  }
);

最后一条 foo(\n function() {...}\n) 之所以不正确,是因为单个实参内部的函数体虽然是多行的,但规则统计的是形参/实参元素之间的换行(相邻元素的 loc.end.line 与 loc.start.line),单个实参不构成"参数之间有换行",因此此时括号内侧不应换行。

正确的代码(默认 "multiline"):

/* eslint function-paren-newline: ["error", "multiline"] */

function foo(bar, baz) {}

var foobar = function(
  bar,
  baz
) {};

var foobar = (bar, baz) => {};

foo(bar, baz, qux);

foo(
  bar,
  baz,
  qux
);

foo(function() {
  return baz;
});

注意 foo(function() {...}) 在这里是正确的:参数只有一项且与其他参数没有"之间换行",因此括号内不换行也是合规的。

选项 "consistent":括号两侧换行状态必须一致

"consistent" 关注的是每一对括号自身的对称性:如果 ( 后有换行而 ) 前没有(或相反),就报告错误。它不像 multiline 那样关心参数是否跨行,只看左右括号的内侧状态是否一致。

不正确的代码("consistent"):

/* eslint function-paren-newline: ["error", "consistent"] */

function foo(bar,
  baz
) {}

var qux = function(bar,
  baz
) {};

var qux = (
  bar,
  baz) => {};

foo(
  bar,
  baz);

foo(
  function() {
    return baz;
  });

正确的代码("consistent"):

/* eslint function-paren-newline: ["error", "consistent"] */

function foo(bar,
  baz) {}

var qux = function(bar, baz) {};

var qux = (
  bar,
  baz
) => {};

foo(
  bar, baz
);

foo(
  function() {
    return baz;
  }
);

可以看到,在 "consistent" 下 function foo(bar,\n baz) 是合法的(左侧 ( 后无换行、右侧 ) 前也无换行,两侧一致),而 foo(\n bar, baz) 同样合法(两侧都有换行)。判断依据正是源码中的 return hasLeftNewline;——以左括号的状态为准对齐右括号(lib/rules/function-paren-newline.js#L128-L130)。

选项 "multiline-arguments":multiline 的灵活变体

"multiline-arguments" 在 multiline 的基础上放宽了"单个参数"的场景:当括号内只有一个形参/实参时,无论括号内是否换行都被允许(此时跟随左括号当前状态即可);当存在多个参数且参数间存在换行时,要求括号内换行。

不正确的代码("multiline-arguments"):

/* eslint function-paren-newline: ["error", "multiline-arguments"] */

function foo(bar,
  baz
) {}

var foobar = function(bar,
  baz
) {};

var foobar = (
  bar,
  baz) => {};

foo(
  bar,
  baz);

foo(
  bar, qux,
  baz
);

最后一条 foo(\n bar, qux,\n baz\n) 是不正确的,因为参数之间存在换行(bar, qux 与 baz 分行),此时规则要求参数之间也要换行——这正是 multiline-arguments 独有的 validateArguments 检查,它会遍历相邻参数对,若参数间无换行则报告 expectedBetween 错误(见 lib/rules/function-paren-newline.js#L218-L241)。

正确的代码("multiline-arguments"):

/* eslint function-paren-newline: ["error", "multiline-arguments"] */

function foo(
  bar,
  baz
) {}

var qux = function(bar, baz) {};

var qux = (
  bar
) => {};

foo(
  function() {
    return baz;
  }
);

注意 var qux = (\n bar\n) => {} 是正确的:只有一个形参时,括号内换行是被允许的(对应源码中 elements.length === 1 时返回 hasLeftNewline 的分支,lib/rules/function-paren-newline.js#L117-L119)。这也是它与默认 "multiline" 最直观的区别:默认模式下单个参数多行书写(如 foo(\n function() {...}\n))会被判错,而 multiline-arguments 不会。

对象选项 { "minItems": value }:按参数数量决定换行

当选项为对象 { "minItems": value } 时,规则按形参/实参的数量决定是否需要括号内换行:数量达到 value 时要求换行,否则禁止换行。该选项适合"参数多了再展开、参数少就单行"的团队规范。

以 { "minItems": 3 } 为例(参数数量 ≥ 3 时才展开换行):

不正确的代码:

/* eslint function-paren-newline: ["error", { "minItems": 3 }] */

function foo(
  bar,
  baz
) {}

function foobar(bar, baz, qux) {}

var barbaz = function(
  bar, baz
) {};

var barbaz = (
  bar,
  baz
) => {};

foo(
  bar,
  baz
);

function foobar(bar, baz, qux) 不正确,是因为 3 个参数达到了 minItems 阈值,必须换行;其余几条则是参数不足 3 个却换行了。

正确的代码:

/* eslint function-paren-newline: ["error", { "minItems": 3 }] */

function foo(bar, baz) {}

var foobar = function(
  bar,
  baz,
  qux
) {};

var foobar = (
  bar, baz, qux
) => {};

foo(bar, baz);

foo(
  bar, baz, qux
);

注意在 minItems 模式下,达到阈值后只要求括号内侧换行,参数之间仍可保持同一行(如 var foobar = (\n bar, baz, qux\n) => {})。由于 "always" 等价于 { "minItems": 0 }、"never" 等价于 { "minItems": Infinity },熟悉这个对象选项之后,字符串选项的内部行为也就一目了然了。

自动修复与修复限制

该规则标记为 fixable: "whitespace",因此开启后运行 eslint --fix 可以自动修正绝大多数换行问题。规则产生的五类报告消息(见 messages 定义)为:

  • expectedAfter:( 后缺少换行,修复方式是在左括号后插入 \n;
  • expectedBefore:) 前缺少换行,修复方式是在右括号前插入 \n;
  • unexpectedAfter:( 后出现多余换行,修复方式是删除 ( 与下一个 token 之间的空白;
  • unexpectedBefore:) 前出现多余换行,修复方式是删除最后一个 token 与 ) 之间的空白;
  • expectedBetween:参数之间缺少换行(仅 multiline-arguments 触发),修复方式是在下一个参数前插入 \n。

但有一个重要的修复限制:如果括号与第一个/最后一个元素之间存在注释,规则会放弃自动修复(返回 null),以避免破坏注释位置。源码中对此有明确处理——( 与首个 token 之间的文本 trim() 后非空则跳过修复,) 前同理(见 lib/rules/function-paren-newline.js#L159-L173 与 lib/rules/function-paren-newline.js#L187-L200)。因此,遇到"括号与参数间夹着注释"的代码,需要手动调整换行。

源码判定流程一览

结合 lib/rules/function-paren-newline.js 的完整实现,该规则对每个命中节点的处理分三步:

  1. 定位括号 token:getParenTokens 根据节点类型(CallExpression/NewExpression 取 callee 后的开括号与末尾闭括号,函数类取第一个开括号与最后一个参数后的闭括号,箭头函数跳过 async 关键字,ImportExpression 取首尾 token),并处理无括号情况返回 null(lib/rules/function-paren-newline.js#L251-L332);
  2. 判定期望状态:shouldHaveNewlines 依据选项计算"括号内是否应当换行"(lib/rules/function-paren-newline.js#L116-L132);
  3. 比对并报告/修复:validateParens 分别检查 ( 后与 ) 前的实际换行状态,与期望不一致时按对应 messageId 报告,必要时附带修复器;multiline-arguments 还会额外调用 validateArguments 检查参数间的换行(lib/rules/function-paren-newline.js#L140-L241)。

其中换行状态的判断基于 token 位置:astUtils.isTokenOnSameLine(leftParen, tokenAfterLeftParen) 为假即视为存在换行。

仓库中配套的规则测试位于 tests/lib/rules/function-paren-newline.js,共 1522 行,覆盖了全部选项在 valid/invalid 两组用例下的行为,包括 async 箭头函数、动态 import()、new Foo、无括号箭头函数、模板字符串实参等边界场景,是验证上述规则语义的最佳参考。

弃用说明与迁移建议

需要特别提醒:该规则已在 ESLint v8.53.0 中标记为弃用(deprecated),计划可用至 v11.0.0。弃用原因是 ESLint 团队将排版类(formatting)规则逐步移出核心库,交由 ESLint Stylistic 中的弃用元数据)。

迁移方式:若项目仍使用旧版本可继续沿用本文配置;若使用 ESLint v9+ 并需要长期维护,建议改用 @stylistic/eslint-plugin 中同名的 function-paren-newline 规则,选项语义保持一致,配置方式如下:

// eslint.config.js(flat config)
import stylistic from "@stylistic/eslint-plugin";

export default [
    {
        plugins: { "@stylistic": stylistic },
        rules: {
            "@stylistic/function-paren-newline": ["error", "multiline"]
        }
    }
];

如果你不想强制函数括号内的换行风格,则不要开启本规则——尤其是当项目中既有全单行写法、又有"长参数列表手动换行"的混合风格时,该规则反而会造成额外噪音。此时更合适的做法是保持现状或改用整体格式化工具(如 Prettier)统一排版。

小结

function-paren-newline 通过一个选项覆盖了从"永远换行"到"永远不换行"的完整策略谱系:"always" 与 "never" 是两个极端,"multiline"(默认)与 "multiline-arguments" 根据参数是否跨行自适应,"consistent" 强调括号两侧对称,而 { "minItems": N } 则按参数数量决定阈值。理解其底层的 minItems 归一化与"仅检查括号内侧"的判定规则,就能准确预判任何代码风格下该规则的行为;在最新项目中,请优先考虑迁移到 @stylistic/eslint-plugin 以获得持续维护。

登录后查看全文
eslint