go-basics

🚀 Go 开发规则

版本: v4.3.0 | 最后更新: 2026-01-22 | 作者: Cursor AI Rules

🎯 适用场景

• 云原生微服务开发
• 网络服务和API服务
• 分布式系统和容器化应用
• 系统工具和命令行程序
• 高并发服务器应用
• DevOps工具和基础设施代码

🏗️ 项目结构

Go Modules 项目布局

go_project/
├── go.mod                    # Go模块定义
├── go.sum                    # 依赖校验文件
├── main.go                   # 程序入口
├── cmd/                      # 主程序
│   └── server/
│       └── main.go
├── internal/                 # 私有代码
│   ├── config/              # 配置管理
│   │   ├── config.go
│   │   └── config_test.go
│   ├── models/              # 数据模型
│   │   ├── user.go
│   │   └── product.go
│   ├── handlers/            # HTTP处理器
│   │   ├── user_handler.go
│   │   └── product_handler.go
│   ├── services/            # 业务逻辑
│   │   ├── user_service.go
│   │   └── product_service.go
│   └── repository/          # 数据访问层
│       ├── user_repo.go
│       └── product_repo.go
├── pkg/                      # 可公开使用的包
│   ├── middleware/
│   └── utils/
├── api/                      # API定义 (protobuf, swagger等)
├── web/                      # Web资源
│   ├── static/
│   └── templates/
├── config/                   # 配置文件
├── scripts/                  # 构建和部署脚本
├── docker/                   # Docker相关
├── docs/                     # 文档
├── Makefile                  # 构建脚本
├── Dockerfile               # Docker镜像定义
└── README.md

包结构设计原则

module github.com/yourname/project

// 清晰的分层架构
├── main.go (程序入口)
├── cmd/ (具体应用)
├── internal/ (私有包)
│   ├── app/ (应用层)
│   ├── domain/ (领域层)
│   └── infrastructure/ (基础设施层)
└── pkg/ (公共包)
    ├── api/ (API定义)
    └── shared/ (共享工具)

📝 编码规范

Effective Go 实践

package main

import (
    "context"
    "database/sql"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "time"
)

// ✅ 推荐：清晰的包命名和导入分组
import (
    "context"
    "net/http"

    "github.com/gorilla/mux"
    "github.com/yourname/project/internal/models"
)

// ✅ 推荐：使用结构体标签和JSON序列化
type User struct {
    ID        int64     `json:"id" db:"id"`
    Username  string    `json:"username" db:"username" validate:"required,min=3,max=50"`
    Email     string    `json:"email" db:"email" validate:"required,email"`
    CreatedAt time.Time `json:"created_at" db:"created_at"`
    UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
}

// ✅ 推荐：构造函数模式
func NewUser(username, email string) (*User, error) {
    if username == "" || email == "" {
        return nil, fmt.Errorf("username and email are required")
    }

    return &User{
        Username:  username,
        Email:     email,
        CreatedAt: time.Now(),
        UpdatedAt: time.Now(),
    }, nil
}

// ✅ 推荐：接口定义和依赖注入
type UserRepository interface {
    Create(ctx context.Context, user *User) error
    GetByID(ctx context.Context, id int64) (*User, error)
    Update(ctx context.Context, user *User) error
    Delete(ctx context.Context, id int64) error
}

type UserService struct {
    repo UserRepository
    // 其他依赖...
}

// 构造函数注入依赖
func NewUserService(repo UserRepository) *UserService {
    return &UserService{
        repo: repo,
    }
}

// ✅ 推荐：错误处理模式
func (s *UserService) CreateUser(ctx context.Context, username, email string) (*User, error) {
    user, err := NewUser(username, email)
    if err != nil {
        return nil, fmt.Errorf("failed to create user: %w", err)
    }

    if err := s.repo.Create(ctx, user); err != nil {
        return nil, fmt.Errorf("failed to save user: %w", err)
    }

    return user, nil
}

// ✅ 推荐：Context 传递和超时控制
func (s *UserService) ProcessUserBatch(ctx context.Context, userIDs []int64) error {
    // 创建带超时的上下文
    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()

    // 使用goroutine处理批量操作
    semaphore := make(chan struct{}, 10) // 限制并发数
    errChan := make(chan error, len(userIDs))

    for _, userID := range userIDs {
        go func(id int64) {
            semaphore <- struct{}{} // 获取信号量
            defer func() { <-semaphore }() // 释放信号量

            if err := s.processSingleUser(ctx, id); err != nil {
                errChan <- err
                return
            }
            errChan <- nil
        }(userID)
    }

    // 收集结果
    for i := 0; i < len(userIDs); i++ {
        if err := <-errChan; err != nil {
            return err
        }
    }

    return nil
}

func (s *UserService) processSingleUser(ctx context.Context, userID int64) error {
    select {
    case <-ctx.Done():
        return ctx.Err()
    default:
        // 处理单个用户
        return nil
    }
}