ban-types

禁止某些类型。

✅

在 "plugin:@typescript-eslint/recommended" 中扩展 ESLint 配置 将启用此规则。

🔧

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

💡

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

一些内置类型有别名，而一些类型被认为是危险的或有害的。禁止某些类型通常是一个好主意，有助于一致性和安全性。

此规则禁止特定类型，并可以建议替代方案。请注意，它不会禁止使用相应的运行时对象。

.eslintrc.cjs

module.exports = {
  "rules": {
    "@typescript-eslint/ban-types": "error"
  }
};

在游乐场中尝试此规则 ↗

示例

使用默认选项的代码示例

❌ 不正确

// use lower-case primitives for consistency
const str: String = 'foo';
const bool: Boolean = true;
const num: Number = 1;
const symb: Symbol = Symbol('foo');
const bigInt: BigInt = 1n;

// use a proper function type
const func: Function = () => 1;

// use safer object types
const lowerObj: Object = {};
const capitalObj: Object = { a: 'string' };

const curly1: {} = 1;
const curly2: {} = { a: 'string' };

在游乐场中打开

✅ 正确

// use lower-case primitives for consistency
const str: string = 'foo';
const bool: boolean = true;
const num: number = 1;
const symb: symbol = Symbol('foo');
const bigInt: bigint = 1n;

// use a proper function type
const func: () => number = () => 1;

// use safer object types
const lowerObj: object = {};
const capitalObj: { a: string } = { a: 'string' };

const curly1: number = 1;
const curly2: Record<'a', string> = { a: 'string' };

在游乐场中打开

选项

此规则接受以下选项

type BanConfig =
  /** Bans a type */
  | {
      /** Type to autofix replace with. Note that autofixers can be applied automatically - so you need to be careful with this option. */
      fixWith?: string;
      /** Custom error message */
      message?: string;
      /** Types to suggest replacing with. */
      suggest?: string[];
    }
  /** Bans the type with a custom message */
  | string
  /** Bans the type with the default message */
  | null
  /** Bans the type with the default message */
  | true
  /** Un-bans the type (useful when paired with `extendDefaults`) */
  | false;

type Options = [
  {
    extendDefaults?: boolean;
    types?: {
      [k: string]: BanConfig;
    };
  },
];

const defaultOptions: Options = [
  {
    /* See below for default options */
  },
];

默认选项提供了一组“最佳实践”，旨在为您的代码库提供安全性和标准化

• 不要使用大写原始类型，您应该使用小写类型以保持一致性。
• 避免使用 Function 类型，因为它在以下方面几乎没有提供安全性
  • 它在调用值时不提供类型安全性，这意味着很容易提供错误的参数。
  • 它接受类声明，这些声明在调用时会失败，因为它们是在没有 new 关键字的情况下调用的。
• 避免使用Object和{}类型，因为它们表示“任何非空值”。
  • 这对许多开发人员来说是一个困惑点，他们认为它意味着“任何对象类型”。
  • 有关更多信息，请参阅此评论。

默认选项

const defaultTypes: Types = {
  String: {
    message: 'Use string instead',
    fixWith: 'string',
  },
  Boolean: {
    message: 'Use boolean instead',
    fixWith: 'boolean',
  },
  Number: {
    message: 'Use number instead',
    fixWith: 'number',
  },
  Symbol: {
    message: 'Use symbol instead',
    fixWith: 'symbol',
  },
  BigInt: {
    message: 'Use bigint instead',
    fixWith: 'bigint',
  },

  Function: {
    message: [
      'The `Function` type accepts any function-like value.',
      'It provides no type safety when calling the function, which can be a common source of bugs.',
      'It also accepts things like class declarations, which will throw at runtime as they will not be called with `new`.',
      'If you are expecting the function to accept certain arguments, you should explicitly define the function shape.',
    ].join('\n'),
  },

  // object typing
  Object: {
    message: [
      'The `Object` type actually means "any non-nullish value", so it is marginally better than `unknown`.',
      '- If you want a type meaning "any object", you probably want `object` instead.',
      '- If you want a type meaning "any value", you probably want `unknown` instead.',
      '- If you really want a type meaning "any non-nullish value", you probably want `NonNullable<unknown>` instead.',
    ].join('\n'),
    suggest: ['object', 'unknown', 'NonNullable<unknown>'],
  },
  '{}': {
    message: [
      '`{}` actually means "any non-nullish value".',
      '- If you want a type meaning "any object", you probably want `object` instead.',
      '- If you want a type meaning "any value", you probably want `unknown` instead.',
      '- If you want a type meaning "empty object", you probably want `Record<string, never>` instead.',
      '- If you really want a type meaning "any non-nullish value", you probably want `NonNullable<unknown>` instead.',
    ].join('\n'),
    suggest: [
      'object',
      'unknown',
      'Record<string, never>',
      'NonNullable<unknown>',
    ],
  },
};

types

一个对象，其键是您要禁止的类型，值是错误消息。

类型可以是类型名称字面量（Foo）、带有泛型参数实例化的类型名称（Foo<Bar>）、空对象字面量（{}）或空元组类型（[]）。

值可以是

• 一个字符串，它是将要报告的错误消息；或者
• false，专门取消禁止此类型（当您使用extendDefaults时很有用）；或者
• 一个具有以下属性的对象
  • message: string - 当匹配类型时要显示的消息。
  • fixWith?: string - 当运行修复程序时，用于替换被禁止类型的字符串。如果省略此项，则不会进行任何修复。
  • suggest?: string[] - 被禁止类型的建议替换列表。

extendDefaults

如果您正在指定自定义types，您可以将其设置为true以扩展默认的types配置。这是一个方便的选项，可以避免在添加另一种类型时复制默认值。

如果这是false，则该规则将仅使用您配置中定义的类型。

示例配置

{
  "@typescript-eslint/ban-types": [
    "error",
    {
      "types": {
        // add a custom message to help explain why not to use it
        "Foo": "Don't use Foo because it is unsafe",

        // add a custom message, AND tell the plugin how to fix it
        "OldAPI": {
          "message": "Use NewAPI instead",
          "fixWith": "NewAPI",
        },

        // un-ban a type that's banned by default
        "{}": false,
      },
      "extendDefaults": true,
    },
  ],
}

何时不使用它

如果您的项目是一个罕见的项目，它有意处理基本类型的类等效项，那么启用默认的ban-types选项可能不值得。您可以考虑使用ESLint 禁用注释来代替完全禁用此规则。

资源

• 规则来源
• 测试来源