Go 项目 Git 开发规范与操作指南

# Go 项目 Git 开发规范与操作指南

本文档规定了项目开发中的目录结构、分支管理、版本标签 (Tag) 使用以及日常协作流程。

---

## 1. 项目结构 (Project Layout)

遵循 [Standard Go Project Layout](https://github.com/golang-standards/project-layout) 规范：

* **`/cmd`**: 应用程序的主入口。
* **`/internal`**: 私有库代码（不想被外部项目引用的代码）。
* **`/pkg`**: 公共库代码（可以被外部引用的代码）。
* **`go.mod` & `go.sum`**: 依赖管理。

### .gitignore 推荐配置
确保不要将二进制文件或 IDE 配置提交到仓库：
```gitignore
# Binaries
/bin/
*.exe
*.dll

# Go Test
*.out

# Environment & IDE
.env
.idea/
.vscode/

2. 分支管理策略 (Branching Strategy)

分支名称	说明	示例	权限
main	主分支，始终保持稳定/可部署状态。	`main`	保护分支 (通过 PR 合并)
feature/	功能分支，用于开发新功能。	`feature/user-login`	开发者读写
fix/	修复分支，用于修复 Bug。	`fix/payment-error`	开发者读写
release/	发布分支，用于预发布准备。	`release/v1.0.0`	管理员/CI

3. 版本标签 (Tagging)

Go Modules 强依赖语义化版本 (SemVer)，打 Tag 时必须遵循格式。

3.1 Tag 命名规范

正式发布: v主版本.次版本.修订号
例：v1.0.0, v1.2.5
测试/预发布: v版本号-阶段.序号
例：v1.0.0-beta.1 (Beta 测试版)
例：v1.0.0-rc.1 (Release Candidate 候选版)

3.2 常用命令 (Cheat Sheet)

打标签 (本地)

推荐使用附注标签 (-a)，包含描述信息：

# 格式：git tag -a <标签名> -m "<描述>"
git tag -a v0.0.1-beta.1 -m "Beta版：集成用户模块"

推送标签 (重要！)

git push 默认不推送标签，必须显式指定。 **注意：必须加上 origin**。

# 错误示范：git push v0.0.1 (会报错)
# 正确示范：
git push origin v0.0.1-beta.1

删除标签

# 1. 删除本地
git tag -d v0.0.1-beta.1

# 2. 删除远程
git push origin --delete v0.0.1-beta.1

4. 远程协作与分支切换

4.1 拉取远程新分支

当同事在远程创建了新分支（如 kiro-beta），你需要同步并切换：

同步元数据 (告诉本地 Git 远程有哪些更新)：

git fetch

切换分支 (直接使用短名称)：

# Git 会自动找到 origin/kiro-beta 并建立关联
git switch kiro-beta

# 老版本 git 使用：git checkout kiro-beta

注意：不要使用 git switch remotes/origin/kiro-beta，这会导致 Detached HEAD 状态。

5. 提交信息规范 (Commit Messages)

为了生成清晰的历史记录，建议遵循 Conventional Commits。

格式: <type>(<scope>): <subject>

feat: 新功能 (Feature)
fix: 修补 Bug
docs: 文档修改
chore: 构建过程或工具变动 (如 go.mod)
refactor: 代码重构

示例:

feat(auth): add jwt token support fix(db): resolve connection timeout

6. 常见错误排查

**Q: 报错 fatal: 'v0.0.1' does not appear to be a git repository**

原因: 执行 git push v0.0.1 时，Git 把 v0.0.1 当作了仓库地址。
解决: 加上远程仓库名 origin -> git push origin v0.0.1。

**Q: 报错 fatal: a branch is expected, got remote branch...**

原因: 切换分支时写了全路径 remotes/origin/xxx。
解决: 只写分支名 -> git switch xxx。


***

**下一步：**
如果你想让这个流程更自动化，比如“推送到 main 分支自动运行测试”或“打 Tag 时自动发布 Release”，我可以为你提供一份 **GitHub Actions 的配置文件 (`.yaml`)**。

```markdown
---

## 7. 日常开发标准流程 (Standard Workflow)

这是一个开发者从“接到需求”到“代码提交”的标准操作闭环。

### 7.1 准备工作
每天开始工作前，确保本地主分支是最新的：
```bash
git checkout main
git pull origin main

7.2 开发新功能

创建分支:

# 从 main 切出新分支
git checkout -b feature/add-email-notification

编码与提交:

修改 Go 代码…
执行 go mod tidy (如果引入了新包)。
提交代码：

git add .
git commit -m "feat(notify): add email sender interface"

7.3 同步与冲突解决

在发起 Pull Request 之前，建议先将 main 分支的最新改动合并到你的分支，以提前解决冲突：

# 1. 切换回 main 更新
git checkout main
git pull origin main

# 2. 切回你的分支
git checkout feature/add-email-notification

# 3. 合并 main (推荐使用 rebase 保持线性历史，但 merge 也可以)
git merge main
# 如果有冲突，手动解决冲突文件，然后 git add 冲突文件 -> git commit

7.4 推送与 PR

git push origin feature/add-email-notification

推送后，前往 GitLab/GitHub 页面发起 Pull Request (Merge Request)。

8. 代码质量与合并要求 (Quality Control)

在 Go 项目中，代码在合并入 main 之前，必须通过以下检查：

8.1 提交前自查 (Self-Check)

请在提交代码前运行以下命令：

格式化代码:

gofmt -w .
# 或者
go fmt ./...

静态分析:

go vet ./...

运行测试:

# 运行所有测试并检查竞态条件
go test -race ./...

8.2 依赖管理

不要提交未使用的依赖。

go mod tidy
git add go.mod go.sum

9. 进阶：自动化工具配置 (Automation)

为了减少人为失误，建议配置自动化工具。

9.1 Pre-commit Hooks (推荐)

使用 pre-commit 框架，在 git commit 时自动拦截不合规的代码。

安装: pip install pre-commit
配置: 在项目根目录创建 .pre-commit-config.yaml:

repos:
-   repo: [https://github.com/dnephin/pre-commit-golang](https://github.com/dnephin/pre-commit-golang)
    rev: v0.5.1
    hooks:
    -   id: go-fmt
    -   id: go-vet
    -   id: go-mod-tidy

启用: pre-commit install

9.2 GolangCI-Lint

这是 Go 社区最流行的聚合 Linter。

# 本地安装与运行
go install [github.com/golangci/golangci-lint/cmd/golangci-lint@latest](https://github.com/golangci/golangci-lint/cmd/golangci-lint@latest)
golangci-lint run

10. 救火指南 (Disaster Recovery)

开发中常见失误的补救措施。

场景 A: 提交信息写错了

# 修改最近一次 commit 的信息
git commit --amend -m "fix(auth): 新的正确描述"
# 如果已经 push 过，需要强制推送 (仅限个人分支)
git push origin -f

场景 B: 开发了一半需要切换分支修 Bug

# 1. 暂存当前工作区修改
git stash save "正在做邮件功能，暂存"

# 2. 切换去修 bug
git switch fix/critical-bug
# ... 修完提交 ...

# 3. 切回来恢复现场
git switch feature/add-email-notification
git stash pop

场景 C: 想要放弃本地所有修改

# 危险操作：重置所有文件到最后一次 commit
git reset --hard HEAD

Last modified on 2025-12-25