Git 实践

cheniy2025/9/17大约 13 分钟

Git最佳实践

提交规范

为什么需要提交规范

良好的提交规范可以提高代码审查效率，自动生成变更日志，并帮助团队成员理解变更的目的和影响范围。

提交信息格式

遵循约定式提交规范的提交信息格式：

<类型>[可选的作用域]: <描述>

[可选的正文]

[可选的脚注]

类型：

feat：新功能
fix：修复bug
docs：文档更新
style：代码风格修改（不影响功能）
refactor：代码重构（既不是新功能也不是修复bug）
perf：性能优化
test：添加或修改测试
build：构建系统或外部依赖项的更改
ci：CI配置文件和脚本的更改
chore：其他不修改源代码或测试的更改

作用域：指定提交影响的范围（可选），如auth、api、ui等。

描述：简短描述，不超过50个字符，使用现在时态，不要加句号。

正文：详细说明变更的原因和与之前行为的对比（可选）。

脚注：引用相关的问题或PR编号，如Fixes #123（可选）。

提交信息示例

feat(auth): 实现用户登录功能

添加了基于JWT的用户认证系统，包括登录表单、后端验证和令牌管理。

Closes #45

fix(api): 修复用户数据查询性能问题

优化了用户数据查询的SQL语句，添加了适当的索引，
将查询时间从平均2秒降低到200ms以下。

Fixes #78

docs: 更新API文档和使用示例

更新了REST API的文档，添加了新端点的描述和请求/响应示例。

原子提交

每个提交应该表示一个逻辑上独立的变更，这样有助于：

更容易理解每个变更的目的
在需要时可以轻松回滚特定变更
简化代码审查过程
提高变更历史的可读性

原子提交的原则

一个提交只做一件事
不要在一个提交中混合不相关的变更
确保每个提交后代码可以构建和测试通过
提交前使用git diff --staged检查变更

使用工具辅助

可以使用以下工具来强制执行提交规范：

Commitizen：交互式命令行工具，引导开发者创建符合规范的提交信息
commitlint：检查提交信息是否符合规范
husky：Git钩子工具，可以在提交前运行检查

# 安装commitizen和相关工具
npm install -g commitizen
npm install --save-dev @commitlint/cli @commitlint/config-conventional husky

# 配置commitlint
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

# 配置husky
npx husky install
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

分支管理策略

主分支保护

主分支（通常是main或master）应该始终保持稳定和可部署状态：

禁止直接推送到主分支
通过Pull Request/Merge Request合并变更
要求代码审查和CI测试通过才能合并
考虑使用签名提交验证身份

GitHub主分支保护设置

在GitHub仓库中设置分支保护：

进入仓库 → Settings → Branches → Branch protection rules → Add rule
在"Branch name pattern"中输入main
选择以下选项：
- Require pull request reviews before merging
- Require status checks to pass before merging
- Require signed commits
- Include administrators
点击"Create"保存规则

分支命名约定

清晰的分支命名有助于团队理解分支的用途和状态：

feature/<功能描述>：新功能开发
bugfix/<问题描述>：修复非紧急bug
hotfix/<问题描述>：修复生产环境中的紧急问题
release/<版本号>：版本发布准备
docs/<文档描述>：文档更新
refactor/<重构描述>：代码重构

分支命名建议

使用小写字母和连字符
简洁但描述性强
可以包含任务ID，如feature/AUTH-123-user-login
避免使用过于通用的名称

分支生命周期管理

定期清理已合并或过时的分支，保持仓库整洁：

# 查看已合并到main的本地分支
git branch --merged main

# 删除已合并的本地分支（排除main和develop）
git branch --merged main | grep -v "\*\|main\|develop" | xargs -n 1 git branch -d

# 查看远程已合并分支
git branch -r --merged main

# 删除远程已合并分支
git branch -r --merged main | grep -v "\*\|main\|develop" | sed 's/origin\///' | xargs -n 1 git push --delete origin

注意

在删除分支前，确保它们确实已经合并或不再需要。使用-d而非-D删除本地分支可以防止误删未合并的分支。

代码审查最佳实践

提交Pull Request前的准备

在创建Pull Request前，确保：

代码符合项目的编码规范
所有测试通过
变更尽可能小而集中
提交历史清晰（考虑使用git rebase -i整理提交）
更新相关文档

Pull Request描述模板

使用模板使Pull Request描述更加结构化：

## 变更描述

简要描述这个PR的目的和变更内容。

## 相关问题

关联的问题或任务ID，如 #123。

## 变更类型

- [ ] 新功能
- [ ] Bug修复
- [ ] 性能优化
- [ ] 重构
- [ ] 文档更新
- [ ] 其他（请说明）

## 测试

描述如何测试这些变更。

## 截图（如适用）

