🔑代码分支管理规范

📋 1. 概述

本文档旨在为团队建立统一的 Git 分支管理规范，覆盖分支创建、开发协作、代码合并和版本发布（Deploy）等核心环节。通过标准化的流程和约定，降低协作成本，提高代码质量，保障发布安全。

1.1 适用范围

  • 所有后端服务项目
  • 所有前端项目
  • 包含但不限于日常需求开发、紧急修复（Hotfix）、版本迭代等场景

1.2 核心原则

原则 说明
主分支始终可发布 master / RELEASE 分支必须保持稳定、可部署状态
分支隔离 不同需求/功能在独立分支开发，避免互相影响
向上合并，禁止反向污染 只允许 master → feature → private 方向同步，严禁 test/pre 合入开发分支
少量多次 频繁提交、频繁合并，避免大范围代码冲突
先审后合 所有合入主分支的代码必须经过 Code Review

🌳 2. 分支模型

2.1 分支体系总览

master / RELEASE          ← 生产环境（只能从此分支打包部署）
  │
  ├── pre-production / pre-branch   ← 预发布环境
  │
  ├── test / testing                ← 测试环境
  │
  ├── feature/xxx                   ← 功能开发主分支（从 master 创建）
  │     │
  │     ├── private/xxx-A           ← 个人开发分支（从 feature 创建）
  │     └── private/xxx-B
  │
  └── hotfix/xxx                    ← 紧急修复分支（从 master 创建）

2.2 各分支职责

分支类型 说明 来源 生命周期
master / RELEASE 生产环境代码，保持稳定可发布 — 永久
pre-production / pre-branch 预发布验证环境 — 永久
test / testing 测试环境 — 永久
feature/xxx 功能开发主分支，承载一个完整需求 从 master 创建 需求上线后删除
private/xxx 个人开发分支，日常编码在此进行 从 feature 创建 合并后及时删除
hotfix/xxx 线上紧急问题修复 从 master 创建 修复上线后删除

gitlab上会对master/pre-production/test/feature分支添加保护，禁止直接推送代码，只允许通过MR进行代码合并。
对于test分支，若项目测试环境不影响其他项目，可放开保护，直接推送代码到test分支。

🏷️ 3. 分支命名规范

3.1 命名格式

<类型>/<简要描述>

3.2 命名规则

分支类型 格式 示例
功能开发主分支 feature/<功能描述> feature/user-management
个人开发分支 private/<日期>-<功能> 或 private/<功能描述> private/20260415-user-login、private/user-list
紧急修复分支 hotfix/<问题描述> hotfix/login-bug

3.3 命名要求

  • 使用小写字母和连字符（kebab-case），如 feature/order-export
  • 名称应清晰描述功能或问题，可读性优先
  • 禁止使用特殊字符、空格、中文

🔄 4. 开发协作流程

4.1 单人开发流程

适用于由单个开发者独立完成的需求。

1. 从 master 创建 feature 分支
2. 从 feature 创建 private 分支
3. 在 private 分支上进行开发、提交
4. 通过 MR 将 private 合并回 feature
5. feature 分支发布灰度，进行测试验证
6. 验证通过后，通过 MR 将 feature 合并到 master

# Step 1: 创建功能分支
git checkout master
git pull origin master
git checkout -b feature/user-management

# Step 2: 创建个人分支
git checkout feature/user-management
git checkout -b private/user-list

# Step 3: 开发并提交
git add .
git commit -m "feat: 添加用户列表功能"

# Step 4: 推送并在 GitLab 提交 MR → feature 分支
git push origin private/user-list

4.2 多人协作开发流程

适用于多人协同完成同一需求/模块的场景。

1. 负责人从 master 创建 feature 分支
2. 各开发者从 feature 创建各自的 private 分支
3. 各自在 private 分支并行开发
4. 每完成一部分功能就提交 MR 合并到 feature（少量多次）
5. feature 分支发布灰度，进行测试验证
6. 功能完成后，合并 feature → master

# 负责人创建功能分支
git checkout master && git pull origin master
git checkout -b feature/user-management

# 开发者 A
git checkout feature/user-management && git pull
git checkout -b private/user-list

# 开发者 B
git checkout feature/user-management && git pull
git checkout -b private/user-form

4.3 紧急修复流程（Hotfix）

适用于生产环境紧急问题修复。

# 1. 从 master 创建 hotfix 分支
git checkout master
git pull origin master
git checkout -b hotfix/login-bug

# 2. 修复问题并提交
git add .
git commit -m "fix: 修复登录验证逻辑错误"

# 3. 推送并在 GitLab 提交 MR → master
git push origin hotfix/login-bug

修复流程要点：

  • hotfix 分支必须从 master 创建
  • 修复完成后发布灰度，提供灰度链接供测试验证
  • 验证通过后通过 MR 合并到 master
  • 合并后需同步到 test / pre-production 分支

