Mock 服务总览与运行机制
以下内容对React_Ts项目中的Mock服务设计方式与运行机制进行说明，实现服务定位、目录结构、启动方式与热重载原理。如需进行代码对照，可参考目录下 react19_ts 项目内实际代码，文档与代码会在git上持续补充
git仓库地址：https://gitee.com/xiaoli-account/react19_ts
如需新增接口、维护业务模块或查看工具函数说明
请阅读 下一篇 【React_TS 学习笔记（2-12-1）Mock 模块开发与项目集成】。
目录
Mock 服务总览与运行机制/├── 一、Mock 服务定位/│ ├── 1.1 为什么需要 Mock 服务│ ├── 1.2 当前实现的设计原则│ └── 1.3 整体工作流├── 二、目录结构与职责/│ ├── 2.1 当前目录结构│ └── 2.2 关键入口职责├── 三、快速开始/│ ├── 3.1 安装依赖│ ├── 3.2 启动方式/│ │ ├── 方式一：在 mock/ 目录独立启动，带热重载│ │ ├── 方式二：在 mock/ 目录独立启动，单次运行│ │ └── 方式三：在项目根目录联合启动前端和 Mock│ └── 3.3 验证启动├── 四、热重载机制/│ ├── 4.1 热重载要解决什么问题│ ├── 4.2 实现原理│ └── 4.3 监听范围与变更提示├── 五、依赖与运行边界/│ ├── 5.1 核心依赖│ └── 5.2 运行边界└── 六、下一步阅读
一、Mock服务定位
1.1 为什么需要 Mock 服务
前端开发最容易被后端接口阻塞的环节，通常不是页面本身，而是：
mock/ 目录提供的这套服务，目标就是让前端可以在后端尚未稳定时，先独立完成页面开发、接口联调和异常场景验证，并且尽量保持与真实接口调用方式一致。
1.2 当前实现的设计原则
| |
|---|
| 按业务领域拆分 module/*.js ，避免所有接口堆在一个文件里 |
| 修改 mock/ 相关文件后自动重启服务，减少手动停启成本 |
| |
| 前端通过代理切换到 Mock 模式，不需要改业务调用代码 |
| |
1.3 整体工作流
┌─────────────────────────────────────────────────────────────┐│ 前端项目 ││ npm run dev:mock ││ 浏览器请求 /mock-api/... │└───────────────────────────────┬─────────────────────────────┘ │ Vite 代理转发 ▼┌─────────────────────────────────────────────────────────────┐│ Mock 服务层 ││ watch.js -> app.js -> Express ││ │ │ ││ └── 监听变更并重启 ├── 注册 module/*.js 路由 ││ ├── 读取 config/*.js 配置 ││ └── 复用 utils/*.js 工具 │└─────────────────────────────────────────────────────────────┘
这意味着：
- Vite 会把
/mock-api 代理到 http://localhost:3000 - Mock 服务内部真正注册的路径，由
mock/config/api-url.js 当前配置决定
二、目录结构与职责
2.1 当前目录结构
mock/├── app.js # Express 服务入口├── watch.js # 热重载 watcher├── package.json # mock 子项目依赖与脚本├── readme.md # 总览与运行机制├── readme2.md # 模块开发与项目集成│├── config/│ ├── api-url.js # 接口路径前缀配置│ └── response.js # 统一响应模板│├── module/│ ├── index.js # 模块统一注册入口│ ├── login.js # 登录认证模块│ ├── user.js # 用户管理模块│ ├── role.js # 角色管理模块│ ├── menu.js # 菜单权限模块│ ├── dept.js # 部门管理模块│ ├── dict.js # 字典管理模块│ ├── dict-data.js # 字典数据模块│ ├── posts.js # 岗位管理模块│ ├── notice.js # 通知公告模块│ ├── version.js # 版本信息模块│ └── example.js # 示例演示模块│└── utils/ ├── common.js # 通用工具（分页、内存存储、模拟数据） ├── captcha.js # 验证码相关工具 └── sm4.js # SM4 加密解密工具
2.2 关键入口职责
| | |
|---|
| 启动 Express 服务并注册所有 mock 路由 | |
| | |
| | |
| | |
| | |
三、快速开始
3.1 安装依赖
在 mock/ 目录安装子项目依赖：
3.2 启动方式
方式一：在 mock/ 目录独立启动，带热重载
对应脚本：
{ "mock": "node watch.js"}
方式二：在 mock/ 目录独立启动，单次运行
对应脚本：
{ "mock:once": "node app.js"}
方式三：在项目根目录联合启动前端和 Mock
根目录脚本会执行 mock.startup.script.js，同时启动：
- Mock 服务：
npm --prefix mock run mock
3.3 验证启动
启动成功后，终端会打印类似输出：
-------------------------------------- React19_Ts Mock Server Successfully ➜ Local: http://localhost:3000 ➜ Network: http://192.168.x.x:3000--------------------------------------
你可以据此确认三件事：
四、热重载机制
4.1 热重载要解决什么问题
Mock 文件通常会被频繁修改，如果每次改完都要手动：
联调效率会明显下降。
因此当前实现选择了“Watcher 进程 + Server 子进程”的方式，把“监听文件”和“处理 HTTP 请求”拆开：
watch.js 只负责检测变更app.js 只负责启动服务- 一旦发现文件变化，Watcher 会关闭旧服务，再拉起新服务
4.2 实现原理
┌─────────────┐ ┌─────────────┐ ┌─────────────┐│ 轮询检测 │────▶│ 快照对比 │────▶│ 差异分析 ││ (800ms) │ │ (mtimeMs) │ │ (增/删/改) │└─────────────┘ └─────────────┘ └──────┬──────┘ │ ▼ ┌─────────────┐ │ 优雅重启 │ │ 子进程管理 │ └─────────────┘
这套机制的关键点是：
- 不直接使用
fs.watch 做大范围监听，避免当前环境下更容易出现监听不稳定或文件数过多问题 - 用
mtimeMs 文件快照做增量对比，逻辑更可控 - 子进程退出与重启都由
watch.js 统一接管，避免端口冲突
4.3 监听范围与变更提示
当前 watch.js 监听的重点目录包括：
const WATCH_TARGETS = [ path.join(ROOT_DIR, "app.js"), path.join(ROOT_DIR, "module"), path.join(ROOT_DIR, "config"),];
当前实现还约束了：
当文件变更时，终端会显示类似日志：
[ mock-watch ] Detected mock file changes, restarting...[ mock-watch ] updated: module/user.js | added: module/new-module.js[ mock-watch ] Mock server restarted
从这些日志里可以快速判断：
五、依赖与运行边界
5.1 核心依赖
| | |
|---|
| | Web 服务器框架，负责接收与返回 HTTP 请求 |
| | |
| | |
| | |
| | |
app.js├── express├── cors└── module/index.js ├── config/*.js └── utils/*.js ├── mockjs └── gm-crypt
5.2 运行边界
当前实现里有两个容易混淆、但必须区分的“前缀”：
前端在 Mock 模式下通过：
VITE_API_BASE_URL=/mock-apiVITE_APP_API_URL=http://localhost:3000
也就是说，浏览器请求的是 /mock-api/*，再由 Vite 代理到 http://localhost:3000/*。
mock/config/api-url.js 当前配置为：
export const API_BEFORE_URL = "";
这表示 Mock 服务注册的真实接口路径当前没有额外前缀，例如：
- 代理转发后：
http://localhost:3000/login
六、下一步阅读
如果你接下来要做的是：
- 复用
utils/common.js、utils/captcha.js、utils/sm4.js
请继续阅读下一篇 【React_TS 学习笔记（2-12-1）Mock 模块开发与项目集成】。
