纲要
go-zero模型代码生成- 基于 SQL 文件生成数据模型
goctl model命令详解- 生成文件结构与职责
- 模型中的缓存机制与查询流程
- 在 RPC 服务中集成数据库操作
- 配置
mysql与redis数据源 - 服务上下文 (
ServiceContext) 依赖注入 - 业务逻辑 (
logic) 中调用模型 - 创建用户示例及测试
- 配置
- 中间件的定义与绑定
- 多路由组设计
- 定义中间件处理函数
- 中间件与路由绑定
- 鉴权中间件示例与测试
数据库模型生成
在微服务开发中,数据持久化是核心环节。go-zero 提供了强大的代码生成工具,能够根据数据库表结构直接生成对应的数据访问层代码,并可选地集成缓存支持,大幅减少重复编码。
准备工作
首先,需要准备好数据库建表的 SQL 文件。假设我们在 user.sql 中定义了 user 表:
CREATE TABLE `user` (
`id` bigint(20) NOT NULL AUTO_INCREMENT,
`name` varchar(50) NOT NULL DEFAULT '',
`phone` varchar(20) NOT NULL DEFAULT '',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
同时确保目标数据库中已经创建了该表。
生成命令
go-zero 通过 goctl model 命令读取 SQL 文件并生成模型代码。基本命令格式如下:
goctl model mysql ddl -src="user.sql" -dir="./model" -c
参数说明:
-src:指定数据源 DDL 文件,支持通配符*匹配所有文件,也可直接指定单个文件。-dir:生成代码的目标目录。-c:启用缓存支持。加上该参数后,生成的模型会包含基于redis的缓存逻辑。
执行成功后,将在 -dir 指定的目录下生成模型文件。
生成文件结构
model/
├── userModel_gen.go # 接口定义与默认实现结构体
├── userModel.go # 自定义扩展方法(通常为空,用于用户自定义逻辑)
└── vars.go # 常量、字段名、缓存键等定义
vars.go
该文件集中管理表相关的常量,例如表名、列名、缓存键前缀等。下面是一个生成后的示例片段:
package model
const (
tableNameUser = "user" // 表名
cacheUserIdPrefix = "cache:user:id:" // 缓存键前缀
)
var (
userFieldNames = []string{"id", "name", "phone"} // 所有字段
userFields = []string{"id", "name", "phone"} // 可写字段
userFieldsAuto = []string{} // 自动生成字段(如自增主键)
)
userModel_gen.go
该文件实现了标准的 CRUD 接口以及默认的数据库操作。
接口定义如下:
type UserModel interface {
Insert(ctx context.Context, data *User) (sql.Result, error)
FindOne(ctx context.Context, id int64) (*User, error)
Update(ctx context.Context, data *User) error
Delete(ctx context.Context, id int64) error
}
默认结构体 defaultUserModel 实现了上述接口,并持有数据库连接和缓存操作对象。其构造函数 newDefaultUserModel 需要传入数据库连接和缓存配置:
type defaultUserModel struct {
db sqlx.SqlConn
cache cache.Cache
}
func newDefaultUserModel(conn sqlx.SqlConn, c cache.CacheConf) *defaultUserModel {
return &defaultUserModel{
db: conn,
cache: cache.New(c, cacheUserIdPrefix),
}
}
userModel.go
该文件用于用户手动扩展模型方法,避免重新生成时被覆盖。初始内容为空,仅声明接口和结构体:
package model
type (
UserModel interface {
userModel
}
customUserModel struct {
*defaultUserModel
}
)
func NewUserModel(conn sqlx.SqlConn, c cache.CacheConf) UserModel {
return &customUserModel{
defaultUserModel: newDefaultUserModel(conn, c),
}
}
这种设计遵循“生成与扩展分离”的原则,团队可以在 customUserModel 中添加自定义查询或复杂业务逻辑。
缓存查询流程
当使用 -c 参数生成模型后,查询流程自动集成了缓存。以 FindOne 为例,内部流程如下:
- 先尝试从缓存中读取记录(缓存键类似
cache:user:id:123)。 - 缓存命中,直接返回结果。
- 缓存未命中,查询数据库。
- 将查询结果写入缓存并返回给调用方。
下图展示了这一流程:
缓存机制使得高频读取操作的性能得到显著提升,开发者无需手动处理缓存失效或更新策略,go-zero 将在数据变更时自动清理相关缓存。
在 RPC 服务中使用模型
模型生成后,需要将其集成到现有的 RPC 服务中。本节以创建用户功能为例进行演示。
环境配置
首先,在 RPC 服务的配置文件(如 etc/user.yaml)中添加 MySQL 和 Redis 的连接信息:
Name: user.rpc
ListenOn: 0.0.0.0:8080
Mysql:
DataSource: root:password@tcp(127.0.0.1:3306)/user?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
CacheRedis:
- Host: 127.0.0.1:6379
Pass: ""
Type: node
对应的 Go 配置结构体也需同步定义:
type Config struct {
zrpc.RpcServerConf
Mysql MysqlConf
CacheRedis cache.CacheConf
}
type MysqlConf struct {
DataSource string
}
服务上下文改造
在 svc/serviceContext.go 中,初始化数据库连接并创建用户模型实例,方便后续逻辑复用。
type ServiceContext struct {
Config config.Config
UserModel model.UserModel
}
func NewServiceContext(c config.Config) *ServiceContext {
conn := sqlx.NewMysql(c.Mysql.DataSource)
return &ServiceContext{
Config: c,
UserModel: model.NewUserModel(conn, c.CacheRedis),
}
}
定义 API 与逻辑
这里我们通过 RPC 服务提供创建用户的接口。首先在 .proto 文件中定义 RPC 方法和消息体。
syntax = "proto3";
package user;
service User {
rpc CreateUser(CreateUserReq) returns (CreateUserResp);
}
message CreateUserReq {
string name = 1;
string phone = 2;
}
message CreateUserResp {
int64 id = 1;
}
执行 goctl rpc protoc 生成对应的 Go 代码后,在 internal/logic/createUserLogic.go 中编写实际业务逻辑:
func (l *CreateUserLogic) CreateUser(in *user.CreateUserReq) (*user.CreateUserResp, error) {
data := &model.User{
Name: in.GetName(),
Phone: in.GetPhone(),
}
result, err := l.svcCtx.UserModel.Insert(l.ctx, data)
if err != nil {
return nil, err
}
id, _ := result.LastInsertId()
return &user.CreateUserResp{
Id: id,
}, nil
}
项目结构
此时整个 RPC 服务的目录结构如下:
rpc/user/
├── etc/
│ └── user.yaml
├── internal/
│ ├── config/
│ │ └── config.go
│ ├── logic/
│ │ └── createUserLogic.go
│ ├── server/
│ │ └── userServer.go
│ └── svc/
│ └── serviceContext.go
├── model/
│ ├── userModel.go
│ ├── userModel_gen.go
│ └── vars.go
├── user.proto
└── user.go
启动服务后,可以通过 gRPC 客户端或调试工具验证接口。数据库成功新增记录即表示模型集成无误。
中间件的定义与使用
在微服务中,认证、鉴权、限流等横切关注点通常以中间件形式实现。go-zero 支持在 API 网关或 RPC 服务中轻松绑定中间件。
路由组与中间件绑定
假设我们有一个 API 服务,其 .api 文件定义如下:
type (
CreateUserReq {
Name string `json:"name"`
Phone string `json:"phone"`
}
CreateUserResp {
Id int64 `json:"id"`
}
UserInfoReq {
Id int64 `json:"id"`
}
UserInfoResp {
Name string `json:"name"`
Phone string `json:"phone"`
}
)
@server (
prefix: /v1
)
service User {
@handler CreateUser
post /user (CreateUserReq) returns (CreateUserResp)
@handler UserInfo
get /user/info (UserInfoReq) returns (UserInfoResp)
}
如果只想对 /user/info 接口添加鉴权,而不影响 /user,可以定义两个路由组,并为其中一组绑定中间件:
@server (
prefix: /v1
middleware: AuthMiddleware // 该组内的所有路由都会经过此中间件
)
service User {
@handler UserInfo
get /user/info (UserInfoReq) returns (UserInfoResp)
}
@server (
prefix: /v1
)
service User {
@handler CreateUser
post /user (CreateUserReq) returns (CreateUserResp)
}
执行 goctl api go 后,会在路由注册文件中自动添加中间件引用。在 internal/handler/routes.go 中可看到类似代码:
func RegisterHandlers(server *rest.Server, serverCtx *svc.ServiceContext) {
server.AddRoutes(
rest.WithMiddlewares(
[]rest.Middleware{serverCtx.AuthMiddleware},
[]rest.Route{
{
Method: http.MethodGet,
Path: "/v1/user/info",
Handler: UserInfoHandler(serverCtx),
},
},
),
)
server.AddRoutes(
[]rest.Route{
{
Method: http.MethodPost,
Path: "/v1/user",
Handler: CreateUserHandler(serverCtx),
},
},
)
}
实现中间件
中间件本身是一个 func(http.HandlerFunc) http.HandlerFunc 类型。我们需要在 svc 中实现该函数并注入到 ServiceContext。
定义中间件文件 internal/middleware/authMiddleware.go:
package middleware
import "net/http"
type AuthMiddleware struct {
}
func NewAuthMiddleware() *AuthMiddleware {
return &AuthMiddleware{}
}
func (m *AuthMiddleware) Handle(next http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
token := r.Header.Get("Authorization")
// 实际项目中会解析 JWT 或调用认证服务
if token != "123456" {
http.Error(w, "permission denied", http.StatusForbidden)
return
}
next(w, r)
}
}
然后在 svc/serviceContext.go 中提供该中间件的实例:
type ServiceContext struct {
Config config.Config
UserModel model.UserModel
AuthMiddleware rest.Middleware
}
func NewServiceContext(c config.Config) *ServiceContext {
conn := sqlx.NewMysql(c.Mysql.DataSource)
return &ServiceContext{
Config: c,
UserModel: model.NewUserModel(conn, c.CacheRedis),
AuthMiddleware: middleware.NewAuthMiddleware().Handle,
}
}
需要注意的是,go-zero 的中间件注册期望的类型是 rest.Middleware(即 func(http.HandlerFunc) http.HandlerFunc),而我们提供的 Handle 方法正好符合该签名,因此可以直接赋值。
测试验证
重新启动 API 服务:
- 访问
POST /v1/user,无需携带认证头,能够正常调用。 - 访问
GET /v1/user/info:- 不带
Authorization头或值不是123456,返回403 permission denied。 - 头部正确时,正常返回业务数据。
- 不带
这样便实现了对不同路由组的差异化中间件控制。
总结
本文从零开始演示了 go-zero 框架中两个核心功能的实践流程:
- 数据库模型生成:利用
goctl model快速从 DDL 生成具备缓存能力的 CRUD 模型,并结合 RPC 服务完成数据的增删改查。 - 中间件集成:通过
.api文件的路由组定义,为部分接口绑定鉴权中间件,展示横切逻辑的优雅实现。
这些基础功能组合起来,能够帮助开发团队高效构建可维护的微服务系统。在后续的迭代中,还可以在此基础上加入更多 go-zero 的高级特性,如限流、熔断、链路追踪等。
2504



被折叠的 条评论
为什么被折叠?



