| name | go-backend-skill |
| description | Use when the user wants to generate a Go + Gin backend project, or when routed from backend-select-skill with Go chosen. Generates a runnable scaffold on the spot following backend-convention-skill. Triggers: "用 Go 写后端", "Gin 项目", "生成 Gin", "golang backend", "go 骨架", "go web 项目". |
Go Backend Skill
现场生成 Gin 后端项目骨架。
依赖：backend-convention-skill（规范）、database-skill（DB）。本 skill 只写 Gin 特定骨架与片段，规则文本不复制。
版本获取（不写死）
优先级：本机已装版本 → 官方最新稳定/LTS → 用户可覆盖 → 写入 versions.md。
- Go：
go version（或 go env GOVERSION）；否则 https://go.dev/VERSION?m=text 或 https://endoflife.date/api/go.json。
- 依赖：
go get -u <mod>@latest 或 https://pkg.go.dev/<mod>?tab=versions。
禁止：在 SKILL.md 写"Go 1.22 / Gin 1.9"等具体数字。
生成步骤
- 从
spec.md 读项目名、模块路径、数据库、表前缀（默认 wg）。
- 按
references/skeleton.md 的目录结构建文件。
- 用下面最小片段生成关键文件，AI 扩写完整。
- 落地两份强制交付物（见下节），缺一不可。
强制交付物（文档）
生成项目时必须与代码同时落地两份文档，漏交视为生成未完成：
| 文档 | 位置 | 生成依据 |
|---|
| 介绍 & 拓展性文档 | docs/project-guide.md | 按 backend-convention-skill references/project-guide-template.md，栈特定段按本 skill references/skeleton.md 末尾「project-guide 填充段」填 |
| 接口契约（接口 md） | 项目根目录 api-contract.md | 以 backend-convention-skill references/default-api-contract.md 为起点（已含 health/auth/users 全量接口），按 api-contract-spec.md 模板追加业务实体接口 |
要求：
project-guide.md 第 4~10 节（接口范式/入参/出参/拦截器链路/鉴权/对接前端/错误码）不得省略，这是前端对接的最低信息量。api-contract.md 必须覆盖骨架自带接口 + 确认的全部业务实体接口，每个接口按模板写全。- 两份文档字段细节不重复：范式进 guide，字段进 contract。
关键文件最小片段
入口 main.go
func main() {
cfg := config.Load()
db := database.New(cfg)
jwtUtil := utils.NewJWTUtil(cfg.JWTSecret, time.Duration(cfg.JWTExpiresIn)*time.Second)
userRepo := repositories.NewUserRepository(db)
userSvc := services.NewUserService(userRepo)
userH := handlers.NewUserHandler(userSvc)
r := gin.Default()
r.Use(middlewares.ErrorHandler(), middlewares.CORS(), middlewares.RequestLog())
api := r.Group("/api")
api.GET("/health", handlers.Health)
userH.RegisterRoutes(api)
r.Run(":" + cfg.AppPort)
}
统一响应
OK/Fail 是本栈唯一包装点；handler 必须经此输出，禁止直接 c.JSON 返业务数据，禁止再注册响应包装中间件（避免漏包/双包）。业务错误可抛 *exceptions.AppError（由 ErrorHandler 捕获转 Fail）或直接 Fail(c, code, msg)，两条路径都汇入 Fail 这一唯一包装点。
type Response struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data"`
}
func OK(c *gin.Context, data interface{}) {
c.JSON(200, Response{Code: 0, Message: "success", Data: data})
}
func Fail(c *gin.Context, code int, message string) {
c.JSON(200, Response{Code: code, Message: message, Data: nil})
}
错误恢复中间件
func ErrorHandler() gin.HandlerFunc {
return func(c *gin.Context) {
defer func() {
if r := recover(); r != nil {
if e, ok := r.(*exceptions.AppError); ok {
Fail(c, e.Code, e.Message)
} else {
log.Printf("panic: %v", r)
Fail(c, -2000, "系统繁忙，请稍后再试")
}
c.Abort()
}
}()
c.Next()
}
}
健康检查
func Health(c *gin.Context) {
OK(c, gin.H{"status": "ok"})
}
标准能力清单
生成项目必须内置以下能力，完整片段见 references/skeleton.md 的"开箱即用片段"节：
| 能力 | 关键文件 |
|---|
统一响应 { code, message, data } | internal/middlewares/response.go |
| 全局异常（-1001 / -2000） | internal/middlewares/response.go 的 ErrorHandler |
| JWT 签发 / 验证 / 当前用户注入 | internal/utils/auth.go + internal/middlewares/auth.go |
| 请求日志（requestId / method / path / status / duration） | internal/middlewares/response.go 的 RequestLog |
| 参数校验 | go-playground/validator，失败转 -1001 |
分页列表 { page, pageSize, total, list } | internal/handlers/user.go 的 List |
| CORS | internal/middlewares/response.go 的 CORS |
| 密码 bcrypt hash | golang.org/x/crypto/bcrypt |
健康检查 /api/health | internal/handlers/health.go |
| Docker / docker-compose | Dockerfile + docker-compose.yml |
| 介绍 & 拓展性文档 | docs/project-guide.md（强制交付物，见上节） |
| api-contract.md（接口 md） | 项目根目录，以 convention default-api-contract.md 为起点按 api-contract-spec.md 补全 |
验证
go mod tidy
go build ./...
go vet ./...
go run cmd/server/main.go
curl http://localhost:8080/api/health
预期：{ "code": 0, "message": "success", "data": { "status": "ok" } }
不做
- 不引 MongoDB（关系型默认 PostgreSQL / MySQL）。
- 不加未请求的中间件。
- 不在 SKILL.md 锁定版本号。
- 不替用户提交。
