GoFrame微服务搭建路径:第一步用gf init demo创建v2.5.4骨架并启动HTTP服务;第二步配MySQL、建表、生成DAO与CRUD接口;第三步加日志与鉴权中间件;第四步启用gRPC服务并对接数据库;第五步拆分为独立user-service进程,通过HTTP/gRPC跨服务通信。

想用GoFrame从零搭建一个能上线的Web服务,再逐步扩展成可拆分、可独立部署的微服务系统,需要一条清晰不绕弯的学习路径。
第一步:跑通标准Web项目骨架
执行 gf init demo 创建项目,不要加 -u 参数——这会强制拉取最新v2主干代码,而当前稳定生产环境推荐使用 v2.5.x 分支。项目生成后,立即检查 go.mod 中的 gf 版本是否为 v2.5.4,不是则手动修改并运行 go mod tidy。
进入 demo 目录,执行 gf run main.go 启动服务。此时终端应输出 Server started on http://127.0.0.1:8000,并在浏览器访问该地址看到默认欢迎页。若端口被占,编辑 manifest/config/config.yaml 中的 server.port 字段为 8001 或其他空闲端口。
这一步验证的是框架基础运行能力,不涉及任何业务逻辑。只要页面能打开,就说明环境、工具链、项目结构三者已对齐。
第二步:接入数据库并生成首组CRUD
在 config/config.yaml 的 database 节点下配置 MySQL 连接串,格式为:link: "mysql:root:password@tcp(127.0.0.1:3306)/demo_db?charset=utf8mb4&parseTime=true"。注意密码中若含特殊字符(如 @ / :),必须做 URL 编码。
创建一张测试表:CREATE TABLE article (id INT PRIMARY KEY AUTO_INCREMENT, title VARCHAR(255), content TEXT, created_at DATETIME DEFAULT CURRENT_TIMESTAMP);
执行命令生成对应模型与DAO:gf gen dao -t article。该命令会在 internal/dao 和 internal/model/do 下生成 article.go 文件。生成后不要手动修改 do/article.go,它由工具维护,后续表结构变更需重新执行此命令。
在 internal/controller 下新建 article.go,写一个最简查询接口:
func (c *Controller) List(ctx context.Context, req *v1.ArticleListReq) (res *v1.ArticleListRes, err error) {
list, _ := dao.Article.Ctx(ctx).OrderDesc("id").All()
res.List = list
return
}
绑定路由:s.BindHandler("/api/article", c.List)。此时访问 http://127.0.0.1:8000/api/article 应返回空数组 [],表示数据层已贯通。
第三步:添加中间件实现统一日志与鉴权雏形
在 internal/middleware 目录(需手动创建)中新建 logger.go,内容为:
func Logger(r *ghttp.Request) {
start := time.Now()
r.Middleware.Next()
g.Log().Infof("%s %s %d %v", r.Method, r.URL.Path, r.Response.Status, time.Since(start))
}
在 main.go 的服务器初始化后插入:s.Use(middleware.Logger)。重启服务,任意请求都会在终端打印带耗时的日志行。
接着添加登录校验中间件:auth.go,检查请求头 X-Auth-Token 是否存在且非空:
func Auth(r *ghttp.Request) {
if r.Header.Get("X-Auth-Token") == "" {
r.Response.Status = 401
r.Response.Write("Unauthorized")
return
}
r.Middleware.Next()
}
将该中间件仅绑定到需要保护的路由:s.Group("/api/admin", middleware.Auth, func(group *ghttp.RouterGroup) { group.GET("/users", c.UserList) })。此时未带 token 访问 /api/admin/users 将直接返回 401。
第四步:启用 gRPC 微服务模块
方法一:启用内置 gRPC 服务端
编辑 manifest/config/config.yaml,在根节点添加 grpc 配置块,其中 address 设为 :9000,避免与 HTTP 端口冲突。
在 manifest/protobuf 下建立目录 user/v1,创建 user.proto,定义 SayHello 接口和 HelloReq/HelloRes 消息体。
执行 gf gen pb,框架自动生成 api/user/v1 接口定义、internal/controller/user 控制器桩、internal/logic/user 逻辑桩。
在 internal/cmd/cmd.go 的 init() 函数中调用 g.Server().AddCommand(gcmd.NewCommand(...)) 注册 gRPC 命令;启动时加参数 --command=grpc 即可单独运行 gRPC 服务。
方法二:反向生成 DAO 并对接已有 MySQL 表
若已有 user 表,执行 gf gen dao -t user 生成 DAO 层,再在 logic/user/user.go 的 SayHello 方法中调用 dao.User.One(ctx, 1) 查询真实用户数据,完成数据库 → gRPC 接口的数据链路打通。
启动命令改为:gf run main.go --command=grpc。此时 grpcurl -plaintext localhost:9000 list 应返回已注册的服务名。
第五步:拆分独立微服务进程
步骤一:复制原项目目录为 user-service,删除其中所有与 article 相关的 controller、logic、dao、model 文件,只保留 user 相关部分。
步骤二:修改 user-service/manifest/config/config.yaml 中的 grpc.name 为 user,database.default.link 指向专用的 user 数据库实例。
步骤三:在原项目 demo 的 logic/article/article.go 中,引入 github.com/gogf/gf/v2/net/gclient,用 g.Client().Post(ctx, "http://localhost:9000/v1/user/sayhello", ...) 调用新服务,完成跨进程通信。
步骤四:分别启动两个进程:
终端1:cd user-service && gf run main.go --command=grpc
终端2:cd demo && gf run main.go
此时 Web 服务中新增文章时,可通过 HTTP 调用 user-service 获取作者信息,两个服务物理隔离、各自编译、独立部署。











