keyfil/文档/基础组件/20250627-Git分支管理规范（修订版）.md

<!-- Space: qifu -->
<!-- Parent: 后端技术&知识&规范 -->
<!-- Parent: 技术方案 -->
<!-- Parent: 基建 -->
<!-- Parent: 00-基础组件 -->
<!-- Title: 20250627-Git分支管理规范（修订版） -->

<!-- Macro: :anchor\((.*)\):
     Template: ac:anchor
     Anchor: ${1} -->
<!-- Macro: \!\[.*\]\((.+)\)\<\!\-\- width=(.*) \-\-\>
     Template: ac:image
     Url: ${1}
     Width: ${2} -->
<!-- Macro: \<\!\-\- :toc: \-\-\>
     Template: ac:toc
     Printable: 'false'
     MinLevel: 2 
     MaxLevel: 4 -->
<!-- Include: 杂项/声明文件.md -->

<!-- :toc: -->

# 20250627-Git分支管理规范（修订版）

## 分支策略概述

- 本规范基于 GitFlow 工作流，结合公司一些实际情况。规范明确了分支类型、使用场景、操作流程及权限控制。
- 支持多团队，多迭代并行开发
    - 多迭代通过 `develop/xxx` 区分
    - 多团队通过 `feature/xxx` 区分

