1.6.4 依赖管理与版本控制 #

// 版本示例
v1.0.0    // 初始稳定版本
v1.1.0    // 新增功能，向后兼容
v1.1.1    // 修复 bug，向后兼容
v2.0.0    // 重大变更，不向后兼容

// go.mod 中的版本约束
module example.com/myproject

go 1.21

require (
    github.com/gin-gonic/gin v1.9.1          // 精确版本
    github.com/sirupsen/logrus v1.9.0        // 最小版本
    golang.org/x/crypto v0.0.0-20230515195234-fca39b76adb4  // 伪版本
)

// 版本选择规则
// Go 会选择满足所有约束的最小版本

# 添加新依赖
go get github.com/gorilla/mux

# 添加特定版本
go get github.com/gorilla/[email protected]

# 添加最新版本
go get github.com/gorilla/mux@latest

# 添加特定分支或提交
go get github.com/gorilla/mux@master
go get github.com/gorilla/mux@abc1234

# 更新依赖
go get -u github.com/gorilla/mux

# 更新到最新的 patch 版本
go get -u=patch github.com/gorilla/mux

# 更新所有依赖
go get -u all

// go.mod
module github.com/example/web-service

go 1.21

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/go-redis/redis/v8 v8.11.5
    github.com/golang-jwt/jwt/v4 v4.5.0
    github.com/sirupsen/logrus v1.9.3
    gorm.io/driver/postgres v1.5.2
    gorm.io/gorm v1.25.2
)

// pkg/auth/jwt.go
package auth

import (
    "fmt"
    "time"

    "github.com/golang-jwt/jwt/v4"
)

// JWTManager JWT 管理器
type JWTManager struct {
    secretKey     string
    tokenDuration time.Duration
}

// Claims JWT 声明
type Claims struct {
    UserID   int    `json:"user_id"`
    Username string `json:"username"`
    Role     string `json:"role"`
    jwt.RegisteredClaims
}

// NewJWTManager 创建 JWT 管理器
func NewJWTManager(secretKey string, tokenDuration time.Duration) *JWTManager {
    return &JWTManager{
        secretKey:     secretKey,
        tokenDuration: tokenDuration,
    }
}

// GenerateToken 生成 JWT token
func (manager *JWTManager) GenerateToken(userID int, username, role string) (string, error) {
    claims := Claims{
        UserID:   userID,
        Username: username,
        Role:     role,
        RegisteredClaims: jwt.RegisteredClaims{
            ExpiresAt: jwt.NewNumericDate(time.Now().Add(manager.tokenDuration)),
            IssuedAt:  jwt.NewNumericDate(time.Now()),
            NotBefore: jwt.NewNumericDate(time.Now()),
            Issuer:    "web-service",
        },
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString([]byte(manager.secretKey))
}

// VerifyToken 验证 JWT token
func (manager *JWTManager) VerifyToken(tokenString string) (*Claims, error) {
    token, err := jwt.ParseWithClaims(
        tokenString,
        &Claims{},
        func(token *jwt.Token) (interface{}, error) {
            if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
                return nil, fmt.Errorf("意外的签名方法: %v", token.Header["alg"])
            }
            return []byte(manager.secretKey), nil
        },
    )

    if err != nil {
        return nil, err
    }

    claims, ok := token.Claims.(*Claims)
    if !ok || !token.Valid {
        return nil, fmt.Errorf("无效的 token")
    }

    return claims, nil
}

// pkg/cache/redis.go
package cache

import (
    "context"
    "encoding/json"
    "time"

    "github.com/go-redis/redis/v8"
)

// RedisCache Redis 缓存实现
type RedisCache struct {
    client *redis.Client
}

// NewRedisCache 创建 Redis 缓存
func NewRedisCache(addr, password string, db int) *RedisCache {
    rdb := redis.NewClient(&redis.Options{
        Addr:     addr,
        Password: password,
        DB:       db,
    })

    return &RedisCache{client: rdb}
}

// Set 设置缓存
func (c *RedisCache) Set(ctx context.Context, key string, value interface{}, expiration time.Duration) error {
    data, err := json.Marshal(value)
    if err != nil {
        return err
    }

    return c.client.Set(ctx, key, data, expiration).Err()
}

