Go Modules 最佳实践 #

myproject/
├── cmd/                    # 主应用程序
│   ├── server/
│   │   └── main.go
│   └── cli/
│       └── main.go
├── internal/               # 私有应用代码
│   ├── service/
│   ├── repository/
│   └── config/
├── pkg/                    # 公共库代码
│   ├── utils/
│   └── api/
├── api/                    # API 定义
│   ├── openapi/
│   └── proto/
├── configs/                # 配置文件
├── scripts/                # 脚本文件
├── docs/                   # 文档
├── go.mod
├── go.sum
├── Makefile
└── README.md

simple-app/
├── main.go
├── handler.go
├── service.go
├── go.mod
├── go.sum
└── README.md

mylib/
├── go.mod
├── go.sum
├── doc.go              # 包文档
├── lib.go              # 主入口
├── lib_test.go         # 测试
├── internal/           # 内部实现
│   └── helper.go
├── examples/           # 示例
│   └── basic/
│       └── main.go
└── README.md

// ✅ 推荐：使用仓库路径
module github.com/myuser/myproject

// ✅ 推荐：使用组织路径
module github.com/myorg/myproject

// ✅ 推荐：私有仓库
module gitlab.company.com/team/project

// ❌ 不推荐：简单名称（仅本地开发可用）
module myproject

module github.com/myuser/myproject

// ✅ 推荐：声明主要 Go 版本
go 1.21

// ❌ 不推荐：过于精确
go 1.21.3

// ❌ 不推荐：过时版本
go 1.16

module github.com/myuser/myproject

go 1.21

// ✅ 推荐：按类型分组，按字母排序
require (
    // Web 框架
    github.com/gin-gonic/gin v1.9.1
    
    // 数据库
    github.com/jackc/pgx/v5 v5.5.0
    github.com/redis/go-redis/v9 v9.3.0
    
    // 工具库
    github.com/google/uuid v1.5.0
)

// ✅ 间接依赖自动管理
require (
    github.com/bytedance/sonic v1.9.1 // indirect
)

# ✅ 推荐：指定版本
go get github.com/gin-gonic/gin@v1.9.1

# ✅ 推荐：使用 latest（开发阶段）
go get github.com/gin-gonic/gin@latest

# ❌ 不推荐：不指定版本
go get github.com/gin-gonic/gin

# ✅ 推荐：添加后整理
go get github.com/gin-gonic/gin@v1.9.1
go mod tidy

# ✅ 推荐：定期更新，分批进行
go get -u=patch           # 只更新补丁版本
go mod tidy
go test ./...

# ✅ 推荐：更新单个依赖
go get github.com/gin-gonic/gin@latest
go mod tidy
go test ./...

# ⚠️ 谨慎：更新所有依赖
go get -u
go mod tidy
go test ./...

# ✅ 推荐：使用 tidy 自动清理
go mod tidy

# ❌ 不推荐：手动编辑 go.mod 后不运行 tidy

选择依赖时考虑：

1. 活跃度
   ├── 最近更新时间
   ├── Issue 处理速度
   └── 社区活跃度

2. 稳定性
   ├── 版本号 >= v1.0.0
   ├── API 稳定性
   └── 向后兼容性

3. 质量
   ├── 测试覆盖率
   ├── 文档完整性
   └── 代码质量

4. 依赖数量
   ├── 传递依赖少
   ├── 无重复功能依赖
   └── 依赖树清晰

5. 许可证
   ├── 兼容项目许可
   ├── 无法律风险
   └── 明确的许可证

# 开发阶段
v0.x.x  # 快速迭代，API 不稳定

# 正式发布
v1.0.0  # API 稳定

# 功能更新
v1.1.0  # 新增功能

# Bug 修复
v1.1.1  # 修复 Bug

# 重大变更
v2.0.0  # 不兼容变更

# 1. 准备发布
go mod tidy
go test ./...
go vet ./...

# 2. 更新 CHANGELOG
# 编辑 CHANGELOG.md

# 3. 提交代码
git add .
git commit -m "release v1.0.0"

# 4. 打标签
git tag -a v1.0.0 -m "Release v1.0.0"

# 5. 推送
git push origin main
git push origin v1.0.0

# 6. 验证
go list -m -versions github.com/myuser/mylib

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- New feature A

## [1.1.0] - 2024-01-15

### Added
- Feature B
- Feature C

### Changed
- Improved performance of X

### Fixed
- Bug #123

### Security
- Fixed CVE-2024-1234

## [1.0.0] - 2024-01-01

### Added
- Initial release

# 项目根目录创建 .envrc 或脚本
# setup.sh