![](https://picture.texous.cn/blog/20250630122310545.png)

## 分支类型与用途

### 1. 主分支 (master)

- **作用**：生产环境代码，存放稳定可发布的版本
- **保护规则**：
    - 禁止直接 push
    - 只接受来自 release 或 hotfix 分支的 Merge Request
    - 至少需要 2 个代码审查批准才能合并
    - 每次合并自动触发版本标签（X.Y.Z）

### 2. 项目迭代分支 (develop/xxx)

- **命名规范**：`develop/<date>-<迭代标识>` (如 `develop/20250601-s14`)
- **创建方式**：从 master 分支切出
- **作用**：单个项目/迭代周期的开发主线
- **生命周期**：
    - 创建：迭代启动时
    - 删除：保留10个历史迭代
- **合并规则**：
    - 接受来自 feature/xxx 分支的 Merge Request

### 3. 功能分支 (feature/xxx)

- **命名规范**：`feature/<date>-<功能描述>` (如 `feature/20250603-user-auth`)
- **创建方式**：从 develop/xxx 分支切出
- **作用**：单个功能/模块的开发
- **生命周期**：
    - 创建：功能开发开始时
    - 删除：功能发布到预发环境后
- **操作规范**：
    - 每天至少 rebase 一次 develop/xxx 分支
    - 功能完成并通过自测后发起 Merge Request

### 4. 发布分支 (release/xxx)

- **命名规范**：`release/<date>-<版本号>` (如 `release/20250625-1.2.0`)
- **创建方式**：从 master 分支切出
- **作用**：版本发布准备
- **操作流程**：
    1. 从 master 切出 release 分支
    2. 合并对应 develop/xxx 分支
    3. 进行预发布测试和修复
    4. 合并到 uat 分支进行用户验收测试
    5. 测试通过后合并到 master
- **保护规则**：
    - 只接受来自 develop/xxx 的 Merge Request
    - 只能合并到 master 和 uat

### 5. 热修复分支（hotfix/xxx）

- **命名规范**：`hotfix/<date>-<问题描述>` (如 `hotfix/20250630-payment-bug`)
- **创建方式**：从 master 分支切出
- **作用**：线上问题修复
- **操作流程**：
    1. 从 master 切出 hotfix 分支
    2. 进行BUG修复
    3. 提交 Merge Request
    4. 修复后合并到 develop/xxx 分支
- **保护规则**：
    - 只能合并到 master 和 develop/xxx

### 6. 环境部署分支

| 分支类型  | 分支名     | 环境    | 更新来源                        | 自动部署规则       |
|-------|---------|-------|-----------------------------|--------------|
| 开发环境  | develop | 开发环境  | develop/xxx 合并              | 每次 push 自动部署 |
| 测试环境  | test    | 测试环境  | develop/xxx 分支合并            | 每次 push 自动部署 |
| UAT环境 | uat     | UAT环境 | release/xxx 合并              | 手动触发部署       |
| 生产环境  | master  | 生产环境  | release/xxx 或 hotfix/xxx 合并 | 手动触发部署       |

## 工作流程详解

### 新功能开发流程

![](https://picture.texous.cn/blog/20250630140742061.png)

### 提测流程

![](https://picture.texous.cn/blog/20250630140857246.png)

### 版本发布流程

![](https://picture.texous.cn/blog/20250630140930403.png)

### 热修复流程

![](https://picture.texous.cn/blog/20250630141021309.png)

## 分支命名规范

| 分支类型   | 命名模式                           | 示例                                  |
|--------|--------------------------------|-------------------------------------|
| 项目迭代分支 | `develop/<date>-s<storyid>`    | `develop/20250601-s14`              |
| 功能分支   | `feature/<date>-<description>` | `feat/20250603-user-authentication` |
| 发布分支   | `release/<date>-<version>`     | `release/20250625-1.2.0`            |
| 热修复分支  | `hotfix/<date>-<issue>`        | `hotfix/20250630-login-error`       |

## 权限控制

### Git 仓库权限矩阵

| 操作                | 开发者 | 技术主管 | 运维工程师 |
|-------------------|-----|------|-------|
| 创建 feature/xxx 分支 | ✓   | ✓    | ✗     |
| 合并到 develop/xxx   | ✗   | ✓    | ✗     |
| 创建 release/xxx 分支 | ✗   | ✓    | ✓     |
| 合并到 master        | ✗   | ✓    | ✓     |
| 创建 hotfix 分支      | ✗   | ✓    | ✓     |
| 删除分支              | ✗   | ✓    | ✓     |

### Merge Request 规则

1. **最小审批人数**：
    - feature → develop/xxx：1人（主R）
    - develop/xxx → release/xxx：1人（主R）
    - release/xxx → master：2人（含1名运维，暂由主R执行）
    - hotfix/xxx → master：2人（含1名运维，暂由主R执行）
    - hotfix/xxx → develop/xxx: 1人（主R）

2. **必需检查**：
    - 所有测试用例通过
    - 代码覆盖率不低于 80%
    - 静态代码分析无严重问题
    - 无合并冲突

## CI/CD 集成规范

### 流水线触发规则

| 分支类型        | 触发动作          | 执行任务            | 是否实现 |
|-------------|---------------|-----------------|------|
| feature/xxx | push          | 单元测试、代码扫描       | ✗    |
| develop/xxx | merge request | 集成测试、Docker 构建  | ✗    |
| develop     | push          | 部署开发环境、API 文档生成 | ✗    |
| test        | push          | 部署测试环境、自动化测试    | ✗    |
| release/xxx | push          | 预发布构建、安全扫描      | ✗    |
| uat         | merge request | 部署UAT环境、性能测试    | ✗    |
| master      | merge request | 生产构建、部署生产、版本标记  | ✗    |
| hotfix/xxx  | push          | 紧急测试套件、快速部署检查   | ✗    |

---

## 最佳实践

### 建议用图形界工具面操作分支

- <font color="red">建议用图形界工具面操作分支！！！</font>
- <font color="red">建议用图形界工具面操作分支！！！</font>
- <font color="red">建议用图形界工具面操作分支！！！</font>
    - IDEA
    - SOURCETREE
    - 小乌龟
    - Gitkraken

### 1. 分支管理

- 使用 `git fetch --prune` 定期清理本地缓存
- 删除已合并的分支：`git branch --merged | grep -v master | xargs git branch -d`
- 使用交互式 rebase 清理提交历史：`git rebase -i HEAD~5`

### 2. 提交规范

- 遵循 Conventional Commits 规范：

```
<类型> [<时间>]: <描述>

[可选 正文]

[可选 脚注]
```

- 类型可参考：https://gitmoji.js.org/
- IDEA插件推荐：Open Gitmoji

示例：

```bash
git commit -m ":sparkles: [2025-06-01]: add OAuth2 support

- Implement Wework OAuth2 provider
- Add token refresh mechanism

Closes #123"
```

### 3. 版本管理

- 主版本 (Major)：不兼容的 API 修改
- 次版本 (Minor)：向下兼容的功能新增
- 修订号 (Patch)：向下兼容的问题修正

#### 使用语义化版本标签：

```bash
git tag -a 1.2.3 -m "Release sso module"
git push origin 1.2.3
```

### 4. 冲突解决

#### 优先在功能分支解决：

```bash
git checkout feature/xxx
git fetch origin
git rebase origin/develop/xxx
#- 解决冲突
git rebase --continue
```

#### 建议用工具解决冲突

- idea
- vscode
- sourcetree
- 小乌龟
- 等等

## 附录：常用命令参考

### 分支操作

```bash
#- 创建迭代分支
git checkout -b develop/20260601-s14 master

#- 创建功能分支
git checkout -b feature/20260603-user-auth develop/20260601-s14

#- 每日同步
git fetch origin
git rebase origin/develop/20260601-s14

#- 提交变更
git add .
git commit -m ":sparkles: [2025-06-01]: add OAuth2 support"

#- 推送功能分支
git push -u origin feature/20260603-user-auth

#- 清理分支
git branch -d feature/20260603-user-auth
```

### 发布操作

```bash
#- 创建发布分支
git checkout -b release/20250625-1.2.0 master

#- 合并开发分支
git merge --no-ff develop/20260601-s14

#- 解决冲突并提交
git add .
git commit -m "Merge develop/20260601-s14 into release/20250625-1.2.0"

#- 测试后合并到master
git checkout master
git merge --no-ff release/20250625-1.2.0
git tag -a 1.2.0 -m "Release 1.2.0"
```

### 热修复

```bash
#- 创建热修复分支
git checkout -b hotfix/20250630-login-error master

#- 修复问题并提交
git add .
git commit -m ":bug: [2025-06-30]: 修复用户数据为空引起的空指针异常"

#- 测试后合并到master
git checkout master
git merge --no-ff hotfix/20250630-login-error
git tag -a 1.2.1 -m "Hotfix for login issue"

#- 合并到develop
git checkout develop/xxx
git merge --no-ff hotfix/20250630-login-error

#- 清理
git branch -d hotfix/20250630-login-error
```