全栈开发（四）版本控制与协作

全栈开发：版本控制与协作

一、UML 建模（Mermaid）

1. Git Flow 分支工作流

2. 交互式 Rebase 流程（清理提交历史）

3. 冲突解决流程（Rebase 方式）

二、项目文件结构组织

我们将创建一个演示项目git-flow-demo，展示分支策略与 Git 钩子实践。

git-flow-demo/ ├── .git/ # Git 仓库（由 git init 创建） ├── .gitignore ├── .gitattributes ├── .github/ # GitHub 相关配置 │ ├── workflows/ │ │ └── ci.yml # CI/CD 工作流 │ └── PULL_REQUEST_TEMPLATE.md # PR 模板 ├── hooks/ # 自定义 Git 钩子（示例） │ ├── pre-commit # 提交前检查 │ ├── commit-msg # 提交信息规范检查 │ └── post-merge # 合并后自动更新依赖 ├── docs/ │ ├── branching-strategy.md # 分支策略文档 │ └── rebase-guide.md # Rebase 操作指南 ├── scripts/ │ ├── release.sh # 发布辅助脚本 │ └── squash-commits.sh # 批量压缩提交脚本 ├── src/ # 示例源代码（任意语言） │ └── index.js ├── package.json # 项目配置（如使用 Node.js） └── README.md # 项目说明

三、源代码实现

1. Git 钩子示例

hooks/pre-commit（提交前代码检查）

#!/bin/sh# 在提交前运行代码格式检查和简单测试echo"Running pre-commit checks..."# 检查是否有未解决的冲突标记ifgrep-r-E'^<<<<<<< |^=======$|^>>>>>>> 'src/;thenecho"ERROR: Merge conflict markers found. Please resolve them before commit."exit1fi# 运行代码格式化（假设使用 Prettier）ifcommand-vprettier&>/dev/null;thenprettier--check"src/**/*.js"if[$?-ne0];thenecho"Prettier check failed. Run 'prettier --write src/' to fix."exit1fifi# 运行单元测试（如果存在）if[-f"package.json"];thennpmtest----watchAll=false--passWithNoTestsif[$?-ne0];thenecho"Tests failed. Commit aborted."exit1fifiecho"Pre-commit checks passed."

hooks/commit-msg（提交信息规范）

#!/bin/sh# 校验提交信息是否符合 Conventional Commits 规范commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore)(\([a-z0-9-]+\))?: .{1,100}'if!grep-qE"$commit_regex""$1";thenecho"ERROR: Commit message must follow Conventional Commits format:"echo" <type>(<scope>): <subject>"echo" e.g., feat(auth): add login functionality"exit1fi# 可选：校验行长度不超过 72 字符ifgrep-qE'^.{73,}'"$1";thenecho"WARNING: Commit subject line exceeds 72 characters (conventional limit)."fi

hooks/post-merge（合并后自动安装依赖）

#!/bin/sh# 在 pull 或 merge 后自动更新依赖if[-f"package.json"];thenecho"package.json changed, running npm install..."npminstallfi

