docs：新增本地服务管理规则优化设计文档
- 强制使用 dev-services.py 控制本地服务 - 前端/H5 固定端口从 5178 开始累加 - 优化 restart 命令，避免无意义重启
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
---
|
||||
author: claude
|
||||
created_at: 2026-06-27
|
||||
purpose: 规范本地服务管理：强制使用 dev-services.py 控制前后端服务，固定前端/H5 端口从 5178 开始累加，优化热加载避免无意义重启
|
||||
---
|
||||
|
||||
# 本地服务管理规则优化设计
|
||||
|
||||
## 背景
|
||||
|
||||
当前项目使用 `dev-services.py` 管理本地前后端服务，但存在以下问题：
|
||||
|
||||
1. 前端/H5 端口分散配置在各自 `vite.config.*` 中，未统一管理
|
||||
2. `dev-services.py` 端口冲突时自动递增，导致端口号不稳定
|
||||
3. 用户已习惯使用 `dev-services.py`，但缺少"禁止无意义重启"的强制约束
|
||||
4. 热加载场景下，开发者可能误重启支持热更新的前端服务，浪费时间
|
||||
|
||||
## 目标
|
||||
|
||||
1. 强制：启动/重启/停止本地前后端服务必须使用 `dev-services.py`
|
||||
2. 固定：前端和 H5 服务端口从 5178 开始累加分配
|
||||
3. 优化：`dev-services.py restart` 在无必须重启的变更时禁止重启
|
||||
4. 一致：更新 CLAUDE.md 规则文档，与脚本行为对齐
|
||||
|
||||
## 方案选择
|
||||
|
||||
采用 **方案 A：dev-services.py 内置固定端口表 + 修改各项目 vite 配置**
|
||||
|
||||
- 端口控制集中且与项目配置一致
|
||||
- 与现有 `dev-services.py` 架构兼容
|
||||
- 便于开发者直接查看配置文件了解端口
|
||||
|
||||
## 详细设计
|
||||
|
||||
### 1. 固定端口分配表
|
||||
|
||||
| 服务 | 目录 | 类型 | 固定端口 |
|
||||
|---|---|---|---|
|
||||
| Emotion-museum-web | `web/` | Vite | 5178 |
|
||||
| Emotion-museum-admin | `web-admin/` | Vite | 5179 |
|
||||
| Emotion-museum-uniapp | `mini-program/` | UniApp H5 | 5180 |
|
||||
| Life-script 前端 | `life-script/` | Vite | 5181 |
|
||||
|
||||
后端服务端口保持现有配置不变。
|
||||
|
||||
### 2. dev-services.py 修改
|
||||
|
||||
#### 2.1 新增固定端口映射
|
||||
|
||||
```python
|
||||
FIXED_FRONTEND_PORTS = {
|
||||
"web": 5178,
|
||||
"web-admin": 5179,
|
||||
"mini-program": 5180,
|
||||
"life-script": 5181,
|
||||
}
|
||||
```
|
||||
|
||||
按项目目录名匹配。如果目录名不在映射中，仍按原有逻辑处理。
|
||||
|
||||
#### 2.2 修改端口分配逻辑
|
||||
|
||||
在 `assign_unique_ports()` 中：
|
||||
- 对 `FIXED_FRONTEND_PORTS` 中定义的服务，强制使用固定端口
|
||||
- 如果固定端口被非前端服务占用，报错退出
|
||||
- 如果固定端口被另一个前端服务占用，报错退出（说明映射配置错误）
|
||||
- 不再对前端服务自动递增端口
|
||||
|
||||
#### 2.3 新增 restart 热加载保护
|
||||
|
||||
定义"必须重启才能生效"的文件模式：
|
||||
|
||||
```python
|
||||
RESTART_REQUIRED_PATTERNS = [
|
||||
r'vite\.config\.(ts|js|mjs|cjs)$',
|
||||
r'tsconfig\.json$',
|
||||
r'\.env(\.[^/]*)?$',
|
||||
r'package\.json$',
|
||||
r'application.*\.ya?ml$',
|
||||
r'pom\.xml$',
|
||||
r'build\.gradle(\.kts)?$',
|
||||
]
|
||||
```
|
||||
|
||||
`restart` 命令执行前：
|
||||
1. 获取 git 工作区中已修改的文件列表：`git diff --name-only`
|
||||
2. 如果没有修改，提示"未检测到代码变更，无需重启"
|
||||
3. 如果修改文件匹配 `RESTART_REQUIRED_PATTERNS`，允许正常 restart
|
||||
4. 如果修改文件不匹配，拒绝 restart 并提示：
|
||||
> 当前修改只涉及支持热加载的源码文件，无需重启。如需强制重启，请使用 `python dev-services.py restart --force`
|
||||
|
||||
#### 2.4 支持 `--force` 参数
|
||||
|
||||
在 `restart` 子命令解析中增加 `--force` 选项，允许用户绕过热加载保护强制重启。
|
||||
|
||||
### 3. 前端项目配置修改
|
||||
|
||||
| 文件 | 修改内容 |
|
||||
|---|---|
|
||||
| `web/vite.config.ts` | `server.port` 改为 5178 |
|
||||
| `web/.env.development` | 添加 `VITE_PORT=5178` |
|
||||
| `web-admin/vite.config.ts` | `server.port` 改为 5179 |
|
||||
| `web-admin/.env.development` | `VITE_APP_PORT` 改为 5179 |
|
||||
| `mini-program/vite.config.js` | `server.port` 改为 5180 |
|
||||
| `mini-program/.env.development` | 添加 `VITE_PORT=5180` |
|
||||
| `life-script/vite.config.js` | `server.port` 改为 5181 |
|
||||
| `life-script/.env.development` | 添加 `VITE_PORT=5181`（不存在则创建） |
|
||||
|
||||
### 4. CLAUDE.md 规则更新
|
||||
|
||||
新增"本地服务管理规则"章节：
|
||||
|
||||
1. **必须使用 dev-services.py**：
|
||||
- 启动、重启、停止本地前后端服务必须使用 `python dev-services.py [命令] [服务名]`
|
||||
- 禁止直接使用 `npm run dev`、`npm run dev:h5`、`mvn spring-boot:run` 等命令
|
||||
|
||||
2. **前端/H5 固定端口**：
|
||||
- `web`: 5178
|
||||
- `web-admin`: 5179
|
||||
- `mini-program`: 5180
|
||||
- `life-script`: 5181
|
||||
|
||||
3. **禁止无意义重启**：
|
||||
- 只有修改必须重启才能生效的文件时，才允许执行 `restart`
|
||||
- 修改源码文件（`.vue`、`.tsx`、`.ts`、`.js`、`.css`、`.scss` 等）时禁止 restart
|
||||
- 确需强制重启时，使用 `python dev-services.py restart --force`
|
||||
|
||||
4. **热加载规则**：
|
||||
- 前端修改源码文件优先利用热加载
|
||||
- 后端修改代码按现有规则处理（本地不启动后端，使用服务器验收）
|
||||
|
||||
### 5. 边界情况
|
||||
|
||||
| 场景 | 行为 |
|
||||
|---|---|
|
||||
| 固定端口被占用 | `dev-services.py` 报错，要求先停止占用该端口的服务 |
|
||||
| 无代码变更执行 restart | 提示无需重启 |
|
||||
| 只修改 `.vue` 文件执行 restart | 拒绝重启，提示使用 `--force` 或无需重启 |
|
||||
| 修改 `vite.config.ts` 执行 restart | 允许正常 restart |
|
||||
| 多个服务同时 restart | 每个服务独立检测，符合规则的重启，不符合的跳过 |
|
||||
| 用户传 `--force` | 跳过所有检测，强制重启 |
|
||||
|
||||
## 修改范围
|
||||
|
||||
| 文件 | 操作 |
|
||||
|---|---|
|
||||
| `dev-services.py` | 修改：添加固定端口映射、优化端口分配、新增热加载保护 |
|
||||
| `web/vite.config.ts` | 修改：端口改为 5178 |
|
||||
| `web/.env.development` | 修改/创建：添加 `VITE_PORT=5178` |
|
||||
| `web-admin/vite.config.ts` | 修改：端口改为 5179 |
|
||||
| `web-admin/.env.development` | 修改：`VITE_APP_PORT` 改为 5179 |
|
||||
| `mini-program/vite.config.js` | 修改：端口改为 5180 |
|
||||
| `mini-program/.env.development` | 修改/创建：添加 `VITE_PORT=5180` |
|
||||
| `life-script/vite.config.js` | 修改：端口改为 5181 |
|
||||
| `life-script/.env.development` | 修改/创建：添加 `VITE_PORT=5181` |
|
||||
| `CLAUDE.md` | 修改：更新本地服务管理规则 |
|
||||
Reference in New Issue
Block a user