4.4 分支合并方向（红线规则）

✅ 允许的合并方向:
   master → feature → private      （代码同步）
   private → feature → master      （代码合并）

❌ 严禁的操作:
   test / pre-production → private  （会污染开发分支）
   test / pre-production → feature  （会污染功能分支）
   private → master                 （跳过 feature，缺少审查）

核心红线：只有 master 和 feature 分支才可以向个人开发分支合并，其它分支一律禁止。

📝 5. Commit 提交规范

遵循 Conventional Commits 规范。

5.1 提交格式

<type>: <subject>

<body>（可选）

5.2 Type 类型

类型 说明 示例
feat 新功能开发 feat: 添加用户登录功能
fix 问题修复 fix: 修复登录页面验证逻辑错误
refactor 代码重构（不改变功能） refactor: 优化订单查询逻辑
docs 文档变更 docs: 更新 API 接口文档
style 代码格式调整（不影响逻辑） style: 格式化代码缩进
test 增加或修改测试 test: 添加用户模块单元测试
chore 构建、依赖等杂项变更 chore: 更新依赖包版本
build 构建系统或 CI/CD 变更 build: 更新 webpack 配置
perf 性能优化 perf: 优化列表查询响应速度

5.3 提交要求

  • 每次提交只包含一个逻辑变更
  • subject 使用中文或英文皆可，但团队内保持统一
  • 禁止提交无意义信息（如 update、fix、test）
  • body 部分可用列表形式描述具体变更内容

示例：

feat: 添加用户管理页面

- 实现用户列表展示
- 添加用户搜索功能
- 完成用户删除操作

🔍 6. Merge Request (MR) 规范

6.1 MR 标题规范

MR 标题应包含类型前缀，与 Commit 类型一致：

feat: 添加用户管理功能
fix: 修复订单金额计算错误
hotfix: 紧急修复支付回调异常

6.2 MR 必填项

项目 要求
标题 包含类型前缀，清晰描述变更内容
审核人 指定对应的 Leader 或模块负责人
关联需求 所有 MR 必须关联对应的需求，且关联准确
描述 说明变更背景、影响范围和测试方式

6.3 MR 审核流程

提交 MR → 代码扫描（Sonar）→ Code Review → 解决评论 → 审核通过 → 合并
  1. 代码扫描：MR 提交后自动触发 Sonar 扫描，扫描未通过禁止合并
  2. Code Review：审核人添加评论后需点击提交按钮使评论生效
  3. 解决评论：提交人须逐一解决 CR 评论，点击 Resolve 标记已解决
  4. 合并时机：CR 问题全部解决后尽快合并，避免长时间挂起

6.4 代码质量要求

指标 要求
Code Smell 必须全部解决，否则将被统计并上报
单元测试覆盖率 不低于 60%，鼓励使用 AI 辅助生成测试用例
Sonar 扫描 必须通过，扫描失败需重试或联系 GitLab 支持

6.5 MR 注意事项

  • Bug 修复：测试提的 bug 不要直接在 test 分支上改，必须在个人开发分支上改完后再合并到 test
  • 及时关闭无效 MR：不合并的 MR 必须及时关闭，避免被相同 commit 的 MR 合并时自动合并
  • Rebase 处理：当 MR 提示需要 rebase 时，将目标分支最新代码合并到 MR 源分支（如 xxx-fortest），不要合并到个人开发分支以免污染

🔀 7. 代码合并策略

7.1 合并到 feature 分支

  • 日常开发中，每完成一部分功能就提交 MR 合并到 feature 分支
  • 不必等功能全部完成才合并——少量多次、持续集成
  • 只有提测时 feature 分支才会用于灰度/测试发布

7.2 合并到 test / pre-production 分支

  • 测试验证阶段，将 feature 或开发分支合并到 test / pre-production
  • 推荐方式：
# （推荐）本地切换到 testing 分支，合并开发主分支
git checkout testing
git pull origin testing
git merge feature/user-management
git push origin testing

仅适用与testing未保护场景

  • 或从开发主分支拉临时分支，提 MR 合并到 testing / pre-branch

7.3 合并到 master / RELEASE 分支

  • 所有合入 master 的代码必须经过完整的 MR + CR 流程
  • 合并前检查变更是否符合预期
  • 建议在上线前 30 分钟以上提交 MR，避免多次 rebase
  • 合并到 master 过程中的 MR 不强制要求 CR（但需自查变更内容）

7.4 冲突解决

private → feature 冲突：

# 在 private 分支本地合并 feature 最新代码
git checkout private/user-list
git pull origin feature/user-management
# 解决冲突后提交
git add .
git commit -m "fix: 解决与 feature 分支的合并冲突"
git push origin private/user-list
# MR 会自动更新

