Skip to main content

return-await

Enforce consistent returning of awaited values.

🔧

此规则报告的一些问题可通过 --fix ESLint 命令行选项自动修复。

💡

此规则报告的一些问题可以通过编辑器 建议 手动修复。

💭

该规则需要 类型信息 才能运行。


返回等待的 Promise 可以更好地获取堆栈跟踪信息以及一致的错误处理（返回的 Promise 不会被异步函数 try/catch 捕获）。

英：Returning an awaited promise can make sense for better stack trace information as well as for consistent error handling (returned promises will not be caught in an async function try/catch).

该规则建立在 eslint/no-return-await 规则之上。 它扩展了基本规则，添加了对在某些情况下可选地要求 return await 的支持。

英：This rule builds on top of the eslint/no-return-await rule. It expands upon the base rule to add support for optionally requiring return await in certain cases.

扩展规则被命名为 return-await 而不是 no-return-await，因为扩展规则可以强制执行肯定或否定。 此外，虽然核心规则现已弃用，但扩展规则在许多情况下仍然有用。

英：The extended rule is named return-await instead of no-return-await because the extended rule can enforce the positive or the negative. Additionally, while the core rule is now deprecated, the extended rule is still useful in many contexts.

选项​

type Options = 'in-try-catch' | 'always' | 'never';

const defaultOptions: Options = 'in-try-catch';

in-try-catch​

要求返回的 Promise 必须在 try-catch-finally 块中进行 await 化，并在其他地方不允许这样做。 具体来说：

英：Requires that a returned promise must be awaited in try-catch-finally blocks, and disallows it elsewhere. Specifically:

  • 如果你在 try 中 return 了一个 promise，那么它一定是 await 的。
  • 如果你在 catch 内 return 一个 promise，并且有 没有 finally，那么它 一定不 就被 awaited 了。
  • 如果你在 catch 内 return 一个 promise，并且有 是一个 finally，那么它 must 就被 awaited 了。
  • 如果你在 finally 中 return 了一个 promise，那么它 一定不 就被 await 了。

in-try-catch 的代码示例：

英：Examples of code with in-try-catch:

async function invalidInTryCatch1() {
  try {
    return Promise.resolve('try');
  } catch (e) {}
}

async function invalidInTryCatch2() {
  try {
    throw new Error('error');
  } catch (e) {
    return await Promise.resolve('catch');
  }
}

async function invalidInTryCatch3() {
  try {
    throw new Error('error');
  } catch (e) {
    return Promise.resolve('catch');
  } finally {
    console.log('cleanup');
  }
}

async function invalidInTryCatch4() {
  try {
    throw new Error('error');
  } catch (e) {
    throw new Error('error2');
  } finally {
    return await Promise.resolve('finally');
  }
}

async function invalidInTryCatch5() {
  return await Promise.resolve('try');
}

async function invalidInTryCatch6() {
  return await 'value';
}
Open in Playground

always​

要求所有返回的 Promise 都经过 await 处理。

英：Requires that all returned promises are awaited.

always 的代码示例：

英：Examples of code with always:

async function invalidAlways1() {
  try {
    return Promise.resolve('try');
  } catch (e) {}
}

async function invalidAlways2() {
  return Promise.resolve('try');
}

async function invalidAlways3() {
  return await 'value';
}
Open in Playground

never​

禁止所有 awaiting 任何返回的 promise。

英：Disallows all awaiting any returned promises.

never 的代码示例：

英：Examples of code with never:

async function invalidNever1() {
  try {
    return await Promise.resolve('try');
  } catch (e) {}
}

async function invalidNever2() {
  return await Promise.resolve('try');
}

async function invalidNever3() {
  return await 'value';
}
Open in Playground

如何使用​

.eslintrc.cjs
module.exports = {
  "rules": {
    // Note: you must disable the base rule as it can report incorrect errors
    "no-return-await": "off",
    "@typescript-eslint/return-await": "error"
  }
};
在线运行试试这个规则 ↗

选项​

参见 eslint/no-return-await 选项。

资源​

摘自 ❤️ ESLint 内核