当前位置：首页 > news >正文

代码分支管理规范

news 2026/4/17 10:10:31

📋 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 → 解决评论 → 审核通过 → 合并

代码扫描：MR 提交后自动触发 Sonar 扫描，扫描未通过禁止合并
Code Review：审核人添加评论后需点击提交按钮使评论生效
解决评论：提交人须逐一解决 CR 评论，点击 Resolve 标记已解决
合并时机：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 → 生产发布

标准发布步骤

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

8.3 灰度发布

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

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

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

使用maven命令升级对应版本
完成版本变动提交后，再提交 MR 合并代码
版本变更代码合并至目标分支后，在指定分支进行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 的合并冲突？

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

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

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

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

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

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

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

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

禁止在扫描未完成时合并
重新触发 MR 扫描
多次失败可尝试关闭 MR 再重新提交
仍无法解决则在 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: 生产发布后发现严重问题怎么办？

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

Q9: 什么时候需要打 Tag？

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

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

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

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

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

sequenceDiagramautonumberparticipant M as master / RELEASEparticipant H as hotfix/xxxparticipant T as test / testingparticipant Pre as pre-productionM->>H: 创建 hotfix 分支H->>H: 修复问题 & commitH->>H: 灰度发布 & 验证H->>M: 提交 MR → masterM->>M: 审核通过，合并M->>M: 生产环境部署M->>M: 打 Tag（修订号 +1）M-->>T: 同步修复到 testM-->>Pre: 同步修复到 pre-productionNote over H: 清理 hotfix 分支

附录 C：分支关系全景图

graph LRsubgraph 永久分支M["master / RELEASE 🟢 生产环境"]Pre["pre-production 🟡 预发布环境"]T["test / testing 🔵 测试环境"]endsubgraph 临时分支F["feature/xxx 功能开发主分支"]PA["private/xxx-A 开发者 A"]PB["private/xxx-B 开发者 B"]HF["hotfix/xxx 紧急修复"]endM -->|"① 创建"| FF -->|"② 创建"| PAF -->|"② 创建"| PBPA -->|"③ MR 合并"| FPB -->|"③ MR 合并"| FF -->|"④ 合并"| TF -->|"⑤ 合并"| PreF -->|"⑥ MR 合并"| MM -->|"创建"| HFHF -->|"MR 合并"| Mstyle M fill:#d4edda,stroke:#28a745style Pre fill:#fff3cd,stroke:#ffc107style T fill:#cce5ff,stroke:#007bffstyle F fill:#f8d7da,stroke:#dc3545style PA fill:#e2e3e5,stroke:#6c757dstyle PB fill:#e2e3e5,stroke:#6c757dstyle HF fill:#f5c6cb,stroke:#dc3545

查看全文

http://www.jsqmd.com/news/646294/