#!/bin/bash

# 配置 Go 版本
go version

# 配置代理
go env -w GOPROXY=https://goproxy.cn,direct

# 配置私有模块
go env -w GOPRIVATE=github.com/mycompany/*

# 下载依赖
go mod download

echo "Environment setup complete!"

# Binaries
*.exe
*.exe~
*.dll
*.so
*.dylib

# Test binary
*.test

# Output
/bin/
/dist/

# Go workspace
go.work
go.work.sum

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

# OS
.DS_Store
Thumbs.db

# Environment
.env
.env.local
*.env

# Logs
*.log
logs/

## 依赖变更审查

- [ ] 新依赖是否必要？
- [ ] 版本选择是否合理？
- [ ] 是否有安全风险？
- [ ] 许可证是否兼容？
- [ ] go.mod 格式是否正确？
- [ ] go.sum 是否更新？
- [ ] 是否运行了 go mod tidy？
- [ ] 测试是否通过？

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

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

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.21'
      - run: go vet ./...
      - uses: golangci/golangci-lint-action@v3

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.21'
          cache: true
      - run: go mod download
      - run: go mod verify
      - run: go test -v -race -coverprofile=coverage.out ./...
      - uses: codecov/codecov-action@v3

  build:
    runs-on: ubuntu-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.21'
      - run: go build -v ./...

# 使用 govulncheck
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...

# 使用 nancy
go list -json -m all | nancy sleuth

# 使用 trivy
trivy fs .

# 每月检查更新
go list -u -m all

# 更新有安全问题的依赖
go get -u=patch
go mod tidy

# 验证更新
go test ./...
govulncheck ./...

# 配置私有模块
go env -w GOPRIVATE=github.com/mycompany/*

# 使用 SSH 认证
git config --global url."git@github.com:".insteadOf "https://github.com/"

# 使用 token 认证
# ~/.netrc
machine github.com
login username
password ghp_xxxx

# CI/CD 中缓存模块
# GitHub Actions
- name: Cache Go modules
  uses: actions/cache@v3
  with:
    path: |
      ~/.cache/go-build
      ~/go/pkg/mod
    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
    restore-keys: |
      ${{ runner.os }}-go-

# 使用 vendor 加速构建
go mod vendor
go build -mod=vendor

# 并行构建
go build -p 4 ./...

# 减小二进制大小
go build -ldflags="-s -w" -o app

# 使用国内代理
go env -w GOPROXY=https://goproxy.cn,direct

# 使用多代理
go env -w GOPROXY=https://goproxy.cn,https://proxy.golang.org,direct

# 企业代理
go env -w GOPROXY=http://proxy.company.com,direct

# Project Name

Brief description of the project.

## Installation

```bash
go get github.com/myuser/myproject

package main

import "github.com/myuser/myproject"

func main() {
    myproject.Run()
}

### 包文档

```go
// Package mylib provides utilities for doing something.
//
// The mylib package provides a simple way to do something.
// It is designed to be easy to use and efficient.
//
// Example:
//
//  package main
//
//  import "github.com/myuser/mylib"
//
//  func main() {
//      result := mylib.DoSomething()
//      fmt.Println(result)
//  }
package mylib

# ❌ 错误
# 直接提交代码，不运行 tidy

# ✅ 正确
go mod tidy
git add go.mod go.sum
git commit -m "update dependencies"

# ❌ 错误
# .gitignore 中忽略 go.sum

# ✅ 正确
git add go.mod go.sum
git commit -m "update dependencies"

# ❌ 错误
# 长期不更新依赖

# ✅ 正确
# 定期检查更新
go list -u -m all
go get -u=patch

# ❌ 错误
git tag 1.0.0  # 缺少 v 前缀

# ✅ 正确
git tag v1.0.0

// ❌ 错误：v2 没有修改导入路径
module github.com/myuser/mylib  // v2.0.0

// ✅ 正确：v2 修改导入路径
module github.com/myuser/mylib/v2  // v2.0.0

- [ ] 创建 go.mod
- [ ] 配置 GOPROXY
- [ ] 配置 GOPRIVATE（如需要）
- [ ] 创建 .gitignore
- [ ] 创建 README.md

- [ ] 定期运行 go mod tidy
- [ ] 提交 go.mod 和 go.sum
- [ ] 定期更新依赖
- [ ] 运行安全检查

- [ ] go mod tidy
- [ ] go mod verify
- [ ] go test ./...
- [ ] go vet ./...
- [ ] govulncheck ./...
- [ ] 更新 CHANGELOG
- [ ] 打正确格式的标签