Go AI Coding Prompt 设计|20260530

将 wswiki 知识库中 Go 相关内容转化为 AI Coding 可复用的模板适用于 AI 辅助生成 Go 项目（以 gozero 为例）

1. 项目初始化 Prompt

## 技术栈
- Go >=1.26
- 包: math/rand/v2, encoding/json/v2
- ❌ 不使用 langchaingo
- ✅ 使用官方 SDK: github.com/openai/openai-go/v3, github.com/modelcontextprotocol/go-sdk

## 工具链
- golangci-lint (配置文件见 .golangci.yaml)
- gofumpt 格式化: gofumpt -l -w .（替代 gofmt，严格超集，向后兼容）
- go fix: API 迁移工具，处理废弃 API 替换，支持 //go:fix inline 指令
- modernize: go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -test ./...（语言特性升级）
- 交叉编译: GOOS=linux GOARCH=amd64 go build
- 依赖管理: go get, go mod tidy
- gopls MCP Server: 内置实验性 MCP 支持, AI 工具可直接通过 gopls 获取诊断/跳转/引用

## Go 1.25/1.26 新特性须知
- testing/synctest: 并发测试的"气泡(Bubble)"机制, 合成假时钟, 几毫秒确定性跑完原本需等数秒的并发超时测试
- Green Tea GC: 按页处理+SIMD 向量化, GC CPU 下降 10%, 重型应用降 50%, 零代码修改
- gofix 现代转换器: 20+ 预置 Modernizers, 一键升级陈旧代码
- MCP 官方 SDK: github.com/modelcontextprotocol/go-sdk, gopls 已内置实验性 MCP Server
- AI 时代优势: "无聊"即护城河, 语法简单确定性强, gofmt 标准化, 强类型编译期验证

## 代码规范
- 错误处理: 遵循 Go 最佳实践, 错误即值, 使用 errors.Is/As 判断
- context aware: 函数签名首参为 context.Context
- goroutine 生命周期: 明确启动/退出, 使用 errgroup 管理并发
- interface 设计: 小接口(1-2方法), 接受接口返回结构体
- 简洁编码: 少嵌套, 早返回, 函数短小
- Go Proverbs 核心: 不要通过共享内存通信, 通过通信共享内存; 错误即值; 清晰的比聪明的好

## 测试规范（极简原则）
- ✅ 仅使用 Go 标准库 testing 包
- ✅ 表驱动测试 (Table Driven Test)
- ✅ 覆盖正常/边界/异常场景
- ✅ xxx_test.go 只测试 xxx.go 中的函数
- ✅ 使用 option 设计模式进行配置初始化（不需要测试）
- ✅ 并发测试使用 testing/synctest, 告别 time.Sleep 玄学
- ✅ 使用 Go TestMain 测试引导模式，不依赖 mock
- ❌ 不使用接口注入测试替身（Test Double）
- ❌ 不使用第三方 mock 框架（gomock、testify/mock）
- ❌ 不使用断言库，使用 if 判断

## 项目结构
.
├── cmd/          # 入口
├── internal/     # 私有包
│   ├── handler/  # HTTP/gRPC handler
│   ├── logic/    # 业务逻辑
│   ├── model/    # 数据模型
│   ├── repo/     # 数据访问
│   └── middleware/ # 中间件
├── pkg/          # 可导出包
├── api/          # API 定义 (proto/api 文件)
├── config/       # 配置
├── Makefile
├── AGENTS.md
├── .golangci.yaml
└── go.mod

## 输出要求
- 提交完整工程: 代码 + 测试 + Makefile + AGENTS.md + .golangci.yaml
- 代码质量: Time Complexity, comments, unit test, project structure, code cleanness
- 技术方案阶段不输出具体代码，只输出方案
- 依赖版本超出训练截止日期时，调用搜索工具确认最新 API

2. 核心代码示例片段

2.1 生产级 HTTP Client

funcNewProductionHttpClient() *http.Client {
 t := &http.Transport{
  DialContext: (&net.Dialer{
   Timeout:   5 * time.Second,
   KeepAlive: 30 * time.Second,
  }).DialContext,
  IdleConnTimeout:       10 * time.Second,
  MaxIdleConns:          100,
  MaxIdleConnsPerHost:   10,
  TLSHandshakeTimeout:   5 * time.Second,
  ResponseHeaderTimeout: 10 * time.Second,
 }
return &http.Client{
  Transport: t,
  Timeout:   30 * time.Second,
 }
}

2.2 并发设计模式（12 种）