添加相关截图。

## 检查清单

- [ ] 代码符合项目编码规范
- [ ] 添加了必要的测试
- [ ] 所有测试通过
- [ ] 更新了相关文档
- [ ] 变更不会引入新的警告

代码审查指南

作为审查者，关注以下方面：

功能性：代码是否实现了预期功能
可读性：代码是否易于理解
可维护性：代码结构是否合理，是否易于修改
性能：是否有性能问题或优化空间
安全性：是否存在安全漏洞
测试覆盖：是否有足够的测试

代码审查清单

设计
- 代码是否符合项目架构
- 是否遵循设计模式和最佳实践
- 是否有不必要的复杂性
功能
- 代码是否实现了需求
- 是否处理了边缘情况
- 是否有用户体验问题
代码质量
- 是否遵循编码规范
- 是否有重复代码
- 命名是否清晰和一致
- 注释是否充分和必要
测试
- 是否有单元测试
- 是否有集成测试
- 测试是否覆盖关键路径和边缘情况
安全
- 是否有输入验证
- 是否有权限检查
- 是否有敏感数据泄露风险

有效的代码审查反馈

提供建设性的反馈：

关注代码，而非开发者
解释为什么需要改变，而不仅仅是指出问题
提供具体的改进建议
区分必须修改的问题和可选的建议
肯定好的实践和解决方案

反馈示例

不好的反馈：

这段代码写得很糟糕，需要重构。

好的反馈：

这个方法有点长（超过50行），可能难以维护。建议将验证逻辑提取到单独的方法中，这样可以提高可读性和可测试性。例如：

private boolean validateUserInput(UserDTO input) {
// 验证逻辑
}

冲突解决策略

预防合并冲突

减少合并冲突的发生：

经常从主分支同步更新（使用git pull --rebase）
将大型功能分解为小的、独立的变更
避免多人同时修改同一文件的同一部分
使用明确的代码所有权和模块化结构

解决冲突的步骤

当冲突发生时：

理解冲突的原因和双方的变更意图
与相关开发者讨论解决方案（如果可能）
手动编辑冲突文件，保留或合并必要的变更
测试解决方案，确保功能正常
提交解决结果

# 当合并或变基出现冲突时

# 查看冲突文件
git status

# 编辑冲突文件，解决冲突
# 冲突标记如下：
# <<<<<<< HEAD
# 当前分支的代码
# =======
# 要合并的分支的代码
# >>>>>>> feature-branch

# 解决冲突后标记为已解决
git add <冲突文件>

# 如果是在合并中
git commit -m "解决合并冲突"

# 如果是在变基中
git rebase --continue

使用合并工具

图形化合并工具可以简化冲突解决：

# 配置合并工具
git config --global merge.tool <工具名>
# 常用选项：vscode, kdiff3, meld, p4merge

# 使用配置的工具解决冲突
git mergetool

推荐的合并工具

VS Code：轻量级，集成Git支持
KDiff3：功能强大，三路比较
Meld：直观的界面，跨平台
P4Merge：专业级工具，可视化强

大型项目管理

模块化仓库结构

对于大型项目，考虑以下仓库组织方式：

单体仓库（Monorepo）：所有相关代码在一个仓库中
- 优点：简化依赖管理，原子提交，统一版本控制
- 缺点：仓库体积大，权限管理复杂
多仓库（Multirepo）：每个模块/服务一个仓库
- 优点：仓库小，权限隔离，团队自治
- 缺点：依赖管理复杂，跨仓库变更困难
混合方式：核心模块使用Monorepo，外围服务使用独立仓库

Monorepo工具

Lerna：JavaScript项目的Monorepo管理工具
Nx：提供Monorepo工作流和构建优化
Bazel：Google的构建系统，支持大规模Monorepo
Gradle复合构建：Java项目的多模块构建

Git性能优化

大型仓库的Git性能优化：

# 浅克隆（只获取最近的历史）
git clone --depth=1 <仓库URL>

# 单分支克隆
git clone --single-branch --branch=main <仓库URL>

# 使用部分克隆（需要服务器支持）
git clone --filter=blob:none <仓库URL>

# 配置Git使用文件系统监视器加速状态检查
git config --global core.fsmonitor true

# 启用并行索引
git config --global index.threads 0

# 压缩Git数据库
git gc --aggressive

大文件处理

对于大文件和二进制文件：

使用Git LFS（Large File Storage）存储大文件
考虑将大文件存储在外部系统（如S3）
在.gitignore中排除生成的文件和构建产物

# 安装Git LFS
git lfs install

# 跟踪特定类型的文件
git lfs track "*.psd" "*.zip" "*.bin"

# 确保.gitattributes被提交
git add .gitattributes

自动化与CI/CD集成

持续集成工作流

