goframe

goframe 快速入门

给 Go 开发者一个”会用 GoFrame”的 AI 副驾,不用每次都翻官方文档。

这是什么?解决什么问题?

GoFrame 是国内使用率靠前的 Go Web/微服务框架之一,文档质量不错但 API 细节多(CLI、ORM、配置、路由、校验、I18N……),新手容易在”我想用 gf gen 怎么写 gf-cli 配置”、“g.DB 怎么注入自定义 logger”这种细节上卡半小时。
goframe Skill 是 GoFrame 官方团队(gogf)维护的 agent-skills 仓库下的官方 Skill。它把 GoFrame 各模块的常见用法、最佳实践、典型坑位写进 SKILL.md,让 AI 在帮你写代码时,直接按照框架的”标准动作”出活,而不是给你一份”看起来像 Go 但实际是 gin 写法”的代码。
特别适合:第一次接触 GoFrame 的后端开发、想统一团队代码风格的 Tech Lead、要把老 gin/iris 项目迁到 GoFrame 的同学。

准备工作

• Go ≥ 1.21
  
• 一个支持 SKILL.md 的 agent
  
• 已安装 gf CLI(go install github.com/gogf/gf/cmd/gf@latest)
  
• 一个空目录作为项目根
  

3 步快速上手

第 1 步:克隆与软链

git clone https://github.com/gogf/skills.git<br>
ln -sf "$(pwd)/skills/goframe" ~/.claude/skills/goframe<br>
```<br>
OpenCode 用户把目标路径改为 `~/.config/opencode/skills/`,Cursor 用户改为 `~/.cursor/skills/`。<br>
### 第 2 步:确认 Skill 加载<br>
```bash<br>
ls ~/.claude/skills/goframe/SKILL.md<br>
grep -E "router|model|config" ~/.claude/skills/goframe/SKILL.md<br>
```<br>
应当能看到 `ghttp`(路由)、`gdb`(ORM)、`gcfg`(配置)等子模块名。重启 agent,`/skills list` 看到 `goframe` 即 OK。<br>
### 第 3 步:用 Skill 起一个新项目<br>
在空目录里进入 agent 对话,说:<br>
```<br>
用 goframe Skill 帮我生成一个 user 模块的 CRUD 工程,<br>
包含:model、dao、service、controller、api 定义,<br>
数据库用 MySQL。<br>
```<br>
AI 会按 Skill 内的"标准工程结构"输出:<br>
- `internal/model/entity/user.go`(实体)<br>
- `internal/dao/user.go`(DAO 层)<br>
- `internal/service/user.go`(业务逻辑)<br>
- `internal/controller/user.go`(HTTP 处理器)<br>
- `api/user/v1/user.go`(gRPC/API 定义)<br>
- `manifest/config/config.yaml`(配置)<br>
- `cmd/server/main.go`(启动入口)<br>
接着你可以追加:<br>
```<br>
帮我用 gf gen dao 重新生成 dao 代码,<br>
并加一条路由: GET /api/v1/user/:id。<br>
```<br>
## 常见踩坑<br>
1. **`gf` CLI 没装或版本不对**:Skill 里很多命令依赖 `gf` CLI。装好后 `gf -v` 验证。<br>
2. **ORM 链式调用写错**:`db.Model("user").Where(g.Map{"id":1}).One()` 这种是常用模板,但 where 条件用 struct 还是 Map 容易混,Skill 会提醒。<br>
3. **配置文件热加载没启用**:`gcfg` 默认不 watch 文件,要让 AI 加 `gcfg.Get().SetFileWatcher` 才能改了不重启。<br>
4. **路由分组和中间件顺序写反**:GoFrame 的 group middleware 是后注册先生效,顺序写反结果完全不同,Skill 会主动标红。<br>
5. **忘了初始化 g.DB**:很多人写好代码跑起来报"nil pointer",其实是没在 `main.go` 里 `g.DB().Init()` 一下。Skill 会显式补上。<br>
6. **gRPC 与 HTTP 混用时端口冲突**:用 `g.Server()` 的同进程多协议时,要把 `SetPort` 分开,Skill 会按官方推荐拆分。<br>
## 初级用法<br>
- **写一个 hello-world 接口**:让 Skill 出"返回 Hello + 当前时间"的极简 HTTP 服务,先跑通链路。<br>
- **写一份 `config.yaml` 模板**:从 Skill 拿到一份"开发/测试/生产"三环境的配置骨架,直接复制改值。<br>
## 高级玩法<br>
- **自动化生成 OpenAPI 文档**:GoFrame 的 `g.Meta` 标签配合 `gf gen swagger`,让 Skill 一次性把 OpenAPI 3.0 文档生成出来。<br>
- **配合 K8s 部署清单**:让 Skill 同时出 Dockerfile + K8s Deployment/Service yaml,端到端可用。<br>
- **批量生成 gRPC proto**:用 Skill 把所有 service 的 `.proto` 文件按统一规范生成,避免命名风格漂移。<br>
## 小技巧<br>
- 用 `gf gen model -p` 加 `-path` 让生成路径和 `internal/model` 保持一致,否则会落得到处都是。<br>
- 多模块项目(monorepo)里把 `manifest` 放到 `app/{module}/manifest`,Skill 知道这套路。<br>
- 写业务逻辑时优先放 service 层而不是 controller,Skill 会主动纠正"Controller 太胖"的反模式。<br>
- 启用 `glog` 的 `SetStackSkip` 可以让日志跳过框架内部栈,排查问题更快。<br>
- 数据库字段名 snake_case,Go 字段名 CamelCase,Skill 会自动配对 `orm:` 标签。<br>

## 参考链接<br>
- [仓库主页](https://github.com/gogf/skills)<br>
- [GoFrame 官方文档](https://goframe.org/)<br>
- [GoFrame CLI 文档](https://goframe.org/docs/cli)<br>
- [GoFrame ORM 文档](https://goframe.org/docs/orm)<br>
- [GoFrame GitHub](https://github.com/gogf/gf)<br>
- 相关 Skill:deprecation-and-migration、clickhouse-io<br>