408 lines
14 KiB
Markdown
408 lines
14 KiB
Markdown
# Git 多分支 + 多模块 单仓库方案（优化版）
|
||
|
||
本方案在原有文档基础上进行了结构重构与细则完善，使其更易落地、可操作性强，并与当前仓库现状保持一致且可平滑演进。
|
||
|
||
## 0. 适用范围与设计目标
|
||
|
||
- 适用范围：Java Spring Boot 后端 + 独立前端工程的单仓库（Monorepo）协作。
|
||
- 总体目标：
|
||
- 公共框架代码统一维护与版本化发布。
|
||
- 业务系统独立演进，低耦合地复用框架能力。
|
||
- 清晰的分支与发布节奏，降低冲突与回归风险。
|
||
|
||
## 1. 仓库结构与现状
|
||
```
|
||
|
||
### 推荐结构（框架含基线前端，业务前端复制自框架）
|
||
```
|
||
JavaProjectRepo/
|
||
├── framework/ # 后端框架（Maven 模块）+ 基线前端
|
||
│ └── frontend/ # 基线前端（可作为模板与上游源）
|
||
├── business-css/ # 业务系统A（Maven 模块）
|
||
│ ├── src/ # 业务A后端代码
|
||
│ └── frontend/ # 业务A前端（由 framework/frontend 复制）
|
||
├── docs/
|
||
├── pom.xml # 父POM（仅管理后端Maven模块）
|
||
```
|
||
|
||
说明：
|
||
- 保持 `framework/frontend` 为“基线前端”，承载公共 UI/组件、构建脚本与基础配置。
|
||
- 每个业务系统在自身目录下维护独立 `frontend/`，初始化时从 `framework/frontend` 复制；后续按业务需求改造。
|
||
- 根 `pom.xml` 仅管理后端模块；各前端项目独立使用 `pnpm/npm/yarn` 管理与构建。
|
||
|
||
## 2. 分支与权限策略
|
||
|
||
### 长期分支
|
||
```bash
|
||
main-framework # 框架稳定版本（受保护）
|
||
develop-framework # 框架开发分支
|
||
main-business-css # 业务稳定分支（单业务时，受保护）
|
||
develop-business-css # 业务开发分支（单业务时）
|
||
# 多业务可扩展：main-business-css / develop-business-css 等
|
||
```
|
||
|
||
### 受保护策略（建议在 Git 服务器上配置）
|
||
- `main-framework`、`main-business-css`：
|
||
- 禁止直接 push；必须通过合并请求（MR/PR）。
|
||
- 必须通过 CI（单元测试 + 构建）与至少 1 人代码评审。
|
||
- 建议启用“必须线性历史”（不允许非快进式合并）或统一使用 squash merge。
|
||
- 标签（tags）仅允许由“发布管理员”或 CI 流水线创建。
|
||
|
||
### 合并策略
|
||
- 框架到业务：业务分支定期合入 `main-framework` 的框架更新（推荐 `git merge --no-ff` 或 `git rebase`，视团队偏好）。
|
||
- 业务到业务稳定：`develop-business-css` → `main-business-css` 通过 MR/PR，保持发布记录清晰。
|
||
- 框架发布：`develop-framework` → `main-framework`，并打版本标签。
|
||
|
||
## 3. 代码组织（Maven 多模块 + 前端）
|
||
|
||
### 根 POM（示例）
|
||
```xml
|
||
<!-- pom.xml -->
|
||
<modules>
|
||
<module>framework</module>
|
||
<module>business-css</module>
|
||
<!-- 前端不纳入 Maven modules；独立管理 -->
|
||
<!-- 如需统一构建，可在 CI 中分阶段调用前端构建脚本 -->
|
||
</modules>
|
||
|
||
<properties>
|
||
<java.version>21</java.version>
|
||
<spring-boot.version>3.x</spring-boot.version>
|
||
<mybatis-plus.version>3.5.6</mybatis-plus.version>
|
||
</properties>
|
||
```
|
||
|
||
### Framework 模块 POM（示例）
|
||
```xml
|
||
<groupId>com.yfd.platform</groupId>
|
||
<artifactId>platform-framework</artifactId>
|
||
<version>1.0.0</version>
|
||
<packaging>jar</packaging>
|
||
|
||
<dependencies>
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-web</artifactId>
|
||
</dependency>
|
||
<dependency>
|
||
<groupId>com.baomidou</groupId>
|
||
<artifactId>mybatis-plus-boot-starter</artifactId>
|
||
<version>${mybatis-plus.version}</version>
|
||
</dependency>
|
||
</dependencies>
|
||
```
|
||
|
||
### Business-App 模块 POM（示例）
|
||
```xml
|
||
<parent>
|
||
<groupId>com.yfd.platform</groupId>
|
||
<artifactId>platform-parent</artifactId>
|
||
<version>1.0.0</version>
|
||
</parent>
|
||
|
||
<artifactId>platform-business-css</artifactId>
|
||
<packaging>war</packaging>
|
||
|
||
<dependencies>
|
||
<dependency>
|
||
<groupId>com.yfd.platform</groupId>
|
||
<artifactId>platform-framework</artifactId>
|
||
<version>${project.version}</version>
|
||
</dependency>
|
||
<!-- 业务特定依赖 -->
|
||
<!-- 如需框架版本对齐，建议使用 BOM 或统一 parent 管理 -->
|
||
<!-- 也可将框架发布到私有仓库（Nexus/Artifactory）后以固定版本依赖 -->
|
||
</dependencies>
|
||
```
|
||
|
||
### 前端工程（建议）
|
||
- `framework/frontend` 作为上游基线；业务前端以复制方式继承并二次开发。
|
||
- 每个业务的前端位于 `business-app-*/frontend`，独立构建与发布；与后端解耦。
|
||
- 公共前端能力尽量沉淀在基线前端的可复用目录（如 `src/shared`、`ui/components`），便于业务端复制后保持一致。
|
||
|
||
### 前端复制与同步策略
|
||
- 初次复制：从 `framework/frontend` 完整复制到 `business-app-x/frontend`，保留 `.editorconfig`、`eslint/prettier`、`tailwind`、`vite` 等工程化文件。
|
||
- 差异化开发：在业务前端中修改业务页面、路由、接口地址、主题等，不直接改动 `framework/frontend`。
|
||
- 上游更新引入（从框架基线同步到业务前端）可选方案：
|
||
- 轻量脚本复制：使用 `robocopy`（Windows）或 `rsync`（Linux/Mac）定期同步除配置与 `node_modules` 外的公共目录；同步前使用分支/MR审阅。
|
||
- 组件库抽取：将通用UI/工具抽取为 `shared` 子包（后续可独立NPM私库），业务端通过包管理升级；当前阶段以目录复制为主。
|
||
- 提交粒度控制：框架前端的公共改动与模板变更使用 `feat(shared):`、`refactor(shared):` 提交，业务端便于识别与选择性采纳。
|
||
|
||
示例：Windows 下使用 `robocopy` 同步公共目录（不覆盖业务自定义配置）
|
||
```powershell
|
||
# 在仓库根执行，将 framework/frontend 的公共目录同步到业务A前端
|
||
$src = "framework/frontend"
|
||
$dst = "business-app-a/frontend"
|
||
# 同步 src 目录与部分工程化文件；排除 node_modules、环境配置
|
||
robocopy $src $dst /MIR /XD node_modules .git .husky /XF .env* pnpm-lock.yaml
|
||
# 可按需选择性同步 src/shared、types 等
|
||
robocopy "$src/src/shared" "$dst/src/shared" /MIR
|
||
```
|
||
|
||
## 4. 开发与协作工作流（落地命令）
|
||
|
||
### 初始化与分支创建
|
||
```bash
|
||
git clone http://121.37.111.42:3000/ThbTech/JavaProjectRepo.git
|
||
cd JavaProjectRepo
|
||
git checkout -b main-framework
|
||
git push -u origin main-framework
|
||
|
||
# 框架开发分支
|
||
git checkout -b develop-framework
|
||
git push -u origin develop-framework
|
||
|
||
# 业务开发分支（如仅一个业务）
|
||
git checkout main-framework
|
||
git checkout -b develop-business-css
|
||
git push -u origin develop-business-css
|
||
```
|
||
|
||
### 框架功能开发
|
||
```bash
|
||
git checkout develop-framework
|
||
# 修改 framework/ 下代码
|
||
git add framework/
|
||
git commit -m "feat(framework): 新增通用权限管理模块"
|
||
git push origin develop-framework
|
||
|
||
# 合并到 main（发布框架版本）
|
||
git checkout main-framework
|
||
git merge --no-ff develop-framework
|
||
git tag -a fw-v1.1.0 -m "框架版本 v1.1.0"
|
||
git push origin main-framework --tags
|
||
```
|
||
|
||
### 业务功能开发与同步框架
|
||
```bash
|
||
git checkout develop-business
|
||
git fetch origin
|
||
git merge origin/main-framework # 合入最新框架
|
||
|
||
# 在 business-css/ 下开发
|
||
git add business-css/
|
||
git commit -m "feat(order): 实现订单管理功能"
|
||
git push origin develop-business-css
|
||
|
||
# 稳定分支（如需要）
|
||
git checkout -b main-business-css
|
||
git push -u origin main-business-css
|
||
```
|
||
|
||
### 业务前端初始化（从框架复制）
|
||
```powershell
|
||
# 以 business-app-a 为例：在仓库根执行
|
||
mkdir business-app-a\frontend
|
||
# 复制基线前端（保留工程化配置，排除 node_modules）
|
||
robocopy framework\frontend business-app-a\frontend /MIR /XD node_modules .git .husky /XF .env* pnpm-lock.yaml
|
||
|
||
# 进入业务前端目录并安装依赖
|
||
cd business-app-a\frontend
|
||
pnpm i || npm ci
|
||
|
||
# 修改业务专属配置：
|
||
# - package.json 的 name、version（如需）
|
||
# - .env.*（API 地址、端口等）
|
||
# - src/pages/*、src/routes/*（业务页面与路由）
|
||
|
||
# 开发与启动
|
||
pnpm dev || npm run dev
|
||
```
|
||
|
||
### 模块级构建与测试（Maven）
|
||
```bash
|
||
# 仅构建框架
|
||
mvn -pl framework -am clean package
|
||
|
||
# 仅测试业务模块
|
||
mvn -pl business-app -am clean test
|
||
|
||
# 全部模块
|
||
mvn clean verify
|
||
```
|
||
|
||
## 5. 版本与标签策略
|
||
|
||
- 框架版本采用 SemVer：`fw-vMAJOR.MINOR.PATCH`，如 `fw-v1.2.0`。
|
||
- 业务版本与框架版本对齐或独立：建议 `biz-<system>-vMAJOR.MINOR.PATCH`，如 `biz-order-v1.0.0`。
|
||
- 标签一律打在稳定分支合并完成后；禁止在临时/开发分支打标签。
|
||
|
||
## 6. 配置管理与覆盖
|
||
|
||
### 框架通用配置示例
|
||
```yaml
|
||
# framework/src/main/resources/application.yml
|
||
spring:
|
||
datasource:
|
||
druid:
|
||
url: jdbc:mysql://${DB_HOST:localhost}:3306/${DB_NAME:platform}?useUnicode=true&characterEncoding=UTF8
|
||
username: ${DB_USER:appuser}
|
||
password: ${DB_PASSWORD:}
|
||
profiles:
|
||
active: @activatedProperties@
|
||
```
|
||
|
||
### 业务特定配置示例
|
||
```yaml
|
||
# business-app/src/main/resources/application-dev.yml
|
||
server:
|
||
port: 8093
|
||
|
||
business:
|
||
order:
|
||
timeout: 3600
|
||
file:
|
||
upload-path: D:/data/business-upload
|
||
|
||
spring:
|
||
datasource:
|
||
druid:
|
||
url: jdbc:mysql://localhost:3306/business_db
|
||
```
|
||
|
||
配置原则：
|
||
- 框架提供默认配置；业务分支优先保留业务特定配置。
|
||
- 配置差异通过 profile 管理；不要在框架直接硬编码业务参数。
|
||
|
||
## 7. 冲突与同步指南
|
||
|
||
### 定期同步流程
|
||
```bash
|
||
git checkout develop-business
|
||
git fetch origin
|
||
git merge origin/main-framework # 或：git rebase origin/main
|
||
|
||
# 处理常见冲突：
|
||
# - application.yml / profiles 差异
|
||
# - 通用实体与业务扩展字段
|
||
# - 依赖版本不一致
|
||
|
||
mvn clean test -pl business-app
|
||
```
|
||
|
||
### 处理建议
|
||
- 配置冲突：业务优先；框架提供可扩展参数，而非覆盖业务。
|
||
- 实体冲突：为框架实体保留扩展点（如继承/组合）；避免强耦合。
|
||
- API 兼容：框架废弃旧 API 需标注 deprecate，过渡期保留兼容层。
|
||
- 推荐启用 `git rerere` 记忆冲突解决，减少重复操作。
|
||
|
||
## 8. CI/CD 集成建议
|
||
|
||
### 典型流水线分阶段
|
||
```yaml
|
||
stages:
|
||
- framework-test
|
||
- business-test
|
||
- frontend-build
|
||
- build
|
||
- deploy
|
||
|
||
framework-test:
|
||
only:
|
||
- develop-framework
|
||
- main
|
||
script:
|
||
- mvn -pl framework -am clean verify
|
||
|
||
business-test:
|
||
only:
|
||
- develop-business
|
||
- business-main
|
||
script:
|
||
- mvn -pl business-app -am clean verify
|
||
|
||
frontend-build:
|
||
only:
|
||
- develop-framework
|
||
- develop-business
|
||
- business-main
|
||
- main
|
||
script:
|
||
# 构建基线前端
|
||
- cd framework/frontend
|
||
- pnpm i --frozen-lockfile || npm ci
|
||
- pnpm build || npm run build
|
||
# 构建业务前端（示例：A；可按项目实际枚举）
|
||
- cd ../../business-css/frontend
|
||
- pnpm i --frozen-lockfile || npm ci
|
||
- pnpm build || npm run build
|
||
```
|
||
|
||
### 分支保护与质量门禁
|
||
- `main`/`business-main` 必须通过上述阶段且无失败后才允许合并。
|
||
- 建议强制代码扫描（如 SpotBugs、ESLint）、制品上传、部署前审批。
|
||
|
||
## 9. 落地与迁移指南
|
||
|
||
### 从当前结构平滑演进到推荐结构
|
||
1. 保持现状：`framework/frontend` 作为基线前端，上游统一维护公共能力。
|
||
2. 新增 `business-app-a/` 模块（后端）：复制示例 POM，引入 `platform-framework` 依赖。
|
||
3. 初始化业务前端：复制 `framework/frontend` → `business-app-a/frontend`，安装依赖并调整 `.env.*`、路由与页面。
|
||
4. 在 Git 服务器上设置分支保护与 MR/PR 规则、必需检查与发布审批。
|
||
5. 建立“前端同步脚本”或“公共组件抽取”机制，周期性从基线前端引入更新并审阅。
|
||
|
||
### CSS 项目（Critical Scenario Simulator, CSS）落地步骤
|
||
1. 根父 POM：在仓库根新增 `pom.xml`（已添加），注册 `framework` 与 `business-css` 模块。
|
||
2. 业务后端：新增 `business-css/pom.xml`，依赖 `com.yfd:platform:1.0` 的 classes JAR（框架已配置 maven-jar-plugin）。
|
||
3. 前端初始化：运行 `./scripts/sync-frontend.ps1 -Source "framework/frontend" -Target "business-css/frontend"`，复制基线前端。
|
||
4. 前端安装与启动：在 `business-css/frontend` 执行 `pnpm i` 或 `npm ci` 后，`pnpm dev`。
|
||
5. 构建与测试：
|
||
- 后端单模块：`mvn -pl business-css -am clean verify`
|
||
- 聚合构建：`mvn clean verify`
|
||
6. 分支策略建议：
|
||
- 框架：`develop-framework` → `main`，标签 `fw-vx.y.z`
|
||
- CSS：`develop-business-css`（或沿用 `develop-business`）→ `business-main`，标签 `biz-css-vx.y.z`
|
||
7. 同步策略：CSS 业务分支定期合入 `origin/main` 的框架更新；前端公共更新通过脚本或 MR 评审引入。
|
||
|
||
### 新业务扩展
|
||
```
|
||
ProjectFrameWork2025/
|
||
├── framework/
|
||
├── business-app-a/
|
||
├── business-app-b/
|
||
├── frontend/
|
||
└── pom.xml
|
||
```
|
||
- 每个业务独立 `develop-business-x` 与 `business-x-main` 分支；统一从 `main` 合入框架更新。
|
||
|
||
## 10. 开发规范（精炼）
|
||
|
||
### 提交消息（Conventional Commits 建议）
|
||
```
|
||
feat(order): 新增订单管理功能
|
||
fix(auth): 修复用户权限验证问题
|
||
docs(api): 更新接口文档
|
||
refactor(payment): 重构支付服务层
|
||
perf(db): 优化数据库查询性能
|
||
```
|
||
|
||
### 分支命名
|
||
- 功能：`feature/<模块>-<简述>`
|
||
- 修复：`hotfix/<问题>-<简述>`
|
||
- 发布：`release/<版本号>`
|
||
|
||
## 11. 运维监控与治理
|
||
|
||
- 分支健康：定期检查各业务分支落后于 `main` 的提交数，提示同步。
|
||
- 冲突监控：统计合并冲突频率与位置，反推框架设计优化点。
|
||
- 框架使用率：记录各业务对框架模块的依赖程度与版本分布，指导演进。
|
||
|
||
## 12. 附录：命令速查
|
||
|
||
```bash
|
||
# 获取模块依赖树
|
||
mvn -pl framework -am dependency:tree
|
||
|
||
# 仅运行某模块测试
|
||
mvn -pl business-app -am -DskipITs=false test
|
||
|
||
# 前端构建（根级）
|
||
cd frontend && pnpm i && pnpm build
|
||
```
|
||
|
||
---
|
||
|
||
本优化版方案兼顾当前仓库现状与后续演进路径，优先实现“可用且可管控”，再循序迭代至“前后端分离、多业务扩展”的理想结构。若需要，我可以进一步：
|
||
- 提供 Git 服务器（Gitea/GitLab）具体保护规则配置截图级操作步骤；
|
||
- 为当前 CI 环境生成可直接使用的脚本与模板文件；
|
||
- 输出 `CODEOWNERS`、PR 模板与自动化检查清单。 |