模式	适用场景	核心 API
errgroup	并发任务+错误收集	`golang.org/x/sync/errgroup`
Pipeline	数据处理流水线	channel + Go 1.23 iter
Worker Pool	控制并发数量	fixed goroutines + job channel
Fan-Out/Fan-In	任务分发合并	multiple goroutines + merge channel
Semaphore	资源访问控制	buffered channel
sync.Once	单次执行/懒初始化	`sync.Once`
sync.Pool	对象复用减少 GC	`sync.Pool`
sync.Map	读多写少并发 Map	`sync.Map` （写多用分片 Map）
Context	取消/超时传播	`context.WithCancel/Timeout/Deadline`
select	多路复用	`select { case <-ch1: ... }`
conc	高级并发抽象	`github.com/sourcegraph/conc`
Channel 模式	单向/缓冲/nil	`chan<-` / `<-chan` / nil channel

2.3 GORM 模板

type User struct {
 ID        uint`gorm:"primarykey"`
 Name      string`gorm:"column:name;type:varchar(100);not null"`
 Age       *int`gorm:"column:age"`
 CreatedAt time.Time
 UpdatedAt time.Time
 DeletedAt gorm.DeletedAt `gorm:"index"`
}

// 操作
db.Where("name = ?", "foo").First(&user)
db.Create(&user)
db.Model(&user).Update("name", "bar")
db.Transaction(func(tx *gorm.DB)error { ... })

2.4 Buf Protobuf 工作流

buf lint                    # 40+ lint 规则检查
buf breaking --against .git  # breaking change 检测
buf generate                # 代码生成
buf format                  # 格式化

2.5 Goose 数据库迁移

-- +goose Up
CREATETABLEusers (idSERIAL PRIMARY KEY, nameTEXT);

-- +goose Down
DROPTABLEusers;

goose up        # 执行迁移
goose down      # 回滚
goose status    # 查看状态
goose fix       # 重新编号

3. AI Coding 工具链 Skill

3.1 代码模板库 (wiki-code-templates)

模板	文件位置	适用场景
Proto 模板	.agents/skills/wiki-code-templates/templates/proto-template.md	编写 .proto 文件
单测模板	.agents/skills/wiki-code-templates/templates/unit-test-template.md	编写单元测试
GORM Gen 模板	.agents/skills/wiki-code-templates/templates/gorm-gen-template.md	配置 GORM Gen
错误码模板	.agents/skills/wiki-code-templates/templates/errno-template.md	定义错误码
中间件模板	.agents/skills/wiki-code-templates/templates/middleware-template.md	实现中间件

3.2 goctl 代码生成

# gRPC: proto -> .pb.go + logic/handler 骨架
goctl rpc protoc *.proto --go_out=. --go-grpc_out=. --zrpc_out=.

# BFF: api -> handler/logic 骨架
goctl api go -api *.api -dir .

3.3 go-zero gRPC 业务服务开发流程

完整流程 806 行文档，位于 .agents/skills/wiki-go-zero-grpc-workflow/SKILL.md，包含：

Git Workflow（feat/bugfix/hotfix/dev/master 分支策略）
Protobuf 编写规范
微服务初始化
gRPC 转 HTTP (Gateway)
错误码管理
Apollo 配置中心
MySQL (GORM Gen)
Redis
定时任务
数据校验（Protobuf gotags）

4. 实体参考（技术选型依据）

实体	用途	Stars	选用场景
Eino	字节 Go LLM 框架	11.4k	AI Agent / LLM 编排
Genkit Go	Google Go AI SDK	官方	类型安全结构化输出
ADK Go	Google AI Agent 框架	官方 1.0	多 Agent 系统
Gatus	健康监控状态页	10k+	服务健康检查
Goose	数据库迁移	10.7k	SQL + Go 函数混合迁移
Buf	Protobuf CLI	11.1k	替代 protoc

5. 关键原则总结

1. 模板 > 复制: 新增代码优先参考模板库，不从现有代码复制
2. 测试不 mock: 仅标准库 testing，表驱动测试，if 判断代替断言
3. 官方 SDK 优先: openai-go/v3, mcp-go-sdk，不用 langchaingo
4. goroutine 生命周期: 明确启动退出，errgroup 管理并发
5. 接口设计: 小接口(1-2方法)，接受接口返回结构体
6. 错误即值: errors.Is/As 判断，不用 panic
7. context 首参: 所有函数签名首参为 context.Context
8. 先 proto/api 再 goctl: 源文件手动编写，骨架代码自动生成

6. 使用方法

# Step 1: 复制模板创建新项目
cp -r templates/go-template/ <new-project>/

# Step 2: 加载对应 skill
# - 通用 Go 项目: 使用本 prompt 作为上下文
# - go-zero gRPC: 加载 wiki-go-zero-grpc-workflow skill
# - 需要代码模板: 加载 wiki-code-templates skill
# - 需要并发设计: 读取 raw/go_concurrency_design_patterns.md

# Step 3: 参考示例
# examples/go-rock/ 下有 httpclient/mongo/aws-msk 真实代码