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 应用通常按 层构建,每一层只与相邻的层通信:

- 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] 的文件夹中,每个示例对应一个子文件夹:
所有示例共用相同的库,这些库在 [examples/package.json] 中声明。它们只需 安装一次,在打开到 [examples] 文件夹的控制台中进行。在 VSCode 中,打开 examples 文件夹:

然后,在 VSCode 集成的终端中,输入命令
此后每个示例都具有 [NestJS] 项目的最小结构:
- [src]:[TypeScript] 代码;
- [views]:来自 [Handlebars] 的视图(从第 4 章开始);
- [nest-cli.json]:[NestJS] 命令行工具的配置;
- [tsconfig.json]:[TypeScript] 编译器的配置。
要运行一个示例,请在其所在文件夹中打开控制台

然后输入:
[npx] 会在上级文件夹的 [node_modules] 文件夹中查找工具 [nest] 。[nest start] 会把 [TypeScript] 代码编译到 [dist] 文件夹中,然后执行 [dist/main.js]。使用 [--watch] 选项时,每当修改 [.ts] 文件,代码就会重新编译并重启服务器:
所有示例都监听 3000 端口:同一时间只能运行一个。在控制台中使用 [Ctrl-C] 停止服务器。
文件 [tsconfig.json] 对所有示例都是相同的:
我们来逐行说明这个文件:
- 第 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] 对所有示例也是通用的:
- 第 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 应用,逐文件讲解 | - |
每个示例只引入少量新概念,各章环环相扣:最好按顺序阅读。而案例研究则运用了前面各章的 所有概念:只要相关,其注释都会指向引入该概念的示例。