Typescript入门-JSDoc注释及tsconfig讲解

JSDoc 注释

TypeScript 直接处理 JS 文件时，如果无法推断出类型，会使用 JS 脚本里面的 JSDoc 注释。

使用 JSDoc 时，有两个基本要求。

（1）JSDoc 注释必须以 /** 开始，其中星号（*）的数量必须为两个。若使用其他形式的多行注释，则 JSDoc 会忽略该条注释。

（2）JSDoc 注释必须与它描述的代码处于相邻的位置，并且注释在上，代码在下。

下面是 JSDoc 的一个简单例子。

/*** @param {string} somebody*/
function sayHello(somebody) {console.log("Hello " + somebody);
}

上面示例中，注释里面的 @param 是一个 JSDoc 声明，表示下面的函数 sayHello() 的参数 somebody 类型为 string。

TypeScript 编译器支持大部分的 JSDoc 声明，下面介绍其中的一些。

• @typedef

  @typedef 命令创建自定义类型，等同于 TypeScript 里面的类型别名。

  /*** @typedef {(number | string)} NumberLike*/
  

  上面示例中，定义了一个名为 NumberLike 的新类型，它是由 number 和 string 构成的联合类型，等同于 TypeScript 的如下语句。

  type NumberLike = string | number;
  

• @type

  @type 命令定义变量的类型。

  /*** @type {string}*/
  let a;
  

  上面示例中，@type 定义了变量 a 的类型为 string。

  在 @type 命令中可以使用由 @typedef 命令创建的类型。

  /*** @typedef {(number | string)} NumberLike*//*** @type {NumberLike}*/
  let a = 0;
  

  在 @type 命令中允许使用 TypeScript 类型及其语法。

  /** @type {true | false} */
  let a;/** @type {number[]} */
  let b;/** @type {Array<number>} */
  let c;/** @type {{ readonly x: number, y?: string }} */
  let d;/** @type {(s: string, b: boolean) => number} */
  let e;
  

• @param

  @param命令用于定义函数参数的类型。

  /*** @param {string}  x*/
  function foo(x) {}
  

  如果是可选参数，需要将参数名放在方括号 [] 里面。

  /*** @param {string}  [x]*/
  function foo(x) {}
  

  方括号里面，还可以指定参数默认值。

  /*** @param {string} [x="bar"]*/
  function foo(x) {}
  

  上面示例中，参数 x 的默认值是字符串 bar。

• @return，@returns

  @return 和 @returns 命令的作用相同，指定函数返回值的类型。

  /*** @return {boolean}*/
  function foo() {return true;
  }/*** @returns {number}*/
  function bar() {return 0;
  }
  

• @extends 和类型修饰符

  @extends 命令用于定义继承的基类。

  /*** @extends {Base}*/
  class Derived extends Base {}
  

  @public、@protected、@private分别指定类的公开成员、保护成员和私有成员。

  @readonly指定只读成员。

  class Base {/*** @public* @readonly*/x = 0;/***  @protected*/y = 0;
  }
  

tsconfig.json

tsconfig.json 是 TypeScript 项目的配置文件，放在项目的根目录。反过来说，如果一个目录里面有 tsconfig.json，TypeScript 就认为这是项目的根目录。

如果项目源码是 JavaScript，但是想用 TypeScript 处理，那么配置文件的名字是jsconfig.json，它跟 tsconfig 的写法是一样的。

tsconfig.json 文件主要供 tsc 编译器使用，它的命令行参数 --project 或 -p 可以指定 tsconfig.json 的位置（目录或文件皆可）。

tsc -p ./dir

如果不指定配置文件的位置，tsc就会在当前目录下搜索 tsconfig.json 文件，如果不存在，就到上一级目录搜索，直到找到为止。

tsconfig.json 文件的格式，是一个 JSON 对象，最简单的情况可以只放置一个空对象{}。下面是一个示例。

{"compilerOptions": {"outDir": "./built","allowJs": true,"target": "es5"},"include": ["./src/**/*"]
}

后面会详细介绍 tsconfig.json 的各个属性，这里简单说一下，上面示例的四个属性的含义。

• include：指定哪些文件需要编译。
• allowJs：指定源目录的 JavaScript 文件是否原样拷贝到编译后的目录。
• outDir：指定编译产物存放的目录。
• target：指定编译产物的 JS 版本。

tsconfig.json 文件可以不必手写，使用 tsc 命令的 --init 参数自动生成。

tsc --init

上面命令生成的 tsconfig.json 文件，里面会有一些默认配置。

你也可以使用别人预先写好的 tsconfig.json 文件，npm 的 @tsconfig 名称空间下面有很多模块，都是写好的 tsconfig.json 样本，比如 @tsconfig/recommended 和 @tsconfig/node16 。

这些模块需要安装，以 @tsconfig/deno 为例。