// Get 获取缓存
func (c *RedisCache) Get(ctx context.Context, key string, dest interface{}) error {
    data, err := c.client.Get(ctx, key).Result()
    if err != nil {
        return err
    }

    return json.Unmarshal([]byte(data), dest)
}

// Delete 删除缓存
func (c *RedisCache) Delete(ctx context.Context, key string) error {
    return c.client.Del(ctx, key).Err()
}

// Exists 检查缓存是否存在
func (c *RedisCache) Exists(ctx context.Context, key string) (bool, error) {
    count, err := c.client.Exists(ctx, key).Result()
    return count > 0, err
}

// Close 关闭连接
func (c *RedisCache) Close() error {
    return c.client.Close()
}

// Ping 测试连接
func (c *RedisCache) Ping(ctx context.Context) error {
    return c.client.Ping(ctx).Err()
}

// pkg/database/models.go
package database

import (
    "time"
    "gorm.io/gorm"
)

// User 用户模型
type User struct {
    ID        uint           `gorm:"primarykey" json:"id"`
    CreatedAt time.Time      `json:"created_at"`
    UpdatedAt time.Time      `json:"updated_at"`
    DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`

    Username string `gorm:"uniqueIndex;not null" json:"username"`
    Email    string `gorm:"uniqueIndex;not null" json:"email"`
    Password string `gorm:"not null" json:"-"`
    Role     string `gorm:"default:user" json:"role"`
    Active   bool   `gorm:"default:true" json:"active"`

    Profile UserProfile `gorm:"foreignKey:UserID" json:"profile,omitempty"`
    Posts   []Post      `gorm:"foreignKey:AuthorID" json:"posts,omitempty"`
}

// UserProfile 用户资料
type UserProfile struct {
    ID        uint           `gorm:"primarykey" json:"id"`
    CreatedAt time.Time      `json:"created_at"`
    UpdatedAt time.Time      `json:"updated_at"`
    DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`

    UserID    uint   `gorm:"not null" json:"user_id"`
    FirstName string `json:"first_name"`
    LastName  string `json:"last_name"`
    Avatar    string `json:"avatar"`
    Bio       string `json:"bio"`
}

