use-unknown-in-catch-callback-variable

Enforce typing arguments in Promise rejection callbacks as unknown.

🔒

在 ESLint 配置中扩展"plugin:@typescript-eslint/strict-type-checked" 可启用此规则。

🔧

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

💡

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

💭

该规则需要类型信息才能运行，但这会带来性能方面的权衡。

此规则强制始终使用 unknown 类型作为 Promise 拒绝回调的参数。

¥This rule enforces that you always use the unknown type for the parameter of a Promise rejection callback.

❌ Incorrect
✅ Correct

Promise.reject(new Error('I will reject!')).catch(err => {
  console.log(err);
});

Promise.reject(new Error('I will reject!')).catch((err: any) => {
  console.log(err);
});

Promise.reject(new Error('I will reject!')).catch((err: Error) => {
  console.log(err);
});

Promise.reject(new Error('I will reject!')).then(
  result => {
    console.log(result);
  },
  err => {
    console.log(err);
  },
);
Open in Playground

Promise.reject(new Error('I will reject!')).catch((err: unknown) => {
  console.log(err);
});
Open in Playground

此规则的原因是使程序员能够对 Promise 错误处理施加约束，类似于 TypeScript 为普通异常处理提供的约束。

¥The reason for this rule is to enable programmers to impose constraints on Promise error handling analogously to what TypeScript provides for ordinary exception handling.

对于普通异常，TypeScript 默认将 catch 变量视为 any。但是，unknown 会是一种更准确的类型，因此 TypeScript 引入 useUnknownInCatchVariables 编译器选项将 catch 变量视为 unknown。

¥For ordinary exceptions, TypeScript treats the catch variable as any by default. However, unknown would be a more accurate type, so TypeScript introduced the useUnknownInCatchVariables compiler option to treat the catch variable as unknown instead.

try {
  throw x;
} catch (err) {
  // err has type 'any' with useUnknownInCatchVariables: false
  // err has type 'unknown' with useUnknownInCatchVariables: true
}

try-catch 块的 Promise 模拟 Promise.prototype.catch() 不受 useUnknownInCatchVariables 编译器选项的影响，其“catch 变量”将始终具有类型 any。

¥The Promise analog of the try-catch block, Promise.prototype.catch(), is not affected by the useUnknownInCatchVariables compiler option, and its "catch variable" will always have the type any.

Promise.reject(x).catch(err => {
  // err has type 'any' regardless of `useUnknownInCatchVariables`
});

但是，你仍然可以提供显式类型注释，这可以让你实现与 useUnknownInCatchVariables 选项对同步 catch 变量相同的效果。

¥However, you can still provide an explicit type annotation, which lets you achieve the same effect as the useUnknownInCatchVariables option does for synchronous catch variables.

Promise.reject(x).catch((err: unknown) => {
  // err has type 'unknown'
});

信息

实际上有一种方法可以让 catch() 和 then() 回调变量在调用站点使用 unknown 类型，而无需显式类型注释，但它的缺点是它涉及覆盖全局类型声明。例如，库 better-TypeScript-lib 为你的项目全局设置了此功能（有关如何操作的详细信息，请参阅相关行 better-TypeScript-lib 源代码）。

¥There is actually a way to have the catch() and then() callback variables use the unknown type without an explicit type annotation at the call sites, but it has the drawback that it involves overriding global type declarations. For example, the library better-TypeScript-lib sets this up globally for your project (see the relevant lines in the better-TypeScript-lib source code for details on how).

要进一步了解这一点，你可能还需要研究此规则提案中的讨论和此 TypeScript 问题将捕获回调变量键入为未知。

¥For further reading on this, you may also want to look into the discussion in the proposal for this rule and this TypeScript issue on typing catch callback variables as unknown.

Flat Config
Legacy Config

eslint.config.mjs
export default tseslint.config({
  rules: {
    "@typescript-eslint/use-unknown-in-catch-callback-variable": "error"
  }
});

.eslintrc.cjs
module.exports = {
  "rules": {
    "@typescript-eslint/use-unknown-in-catch-callback-variable": "error"
  }
};

在线运行试试这个规则 ↗

选项

该规则不可配置。

何时不使用它

¥When Not To Use It

如果你的代码库尚无法启用 useUnknownInCatchVariables，则启用此规则可能同样困难。

¥If your codebase is not yet able to enable useUnknownInCatchVariables, it likely would be similarly difficult to enable this rule.

如果你修改了全局类型声明以使 then() 和 catch() 回调使用没有显式类型注释的 unknown 类型，则不需要此规则。

¥If you have modified the global type declarations in order to make then() and catch() callbacks use the unknown type without an explicit type annotation, you do not need this rule.

选项​

何时不使用它​

相关​

选项

何时不使用它

相关