Skip to content

Commit 4b44fc1

Browse files
zhongspzhongsp
authored
New section: Project References (zhongsp#218)
New section "project references". close zhongsp#216
1 parent 857c5ed commit 4b44fc1

4 files changed

Lines changed: 215 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@
5858
* [使用](./doc/handbook/declaration%20files/Consumption.md)
5959
* [工程配置](./doc/handbook/tsconfig.json.md)
6060
* [tsconfig.json](./doc/handbook/tsconfig.json.md)
61+
* [工程引用](./doc/handbook/Project%20References.md)
6162
* [NPM包的类型](./doc/handbook/Typings%20for%20NPM%20Packages.md)
6263
* [编译选项](./doc/handbook/Compiler%20Options.md)
6364
* [配置 Watch](./doc/handbook/Configuring%20Watch.md)

‎SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@
4343
* [使用](./doc/handbook/declaration files/Consumption.md)
4444
* [工程配置](./doc/handbook/tsconfig.json.md)
4545
* [tsconfig.json](./doc/handbook/tsconfig.json.md)
46+
* [工程引用](./doc/handbook/Project References.md)
4647
* [NPM包的类型](./doc/handbook/Typings for NPM Packages.md)
4748
* [编译选项](./doc/handbook/Compiler Options.md)
4849
* [配置 Watch](./doc/handbook/Configuring Watch.md)

‎doc/handbook/Project References.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
工程引用是TypeScript 3.0的新特性，它支持将TypeScript程序的结构分割成更小的组成部分。
2+
3+
这样可以改善构建时间，强制在逻辑上对组件进行分离，更好地组织你的代码。
4+
5+
TypeScript 3.0还引入了`tsc`的一种新模式，即`--build`标记，它与工程引用协同工作可以加速TypeScript的构建。
6+
7+
# 一个工程示例
8+
9+
让我们来看一个非常普通的工程，并瞧瞧工程引用特性是如何帮助我们更好地组织代码的。
10+
假设这个工程具有两个模块：`converter`和`unites`，以及相应的测试代码：
11+
12+
```shell
13+
/src/converter.ts
14+
/src/units.ts
15+
/test/converter-tests.ts
16+
/test/units-tests.ts
17+
/tsconfig.json
18+
```
19+
20+
测试文件导入相应的实现文件并进行测试：
21+
22+
```ts
23+
// converter-tests.ts
24+
import * as converter from "../converter";
25+
26+
assert.areEqual(converter.celsiusToFahrenheit(0), 32);
27+
```
28+
29+
在之前，这种使用单一`tsconfig`文件的结构会稍显笨拙：
30+
31+
* 实现文件也可以导入测试文件
32+
* 无法同时构建`test`和`src`，除非把`src`也放在输出文件夹中，但通常并不想这样做
33+
* 仅对实现文件的*内部*细节进行改动，必需再次对测试进行*类型检查*，尽管这是根本不必要的
34+
* 仅对测试文件进行改动，必需再次对实现文件进行*类型检查*，尽管其实什么都没有变
35+
36+
你可以使用多个`tsconfig`文件来解决*部分*问题，但是又会出现新问题：
37+
38+
* 缺少内置的实时检查，因此你得多次运行`tsc`
39+
* 多次调用`tsc`会增加我们等待的时间
40+
* `tsc -w`不能一次在多个配置文件上运行
41+
42+
工程引用可以解决全部这些问题，而且还不止。
43+
44+
# 何为工程引用？
45+
46+
`tsconfig.json`增加了一个新的顶层属性`references`。它是一个对象的数组，指明要引用的工程：
47+
48+
```js
49+
{
50+
"compilerOptions": {
51+
// The usual
52+
},
53+
"references": [
54+
{ "path": "../src" }
55+
]
56+
}
57+
```
58+
59+
每个引用的`path`属性都可以指向到包含`tsconfig.json`文件的目录，或者直接指向到配置文件本身（名字是任意的）。
60+
61+
当你引用一个工程时，会发生下面的事：
62+
63+
* 导入引用工程中的模块实际加载的是它*输出*的声明文件（`.d.ts`）。
64+
* 如果引用的工程生成一个`outFile`，那么这个输出文件的`.d.ts`文件里的声明对于当前工程是可见的。
65+
* 构建模式（后文）会根据需要自动地构建引用的工程。
66+
67+
当你拆分成多个工程后，会显著地加速类型检查和编译，减少编辑器的内存占用，还会改善程序在逻辑上进行分组。
68+
69+
# `composite`
70+
71+
引用的工程必须启用新的`composite`设置。
72+
这个选项用于帮助TypeScript快速确定引用工程的输出文件位置。
73+
若启用`composite`标记则会发生如下变动：
74+
75+
* 对于`rootDir`设置，如果没有被显式指定，默认为包含`tsconfig`文件的目录
76+
* 所有的实现文件必须匹配到某个`include`模式或在`files`数组里列出。如果违反了这个限制，`tsc`会提示你哪些文件未指定。
77+
* 必须开启`declaration`选项。
78+
79+
# `declarationMaps`
80+
81+
我们增加了对[declaration source maps](https://github.com/Microsoft/TypeScript/issues/14479)的支持。
82+
如果启用`--declarationMap`，在某些编辑器上，你可以使用诸如“Go to Definition”，重命名以及跨工程编辑文件等编辑器特性。
83+
84+
# 带`prepend`的`outFile`
85+
86+
你可以在引用中使用`prepend`选项来启用前置某个依赖的输出：
87+
88+
```js
89+
"references": [
90+
{ "path": "../utils", "prepend": true }
91+
]
92+
```
93+
94+
前置工程会将工程的输出添加到当前工程的输出之前。
95+
它对`.js`文件和`.d.ts`文件都有效，`source map`文件也同样会正确地生成。
96+
97+
`tsc`永远只会使用磁盘上已经存在的文件来进行这个操作，因此你可能会创建出一个无法生成正确输出文件的工程，因为有些工程的输出可能会在结果文件中重覆了多次。
98+
例如：
99+
100+
```txt
101+
A
102+
^ ^
103+
/ \
104+
B C
105+
^ ^
106+
\ /
107+
D
108+
```
109+
110+
这种情况下，不能前置引用，因为在`D`的最终输出里会有两份`A`存在 - 这可能会发生未知错误。
111+
112+
# 关于工程引用的说明
113+
114+
工程引用在某些方面需要你进行权衡.
115+
116+
因为有依赖的工程要使用它的依赖生成的`.d.ts`，因此你必须要检查相应构建后的输出*或*在下载源码后进行构建，然后才能在编辑器里自由地导航。
117+
我们是在操控幕后的`.d.ts`生成过程，我们应该减少这种情况，但是目前还们建议提示开发者在下载源码后进行构建。
118+
119+
此外，为了兼容已有的构建流程，`tsc`*不会*自动地构建依赖项，除非启用了`--build`选项。
120+
下面让我们看看`--build`。
121+
122+
# TypeScript构建模式
123+
124+
在TypeScript工程里支持增量构建是个期待已久的功能。
125+
在TypeScrpt 3.0里，你可以在`tsc`上使用`--build`标记。
126+
它实际上是个新的`tsc`入口点，它更像是一个构建的协调员而不是简简单单的编译器。
127+
128+
运行`tsc --build`（简写`tsc -b`）会执行如下操作：
129+
130+
* 找到所有引用的工程
131+
* 检查它们是否为最新版本
132+
* 按顺序构建非最新版本的工程
133+
134+
可以给`tsc -b`指定多个配置文件地址（例如：`tsc -b src test`）。
135+
如同`tsc -p`，如果配置文件名为`tsconfig.json`，那么文件名则可省略。
136+
137+
## `tsc -b`命令行
138+
139+
你可以指令任意数量的配置文件：
140+
141+
```shell
142+
> tsc -b # Build the tsconfig.json in the current directory
143+
> tsc -b src # Build src/tsconfig.json
144+
> tsc -b foo/release.tsconfig.json bar # Build foo/release.tsconfig.json and bar/tsconfig.json
145+
```
146+
147+
不需要担心命令行上指定的文件顺序 - `tsc`会根据需要重新进行排序，被依赖的项会优先构建。
148+
149+
`tsc -b`还支持其它一些选项：
150+
151+
* `--verbose`：打印详细的日志（可以与其它标记一起使用）
152+
* `--dry`: 显示将要执行的操作但是并不真正进行这些操作
153+
* `--clean`: 删除指定工程的输出（可以与`--dry`一起使用）
154+
* `--force`: 把所有工程当作非最新版本对待
155+
* `--watch`: 观察模式（可以与`--verbose`一起使用）
156+
157+
# 说明
158+
159+
一般情况下，就算代码里有语法或类型错误，`tsc`也会生成输出（`.js`和`.d.ts`），除非你启用了`noEmitOnError`选项。
160+
这在增量构建系统里就不好了 - 如果某个过期的依赖里有一个新的错误，那么你只能看到它*一次*，因为后续的构建会跳过这个最新的工程。
161+
正是这个原因，`tsc -b`的作用就好比在所有工程上启用了`noEmitOnError`。
162+
163+
如果你想要提交所有的构建输出（`.js`, `.d.ts`, `.d.ts.map`等），你可能需要运行`--force`来构建，因为一些源码版本管理操作依赖于源码版本管理工具保存的本地拷贝和远程拷贝的时间戳。
164+
165+
# MSBuild
166+
167+
如果你的工程使用msbuild，你可以用下面的方式开启构建模式。
168+
169+
```xml
170+
<TypeScriptBuildMode>true</TypeScriptBuildMode>
171+
```
172+
173+
将这段代码添加到`proj`文件。它会自动地启用增量构建模式和清理工作。
174+
175+
注意，在使用`tsconfig.json` / `-p`时，已存在的TypeScript工程属性会被忽略 - 因此所有的设置需要在`tsconfig`文件里进行。
176+
177+
一些团队已经设置好了基于msbuild的构建流程，并且`tsconfig`文件具有和它们匹配的工程一致的*隐式*图序。
178+
若你的项目如此，那么可以继续使用`msbuild`和`tsc -p`以及工程引用；它们是完全互通的。
179+
180+
# 指导
181+
182+
## 整体结构
183+
184+
当`tsconfig.json`多了以后，通常会使用[配置文件继承](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html)来集中管理公共的编译选项。
185+
这样你就可以在一个文件里更改配置而不必在多个文件中进行修改。
186+
187+
另一个最佳实践是有一个`solution`级别的`tsconfig.json`文件，它仅仅用于引用所有的子工程。
188+
它用于提供一个简单的入口；比如，在TypeScript源码里，我们可以简单地运行`tsc -b src`来构建所有的节点，因为我们在`src/tsconfig.json`文件里列出了所有的子工程。
189+
注意从3.0开始，如果`tsconfig.json`文件里有至少一个工程引用`reference`，那么`files`数组为空的话也不会报错。
190+
191+
你可以在TypeScript源码仓库里看到这些模式 - 阅读`src/tsconfig_base.json`，`src/tsconfig.json`和`src/tsc/tsconfig.json`。
192+
193+
## 相对模块的结构
194+
195+
通常地，将代码转成使用相对模块并不需要改动太多。
196+
只需在某个给定父目录的每个子目录里放一个`tsconfig.json`文件，并相应添加`reference`。
197+
然后将`outDir`指定为输出目录的子目录或将`rootDir`指定为所有工程的某个公共根目录。
198+
199+
## `outFile`的结构
200+
201+
使用了`outFile`的编译输出结构十分灵活，因为相对路径是无关紧要的。
202+
要注意的是，你通常不需要使用`prepend` - 因为这会改善构建时间并结省I/O。
203+
TypeScript项目本身是一个好的参照 - 我们有一些“library”的工程和一些“endpoint”工程，“endpoint”工程会确保足够小并仅仅导入它们需要的“library”。
204+
205+
<!--
206+
## Structuring for monorepos
207+
208+
TODO: Experiment more and figure this out. Rush and Lerna seem to have different models that imply different things on our end
209+
-->

‎preface.md‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ TypeScript目前还在积极的开发完善之中，不断地会有新的特性
6565
* [使用](./doc/handbook/declaration files/Consumption.html)
6666
* [工程配置](./doc/handbook/tsconfig.json.html)
6767
* [tsconfig.json](./doc/handbook/tsconfig.json.html)
68+
* [工程引用](./doc/handbook/Project References.html)
6869
* [NPM包的类型](./doc/handbook/Typings for NPM Packages.html)
6970
* [编译选项](./doc/handbook/Compiler Options.html)
7071
* [配置 Watch](./doc/handbook/Configuring Watch.html)
@@ -109,14 +110,10 @@ TypeScript目前还在积极的开发完善之中，不断地会有新的特性
109110
* [TypeScript 1.5](./doc/breaking-changes/TypeScript 1.5.html)
110111
* [TypeScript 1.4](./doc/breaking-changes/TypeScript 1.4.html)
111112

112-
## 主要修改 (Latest 5 updates)
113+
## 最新修改
113114

114-
* 2017-11-07 新增章节：[JavaScript文件里的类型检查](./doc/handbook/Type Checking JavaScript Files.html)
115-
* 2017-05-16 新增章节：[教程-5分钟了解TypeScript](./doc/handbook/tutorials/TypeScript in 5 minutes.html)
116-
* 2017-05-01 新增章节：[教程-React](./doc/handbook/tutorials/React.html)
117-
* 2016-11-27 新增章节：[使用`/// <reference types="..." />`](./doc/handbook/Triple-Slash Directives.html)
118-
* 2016-11-23 新增章节：[变量声明 - 展开操作符](./doc/handbook/Variable Declarations.html)
119-
* 2016-10-23 新增章节：[高级类型 - 可辨识联合（Discriminated Unions）](./doc/handbook/Advanced Types.html)
115+
* 2018-08-15 新增章节：[工程引用](./doc/handbook/Project References.html)
116+
* [TypeScript 3.0](./doc/release-notes/TypeScript 3.0.html)
120117

121118
## 相关链接
122119

0 commit comments

Comments
 (0)