跳至主要內容

Git 最佳实践与规范

HSXISAWD2026/3/20大约 6 分钟GitGit最佳实践规范

Git 最佳实践与规范

建立高效、规范的 Git 使用习惯

提交规范

Conventional Commits 规范

格式：

<type>(<scope>): <subject>
<空行>
<body>
<空行>
<footer>

Type（类型）- 必填：

Type说明
feat新功能
fixBug 修复
docs文档更新
style代码格式（不影响功能）
refactor重构（既不是新功能也不是修复）
perf性能优化
test测试相关
build构建系统或外部依赖变更
ciCI 配置文件和脚本变更
chore其他不修改源代码或测试文件的变更
revert回滚之前的提交

Scope（范围）- 可选：指定提交影响的范围，如：auth, api, ui, database

Subject（标题）- 必填：

  • 使用祈使句，现在时态
  • 首字母小写
  • 结尾不加句号
  • 不超过 50 个字符

Body（正文）- 可选：说明 what 和 why，每行不超过 72 个字符

Footer（页脚）- 可选：关联 Issue（Closes #123）、破坏性变更（BREAKING CHANGE:）

提交示例

# 简单提交
feat(auth): add OAuth2 login support

# 带正文的提交
fix(api): resolve null pointer exception in user service

The user service was throwing NPE when the user profile
was not fully loaded. Added null checks and default values.

Fixes #234

# 破坏性变更
feat(api)!: change user endpoint response format

BREAKING CHANGE: The /api/user endpoint now returns a different
JSON structure. The 'name' field is replaced with 'firstName'
and 'lastName' fields.

Migration guide:
- Update client code to use new field names
- Run migration script to update existing data

Closes #345

提交大小原则

原子提交原则：

  • ✅ 一个提交只做一件事
  • ✅ 每个提交都可以独立编译和运行
  • ✅ 每个提交都有意义（可回滚、可 cherry-pick）

提交应该包含：

  • ✅ 相关的代码变更
  • ✅ 相关的测试更新
  • ✅ 相关的文档更新

提交不应该：

  • ❌ 混合多个不相关的变更
  • ❌ 包含未完成的代码
  • ❌ 破坏构建或测试
  • ❌ 太大（难以审查）
  • ❌ 太小（如单独修复空格）

理想的提交大小：

  • 可以在几分钟内理解
  • 修改文件数 < 10
  • 代码行数变更 < 400

分支规范

分支命名规范

# 功能分支
feature/<issue-id>-<short-description>
feature/AUTH-123-oauth-login
feature/add-user-profile

# Bug 修复
fix/<issue-id>-<short-description>
fix/BUG-456-login-redirect
bugfix/header-overflow

# 热修复
hotfix/<issue-id>-<short-description>
hotfix/SEC-789-xss-vulnerability

# 发布分支
release/<version>
release/1.2.0
release/2024.01

# 实验性分支
experiment/<description>
spike/<description>

分支生命周期

分支存活时间建议：

分支类型建议存活时间
功能分支< 1 周
Bug 修复< 2 天
热修复< 1 天

工作流最佳实践

每日工作流程

# 开始工作前
git checkout main
git pull origin main

# 创建或切换到功能分支
git checkout -b feature/my-feature
# 或
git checkout feature/my-feature
git rebase main  # 同步最新代码

# 开发过程中
# 1. 写代码
# 2. 测试
# 3. 提交
git add -p  # 交互式添加，检查每个变更
git commit -m "feat: add feature"

# 定期同步
git fetch origin
git rebase origin/main

# 推送
git push -u origin feature/my-feature

# 完成后创建 PR
gh pr create --title "Add feature" --body "Description"

代码审查最佳实践

## 作为提交者

- [ ] PR 标题清晰描述了变更
- [ ] 提供了足够的上下文和背景
- [ ] 变更已经过本地测试
- [ ] 没有引入新的警告或错误
- [ ] 代码符合项目规范
- [ ] 更新了相关文档
- [ ] PR 大小合理（< 400 行）

## 作为审查者

- [ ] 理解变更的目的
- [ ] 检查代码逻辑正确性
- [ ] 检查边界情况处理
- [ ] 检查错误处理
- [ ] 检查安全性
- [ ] 检查性能影响
- [ ] 检查测试覆盖
- [ ] 提供建设性反馈

安全最佳实践

敏感信息处理

绝对不要提交 ❌：

  • 密码和密钥
  • API 令牌
  • 私钥和证书
  • 数据库连接字符串
  • 个人身份信息
  • 生产环境配置