有效的CI工作流应包括：

代码检查（linting）
编译/构建
单元测试
集成测试
安全扫描
性能测试（对关键变更）

GitHub Actions CI示例

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up JDK
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
        
    - name: Cache Maven packages
      uses: actions/cache@v3
      with:
        path: ~/.m2
        key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
        
    - name: Code quality check
      run: ./mvnw checkstyle:check
      
    - name: Build with Maven
      run: ./mvnw -B package
      
    - name: Run tests
      run: ./mvnw test
      
    - name: Security scan
      uses: aquasecurity/trivy-action@master
      with:
        scan-type: 'fs'
        ignore-unfixed: true
        format: 'sarif'
        output: 'trivy-results.sarif'
        severity: 'CRITICAL,HIGH'

自动化发布流程

使用Git标签和CI/CD自动化发布：

创建语义化版本标签
触发CI/CD流水线
构建和测试
生成变更日志
创建发布包
部署到目标环境

自动化发布工具

semantic-release：全自动版本管理和发布
standard-version：自动版本控制和CHANGELOG生成
release-it：自动化发布工具，支持多种平台
GitLab/GitHub Releases：与CI/CD集成的发布管理

Git Hooks自动化

使用Git Hooks自动化常见任务：

# pre-commit：提交前运行检查
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh

# 运行代码格式化
echo "Running code formatter..."
./gradlew spotlessApply

# 运行静态分析
echo "Running static analysis..."
./gradlew checkstyleMain

# 运行单元测试
echo "Running unit tests..."
./gradlew test

# 如果有错误，阻止提交
if [ $? -ne 0 ]; then
  echo "Tests failed. Commit aborted."
  exit 1
fi
EOF

chmod +x .git/hooks/pre-commit

安全最佳实践

敏感信息管理

防止敏感信息泄露：

使用.gitignore排除包含敏感信息的文件
使用环境变量或专用的密钥管理系统存储密钥
考虑使用git-secrets等工具扫描提交中的敏感信息

# .gitignore示例
.env
.env.local
secrets.yml
*.pem
*.key

警告

如果不小心提交了敏感信息：

立即更改泄露的凭证
使用git filter-branch或BFG Repo-Cleaner从历史中移除
强制推送更改（需要与团队协调）

签名提交

使用GPG签名验证提交的真实性：

# 生成GPG密钥
gpg --full-generate-key

# 查看GPG密钥
gpg --list-secret-keys --keyid-format=long

# 配置Git使用GPG密钥
git config --global user.signingkey <密钥ID>

# 启用自动签名提交
git config --global commit.gpgsign true

# 手动签名提交
git commit -S -m "签名的提交"

# 签名标签
git tag -s v1.0.0 -m "签名的标签"

权限管理

在团队环境中实施适当的权限控制：

使用基于角色的访问控制（RBAC）
限制对主分支的直接推送权限
实施强制代码审查
定期审查仓库访问权限

文档与知识共享

仓库文档

每个仓库应包含以下文档：

README.md：项目概述、安装和使用说明
CONTRIBUTING.md：贡献指南和工作流程
CHANGELOG.md：版本历史和变更记录
LICENSE：开源许可证（如适用）
SECURITY.md：安全政策和漏洞报告流程

README.md模板

# 项目名称

简短的项目描述。

## 功能

- 功能1：描述
- 功能2：描述
- ...

## 安装

```bash
# 安装步骤

使用

// 使用示例

配置

描述配置选项和方法。

开发

先决条件

需要的工具和依赖

设置开发环境

# 设置步骤

测试

# 运行测试的命令

贡献

请阅读CONTRIBUTING.md了解贡献流程。

许可证

本项目采用许可证名称许可。

Git风格指南

创建团队Git风格指南，包括：

分支命名约定
提交信息格式
合并和变基策略
代码审查流程
发布流程

知识共享与培训

促进团队Git知识共享：

组织Git工作坊和培训
创建内部Wiki或知识库
记录常见问题和解决方案
鼓励结对编程和代码审查

小结

本文详细介绍了Git的最佳实践，包括：

提交规范：如何编写有意义的提交信息
分支管理策略：保护主分支和有效的分支命名
代码审查最佳实践：提高代码质量和知识共享
冲突解决策略：预防和处理合并冲突
大型项目管理：仓库结构和性能优化
自动化与CI/CD集成：提高开发效率和质量
安全最佳实践：保护代码和敏感信息
文档与知识共享：促进团队协作

遵循这些最佳实践，可以帮助你和你的团队更高效地使用Git，提高代码质量，并简化协作流程。

持续改进

定期回顾和改进Git工作流
关注Git和相关工具的新特性
收集团队反馈，调整流程以适应团队需求
度量和分析工作流效率，找出瓶颈