注意：将这些钩子复制到.git/hooks/目录并赋予可执行权限（chmod +x .git/hooks/*）。也可通过工具（如husky）自动管理。

2. 辅助脚本

scripts/release.sh（发布新版本）

#!/bin/bash# 使用 Git Flow 发布新版本set-e# 参数检查if[$#-ne1];thenecho"Usage:$0<version>"echo"Example:$01.2.0"exit1fiVERSION=$1echo"🚀 Starting release process for version$VERSION"# 确保在 develop 分支且工作区干净gitcheckout developgitpull origin developif[-n"$(gitstatus--porcelain)"];thenecho"❌ Working directory not clean. Commit or stash changes."exit1fi# 创建 release 分支gitcheckout-brelease/$VERSION# 更新版本号（假设在 package.json 中）if[-f"package.json"];thennpmversion$VERSION--no-git-tag-versiongitaddpackage.jsongitcommit-m"chore(release): bump version to$VERSION"fi# 合并到 main 并打标签gitcheckout maingitmerge --no-ff release/$VERSION-m"chore(release): merge release/$VERSION"gittag-a"v$VERSION"-m"Release version$VERSION"# 合并回 developgitcheckout developgitmerge --no-ff release/$VERSION-m"chore(release): merge release/$VERSIONback to develop"# 删除 release 分支gitbranch-drelease/$VERSION# 推送所有变更和标签gitpush origin main develop--tagsecho"✅ Release$VERSIONcompleted. Pushed to remote."

scripts/squash-commits.sh（批量压缩提交）

#!/bin/bash# 交互式压缩最近 n 个提交set-eif[$#-ne1];thenecho"Usage:$0<number_of_commits>"exit1fiCOUNT=$1echo"Squashing last$COUNTcommits. This will open an editor..."gitrebase-iHEAD~$COUNTecho"If you force-push, use: git push --force-with-lease"

3. GitHub Actions CI 工作流

.github/workflows/ci.yml

name:CIon:push:branches:[main,develop]pull_request:branches:[main,develop]jobs:build:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4with:fetch-depth:0# 获取全部历史，用于检查分支策略-name:Set up Node.jsuses:actions/setup-node@v4with:node-version:'18'-name:Install dependenciesrun:npm ci-name:Lint and formatrun:|npm run lint npm run format:check-name:Run testsrun:npm test-name:Check branch naming (Git Flow)run:|# 检查分支名是否符合规范 BRANCH_NAME=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}} if [[ ! "$BRANCH_NAME" =~ ^(main|develop|feature/|release/|hotfix/) ]]; then echo "❌ Invalid branch name: $BRANCH_NAME" exit 1 fi

4. PR 模板（.github/PULL_REQUEST_TEMPLATE.md）

## 📝 变更描述 <!-- 简要说明本次 PR 修改的内容 --> ## 🔗 相关 Issue <!-- 如果有关联的 Issue，请在此链接 --> ## ✅ 自测清单 - [ ] 代码已通过 Prettier 格式化 - [ ] 单元测试已通过 - [ ] 遵循 Git Commit 规范 - [ ] 已在本地测试功能正常 ## 📸 截图（如需要） <!-- 可添加 UI 变更截图 --> ## 🚀 合并后操作 - [ ] 是否需要更新文档？ - [ ] 是否需要打标签发布？

四、深入解析与实践指南

1. 分支策略详解

Git Flow

• 永久分支：main（生产环境）、develop（开发集成）
• 临时分支：
  • feature/*：从develop切出，完成后合并回develop
  • release/*：从develop切出，用于发布前测试，完成后合并到main和develop
  • hotfix/*：从main切出，紧急修复，完成后合并到main和develop
• 适用场景：有明确版本发布周期的项目。

GitHub Flow

• 仅保留main分支作为永久分支
• 所有新功能从main切出分支，通过 Pull Request 合并
• 合并后立即部署
• 适用场景：持续交付、频繁部署的项目。

分支命名规范

feature/add-login-page feature/refactor-api release/1.2.0 hotfix/fix-crash-on-startup

2. 冲突解决与 Rebase

避免无意义的合并提交

# 在 feature 分支开发时，定期变基到 developgitcheckout feature/my-featuregitfetch origin developgitrebase origin/develop# 解决冲突后继续gitrebase--continue

交互式 Rebase 清理提交

# 压缩最近 5 个提交为一个gitrebase-iHEAD~5# 编辑器中将需要合并的提交前面的 pick 改为 squash 或 fixup

强制推送注意事项

# 使用 --force-with-lease 替代 --force，避免覆盖他人推送gitpush --force-with-lease origin feature/my-feature

3. Git 钩子实战

• pre-commit：在提交前运行代码检查、测试，防止低质量代码进入仓库。
• commit-msg：确保提交信息格式统一，便于自动生成 Change Log。
• post-merge：在拉取代码后自动安装依赖、迁移数据库等。

可以通过husky（Node.js）或pre-commit（Python）等工具管理钩子，使钩子脚本可以版本化。

4. 协作规范

Pull Request 规范

• 标题遵循<type>(<scope>): <subject>格式
• 描述包含变更内容、测试情况、相关 Issue
• 至少一人 Code Review 后方可合并

版本发布流程

1. 从develop切出release/x.y.z分支
2. 更新版本号、文档
3. 合并到main并打标签
4. 合并回develop
5. 部署生产环境

紧急修复流程

1. 从main切出hotfix/xxx分支
2. 修复问题
3. 合并到main并打新标签
4. 同步合并到develop

五、总结

版本控制与协作是全栈开发的重要一环，通过合理的分支策略、规范的提交信息、有效的冲突解决和自动化的钩子，可以显著提升团队协作效率和代码质量。本方案提供了从理论到实践的完整指南，包括：

• 分支模型：Git Flow 和 GitHub Flow 的选择与应用
• 工具脚本：Git 钩子、发布脚本、PR 模板
• CI/CD：GitHub Actions 自动检查分支命名和代码质量
• 操作指南：交互式 rebase、冲突解决、强制推送注意事项