正确做法 ✅：

  • 使用 .env 文件存储敏感配置
  • 确保 .env 在 .gitignore 中
  • 使用 .env.example 作为模板
  • 使用环境变量或密钥管理服务
  • 使用 git-secrets 或类似工具

意外提交敏感信息后 🚨：

  1. 立即更换所有暴露的凭证
  2. 使用 git filter-repo 从历史中删除
  3. 强制推送到所有远程
  4. 通知所有协作者重新克隆
  5. 审计是否有未授权访问

.gitignore 模板

# 环境和配置
.env
.env.local
.env.*.local
*.pem
*.key
config/secrets.yml
config/credentials.yml.enc

# IDE
.idea/
.vscode/
*.swp
*.swo
*~

# 依赖
node_modules/
vendor/
__pycache__/
venv/

# 构建产物
dist/
build/
*.egg-info/
*.pyc
*.class

# 日志
logs/
*.log
npm-debug.log*

# 操作系统
.DS_Store
Thumbs.db

# 测试覆盖率
coverage/
.coverage
htmlcov/

# 临时文件
tmp/
temp/
*.tmp
*.bak

项目结构规范

仓库根目录文件

project/
├── .github/                    # GitHub 特定配置
│   ├── workflows/              # GitHub Actions
│   ├── ISSUE_TEMPLATE/         # Issue 模板
│   ├── PULL_REQUEST_TEMPLATE/  # PR 模板
│   └── CODEOWNERS              # 代码所有者
├── .husky/                     # Git hooks
├── docs/                       # 文档
├── src/                        # 源代码
├── tests/                      # 测试
├── .editorconfig               # 编辑器配置
├── .gitattributes              # Git 属性
├── .gitignore                  # Git 忽略
├── .prettierrc                 # Prettier 配置
├── .eslintrc.js                # ESLint 配置
├── CHANGELOG.md                # 变更日志
├── CONTRIBUTING.md             # 贡献指南
├── LICENSE                     # 许可证
├── README.md                   # 项目说明
└── package.json                # 项目配置

CONTRIBUTING.md 模板

# 贡献指南

感谢你对本项目的兴趣！

## 行为准则

请阅读并遵守我们的 [行为准则](CODE_OF_CONDUCT.md)。

## 如何贡献

### 报告 Bug

1. 搜索现有 Issue 确认没有重复
2. 使用 Bug 报告模板创建 Issue
3. 提供复现步骤和环境信息

### 提出新功能

1. 搜索现有 Issue 和 PR
2. 使用功能请求模板创建 Issue
3. 说明用例和期望行为

### 提交代码

1. Fork 本仓库
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 遵循代码规范进行开发
4. 编写测试覆盖新代码
5. 提交更改：`git commit -m 'feat: add amazing feature'`
6. 推送分支：`git push origin feature/amazing-feature`
7. 创建 Pull Request

## 开发环境设置

```bash
# 克隆仓库
git clone https://github.com/user/repo.git
cd repo

# 安装依赖
npm install

# 运行测试
npm test
```

代码规范

审查流程

  1. 自动化检查必须通过
  2. 至少一名维护者审批
  3. 解决所有审查意见

---

## 团队协作规范

### 代码所有者制度

```bash
# .github/CODEOWNERS

# 默认审查者
* @team-lead @senior-dev

# 前端代码
/src/components/ @frontend-team
/src/styles/ @frontend-team

# 后端代码
/src/api/ @backend-team
/src/services/ @backend-team

# 数据库相关
/migrations/ @dba-team @backend-team
/src/models/ @backend-team

# 基础设施
/docker/ @devops-team
/.github/workflows/ @devops-team
/terraform/ @devops-team

# 安全相关
/src/auth/ @security-team
/src/crypto/ @security-team

# 文档
/docs/ @tech-writer
README.md @tech-writer @team-lead

分支保护规则

# 建议的 main 分支保护规则

required_reviews: 1
dismiss_stale_reviews: true
require_code_owner_reviews: true
required_status_checks:
  - ci/test
  - ci/lint
  - ci/build
require_up_to_date_branches: true
require_signed_commits: false # 可选
include_administrators: true
allow_force_pushes: false
allow_deletions: false

持续改进

定期审计

# 清理已合并的分支
git branch --merged main | grep -v "main" | xargs git branch -d

# 清理远程已删除的跟踪分支
git remote prune origin

# 查看大文件
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  sed -n 's/^blob //p' | sort -rnk2 | head -20

# 检查仓库健康
git fsck
git gc

# 统计贡献者
git shortlog -sn --all
Default footer
Copyright © 2026 HSXISAWD