feature → master 冲突：

# 从 feature 拉出临时 private 分支
git checkout feature/user-management
git checkout -b private/sync-release
# 合并 master 最新代码
git merge master
# 解决冲突后提交 MR → feature
# feature → master 的 MR 会自动更新

注意： 严禁直接将 master 合入 feature 分支来解决冲突（应通过临时分支中转）。

🚀 8. 版本发布与部署（Deploy）

8.1 环境与分支对应关系

环境 对应分支 打包规则
生产环境（Production） master / RELEASE 只能从此分支打包
预发布环境（Pre-production） pre-production / pre-branch 只能从此分支打包
测试环境（Testing） test / testing 只能从此分支打包

严格约束： 各环境只能从对应分支打包部署，禁止跨分支打包。

8.2 发布流程

开发完成 → 合并到 test → 测试验证
         → 合并到 pre-production → 预发布验证
         → 合并到 master → 生产发布

标准发布步骤

  1. 开发自测：在 feature 分支发布灰度环境，提供灰度链接进行自测
  2. 测试验证：合并到 test/testing 分支，在测试环境进行完整测试
  3. 预发布验证：合并到 pre-production/pre-branch 分支，进行预发布验证
  4. 生产发布：通过 MR 合并到 master/RELEASE 分支，从 master 打包部署
  5. 上线审批：部署触发审批流，上线前须提前周知相关负责人

8.3 灰度发布

  • 开发主分支（feature）支持灰度发布，用于开发自测和测试验证
  • hotfix 分支同样可发布灰度，供修复验证
  • 灰度发布后需提供灰度链接给测试同学

8.4 版本号管理（后端服务）

对于需要升级 jar 包版本的服务，按以下步骤操作：

  1. 使用maven命令升级对应版本
  2. 完成版本变动提交后，再提交 MR 合并代码
  3. 版本变更代码合并至目标分支后，在指定分支进行deploy

8.5 回滚策略

当生产发布出现问题时，按以下优先级处理：

场景 处理方式
问题可快速修复 走 Hotfix 流程，修复后重新发布
问题影响范围大、无法快速修复 在 CI/CD 平台回滚到上一个稳定版本
回滚后需排查 从 master 的上一个稳定 commit 创建 hotfix 分支进行分析

回滚原则： 优先恢复服务可用性，再排查根因。回滚操作须通知相关负责人并记录事故报告。

8.6 Tag 与版本标记

  • 每次生产发布成功后，建议在 master 分支打 Tag 标记版本
  • Tag 命名格式：v<主版本>.<次版本>.<修订号>，如 v1.2.0、v1.2.1
  • Hotfix 发布递增修订号，如 v1.2.0 → v1.2.1
  • 功能迭代递增次版本号，如 v1.2.1 → v1.3.0
# 打 Tag 示例
git checkout master
git pull origin master
git tag -a v1.3.0 -m "feat: 用户管理模块上线"
git push origin v1.3.0

💡 9. 最佳实践

✅ 推荐做法

实践 说明
频繁合并 每完成一部分功能就合并到 feature 分支，避免最后一次性合并导致大量冲突和 CR 负担
保持同步 合并前先拉取最新的 feature 分支代码，解决冲突后再合并
清晰提交 使用规范的 commit 信息，每次提交只包含一个逻辑变更
及时清理 合并完成后删除已合并的 private 和 feature 分支
本地调试隔离 本地调试时添加 dubbo 注册分组参数，避免服务注册到测试环境
MR 日常化 每天的开发内容都可提交 MR 到开发主分支，降低单次 CR 量

❌ 避免做法

禁止行为 原因
在 feature 分支直接开发（多人协作时） 多人直接修改同一分支极易冲突
长时间不合并代码 积累大量差异，增加冲突风险和 CR 难度
提交不相关的代码变更 影响 CR 质量，增加回滚风险
private 分支直接合并到 master 跳过 feature 分支的集成验证和 CR
从 test/pre-production 拉取个人开发分支 环境分支代码混杂，会污染开发分支
将 test/pre-production 合入个人开发分支 同上，严重的分支污染
直接在 test 分支上修复 bug 修复无法追溯，且无法同步到其他环境
Sonar 扫描未通过就强制合并 引入代码质量问题

❓ 10. 常见问题（FAQ）

Q1: 如何解决 private → feature 的合并冲突？

  1. private 分支提交 MR 合并至 feature 分支
  2. 发现有冲突提示需要 rebase
  3. 在 private 分支本地合并 feature 分支，解决冲突
  4. 提交解决后的代码并推送
  5. 提交后 MR 会自动更新