npm install --save-dev @tsconfig/deno
# 或者
yarn add --dev @tsconfig/deno

安装以后，就可以在 tsconfig.json 里面引用这个模块，相当于继承它的设置，然后进行扩展。

{"extends": "@tsconfig/deno/tsconfig.json"
}

@tsconfig 空间下包含的完整 tsconfig 文件目录，可以查看 GitHub。

tsconfig.json 的一级属性并不多，只有很少几个，下面先逐一介绍一级属性。

• compilerOptions

  最核心的配置项，用于设置 TypeScript 编译器的具体行为（如目标版本、模块系统等）。包含众多子选项，例如 target（编译目标 JS 版本）、module（模块系统）、strict（严格模式开关）等。

• include

  include 属性指定所要编译的文件列表，既支持逐一列出文件，也支持通配符。文件位置相对于当前配置文件而定。

  {"include": ["src/**/*", "tests/**/*"]
  }
  

  include属性支持三种通配符。

  • ?：指代单个字符
  • *：指代任意字符，不含路径分隔符
  • **：指定任意目录层级。

  如果不指定文件后缀名，默认包括 .ts、.tsx 和 .d.ts 文件。如果打开了 allowJs，那么还包括 .js 和 .jsx 。

• exclude

  exclude 属性是一个数组，必须与 include 属性一起使用，用来从编译列表中去除指定的文件。它也支持使用与 include 属性相同的通配符。

  {"include": ["**/*"],"exclude": ["**/*.spec.ts"]
  }
  

• extends

  tsconfig.json 可以继承另一个 tsconfig.json 文件的配置。如果一个项目有多个配置，可以把共同的配置写成 tsconfig.base.json，其他的配置文件继承该文件，这样便于维护和修改。

  extends 属性用来指定所要继承的配置文件。它可以是本地文件。

  {"extends": "../tsconfig.base.json"
  }
  

  如果 extends 属性指定的路径不是以 ./ 或 ../ 开头，那么编译器将在 node_modules 目录下查找指定的配置文件。

  extends 属性也可以继承已发布的 npm 模块里面的 tsconfig 文件。

  {"extends": "@tsconfig/node12/tsconfig.json"
  }
  

  extends 指定的 tsconfig.json 会先加载，然后加载当前的 tsconfig.json。如果两者有重名的属性，后者会覆盖前者。

• files

  files 属性指定编译的文件列表，如果其中有一个文件不存在，就会报错。

  它是一个数组，排在前面的文件先编译。

  {"files": ["a.ts", "b.ts"]
  }
  

  该属性必须逐一列出文件，不支持文件匹配。如果文件较多，建议使用 include 和 exclude 属性。

• references

  references 属性是一个数组，数组成员为对象，适合一个大项目由许多小项目构成的情况，用来设置需要引用的底层项目。

  {"references": [{ "path": "../pkg1" },{ "path": "../pkg2/tsconfig.json" }]
  }
  

  references 数组成员对象的 path 属性，既可以是含有文件 tsconfig.json 的目录，也可以直接是该文件。

  references 是 TypeScript 项目引用（Project References）功能的核心配置项，主要用于大型项目的模块化管理和加速编译。下面详细解释它在实际项目中的作用：

  1. 项目拆分与依赖管理

     在大型项目中，通常会将代码拆分为多个子项目（包、模块），每个子项目有自己的 tsconfig.json。通过 references，你可以在主项目的 tsconfig.json 中声明对其他子项目的依赖关系：

     {"references": [{ "path": "../pkg1" },{ "path": "../pkg2/tsconfig.json" }]
     }
     

     这样 TypeScript 就知道主项目依赖哪些子项目，能自动处理编译顺序。

  2. 加速增量编译

     被引用的子项目（如 pkg1、pkg2）的 tsconfig.json 必须设置 "composite": true。这样 TypeScript 会为这些子项目生成 .tsbuildinfo 文件，记录编译信息。

     {"compilerOptions": {"composite": true}
     }
     

     当你只修改了某个子项目，TypeScript 只会重新编译受影响的部分，而不是整个项目，极大提升编译速度。

  3. 保证类型安全

     通过 references，主项目可以直接引用子项目的类型声明（.d.ts 文件），确保类型检查的准确性和一致性，避免类型丢失或不一致的问题。

  4. 支持独立开发与测试

     每个子项目都可以独立开发、测试和编译，最后通过 references 组合成一个完整的大项目，便于团队协作和代码复用。

     总结

     • references 用于声明 TypeScript 项目之间的依赖关系。
     • 能加速大型项目的编译，提升开发效率。
     • 保证类型安全，便于模块化开发和团队协作。

     如果你在用 monorepo（如 Lerna、Yarn Workspaces）管理多个包，references 是官方推荐的最佳实践。

  5. compileOptions

     compilerOptions 属性用来定制编译行为。这个属性可以省略，这时编译器将使用默认设置。