// Post 文章模型
type Post struct {
    ID        uint           `gorm:"primarykey" json:"id"`
    CreatedAt time.Time      `json:"created_at"`
    UpdatedAt time.Time      `json:"updated_at"`
    DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`

    Title     string `gorm:"not null" json:"title"`
    Content   string `gorm:"type:text" json:"content"`
    Published bool   `gorm:"default:false" json:"published"`
    AuthorID  uint   `gorm:"not null" json:"author_id"`

    Author User `gorm:"foreignKey:AuthorID" json:"author,omitempty"`
}

// pkg/database/database.go
package database

import (
    "fmt"
    "time"

    "gorm.io/driver/postgres"
    "gorm.io/gorm"
    "gorm.io/gorm/logger"
)

// Config 数据库配置
type Config struct {
    Host     string
    Port     int
    User     string
    Password string
    DBName   string
    SSLMode  string
}

// Database 数据库管理器
type Database struct {
    DB *gorm.DB
}

// New 创建数据库连接
func New(config Config) (*Database, error) {
    dsn := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=%s",
        config.Host, config.Port, config.User, config.Password, config.DBName, config.SSLMode)

    db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
        Logger: logger.Default.LogMode(logger.Info),
    })
    if err != nil {
        return nil, fmt.Errorf("连接数据库失败: %w", err)
    }

    // 配置连接池
    sqlDB, err := db.DB()
    if err != nil {
        return nil, fmt.Errorf("获取数据库实例失败: %w", err)
    }

    sqlDB.SetMaxIdleConns(10)
    sqlDB.SetMaxOpenConns(100)
    sqlDB.SetConnMaxLifetime(time.Hour)

    return &Database{DB: db}, nil
}

// AutoMigrate 自动迁移
func (d *Database) AutoMigrate() error {
    return d.DB.AutoMigrate(&User{}, &UserProfile{}, &Post{})
}

// Close 关闭数据库连接
func (d *Database) Close() error {
    sqlDB, err := d.DB.DB()
    if err != nil {
        return err
    }
    return sqlDB.Close()
}

// Health 健康检查
func (d *Database) Health() error {
    sqlDB, err := d.DB.DB()
    if err != nil {
        return err
    }
    return sqlDB.Ping()
}

// 处理版本冲突的示例

// 情况1: 直接依赖冲突
// 项目需要 package A v1.2.0 和 package B，但 B 需要 A v1.1.0
// Go 会选择 v1.2.0（最高版本）

// 情况2: 间接依赖冲突
// 使用 go mod why 查看依赖原因
// go mod why github.com/conflicting/package

// 情况3: 使用 replace 指令解决冲突
// go.mod
module example.com/myproject

require (
    github.com/package-a v1.2.0
    github.com/package-b v2.0.0
)

// 替换有问题的依赖
replace github.com/problematic/package => github.com/fixed/package v1.0.0

// 使用本地版本进行开发
replace github.com/mycompany/internal => ../internal-package

// 创建一个工具库模块
// go.mod
module github.com/example/mathutils

go 1.21

// mathutils.go
package mathutils

import (
    "errors"
    "math"
)

// Version 库版本
const Version = "1.0.0"

// Calculator 计算器
type Calculator struct {
    precision int
}

// New 创建新的计算器
func New(precision int) *Calculator {
    if precision < 0 {
        precision = 2
    }
    return &Calculator{precision: precision}
}

// Add 加法
func (c *Calculator) Add(a, b float64) float64 {
    return c.round(a + b)
}

// Subtract 减法
func (c *Calculator) Subtract(a, b float64) float64 {
    return c.round(a - b)
}

// Multiply 乘法
func (c *Calculator) Multiply(a, b float64) float64 {
    return c.round(a * b)
}

// Divide 除法
func (c *Calculator) Divide(a, b float64) (float64, error) {
    if b == 0 {
        return 0, errors.New("除数不能为零")
    }
    return c.round(a / b), nil
}

// Power 幂运算
func (c *Calculator) Power(base, exponent float64) float64 {
    return c.round(math.Pow(base, exponent))
}

// Sqrt 平方根
func (c *Calculator) Sqrt(x float64) (float64, error) {
    if x < 0 {
        return 0, errors.New("负数不能开平方根")
    }
    return c.round(math.Sqrt(x)), nil
}

// round 四舍五入到指定精度
func (c *Calculator) round(value float64) float64 {
    multiplier := math.Pow(10, float64(c.precision))
    return math.Round(value*multiplier) / multiplier
}

// SetPrecision 设置精度
func (c *Calculator) SetPrecision(precision int) {
    if precision >= 0 {
        c.precision = precision
    }
}

// GetPrecision 获取精度
func (c *Calculator) GetPrecision() int {
    return c.precision
}

// 包级别的便利函数
var defaultCalculator = New(2)

// Add 包级别的加法函数
func Add(a, b float64) float64 {
    return defaultCalculator.Add(a, b)
}

// Subtract 包级别的减法函数
func Subtract(a, b float64) float64 {
    return defaultCalculator.Subtract(a, b)
}

// Multiply 包级别的乘法函数
func Multiply(a, b float64) float64 {
    return defaultCalculator.Multiply(a, b)
}

// Divide 包级别的除法函数
func Divide(a, b float64) (float64, error) {
    return defaultCalculator.Divide(a, b)
}

// mathutils_test.go
package mathutils

import (
    "testing"
)

func TestCalculator_Add(t *testing.T) {
    calc := New(2)

    tests := []struct {
        name     string
        a, b     float64
        expected float64
    }{
        {"正数相加", 1.5, 2.3, 3.8},
        {"负数相加", -1.5, -2.3, -3.8},
        {"零相加", 0, 5.5, 5.5},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := calc.Add(tt.a, tt.b)
            if result != tt.expected {
                t.Errorf("Add(%v, %v) = %v, 期望 %v", tt.a, tt.b, result, tt.expected)
            }
        })
    }
}

func TestCalculator_Divide(t *testing.T) {
    calc := New(2)

    // 正常除法
    result, err := calc.Divide(10, 2)
    if err != nil {
        t.Errorf("Divide(10, 2) 返回错误: %v", err)
    }
    if result != 5.0 {
        t.Errorf("Divide(10, 2) = %v, 期望 5.0", result)
    }

    // 除零测试
    _, err = calc.Divide(10, 0)
    if err == nil {
        t.Error("Divide(10, 0) 应该返回错误")
    }
}

func TestPackageLevelFunctions(t *testing.T) {
    result := Add(3, 4)
    if result != 7 {
        t.Errorf("Add(3, 4) = %v, 期望 7", result)
    }

    result, err := Divide(10, 2)
    if err != nil {
        t.Errorf("Divide(10, 2) 返回错误: %v", err)
    }
    if result != 5 {
        t.Errorf("Divide(10, 2) = %v, 期望 5", result)
    }
}

// 基准测试
func BenchmarkCalculator_Add(b *testing.B) {
    calc := New(2)
    for i := 0; i < b.N; i++ {
        calc.Add(1.5, 2.3)
    }
}

func BenchmarkCalculator_Multiply(b *testing.B) {
    calc := New(2)
    for i := 0; i < b.N; i++ {
        calc.Multiply(1.5, 2.3)
    }
}

# 1. 确保代码质量
go test ./...
go vet ./...
go mod tidy

# 2. 创建版本标签
git add .
git commit -m "Release v1.0.0"
git tag v1.0.0
git push origin v1.0.0

# 3. 发布到 Go 模块代理
# Go 模块代理会自动索引公开的 Git 仓库

# 4. 验证发布
go list -m github.com/example/[email protected]

// example_test.go
package mathutils_test

import (
    "fmt"
    "github.com/example/mathutils"
)

// Example 基本使用示例
func Example() {
    // 使用包级别函数
    result := mathutils.Add(3.14, 2.86)
    fmt.Printf("3.14 + 2.86 = %.2f\n", result)

    // 使用计算器实例
    calc := mathutils.New(3)
    result = calc.Multiply(2.5, 4.0)
    fmt.Printf("2.5 * 4.0 = %.3f\n", result)

    // Output:
    // 3.14 + 2.86 = 6.00
    // 2.5 * 4.0 = 10.000
}

// ExampleCalculator_Divide 除法示例
func ExampleCalculator_Divide() {
    calc := mathutils.New(2)

    result, err := calc.Divide(10, 3)
    if err != nil {
        fmt.Printf("错误: %v\n", err)
        return
    }

    fmt.Printf("10 / 3 = %.2f\n", result)

    // Output:
    // 10 / 3 = 3.33
}

# 检查已知漏洞
go list -json -m all | nancy sleuth

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

# 更新有漏洞的依赖
go get -u github.com/vulnerable/package

// scripts/audit.go
package main

import (
    "encoding/json"
    "fmt"
    "os"
    "os/exec"
    "strings"
    "time"
)

// Module 模块信息
type Module struct {
    Path     string    `json:"Path"`
    Version  string    `json:"Version"`
    Time     time.Time `json:"Time"`
    Indirect bool      `json:"Indirect"`
}

// ModuleList 模块列表
type ModuleList struct {
    Modules []Module
}

func main() {
    // 获取所有依赖
    cmd := exec.Command("go", "list", "-json", "-m", "all")
    output, err := cmd.Output()
    if err != nil {
        fmt.Printf("获取依赖列表失败: %v\n", err)
        os.Exit(1)
    }

    // 解析输出
    var modules []Module
    decoder := json.NewDecoder(strings.NewReader(string(output)))

    for decoder.More() {
        var module Module
        if err := decoder.Decode(&module); err != nil {
            continue
        }
        modules = append(modules, module)
    }

    // 分析依赖
    fmt.Println("依赖审计报告")
    fmt.Println(strings.Repeat("=", 50))

    directCount := 0
    indirectCount := 0
    oldDeps := 0

    for _, module := range modules {
        if module.Path == "" {
            continue // 跳过主模块
        }

        if module.Indirect {
            indirectCount++
        } else {
            directCount++
        }

        // 检查过期依赖（超过1年）
        if time.Since(module.Time) > 365*24*time.Hour {
            oldDeps++
            fmt.Printf("⚠️  过期依赖: %s@%s (更新于: %s)\n",
                module.Path, module.Version, module.Time.Format("2006-01-02"))
        }
    }

    fmt.Printf("\n统计信息:\n")
    fmt.Printf("直接依赖: %d\n", directCount)
    fmt.Printf("间接依赖: %d\n", indirectCount)
    fmt.Printf("过期依赖: %d\n", oldDeps)
    fmt.Printf("总依赖数: %d\n", len(modules)-1) // 减去主模块

    if oldDeps > 0 {
        fmt.Printf("\n建议运行 'go get -u all' 更新依赖\n")
    }
}

# 配置私有模块
export GOPRIVATE=github.com/mycompany/*
export GONOPROXY=github.com/mycompany/*
export GONOSUMDB=github.com/mycompany/*

# 或者在 go.env 中配置
go env -w GOPRIVATE=github.com/mycompany/*

// tools/deps-manager/main.go
package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "os"
    "os/exec"
    "path/filepath"
    "strings"
)

// DependencyPolicy 依赖策略
type DependencyPolicy struct {
    AllowedDomains   []string `json:"allowed_domains"`
    BlockedPackages  []string `json:"blocked_packages"`
    RequiredVersions map[string]string `json:"required_versions"`
}

// PolicyChecker 策略检查器
type PolicyChecker struct {
    policy DependencyPolicy
}

// NewPolicyChecker 创建策略检查器
func NewPolicyChecker(policyFile string) (*PolicyChecker, error) {
    data, err := ioutil.ReadFile(policyFile)
    if err != nil {
        return nil, err
    }

    var policy DependencyPolicy
    err = json.Unmarshal(data, &policy)
    if err != nil {
        return nil, err
    }

    return &PolicyChecker{policy: policy}, nil
}

// CheckProject 检查项目依赖
func (pc *PolicyChecker) CheckProject(projectPath string) error {
    // 切换到项目目录
    oldDir, _ := os.Getwd()
    defer os.Chdir(oldDir)
    os.Chdir(projectPath)

    // 获取依赖列表
    cmd := exec.Command("go", "list", "-json", "-m", "all")
    output, err := cmd.Output()
    if err != nil {
        return fmt.Errorf("获取依赖失败: %w", err)
    }

    // 解析依赖
    var violations []string
    decoder := json.NewDecoder(strings.NewReader(string(output)))

    for decoder.More() {
        var module struct {
            Path    string `json:"Path"`
            Version string `json:"Version"`
        }

        if err := decoder.Decode(&module); err != nil {
            continue
        }

        if module.Path == "" {
            continue
        }

        // 检查域名白名单
        allowed := false
        for _, domain := range pc.policy.AllowedDomains {
            if strings.HasPrefix(module.Path, domain) {
                allowed = true
                break
            }
        }

        if !allowed {
            violations = append(violations,
                fmt.Sprintf("未授权域名: %s", module.Path))
        }

        // 检查黑名单
        for _, blocked := range pc.policy.BlockedPackages {
            if strings.Contains(module.Path, blocked) {
                violations = append(violations,
                    fmt.Sprintf("被禁止的包: %s", module.Path))
            }
        }

        // 检查版本要求
        if requiredVersion, exists := pc.policy.RequiredVersions[module.Path]; exists {
            if module.Version != requiredVersion {
                violations = append(violations,
                    fmt.Sprintf("版本不匹配: %s 需要 %s，当前 %s",
                        module.Path, requiredVersion, module.Version))
            }
        }
    }

    if len(violations) > 0 {
        fmt.Println("依赖策略违规:")
        for _, violation := range violations {
            fmt.Printf("  ❌ %s\n", violation)
        }
        return fmt.Errorf("发现 %d 个策略违规", len(violations))
    }

    fmt.Println("✅ 依赖策略检查通过")
    return nil
}

func main() {
    if len(os.Args) < 3 {
        fmt.Println("用法: deps-manager <policy.json> <project-path>")
        os.Exit(1)
    }

    policyFile := os.Args[1]
    projectPath := os.Args[2]

    checker, err := NewPolicyChecker(policyFile)
    if err != nil {
        fmt.Printf("加载策略文件失败: %v\n", err)
        os.Exit(1)
    }

    err = checker.CheckProject(projectPath)
    if err != nil {
        fmt.Printf("检查失败: %v\n", err)
        os.Exit(1)
    }
}

// policy.json
{
  "allowed_domains": [
    "github.com/gin-gonic/",
    "github.com/sirupsen/",
    "golang.org/x/",
    "google.golang.org/",
    "gorm.io/",
    "github.com/mycompany/"
  ],
  "blocked_packages": ["github.com/dangerous/package", "insecure-lib"],
  "required_versions": {
    "github.com/gin-gonic/gin": "v1.9.1",
    "github.com/sirupsen/logrus": "v1.9.3"
  }
}