useExplicitType

TypeScript and TSX

摘要

¥Summary

规则生效日期：v1.9.3

¥Rule available since: v1.9.3
诊断类别：lint/nursery/useExplicitType

¥Diagnostic Category: lint/nursery/useExplicitType
此规则没有修复方案。

¥This rule doesn’t have a fix.
此规则的默认严重级别为 error。

¥The default severity of this rule is error.
来源：

¥Sources:
- 灵感来自 @typescript-eslint/explicit-function-return-type
  
  ¥Inspired from @typescript-eslint/explicit-function-return-type
- 灵感来自 @typescript-eslint/explicit-module-boundary-types
  
  ¥Inspired from @typescript-eslint/explicit-module-boundary-types

如何配置

¥How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useExplicitType": "error"
6
      }
7
    }
8
  }
9
}

描述

¥Description

强制在函数、方法、变量和参数中使用类型。

¥Enforce types in functions, methods, variables, and parameters.

TypeScript 中的函数通常不需要显式地添加返回类型注解。省略返回类型可以减少需要读写的代码量，并允许编译器从函数内容中推断返回类型。

¥Functions in TypeScript often don’t need to be given an explicit return type annotation. Leaving off the return type is less code to read or write and allows the compiler to infer it from the contents of the function.

但是，显式返回类型确实能让函数返回的类型更加清晰易懂。它们还可以提高包含大量大型函数的大型代码库中 TypeScript 的类型检查性能。显式返回类型通过断言返回类型来降低 bug 的发生概率，并避免因更改一个函数体而导致另一个函数内部出现故障，从而避免 “远程操作” 的意外情况。

¥However, explicit return types do make it visually clearer what type is returned by a function. They can also speed up TypeScript type-checking performance in large codebases with many large functions. Explicit return types also reduce the chance of bugs by asserting the return type, and it avoids surprising “action at a distance,” where changing the body of one function may cause failures inside another function.

为模块级变量添加注释可以达到类似的目的。此规则仅允许将字面量和某些对象赋值给未类型化的变量。允许的对象不得包含扩展语法和非字面值。此外，值为 null 或 undefined 的 let 和 var 变量需要显式注解。

¥Annotating module-level variables serves a similar purpose. This rule only allows assignment of literals and some objects to untyped variables. Objects that are allowed must not contain spread syntax and values that aren’t literals. Additionally, let and var variables with null or undefined as value require explicit annotation.

此规则强制函数必须具有显式的返回类型注解。

¥This rule enforces that functions do have an explicit return type annotation.

示例

¥Examples

无效

¥Invalid

1
// Should indicate that no value is returned (void)
2
function test() {
3
  return;
4
}

code-block.ts:2:1 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function.
  
    1 │ // Should indicate that no value is returned (void)
  > 2 │ function test() {
      │ ^^^^^^^^^^^^^
    3 │   return;
    4 │ }
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.

1
// Should indicate that a number is returned
2
var fn = function () {
3
   return 1;
4
};

code-block.ts:2:10 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function.
  
    1 │ // Should indicate that a number is returned
  > 2 │ var fn = function () {
      │          ^^^^^^^^^^^^^
  > 3 │    return 1;
  > 4 │ };
      │ ^
    5 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.

1
// Should indicate that a string is returned
2
var arrowFn = () => 'test';

code-block.ts:2:15 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function.
  
    1 │ // Should indicate that a string is returned
  > 2 │ var arrowFn = () => ‘test’;
      │               ^^^^^^^^^^^^
    3 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.

1
class Test {
2
  // Should indicate that no value is returned (void)
3
  method() {
4
    return;
5
  }
6
}

code-block.ts:3:3 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on member.
  
    1 │ class Test {
    2 │   // Should indicate that no value is returned (void)
  > 3 │   method() {
      │   ^^^^^^^^^^
  > 4 │     return;
  > 5 │   }
      │   ^
    6 │ }
    7 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the member.

1
// Should indicate that no value is returned (void)
2
function test(a: number) {
3
  a += 1;
4
}

code-block.ts:2:1 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function.
  
    1 │ // Should indicate that no value is returned (void)
  > 2 │ function test(a: number) {
      │ ^^^^^^^^^^^^^
    3 │   a += 1;
    4 │ }
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.

1
// Should use const assertions
2
var func = (value: number) => ({ type: 'X', value }) as any;

