Skip to content

1. 简介

本文档的 PDF 在 这里。

本文档的代码在 这里。

本文档由 Anthropic 的 AI Claude 撰写。它是课程 “NestJS Web 框架分步入门”的延续,并 转换了视角:

  • 在 [NestJS] 课程中,服务器 生成 HTML 页面(视图引擎 [Handlebars]);浏览器只负责显示;
  • 在本课程中,页面由 浏览器中的 [React] 应用生成;服务器如今只是一个 JSON 服务器,仅提供数据。

不过,应用的页面保持不变:它们就是之前已用其他框架介绍过的 [RdvMedecins] 应用的页面(带验证码(CAPTCHA)的登录、医生日程、预约窗口、患者门户、医生和客户端管理、账户创建、法语和英语)。

本文档的结构与前几份文档相同:先是大量简短的示例,每个示例聚焦 [React] 的一个具体概念,然后是一个完整的案例研究——应用 [RdvMedecins] 的 [React] 客户端——并为所有文件加上注释。它与课程 *Vue.js 框架分步入门* 和 *Angular 框架分步入门*的结构相同:熟悉 [Vue.js] 或 [Angular] 的读者会看到同样的示例,只是以 [React] 的风格编写:共 25 个示例,编号与 [Angular] 课程中的相同。

关于这个主题已经有一门课程:React 客户端/服务器示例 / NestJS (2026),它同时涵盖服务器和客户端。本文档与它的区别在于方法:服务器被视为 黑盒,我们只关心 API 和 JSON;在着手完整的客户端之前,我们先 分步学习 [React] 。

1.1. React 在 Web 应用中的角色

应用由两部分组成,它们之间只通过请求进行通信:

Image

  • 1:在浏览器中运行的 [React] 应用向服务器发送 HTTP 请求,例如 [GET /api/schedule?doctorId=1&day=2026-10-05];
  • 2:服务器返回 JSON 数据:该医生当天的日程。它不生成任何页面;
  • 3:利用这些数据,[React] 更新浏览器中显示的页面,而无需重新加载。

下图对比了这两种架构:

Image

浏览器在启动时只加载一个几乎为空的 HTML 页面。其余一切都由 [JavaScript] 代码生成:这就是所谓的 单页应用 (SPA,即 [Single Page Application])。当用户点击内部链接时,不会向服务器请求页面:路由器改变显示的 URL 并替换页面内容。

[React] 是由 [Facebook] (现为 [Meta])创建并于 2013 年发布的库。它是目前使用最广泛的 Web 界面构建库,基于三个概念:

  • 组件:界面被拆分为可复用的部分(导航栏、表单字段、确认窗口等)。[React] 组件就是一个返回需要显示内容的简单 [JavaScript] (或 [TypeScript])函数,用 JSX 编写,这是一种融合了 HTML 与 [JavaScript] 的语法;
  • 状态 与 声明式渲染:组件的数据保存在它的 状态 ([useState])中。状态改变时,[React] 调用组件的函数,将结果与上一次比较,并自动更新页面上发生变化的部分。我们从不编写直接修改页面的代码:我们 根据状态来描述页面;
  • Hook:组件通过这些函数([useState]、[useEffect]、[useContext]……)访问 [React] 的各种机制:状态、副作用和共享数据。你可以编写自己的 Hook 来复用某种行为。

与 [Angular] 不同,[React] 不是“一体化”框架:它是一个渲染库。路由器、表单、HTTP 客户端、翻译和共享状态都由开发者选择的其他库提供。本课程使用最常见的几个:[React Router] (路由器)、[React Hook Form] (一个示例性的表单库)、[TanStack Query] (读取服务器数据)、[Zustand] (共享状态)和 [i18next] (多语言)。构建工具是 [Vite]。

我们将使用 [React] 19 及其最新的实现方式:函数组件与 Hook(过去以类编写的旧组件已不再使用)、表单 action([useActionState])、[use()] 与 [<Suspense>]、由组件放置的 [<title>] 、[useEffectEvent] 和 [<Activity>] (React 19.2)。

1.2. 所用工具

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

  • [Node.js] 24(或至少 22.22:这是 [React Router] 8 的要求)及其包管理器 [npm];
  • 编辑器 [Visual Studio Code],它无需任何额外扩展即可支持 [TypeScript] 和 JSX;
  • 一款较新的浏览器([Chrome]、[Firefox]、[Edge]),最好安装 [React Developer Tools] 扩展;
  • 命令行工具 [curl],它可以显示原始的 HTTP 响应;
  • 数据库管理系统 [MySQL] (或 [MariaDB]),例如 [Laragon] 在 [Windows] 下自带的那个:JSON 服务器需要它,详见介绍该服务器的章节。

所用的库以 [package.json] 文件中的为准:[React] 19.3、[React Router] 8.4、[Vite] 8.3、[TypeScript] 6.0、[React Hook Form] 7.89、[TanStack Query] 5.104、[Zustand] 5.0、[i18next] 26 和 [react-i18next] 17、[Bootstrap] 5.3。

1.3. 示例

文档中的代码组织在三个文件夹中:

1
2
3
4
deliverable/
├── examples-react/            the 25 small React examples
├── rdvmedecins-nestjs-json/   the RdvMedecins JSON server (the "black box")
└── rdvmedecins-react/         the React client of the case study

examples 文件夹包含 25 个小型应用,每个示例一个,它们共用同一组库:

examples-react/
├── 01-first-application/
│   ├── index.html
│   └── src/
├── 02-state/
├── ...
├── 25-server-errors/
├── common/            code shared by examples 24 and 25
├── node_modules/
├── package.json
├── tsconfig.json
└── vite.config.ts     the Vite configuration, shared by all the examples

只需安装一次这些库,在 [examples-react] 文件夹下打开的控制台中执行(在 [VS Code] 中:Terminal 菜单 / New Terminal):

npm install

然后输入示例的名称来运行它:

npm start 01-first-application

[Vite] 开发服务器在 5173 端口提供示例:请在 http://localhost:5173/ 打开它。修改文件时无需重启该服务器:每个保存的文件都会立即重新编译,浏览器页面自动更新,通常连状态都不会丢失。在运行下一个示例之前,请在控制台中输入 [Ctrl-C] 停止它(同一时间只能有一个示例占用 5173 端口)。

示例 22 到 25 会查询 JSON 服务器和 [RdvMedecins] 服务器:你需要先安装并启动它们,具体见专门介绍它们的章节。

1.4. 文档内容

章
内容
示例
入门
应用、状态、JSX、事件、受控字段、useReducer、验证、React Hook Form、格式化
01–09
组件
props、向上传递给父组件的函数、组合(children、render props)、生命周期与副作用、上下文、自定义 Hook、确认对话框
10 到 16
路由
React Router、导航守卫 (中间件)
17 和 18
异步操作与共享状态
定时器、防抖、过期响应、use() 与 Suspense、Zustand
19 和 20
国际化
法语和英语的应用(i18next)
21
服务器:黑盒
JSON 服务器的安装、它的 API、curl 示例
-
与服务器交互
fetch、登录与 Cookie、表单 action、API 访问层、TanStack Query、服务器错误
22–25
案例研究
RdvMedecins 应用的 React 客户端
-
部署
由 JSON 服务器提供服务的已编译客户端
-

每个示例都附有完整的代码(逐行注释)以及运行截图。代码本身有大量注释:这些注释是课程的一部分。