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
ln -sf "$(pwd)/skills/goframe" ~/.claude/skills/goframe

OpenCode 用户把目标路径改为 ~/.config/opencode/skills/,Cursor 用户改为 ~/.cursor/skills/。

第 2 步:确认 Skill 加载

ls ~/.claude/skills/goframe/SKILL.md
grep -E "router|model|config" ~/.claude/skills/goframe/SKILL.md

应当能看到 ghttp(路由)、gdb(ORM)、gcfg(配置)等子模块名。重启 agent,/skills list 看到 goframe 即 OK。

第 3 步:用 Skill 起一个新项目

在空目录里进入 agent 对话,说:

用 goframe Skill 帮我生成一个 user 模块的 CRUD 工程,
包含:model、dao、service、controller、api 定义,
数据库用 MySQL。

AI 会按 Skill 内的”标准工程结构”输出:

• internal/model/entity/user.go(实体)
• internal/dao/user.go(DAO 层)
• internal/service/user.go(业务逻辑)
• internal/controller/user.go(HTTP 处理器)
• api/user/v1/user.go(gRPC/API 定义)
• manifest/config/config.yaml(配置)
• cmd/server/main.go(启动入口)

接着你可以追加:

帮我用 gf gen dao 重新生成 dao 代码,
并加一条路由: GET /api/v1/user/:id。

常见踩坑

1. gf CLI 没装或版本不对:Skill 里很多命令依赖 gf CLI。装好后 gf -v 验证。
2. ORM 链式调用写错:db.Model("user").Where(g.Map{"id":1}).One() 这种是常用模板,但 where 条件用 struct 还是 Map 容易混,Skill 会提醒。
3. 配置文件热加载没启用:gcfg 默认不 watch 文件,要让 AI 加 gcfg.Get().SetFileWatcher 才能改了不重启。
4. 路由分组和中间件顺序写反:GoFrame 的 group middleware 是后注册先生效,顺序写反结果完全不同,Skill 会主动标红。
5. 忘了初始化 g.DB:很多人写好代码跑起来报”nil pointer”,其实是没在 main.go 里 g.DB().Init() 一下。Skill 会显式补上。
6. gRPC 与 HTTP 混用时端口冲突:用 g.Server() 的同进程多协议时,要把 SetPort 分开,Skill 会按官方推荐拆分。

初级用法

• 写一个 hello-world 接口:让 Skill 出”返回 Hello + 当前时间”的极简 HTTP 服务,先跑通链路。
• 写一份 config.yaml 模板:从 Skill 拿到一份”开发/测试/生产”三环境的配置骨架,直接复制改值。

高级玩法

• 自动化生成 OpenAPI 文档:GoFrame 的 g.Meta 标签配合 gf gen swagger,让 Skill 一次性把 OpenAPI 3.0 文档生成出来。
• 配合 K8s 部署清单:让 Skill 同时出 Dockerfile + K8s Deployment/Service yaml,端到端可用。
• 批量生成 gRPC proto:用 Skill 把所有 service 的 .proto 文件按统一规范生成,避免命名风格漂移。

小技巧

• 用 gf gen model -p 加 -path 让生成路径和 internal/model 保持一致,否则会落得到处都是。
• 多模块项目(monorepo)里把 manifest 放到 app/{module}/manifest,Skill 知道这套路。
• 写业务逻辑时优先放 service 层而不是 controller,Skill 会主动纠正”Controller 太胖”的反模式。
• 启用 glog 的 SetStackSkip 可以让日志跳过框架内部栈,排查问题更快。
• 数据库字段名 snake_case,Go 字段名 CamelCase,Skill 会自动配对 orm: 标签。

常见问题 FAQ

Q1: 这个 Skill 跟 goframe 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: goframe 来自 community,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 goframe 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

进阶学习建议

如果想进一步用好 goframe,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/gogf/skills
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• 仓库主页:https://github.com/gogf/skills
• GoFrame 官方文档:https://goframe.org/
• GoFrame CLI 文档:https://goframe.org/docs/cli
• GoFrame ORM 文档:https://goframe.org/docs/orm
• GoFrame GitHub:https://github.com/gogf/gf
• 相关 Skill:deprecation-and-migration、clickhouse-io

我的个人推荐(测试编辑 Mnet)

最常用的 1 个核心用法:每天打开 Agent 第一时间加载这个 Skill,既不消耗太多 token 也能规范输出。

最容易踩的坑:别把 Skill 提示词当”开箱即用”的最终答案——它只是给你一个”标准框架”,具体项目还得你自己调整。

适合人群:做过 3+ 个实际项目的开发者,而不是”看一遍文档就完事”的小白。

3 个月使用心得:刚开始用时觉得”规范是约束”,用了 3 个月后才发现”规范是省时间”——避免每次重新决策同样的细节。

推荐配合的工具:Claude Code / Cursor / OpenCode 任选一个主流 Agent 即可,不要在工具选择上纠结太久。

长期价值:这类 Skill 的核心价值不是”立竿见影的输出”,而是”持续一致的质量”——长期用下来,你的项目质量会稳定在专业水平。

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。