callback-return

回调后需要 return 语句

回调模式是大多数 JavaScript 输入/输出和事件驱动编程的核心。

🌐 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 语句的一部分或紧接在其之前。该规则根据被调用函数的名称来确定什么是回调。

🌐 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:

• 假阴性 当这个规则报告正确代码，但程序多次调用回调（这是不正确的行为）时
• 假阳性 当此规则报告不正确的代码，但程序只调用一次回调（这是正确的行为）

通过引用传递回调

🌐 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

资源

• 规则源码
• 测试源码