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 应用中的角色
应用由两部分组成,它们之间只通过请求进行通信:

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

浏览器在启动时只加载一个几乎为空的 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. 示例
文档中的代码组织在三个文件夹中:
examples 文件夹包含 25 个小型应用,每个示例一个,它们共用同一组库:
只需安装一次这些库,在 [examples-react] 文件夹下打开的控制台中执行(在 [VS Code] 中:Terminal 菜单 / New Terminal):
然后输入示例的名称来运行它:
[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 服务器提供服务的已编译客户端 | - |
每个示例都附有完整的代码(逐行注释)以及运行截图。代码本身有大量注释:这些注释是课程的一部分。