ThbTech/JavaProjectRepo

Fork 0

ProjectFrameWork2025 4dadab0990 chore(main-framework): remove non-framework dirs and keep aggregator for framework

2025-11-09 15:31:59 +08:00

14 KiB

Raw Blame History

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（示例）

<!-- 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（示例）

<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（示例）

<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 同步公共目录（不覆盖业务自定义配置）

# 在仓库根执行，将 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. 开发与协作工作流（落地命令）

初始化与分支创建

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

框架功能开发

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

业务功能开发与同步框架

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

业务前端初始化（从框架复制）

# 以 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）

# 仅构建框架
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. 配置管理与覆盖

框架通用配置示例

# 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@

业务特定配置示例

# 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. 冲突与同步指南

定期同步流程

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 集成建议

典型流水线分阶段

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. 落地与迁移指南

从当前结构平滑演进到推荐结构

保持现状：framework/frontend 作为基线前端，上游统一维护公共能力。
新增 business-app-a/ 模块（后端）：复制示例 POM，引入 platform-framework 依赖。
初始化业务前端：复制 framework/frontend → business-app-a/frontend，安装依赖并调整 .env.*、路由与页面。
在 Git 服务器上设置分支保护与 MR/PR 规则、必需检查与发布审批。
建立“前端同步脚本”或“公共组件抽取”机制，周期性从基线前端引入更新并审阅。

CSS 项目（Critical Scenario Simulator, CSS）落地步骤

根父 POM：在仓库根新增 pom.xml（已添加），注册 framework 与 business-css 模块。
业务后端：新增 business-css/pom.xml，依赖 com.yfd:platform:1.0 的 classes JAR（框架已配置 maven-jar-plugin）。
前端初始化：运行 ./scripts/sync-frontend.ps1 -Source "framework/frontend" -Target "business-css/frontend"，复制基线前端。
前端安装与启动：在 business-css/frontend 执行 pnpm i 或 npm ci 后，pnpm dev。
构建与测试：
- 后端单模块：mvn -pl business-css -am clean verify
- 聚合构建：mvn clean verify
分支策略建议：
- 框架：develop-framework → main，标签 fw-vx.y.z
- CSS：develop-business-css（或沿用 develop-business）→ business-main，标签 biz-css-vx.y.z
同步策略：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. 附录：命令速查

# 获取模块依赖树
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 模板与自动化检查清单。

14 KiB Raw Blame History Unescape Escape

Git 多分支 + 多模块 单仓库方案（优化版）