Q2: 如何同步最新的 master 代码到 feature 分支？

  1. 从 feature 分支拉出一个 private 临时分支
  2. 在临时分支本地合并 master 分支
  3. 临时分支提交 MR 合并至 feature 分支
  4. 合并后 feature → master 的 MR 会自动更新

Q3: private 分支可以直接合并到 master 吗？

不建议。 应该先合并到 feature 分支，再由 feature 合并到 master，保持完整的代码审查流程。

Q4: MR 出现 rebase 提示怎么处理？

这是因为目标分支有了新的提交。将目标分支的最新代码合并到 MR 的源分支（如 xxx-fortest、xxx-forpre），注意不要合到个人开发分支，否则开发分支会被污染。

Q5: Sonar 扫描结果上传失败怎么办？

  1. 禁止在扫描未完成时合并
  2. 重新触发 MR 扫描
  3. 多次失败可尝试关闭 MR 再重新提交
  4. 仍无法解决则在 GitLab 话题群联系 GitLab 同学协助

Q6: 本地调试如何避免影响测试环境？

在 IDEA 的 JVM 启动参数中添加 dubbo 注册分组：

-Ddubbo.registry.provider.group=zk-test-<你的名字缩写>
-Dkeycenter.dev.enable=true

分组名保持唯一，不要与测试环境相同。

Q7: 什么时候合并代码到 testing / pre-branch 分支？

推荐在测试验证完成后在本地完成合并：

# 推荐方式
git checkout testing
git pull origin testing
git merge feature/user-management
git push origin testing

或从开发主分支拉临时分支，提 MR 合并到 testing/pre-branch。

Q8: 生产发布后发现严重问题怎么办？

  1. 立即评估影响范围，通知相关负责人
  2. 若问题可快速修复（< 30 分钟），走 Hotfix 流程
  3. 若无法快速修复，在 CI/CD 平台回滚到上一个稳定版本
  4. 回滚后创建 hotfix 分支排查根因，修复后重新走发布流程

Q9: 什么时候需要打 Tag？

每次生产环境发布成功后，建议在 master 分支打 Tag 标记版本号（如 v1.3.0），方便后续回溯和回滚。

📎 附录：分支生命周期示意

附录 A：标准开发流程时序图

sequenceDiagram autonumber participant M as master / RELEASE participant F as feature/xxx participant P as private/xxx participant T as test / testing participant Pre as pre-production M->>F: 创建功能分支 F->>P: 创建个人开发分支 loop 日常开发（少量多次） P->>P: 编码 & commit P->>F: 提交 MR + Code Review F->>F: 审核通过，合并 end F->>F: 灰度发布 & 开发自测 F->>T: 合并到测试分支 T->>T: 测试环境验证 F->>Pre: 合并到预发布分支 Pre->>Pre: 预发布环境验证 F->>M: 提交 MR + Code Review M->>M: 审核通过，合并 M->>M: 生产环境部署上线 M->>M: 打 Tag 标记版本 Note over F,P: 清理 feature / private 分支

附录 B：Hotfix 紧急修复时序图

sequenceDiagram autonumber participant M as master / RELEASE participant H as hotfix/xxx participant T as test / testing participant Pre as pre-production M->>H: 创建 hotfix 分支 H->>H: 修复问题 & commit H->>H: 灰度发布 & 验证 H->>M: 提交 MR → master M->>M: 审核通过，合并 M->>M: 生产环境部署 M->>M: 打 Tag（修订号 +1） M-->>T: 同步修复到 test M-->>Pre: 同步修复到 pre-production Note over H: 清理 hotfix 分支

附录 C：分支关系全景图

graph LR subgraph 永久分支 M["master / RELEASE<br/>🟢 生产环境"] Pre["pre-production<br/>🟡 预发布环境"] T["test / testing<br/>🔵 测试环境"] end subgraph 临时分支 F["feature/xxx<br/>功能开发主分支"] PA["private/xxx-A<br/>开发者 A"] PB["private/xxx-B<br/>开发者 B"] HF["hotfix/xxx<br/>紧急修复"] end M -->|"① 创建"| F F -->|"② 创建"| PA F -->|"② 创建"| PB PA -->|"③ MR 合并"| F PB -->|"③ MR 合并"| F F -->|"④ 合并"| T F -->|"⑤ 合并"| Pre F -->|"⑥ MR 合并"| M M -->|"创建"| HF HF -->|"MR 合并"| M style M fill:#d4edda,stroke:#28a745 style Pre fill:#fff3cd,stroke:#ffc107 style T fill:#cce5ff,stroke:#007bff style F fill:#f8d7da,stroke:#dc3545 style PA fill:#e2e3e5,stroke:#6c757d style PB fill:#e2e3e5,stroke:#6c757d style HF fill:#f5c6cb,stroke:#dc3545
posted @ 2026-04-15 19:22  丿似锦  阅读(130)  评论(0)    收藏  举报