go-setup

用途

go-setup 是一个面向 Go 项目初始化的技能，用于在启动新 Go 项目时提供项目结构决策、库选择、架构规划与配置设置方面的指导。当需要新建 Go 项目、决定项目结构、选择库与依赖、搭建构建工具与配置时可以使用它。

主要能力

该技能覆盖 Go 项目初始化与设置，包括：项目结构决策、库选择、架构规划、配置设置。

项目结构参考

详细的结构指南被拆分为多个聚焦的参考文件：

CLI / TUI 应用：简单 CLI、支撑包、使用 Bubble Tea 的 TUI
单服务：基础服务、带数据库的服务、服务层职责
Monorepo：go.work、多服务 justfile、CI
混合：CLI + 服务 + 共享包的组合布局
推荐库：核心、CLI/TUI、数据库、并发、测试、构建工具

常用命令

just build          # Build binary
just run            # Run application
just dev            # Run with hot reload

just check          # vet + test-unit + lint
just lint           # golangci-lint
just test-unit      # Unit tests only
just test-all       # All tests

just migrate-up     # Apply migrations
just migrate-down   # Rollback migrations
just sqlc           # Generate SQL code

标准 justfile 模板

# Variables
binary := "myapp"
main := "./cmd/server"

# Default recipe (runs with just `just`)
default: build

# Build binary
build:
    go build -o bin/{{binary}} {{main}}

# Run application
run:
    go run {{main}}

# Development with hot reload (requires air)
dev:
    air

# Run all checks
check: lint test

# Run linter
lint:
    golangci-lint run ./...

# Run unit tests
test:
    go test -v -race ./...

# Run unit tests with coverage
test-coverage:
    go test -v -race -coverprofile=coverage.out ./...
    go tool cover -html=coverage.out -o coverage.html

# Run integration tests
test-integration:
    go test -v ./test/integration/...

# Run E2E tests
test-e2e:
    go test -v ./test/e2e/...

# Run all tests
test-all: test test-integration test-e2e

# Database migrations
migrate-up:
    migrate -path ./db/migrations -database "$DATABASE_URL" up

migrate-down:
    migrate -path ./db/migrations -database "$DATABASE_URL" down

# Generate SQL code
sqlc:
    sqlc generate

# Clean build artifacts
clean:
    rm -rf bin/
    rm -f coverage.out coverage.html

# Install binary to GOPATH
install:
    go install {{main}}

配置

环境变量（推荐）：

package config

import "github.com/caarlos0/env/v11"

type Config struct {
    Port         int    `env:"PORT" envDefault:"8080"`
    DatabaseURL  string `env:"DATABASE_URL" envRequired:"true"`
    LogLevel     string `env:"LOG_LEVEL" envDefault:"info"`
    JWTSecret    string `env:"JWT_SECRET" envRequired:"true"`
}

func Load() (*Config, error) {
    cfg := &Config{}
    if err := env.Parse(cfg); err != nil {
        return nil, err
    }
    return cfg, nil
}

.env 文件（仅开发环境）：

# .env (gitignored)
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
JWT_SECRET=dev-secret
LOG_LEVEL=debug
PORT=8080

关键原则

来自官方 Go 文档：

从简开始——小型项目单个 main.go 即可
使用 internal/ 存放私有包（由编译器强制）
使用 cmd/ 存放多个二进制文件
仅在包需要被他人导入时使用 pkg/
绝不使用 /src——这是 Java 模式，不是 Go 模式

常见错误

不要	应该
创建 /src 目录	使用根目录或 cmd/
对小项目过度工程	从简开始，逐步演进
仅为组织文件而创建包	为逻辑边界创建包
照搬 Java/Python 结构	遵循 Go 惯例
过早抽象	等到需要时再抽象

何时创建新包

在以下情况创建新包：

代码需要在多处复用
希望强制代码之间的边界
作为“黑盒”可降低认知负担

不要仅为以下目的创建包：

组织文件
减小文件体积
匹配其他语言的结构

初始化检查清单

启动新 Go 项目时：

初始化 go module：go mod init github.com/org/project
根据项目类型选择结构
添加 justfile
配置 golangci-lint
设置 CI/CD（GitHub Actions）
添加 .gitignore
创建 README.md
设置数据库迁移（如需要）
配置 sqlc（如使用）
添加基础测试

Go 的 .gitignore

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

# Test
*.test
*.out
coverage.out

# Go workspace
go.work
go.work.sum

# Environment
.env
.env.local
*.env

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

# Build
dist/

CI/CD 示例（GitHub Actions）

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      
      - uses: extractions/setup-just@v2
      
      - name: Download dependencies
        run: go mod download
      
      - name: Run checks
        run: just check
      
      - name: Run all tests
        run: just test-all

CI 注意事项：

just 并未预装在 GitHub runner 上。需添加 extractions/setup-just@v2，或直接调用底层命令（go vet、golangci-lint run）；假设存在 just 的工作流会在首次运行时因 command not found（退出码 127）而失败。
在首批真实代码落地前，为配方添加守卫（find . -name '*.go' | grep -q . → 跳过并输出消息），并将 lint/vet/test 步骤标记为 continue-on-error：golangci-lint 在空模块上会以非零退出，导致仅有文档和规划文件的仓库 CI 失败。
将环境相关的检查（机器本地路径、个人工具链 linter）保留在本地 git hooks 中，而非 CI。CI runner 缺少这些检查所探测的 home 目录状态。

适用场景

适用于新建 Go 项目、决定项目结构、选择库与依赖、搭建构建工具与配置等场景。

限制

资料未提供该技能的收费、价格、平台支持范围等具体信息。

技能介绍

用途