code-block.ts:2:12 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function.
  
    1 │ // Should use const assertions
  > 2 │ var func = (value: number) => ({ type: ‘X’, value }) as any;
      │            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    3 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.

1
// Unspecified variable type
2
function fn(): string {
3
    return "Not inline";
4
}
5
const direct = fn();

code-block.ts:5:7 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ The variable doesn’t have a type defined.
  
    3 │     return “Not inline”;
    4 │ }
  > 5 │ const direct = fn();
      │       ^^^^^^
    6 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a type to the variable.

1
// Unspecified object member type
2
function fn(): string {
3
    return "Not inline";
4
}
5
const nested = { result: fn() };

code-block.ts:5:7 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ The variable doesn’t have a type defined.
  
    3 │     return “Not inline”;
    4 │ }
  > 5 │ const nested = { result: fn() };
      │       ^^^^^^
    6 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a type to the variable.

1
// let bindings of null and undefined are usually overwritten by other code
2
let foo = null;

code-block.ts:2:5 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ The variable doesn’t have a type defined.
  
    1 │ // let bindings of null and undefined are usually overwritten by other code
  > 2 │ let foo = null;
      │     ^^^
    3 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a type to the variable.

以下示例对于高阶函数而言是不正确的，因为返回的函数没有指定返回类型：

¥The following example is considered incorrect for a higher-order function, as the returned function does not specify a return type:

1
var arrowFn = () => () => {};

code-block.ts:1:21 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function.
  
  > 1 │ var arrowFn = () => () => {};
      │                     ^^^^^^^^
    2 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.

1
var arrowFn = () => {
2
  return () => { };
3
}

