callback-return

回调后需要 return 语句

回调模式是 JavaScript 中大多数 I/O 和事件驱动编程的核心。

¥The callback pattern is at the heart of most I/O and event-driven programming in JavaScript.

function doSomething(err, callback) {
    if (err) {
        return callback(err);
    }
    callback();
}
1
2
3
4
5
6

为了防止多次调用回调，在主函数体之外触发回调时，return 很重要。忽略此技术通常会导致你多次执行某项操作的问题。例如，在 HTTP 请求的情况下，你可能会尝试多次发送 HTTP 标头，从而导致 Node.js 向 throw 发送 Can't render headers after they are sent to the client. 错误。

¥To prevent calling the callback multiple times it is important to return anytime the callback is triggered outside of the main function body. Neglecting this technique often leads to issues where you do something more than once. For example, in the case of an HTTP request, you may try to send HTTP headers more than once leading Node.js to throw a Can't render headers after they are sent to the client. error.

规则详情

¥Rule Details

此规则旨在确保在主功能块之外使用的回调始终是 return 语句的一部分或紧接在 return 语句之前。此规则根据被调用函数的名称决定什么是回调。

¥This rule is aimed at ensuring that callbacks used outside of the main function block are always part-of or immediately preceding a return statement. This rule decides what is a callback based on the name of the function being called.

选项

¥Options

该规则采用单一选项 - 可能的回调名称的数组 - 其中可能包括对象方法。默认回调名称为 callback、cb、next。

¥The rule takes a single option - an array of possible callback names - which may include object methods. The default callback names are callback, cb, next.

默认回调名称

¥Default callback names

使用默认 ["callback", "cb", "next"] 选项的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the default ["callback", "cb", "next"] option:

/*eslint callback-return: "error"*/

function foo(err, callback) {
    if (err) {
        callback(err);
    }
    callback();
}
1
2
3
4
5
6
7
8

使用默认 ["callback", "cb", "next"] 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the default ["callback", "cb", "next"] option:

/*eslint callback-return: "error"*/

function foo(err, callback) {
    if (err) {
        return callback(err);
    }
    callback();
}
1
2
3
4
5
6
7
8

提供的回调名称

¥Supplied callback names

使用选项 ["done", "send.error", "send.success"] 的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the option ["done", "send.error", "send.success"]:

/*eslint callback-return: ["error", ["done", "send.error", "send.success"]]*/

function foo(err, done) {
    if (err) {
        done(err);
    }
    done();
}

function bar(err, send) {
    if (err) {
        send.error(err);
    }
    send.success();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

使用选项 ["done", "send.error", "send.success"] 的此规则的正确代码示例：

¥Examples of correct code for this rule with the option ["done", "send.error", "send.success"]:

/*eslint callback-return: ["error", ["done", "send.error", "send.success"]]*/

function foo(err, done) {
    if (err) {
        return done(err);
    }
    done();
}

function bar(err, send) {
    if (err) {
        return send.error(err);
    }
    send.success();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

已知限制

¥Known Limitations

因为通过静态分析很难理解程序的含义，所以这条规则有局限性：

¥Because it is difficult to understand the meaning of a program through static analysis, this rule has limitations:

• 当此规则报告正确代码但程序多次调用回调（这是不正确的行为）时的漏报

  ¥false negatives when this rule reports correct code, but the program calls the callback more than one time (which is incorrect behavior)

• 当这条规则报告不正确的代码时误报，但程序只调用一次回调（这是正确的行为）

  ¥false positives when this rule reports incorrect code, but the program calls the callback only one time (which is correct behavior)

通过引用传递回调

¥Passing the callback by reference

该规则的静态分析不会检测到如果回调是函数的参数（例如 setTimeout），则程序会调用该回调。

¥The static analysis of this rule does not detect that the program calls the callback if it is an argument of a function (for example, setTimeout).

此规则报告正确代码时的误报示例：

¥Example of a false negative when this rule reports correct code:

/*eslint callback-return: "error"*/

function foo(err, callback) {
    if (err) {
        setTimeout(callback, 0); // this is bad, but WILL NOT warn
    }
    callback();
}
1
2
3
4
5
6
7
8

在嵌套函数中触发回调

¥Triggering the callback within a nested function

此规则的静态分析未检测到程序从嵌套函数或立即调用函数表达式 (IIFE) 中调用回调。

¥The static analysis of this rule does not detect that the program calls the callback from within a nested function or an immediately-invoked function expression (IIFE).

此规则报告正确代码时的误报示例：

¥Example of a false negative when this rule reports correct code:

/*eslint callback-return: "error"*/

function foo(err, callback) {
    if (err) {
        process.nextTick(function() {
            return callback(); // this is bad, but WILL NOT warn
        });
    }
    callback();
}
1
2
3
4
5
6
7
8
9
10

if/else 语句

¥If/else statements

该规则的静态分析没有检测到程序在 if 语句的每个分支中只调用了一次回调。

¥The static analysis of this rule does not detect that the program calls the callback only one time in each branch of an if statement.

此规则报告错误代码时的误报示例：

¥Example of a false positive when this rule reports incorrect code:

/*eslint callback-return: "error"*/

function foo(err, callback) {
    if (err) {
        callback(err); // this is fine, but WILL warn
    } else {
        callback();    // this is fine, but WILL warn
    }
}
1
2
3
4
5
6
7
8
9

何时不使用

¥When Not To Use It

在某些情况下，你可能希望多次调用回调函数。在这些情况下，此规则可能会导致不正确的行为。在这些情况下，你可能希望为这些回调保留一个特殊名称，而不是将其包含在触发警告的回调列表中。

¥There are some cases where you might want to call a callback function more than once. In those cases this rule may lead to incorrect behavior. In those cases you may want to reserve a special name for those callbacks and not include that in the list of callbacks that trigger warnings.

相关规则

• handle-callback-err

版本

此规则是在 ESLint v1.0.0-rc-1 中引入。

进阶读物

GitHub - maxogden/art-of-node: a short introduction to node.js
github.com

What are the error conventions? - docs.nodejitsu.com
web.archive.org

资源

• 规则源码
• 测试源码