Typescript入门-JSDoc注释及tsconfig讲解

JSDoc 注释

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

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

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

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

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

ts 复制代码

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

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

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

@typedef

@typedef 命令创建自定义类型，等同于 TypeScript 里面的类型别名。
ts 复制代码
```
/**
 * @typedef {(number | string)} NumberLike
 */
```
上面示例中，定义了一个名为 NumberLike 的新类型，它是由 number 和 string 构成的联合类型，等同于 TypeScript 的如下语句。
ts 复制代码
```
type NumberLike = string | number;
```

@type

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

ts 复制代码

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

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

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

ts 复制代码

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

/**
 * @type {NumberLike}
 */
let a = 0;

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

ts 复制代码

/** @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命令用于定义函数参数的类型。
ts 复制代码
```
/**
 * @param {string}  x
 */
function foo(x) {}
```
如果是可选参数，需要将参数名放在方括号 [] 里面。
ts 复制代码
```
/**
 * @param {string}  [x]
 */
function foo(x) {}
```
方括号里面，还可以指定参数默认值。
ts 复制代码
```
/**
 * @param {string} [x="bar"]
 */
function foo(x) {}
```
上面示例中，参数 x 的默认值是字符串 bar。

@return，@returns

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

ts 复制代码

/**
 * @return {boolean}
 */
function foo() {
  return true;
}

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

@extends 和类型修饰符

@extends 命令用于定义继承的基类。
ts 复制代码
```
/**
 * @extends {Base}
 */
class Derived extends Base {}
```
@public、@protected、@private分别指定类的公开成员、保护成员和私有成员。

@readonly指定只读成员。
ts 复制代码
```
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 的位置（目录或文件皆可）。

cmd 复制代码

tsc -p ./dir

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

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

json 复制代码

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

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

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

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

cmd 复制代码

tsc --init

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

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

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

cmd 复制代码

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

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

json 复制代码

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

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

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

compilerOptions

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

include 属性指定所要编译的文件列表，既支持逐一列出文件，也支持通配符。文件位置相对于当前配置文件而定。
json 复制代码
```
{
  "include": ["src/**/*", "tests/**/*"]
}
```
include属性支持三种通配符。
- ?：指代单个字符
- *：指代任意字符，不含路径分隔符
- **：指定任意目录层级。
如果不指定文件后缀名，默认包括 .ts、.tsx 和 .d.ts 文件。如果打开了 allowJs，那么还包括 .js 和 .jsx 。
exclude

exclude 属性是一个数组，必须与 include 属性一起使用，用来从编译列表中去除指定的文件。它也支持使用与 include 属性相同的通配符。
json 复制代码
```
{
  "include": ["**/*"],
  "exclude": ["**/*.spec.ts"]
}
```
extends

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

extends 属性用来指定所要继承的配置文件。它可以是本地文件。
json 复制代码
```
{
  "extends": "../tsconfig.base.json"
}
```
如果 extends 属性指定的路径不是以 ./ 或 ../ 开头，那么编译器将在 node_modules 目录下查找指定的配置文件。

extends 属性也可以继承已发布的 npm 模块里面的 tsconfig 文件。
json 复制代码
```
{
  "extends": "@tsconfig/node12/tsconfig.json"
}
```
extends 指定的 tsconfig.json 会先加载，然后加载当前的 tsconfig.json。如果两者有重名的属性，后者会覆盖前者。
files

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

它是一个数组，排在前面的文件先编译。
json 复制代码
```
{
  "files": ["a.ts", "b.ts"]
}
```
该属性必须逐一列出文件，不支持文件匹配。如果文件较多，建议使用 include 和 exclude 属性。
references

references 属性是一个数组，数组成员为对象，适合一个大项目由许多小项目构成的情况，用来设置需要引用的底层项目。
json 复制代码
```
{
  "references": [
    { "path": "../pkg1" },
    { "path": "../pkg2/tsconfig.json" }
  ]
}
```
references 数组成员对象的 path 属性，既可以是含有文件 tsconfig.json 的目录，也可以直接是该文件。

references 是 TypeScript 项目引用（Project References）功能的核心配置项，主要用于大型项目的模块化管理和加速编译。下面详细解释它在实际项目中的作用：
1. 项目拆分与依赖管理
  
  在大型项目中，通常会将代码拆分为多个子项目（包、模块），每个子项目有自己的 tsconfig.json。通过 references，你可以在主项目的 tsconfig.json 中声明对其他子项目的依赖关系：
  json 复制代码
```
{
  "references": [
    { "path": "../pkg1" },
    { "path": "../pkg2/tsconfig.json" }
  ]
}
```
  这样 TypeScript 就知道主项目依赖哪些子项目，能自动处理编译顺序。
2. 加速增量编译
  
  被引用的子项目（如 pkg1、pkg2）的 tsconfig.json 必须设置 "composite": true。这样 TypeScript 会为这些子项目生成 .tsbuildinfo 文件，记录编译信息。
  json 复制代码
```
{
  "compilerOptions": {
    "composite": true
  }
}
```
  当你只修改了某个子项目，TypeScript 只会重新编译受影响的部分，而不是整个项目，极大提升编译速度。
3. 保证类型安全
  
  通过 references，主项目可以直接引用子项目的类型声明（.d.ts 文件），确保类型检查的准确性和一致性，避免类型丢失或不一致的问题。
4. 支持独立开发与测试
  
  每个子项目都可以独立开发、测试和编译，最后通过 references 组合成一个完整的大项目，便于团队协作和代码复用。
  
  总结
  - references 用于声明 TypeScript 项目之间的依赖关系。
  - 能加速大型项目的编译，提升开发效率。
  - 保证类型安全，便于模块化开发和团队协作。
  如果你在用 monorepo（如 Lerna、Yarn Workspaces）管理多个包，references 是官方推荐的最佳实践。
5. compileOptions
  
  compilerOptions 属性用来定制编译行为。这个属性可以省略，这时编译器将使用默认设置。