跳到主要内容

Git 工作流规范指南

概述​

本文档定义了井云服务中心后端项目的 Git 工作流规范，包括分支管理、提交规范、代码审查流程等，确保团队协作的高效性和代码质量。

分支管理策略​

主分支​

  • main: 主分支，始终保持可发布状态

    • 只接受来自 develop 和 release/* 分支的合并
    • 每次合并都会触发自动部署到生产环境
    • 禁止直接在 main 分支上开发

  • develop: 开发分支，集成最新功能

    • 所有功能分支都从此分支拉取
    • 功能开发完成后合并回此分支
    • 定期会合并到 main 分支发布新版本

支持分支​

  • feature/*: 功能分支

    • 格式: feature/功能描述 或 feature/JIRA-123-功能描述
    • 从 develop 分支拉取
    • 开发完成后合并回 develop 分支
    • 示例: feature/user-authentication, feature/JIRA-456-add-payment

  • hotfix/*: 热修复分支

    • 格式: hotfix/问题描述 或 hotfix/JIRA-789-紧急修复
    • 从 main 分支拉取
    • 修复完成后合并回 main 和 develop 分支
    • 示例: hotfix/memory-leak-fix, hotfix/JIRA-999-security-patch

  • release/*: 发布分支

    • 格式: release/版本号
    • 从 develop 分支拉取
    • 用于发布前的最后准备和测试
    • 完成后合并到 main 和 develop 分支
    • 示例: release/v1.2.0, release/v2.0.0-beta

  • bugfix/*: Bug修复分支

    • 格式: bugfix/问题描述 或 bugfix/JIRA-456-bug修复
    • 从 develop 分支拉取
    • 修复完成后合并回 develop 分支
    • 示例: bugfix/login-validation-error, bugfix/JIRA-123-fix-api-response

分支命名规范​

基本规则​

  • 使用小写字母
  • 用连字符 - 分隔单词
  • 名称要简洁明了，能够描述分支用途
  • 避免使用中文字符

推荐格式​

feature/功能描述
feature/JIRA-编号-功能描述
bugfix/问题描述
bugfix/JIRA-编号-问题描述
hotfix/紧急问题描述
hotfix/JIRA-编号-紧急修复
release/版本号

示例​

✅ 正确示例:
feature/user-authentication
feature/JIRA-123-add-oauth-login
bugfix/api-response-validation
hotfix/security-vulnerability-patch
release/v1.5.0

❌ 错误示例:
feature/userAuthentication (使用驼峰命名)
feature/用户认证 (使用中文)
feature/add user login (包含空格)
123-fix-bug (以数字开头)

提交信息规范​

提交信息格式​

<类型>(<范围>): <主题>

<详细描述>

<相关链接>

类型 (Type)​

  • feat: 新功能
  • fix: Bug修复
  • docs: 文档更新
  • style: 代码格式调整（不影响功能）
  • refactor: 代码重构
  • perf: 性能优化
  • test: 测试相关
  • chore: 构建过程或辅助工具的变动
  • ci: CI/CD相关配置变更
  • build: 构建系统或依赖变更

范围 (Scope)​

范围用于指明提交影响的部分，可以是：

  • 服务名称: gateway, auth, user, tenant, agent, payment, integration, cron
  • 模块名称: api, biz, data, service, middleware
  • 功能模块: database, cache, mq, config

主题 (Subject)​

  • 简洁描述提交内容
  • 使用祈使句，动词开头
  • 首字母小写
  • 结尾不加句号

详细描述 (Body)​

  • 详细说明本次提交的内容
  • 解释为什么做这个改动
  • 说明实现方式或技术细节
  • 可以包含多行
  • 关联的 Issue 或 PR 编号
  • 破坏性变更说明
  • 其他相关链接

提交信息示例​

新功能​

feat(auth): add wechat login support

Implement wechat OAuth2 login flow with QR code generation
and callback handling. Users can now login using their
WeChat accounts.

Closes #123

Bug修复​

fix(gateway): resolve token validation middleware issue

Fixed JWT token validation that was incorrectly rejecting
valid tokens due to clock skew. Added 30-second tolerance
to prevent time sync issues.

Fixes #456

文档更新​

docs(readme): update installation instructions

Added Docker Compose setup instructions and updated
environment variable documentation for local development.

重构​

refactor(user): optimize database query performance

Replaced N+1 query pattern with batch loading approach.
Reduced API response time from 500ms to 50ms for user
list endpoint.

代码审查流程​

Pull Request 规范​

PR 标题格式​

<类型>(<范围>): <标题>

标题格式与提交信息保持一致。

PR 描述模板​

## 变更描述
简要描述本次变更的内容和目的。

## 变更类型
- [ ] 新功能
- [ ] Bug修复
- [ ] 文档更新
- [ ] 代码重构
- [ ] 性能优化
- [ ] 其他

## 测试
- [ ] 单元测试已通过
- [ ] 集成测试已通过
- [ ] 手动测试已完成

## 检查清单
- [ ] 代码符合项目编码规范
- [ ] 已添加必要的测试用例
- [ ] 文档已更新（如需要）
- [ ] 无安全漏洞
- [ ] 性能影响已评估

## 相关 Issue
Closes #issue_number

## 截图（如适用）
添加相关截图说明变更效果。

审查者职责​

  1. 代码质量检查

    • 检查代码是否符合项目编码规范
    • 评估代码的可读性和维护性
    • 确认没有明显的性能问题

  2. 逻辑正确性验证

    • 验证业务逻辑是否正确
    • 检查边界条件处理
    • 确认错误处理是否完善

  3. 测试覆盖度

    • 确认有足够的测试用例
    • 检查测试的有效性
    • 验证测试覆盖率

  4. 安全性审查

    • 检查是否有安全漏洞
    • 验证权限控制是否正确
    • 确认敏感信息处理

提交者职责​

  1. 代码质量

    • 确保代码通过所有自动化检查
    • 遵循项目编码规范
    • 提供清晰的提交信息

  2. 测试

    • 编写充分的测试用例
    • 确保测试覆盖率达标
    • 进行必要的手动测试

  3. 文档

    • 更新相关文档
    • 提供清晰的变更说明
    • 添加必要的注释

合并策略​

合并条件​

  • 所有自动化检查通过
  • 至少一个团队成员审查并批准
  • 解决所有审查意见
  • 无合并冲突

合并方法​

  • feature/develop分支: 使用 squash merge 保持提交历史整洁
  • hotfix分支: 使用 merge merge 保留修复历史
  • release分支: 使用 merge merge 保留发布历史

合并后操作​

  • 删除已合并的功能分支
  • 更新相关文档
  • 通知相关团队

常见问题​

Q: 如何处理提交历史中的敏感信息？​

A:

  1. 立即修改敏感信息（密码、密钥等）
  2. 使用 git filter-branch 或 git rebase -i 从历史中移除
  3. 强制推送更新后的历史
  4. 轮换已暴露的密钥

Q: 如何处理大的重构？​

A:

  1. 创建 refactor/ 分支
  2. 将重构拆分为多个小的提交
  3. 每个提交都要保持代码可编译和测试通过
  4. 在 PR 中详细说明重构的原因和步骤

Q: 如何处理紧急修复？​

A:

  1. 从 main 分支创建 hotfix/ 分支
  2. 快速修复问题并添加测试
  3. 合并到 main 并立即发布
  4. 同时合并到 develop 分支

Q: 如何处理合并冲突？​

A:

  1. 拉取最新的目标分支代码
  2. 仔细分析冲突原因
  3. 与相关开发者沟通解决方案
  4. 测试合并后的代码
  5. 提交合并结果

工具推荐​

Git 客户端​

  • 命令行: Git CLI
  • GUI: SourceTree, GitKraken, VS Code Git

Git Hooks​

  • pre-commit: 代码格式检查和静态分析
  • commit-msg: 提交信息格式验证
  • pre-push: 运行测试套件

CI/CD 集成​

  • GitHub Actions: 自动化测试和部署
  • GitLab CI: 持续集成和部署
  • Jenkins: 自定义 CI/CD 流水线

最佳实践​

日常开发​

  1. 频繁提交，保持提交粒度小
  2. 每个提交都要有明确的意图
  3. 及时拉取最新代码，减少冲突
  4. 定期清理本地分支

分支管理​

  1. 保持分支生命周期短
  2. 及时删除已合并的分支
  3. 避免长期存在的功能分支
  4. 定期同步主分支代码

协作沟通​

  1. 在 PR 中提供充分的上下文
  2. 及时响应审查意见
  3. 建设性的代码审查反馈
  4. 重要的变更提前沟通

参考资源​

本文档会根据团队实践持续更新，如有问题或建议，请提交 Issue 或 PR。