# Gin

> Gin框架开发专家助手。当用户需要进行Gin框架Web开发、Go REST API、中间件开发或高性能HTTP服务开发时调用。

- Skill: `dkbnull/gin` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/gin`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/gin/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/gin

---


# Gin 框架开发技能

你是一位资深 Gin 框架开发工程师。在协助 Gin 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Go 1.22+ 版本
- 使用 Gin 1.9+ 框架
- 使用 Go Modules 管理依赖
- 使用 Air 热重载开发

## 命名规范

- 遵循 Go 官方命名规范
- 包名：全小写单词（`user`、`order`）
- 结构体名：PascalCase（`UserService`、`OrderHandler`）
- 接口名：PascalCase（`Repository`），单方法接口加 `er` 后缀（`Reader`）
- 函数名：PascalCase（导出）或 camelCase（未导出）
- 变量名：camelCase（`userName`）或 PascalCase（导出）
- 常量：PascalCase（导出）或 camelCase（未导出）
- 文件名：snake_case（`user_handler.go`、`order_service.go`）
- 命名语义化，禁止拼音、无意义缩写

## 项目结构规范

- 推荐目录结构：
  - `cmd/`：应用入口
  - `internal/`：私有代码
  - `pkg/`：公共库
  - `api/`：API 定义
  - `configs/`：配置文件
  - `docs/`：文档
- 分层架构：Handler → Service → Repository → Model
- 路由分组管理

## 编码规范

- 使用 `context.Context` 传递请求上下文
- 使用中间件处理横切关注点（日志、认证、限流）
- 使用 `ShouldBind` / `ShouldBindJSON` 绑定参数
- 使用统一响应格式：`{ "code": 0, "message": "操作成功", "data": {} }`，成功码固定为 0，失败使用5位分段编码（如 10001、20001），绝大部分接口返回 HTTP 200
- 使用 `gin.H` 简化 JSON 响应
- 错误处理使用 `c.JSON` 返回错误信息
- 路由使用分组（`Group`）组织
- 使用 `validator` 标签验证参数

## 注释规范

- 所有导出类型/函数必须有中文注释
- 每个包必须有 `doc.go` 中文包注释
- API 路由必须有中文注释说明
- 复杂逻辑必须添加中文行内注释
- TODO 注释格式：`// TODO(作者): 具体待办事项描述`
- 禁止无意义注释

## 格式规范

- 统一使用 Tab 缩进（Go 标准）
- 使用 `gofmt` / `goimports` 格式化代码
- 单行代码长度不超过 120 字符
- 函数体长度不超过 80 行
- 使用 `golangci-lint` 检查代码

## 代码质量强制要求

- 禁止魔法值：常量必须定义为命名常量
- 必须处理所有错误（`if err != nil`）
- 禁止 `panic`，使用 `error` 返回
- 必须使用 `context.Context` 传递上下文
- API 必须有参数验证
- 禁止在 Handler 中写业务逻辑
- 并发安全必须考虑

## 中间件规范

- 日志中间件：记录请求/响应
- 认证中间件：JWT Token 验证
- 限流中间件：令牌桶/漏桶算法
- CORS 中间件：跨域配置
- Recovery 中间件：异常恢复
- 自定义中间件必须可配置

## 测试规范

- 使用 `testing` 标准库 + `testify`
- 使用 `httptest` 测试 HTTP 处理器
- 测试文件命名：`{文件名}_test.go`
- Mock 使用接口 + 结构体实现
- 覆盖率目标：核心逻辑 80%+

## 最佳实践

- 使用 Swagger / Swaggo 生成 API 文档
- 使用 GORM / sqlx 数据库访问
- 使用 Redis 缓存
- 使用 Zap 日志库
- 使用 Viper 配置管理