code-block.ts:2:10 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function.
  
    1 │ var arrowFn = () => {
  > 2 │   return () => { };
      │          ^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.

以下示例对于高阶函数被认为是错误的，因为函数体包含多个语句。我们仅检查第一个语句是否为函数返回值。

¥The following example is considered incorrect for a higher-order function because the function body contains multiple statements. We only check whether the first statement is a function return.

1
// A function has multiple statements in the body
2
function f() {
3
  if (x) {
4
    return 0;
5
  }
6
  return (): void => {}
7
}

code-block.ts:2:1 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function.
  
    1 │ // A function has multiple statements in the body
  > 2 │ function f() {
      │ ^^^^^^^^^^
    3 │   if (x) {
    4 │     return 0;
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.

1
// A function has multiple statements in the body
2
function f() {
3
  let str = "test";
4
  return (): string => {
5
    str;
6
  }
7
}

code-block.ts:2:1 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function.
  
    1 │ // A function has multiple statements in the body
  > 2 │ function f() {
      │ ^^^^^^^^^^
    3 │   let str = “test”;
    4 │   return (): string => {
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.

1
// A function has multiple statements in the body
2
function f() {
3
  let str = "test";
4
}

code-block.ts:2:1 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function.
  
    1 │ // A function has multiple statements in the body
  > 2 │ function f() {
      │ ^^^^^^^^^^
    3 │   let str = “test”;
    4 │ }
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.

以下示例对于没有返回类型的接口方法而言是不正确的：

¥The following example is considered incorrect for an interface method without a return type:

1
interface Array<Type> {
2
  method();
3
}

code-block.ts:2:3 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on member.
  
    1 │ interface Array<Type> {
  > 2 │   method();
      │   ^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the member.

以下示例对于没有返回类型的函数类型声明而言是不正确的：

¥The following example is considered incorrect for a type declaration of a function without a return type:

1
type MyObject = {
2
  (input: string);
3
  propertyName: string;
4
};

code-block.ts:2:3 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on member.
  
    1 │ type MyObject = {
  > 2 │   (input: string);
      │   ^^^^^^^^^^^^^^^^
    3 │   propertyName: string;
    4 │ };
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the member.

以下示例对于没有返回类型的抽象类方法而言是不正确的：

¥The following example is considered incorrect for an abstract class method without a return type:

1
abstract class MyClass {
2
  public abstract method();
3
}

code-block.ts:2:3 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on member.
  
    1 │ abstract class MyClass {
  > 2 │   public abstract method();
      │   ^^^^^^^^^^^^^^^^^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the member.

以下示例对于没有返回类型的抽象类 getter 而言是不正确的：

¥The following example is considered incorrect for an abstract class getter without a return type:

1
abstract class P<T> {
2
  abstract get poke();
3
}

code-block.ts:2:3 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on member.
  
    1 │ abstract class P<T> {
  > 2 │   abstract get poke();
      │   ^^^^^^^^^^^^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the member.

以下示例对于命名空间中没有返回类型的函数声明被认为是错误的：

¥The following example is considered incorrect for a function declaration in a namespace without a return type:

1
declare namespace myLib {
2
  function makeGreeting(s: string);
3
}

code-block.ts:2:3 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function declaration.
  
    1 │ declare namespace myLib {
  > 2 │   function makeGreeting(s: string);
      │   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function declaration.

以下示例对于没有返回类型的模块函数导出而言是不正确的：

¥The following example is considered incorrect for a module function export without a return type:

1
declare module "foo" {
2
  export default function bar();
3
}

code-block.ts:2:18 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Missing return type on function declaration.
  
    1 │ declare module “foo” {
  > 2 │   export default function bar();
      │                  ^^^^^^^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function declaration.

以下示例被认为是错误的，因为 arg 的类型是 any。

¥The following example is considered incorrect because arg has any type.

1
var arrowFn = (arg: any): string => `test ${arg}`;

code-block.ts:1:21 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ The parameter has an any type.
  
  > 1 │ var arrowFn = (arg: any): string => `test ${arg}`;
      │                     ^^^
    2 │ 
  
  ℹ Declaring the type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Replace any with unknown or a more specific type.

有效

¥Valid

1
// No return value should be expected (void)
2
function test(): void {
3
  return;
4
}

1
// A return value of type number
2
var fn = function (): number {
3
  return 1;
4
}

1
// A return value of type string
2
var arrowFn = (): string => 'test';

1
// A literal value
2
const PREFIX = "/prefix";

1
// Explicit variable annotation
2
function func(): string {
3
    return "";
4
}
5
let something: string = func();

1
class Test {
2
  // No return value should be expected (void)
3
  method(): void {
4
    return;
5
  }
6
}

以下示例被认为是立即返回扩展名为 as const 的值的函数的正确代码：

¥The following example is considered correct code for a function immediately returning a value with as const:

1
var func = (value: number) => ({ foo: 'bar', value }) as const;

以下示例对于使用类型断言赋值的情况被认为是正确的代码：

¥The following example is considered correct code for a value assigned using type assertion:

1
function fn(): string {
2
    return "Not inline";
3
}
4
const direct = fn() as string;
5
const nested = { result: fn() as string };

以下示例被认为是特定表达式上下文（例如立即执行函数表达式 (IIFE)、作为参数传递的函数或数组中的函数）中允许的函数的正确代码：

¥The following examples are considered correct code for a function allowed within specific expression contexts, such as an IIFE, a function passed as an argument, or a function inside an array:

1
// Callbacks without return types
2
setTimeout(function() { console.log("Hello!"); }, 1000);

1
// Callbacks without argument types (immediately nested in a function call)
2
new Promise((resolve) => resolve(1));

1
// IIFE
2
(() => {})();

以下示例被认为是高阶函数的正确代码，其中返回的函数显式指定了返回类型，并且函数体仅包含一条语句：

¥The following example is considered correct code for a higher-order function, where the returned function explicitly specifies a return type and the function body contains only one statement:

1
// the outer function returns an inner function that has a `void` return type
2
var arrowFn = () => (): void => {};

1
// the outer function returns an inner function that has a `void` return type
2
var arrowFn = () => {
3
  return (): void => { };
4
}

以下示例被认为是函数表达式中变量类型注解的正确代码：

¥The following examples are considered correct for type annotations on variables in function expressions:

1
// A function with a type assertion using `as`
2
var asTyped = (() => '') as () => string;

1
// A function with a type assertion using `<>`
2
var castTyped = <() => string>(() => '');

1
// A variable declarator with a type annotation.
2
type FuncType = () => string;
3
var arrowFn: FuncType = () => 'test';

1
// A function is a default parameter with a type annotation
2
type CallBack = () => void;
3
var f = (gotcha: CallBack = () => { }): void => { };

1
// A class property with a type annotation
2
type MethodType = () => void;
3
class App {
4
    private method: MethodType = () => { };
5
}

useExplicitType

摘要

如何配置

描述

示例

无效

有效

相关链接