Skip to content

1. 引言

本文档的 PDF 在 |这里|。

本文档的代码在 |这里|。

本文档由 Anthropic 的 AI Claude 生成。其目的是将文档 *通过示例介绍 ASP.NET MVC*(2013)改编为 [NestJS] Web 框架:

  • [ASP.NET MVC] 框架和 [C#] 语言被 [NestJS] 框架和 [TypeScript] 语言取代;
  • [Razor] 视图被 [Handlebars] 视图取代;
  • [Entity Framework] 数据访问被 ORM [TypeORM] 和 [MySQL] 数据库取代。

本文档沿用原课程的结构:先是许多小项目,每个项目只聚焦一个概念,随后是 一个 完整的 案例研究——一个用于安排医疗诊所预约的 Web 应用——所有文件都带有完整注释。原课程中专门讲解 Web 编程基础(HTTP 协议、HTML 语言)的一章没有收录:这些基础知识默认读者已经掌握。

1.1. NestJS 在 Web 应用中的角色

Web 应用通常按 层构建,每一层只与相邻的层通信:

Image

  • Web 层接收来自浏览器的 HTTP 请求,并向其返回 HTML 页面。[NestJS] 帮助我们编写这一层;
  • 业务层包含应用的业务规则(例如,“一个患者只能有一个即将到来的预约”)。它对 Web 一无所知:它同样可以为命令行应用提供服务;
  • 数据访问层([DAO] 层,即 [Data Access Object])负责读写数据库。我们将使用 ORM [TypeORM] ([Object Relational Mapper]),它把表的行映射为 [TypeScript] 对象。

Web 层本身遵循 [MVC] ([Model – View – Controller])模式:

  • 控制器 (C)是一个类,其方法——称为 操作——各自处理一种特定类型的请求(例如 [GET /schedule])。操作读取请求参数,调用业务层,然后选择要显示的视图;
  • 模型 (M)是操作传递给视图的一组数据:一个简单的 [JavaScript] 对象;
  • 视图 (V)是一个 [Handlebars] 文件(扩展名 [.hbs]):一个 HTML 文件,其中的 [{{...}}] 标签会被模型中的数据替换。

请求的处理按照图中的编号步骤进行:

  • 1:浏览器发送一个 HTTP 请求,例如 [GET /schedule?doctorId=1&day=2026-09-24];
  • 2:[NestJS]基于 Web 服务器 [Express],选择负责处理该请求的操作:这就是 路由。在到达这一步之前,请求可能会经过 中间件、守卫、拦截器和 管道,我们将在后续章节中探讨;
  • 3:操作向业务层请求它所需的数据;
  • 4:它构建视图模板,并指定应显示它的视图;
  • 5:[Handlebars] 视图引擎生成 HTML 页面,由 [NestJS] 返回给浏览器。

[NestJS] 是一个用 [Node.js] 框架,使用 [TypeScript] 编写。它借鉴了 [Spring] ([Java])和 [Angular] 框架的概念:装饰器 ([@Controller]、[@Get]、[@Injectable]……)描述每个类的角色,依赖注入 为每个对象提供其所需的依赖。它常用于编写向 [JavaScript] 客户端([Angular]、[React]、[Flutter]……)返回 JSON 的服务器。本文档用它来编写一个 经典 Web 应用:由服务器生成 HTML 页面,浏览器只负责显示。

1.2. 使用的工具

示例是使用以下工具编写和测试的(安装方法见附录):

  • [Node.js] 20 及其包管理器 [npm];
  • 编辑器 [Visual Studio Code];
  • 一个较新的浏览器([Chrome]、[Firefox]、[Edge]);
  • 命令行工具 [curl],它显示原始的 HTTP 响应(它随 [Windows] 10 和 11 一同提供);
  • 数据库管理系统 [MySQL] (或 [MariaDB]),例如 [Laragon] 在 [Windows] 下提供的那个,从数据访问一章开始使用。

库的版本以示例文件夹中的 [package.json] 文件为准:[NestJS] 10、[TypeScript] 5、[hbs] 4([Handlebars])、[class-validator] 0.14、[TypeORM] 0.3、[Bootstrap] 5。

1.3. 示例

示例存放在名为 [examples] 的文件夹中,每个示例对应一个子文件夹:

1
2
3
4
5
6
7
8
examples/
├── 01-structure/
├── 02-routing/
├── ...
├── 28-layers/
├── node_modules/
├── package.json
└── package-lock.json

所有示例共用相同的库,这些库在 [examples/package.json] 中声明。它们只需 安装一次,在打开到 [examples] 文件夹的控制台中进行。在 VSCode 中,打开 examples 文件夹:

Image

然后,在 VSCode 集成的终端中,输入命令

npm install

此后每个示例都具有 [NestJS] 项目的最小结构:

13-first-view/
├── src/
│   ├── app.module.ts
│   ├── main.ts
│   └── views.controller.ts
├── views/
│   ├── index.hbs
│   └── unknown.hbs
├── nest-cli.json
└── tsconfig.json
  • [src]:[TypeScript] 代码;
  • [views]:来自 [Handlebars] 的视图(从第 4 章开始);
  • [nest-cli.json]:[NestJS] 命令行工具的配置;
  • [tsconfig.json]:[TypeScript] 编译器的配置。

要运行一个示例,请在其所在文件夹中打开控制台

Image

然后输入:

npx nest start

[npx] 会在上级文件夹的 [node_modules] 文件夹中查找工具 [nest] 。[nest start] 会把 [TypeScript] 代码编译到 [dist] 文件夹中,然后执行 [dist/main.js]。使用 [--watch] 选项时,每当修改 [.ts] 文件,代码就会重新编译并重启服务器:

npx nest start --watch

所有示例都监听 3000 端口:同一时间只能运行一个。在控制台中使用 [Ctrl-C] 停止服务器。

文件 [tsconfig.json] 对所有示例都是相同的:

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2022",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "allowSyntheticDefaultImports": true,
    "strictNullChecks": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

我们来逐行说明这个文件:

  • 第 3 行:编译后的代码使用 [CommonJS] 的 [Node.js] 模块([require]);
  • 第 4 行:生成的代码是较新的 [JavaScript] (ES2022),其中包含 [Node.js] 20 支持的特性;
  • 第 6–7 行:源代码在 [src] 中,编译后的代码在 [dist] 中;
  • 第 9–10 行:是 [NestJS] 所必需的。装饰器([@Controller]……)是 [TypeScript] 中必须启用的特性,而 [emitDecoratorMetadata] 会在编译后的代码中保留构造函数和方法参数的 类型:正是借助它,[NestJS] 才知道要向构造函数注入哪个对象;
  • 第 12 行:编译器会报告对可能为 [null] 或 [undefined] 的值的使用;
  • 第 13 行:不检查库的声明文件(编译更快)。

文件 [nest-cli.json] 对所有示例也是通用的:

1
2
3
4
5
6
7
8
{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "deleteOutDir": true
  }
}
  • 第 4 行:源代码在 [src] 中;
  • 第 6 行:每次编译前都会清空 [dist] 文件夹(从 [src] 中删除的文件不会留下过时的编译副本)。

1.4. 文档内容

本文档按如下方式展开:

章
内容
示例
控制器、操作、
从浏览器到操作:路由、响应、重定向、模块
01 至 06
操作模板
请求参数:转换、验证、POST 表单
07 至 12
视图及其模板
Handlebars、模板、局部视图、辅助函数、表单、验证、PRG
13 至 21
国际化
法语和英语的应用
22
数据作用域
应用、查询、客户端
23
请求的生命周期
中间件、守卫、拦截器、管道、异常过滤器
24
身份验证与授权
Cookie 中的 JWT、角色、CAPTCHA、尝试次数限制
25–27
分层架构
使用 TypeORM 和 MySQL 的 Web / 业务逻辑 / DAO
28
案例研究
RdvMedecins 应用,逐文件讲解
-

每个示例只引入少量新概念,各章环环相扣:最好按顺序阅读。而案例研究则运用了前面各章的 所有概念:只要相关,其注释都会指向引入该概念的示例。