跳到主要内容
版本：2.10.x(Latest)

用户 gRPC 服务实践

Github Source: https://github.com/gogf/examples/tree/main/practices/user-grpc-service

介绍​

本示例展示了一个完整的基于gRPC和GoFrame框架构建的用户微服务。该示例包含：

  • 用户的完整CRUD操作（创建、查询、列表、删除）
  • 基于Protocol Buffers的gRPC服务实现
  • MySQL数据库集成与DAO模式数据访问
  • Service层业务逻辑封装
  • 从数据库Schema自动生成代码
  • 生产级项目结构组织

目录结构​

.
├── api/                   # API 定义
│   ├── pbentity/          # 自动生成的protobuf实体(自动生成)
│   └── user/              # 用户服务 API
│       └── v1/            # API版本v1(自动生成)
├── hack/                  # 开发工具
│   └── config.yaml        # CLI 工具配置
├── internal/              # 内部包
│   ├── cmd/               # 命令定义
│   ├── consts/            # 常量
│   ├── controller/        # gRPC 控制器
│   │   └── user/          # 用户控制器
│   ├── dao/               # 数据访问对象(自动生成)
│   ├── model/             # 数据模型
│   │   ├── do/            # 领域对象(自动生成)
│   │   └── entity/        # 数据库实体(自动生成)
│   └── service/           # 业务逻辑
│       └── user/          # 用户服务
├── manifest/              # 部署清单
│   ├── config/            # 配置文件
│   │   └── config.yaml    # 应用配置
│   ├── deploy/            # 部署文件
│   ├── docker/            # Docker 文件
│   ├── protobuf/          # Protocol Buffer 定义
│   │   ├── pbentity/      # 实体定义(自动生成)
│   │   └── user/          # 用户服务定义
│   └── sql/               # SQL 脚本
│       └── create.sql     # 数据库表结构
├── main.go                # 应用入口
├── go.mod                 # Go 模块文件
└── Makefile               # 构建自动化

功能特性​

本示例展示了以下功能特性：

服务实现​

  • 基于Protocol Buffers的gRPC服务器
  • 用户CRUD操作（Create、GetOne、GetList、Delete）
  • 请求参数验证
  • 错误处理
  • 上下文管理

数据库集成​

  • MySQL数据库连接
  • DAO模式数据访问
  • 自动生成DAO、DO和Entity代码
  • 事务支持
  • 查询构建器

项目组织​

  • 标准GoFrame项目结构
  • 关注点分离（Controller、Service、DAO）
  • 配置管理
  • 日志支持
  • Makefile构建自动化

环境要求​

前置准备​

安装GoFrame CLI工具​

go install github.com/gogf/gf/cmd/gf/v2@latest

或者使用 Makefile：

make cli

配置 MySQL 数据库​

使用Docker运行MySQL数据库：

docker run -d \
  --name mysql-user-service \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=12345678 \
  -e MYSQL_DATABASE=test \
  mysql:8.0

初始化数据库​

执行SQL脚本创建用户表：

# 连接到 MySQL
docker exec -i mysql-user-service mysql -uroot -p12345678 test < manifest/sql/create.sql

或者手动执行以下SQL：

CREATE TABLE `user` (
    `id` int unsigned NOT NULL AUTO_INCREMENT COMMENT 'User ID',
    `passport` varchar(45) NOT NULL COMMENT 'User Passport',
    `password` varchar(45) NOT NULL COMMENT 'User Password',
    `nickname` varchar(45) NOT NULL COMMENT 'User Nickname',
    `create_at` datetime DEFAULT NULL COMMENT 'Created Time',
    `update_at` datetime DEFAULT NULL COMMENT 'Updated Time',
    `delete_at` datetime DEFAULT NULL COMMENT 'Deleted Time',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uniq_passport` (`passport`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

配置说明​

在manifest/config/config.yaml中更新数据库配置：

database:
  default:
    link: "mysql:root:12345678@tcp(127.0.0.1:3306)/test"
    debug: true

使用说明​

生成代码​

从数据库生成DAO、DO和Entity代码：

make dao

生成Protocol Buffer Go文件：

make pb

从数据库生成Protocol Buffer实体文件：

make pbentity

运行服务器​

启动gRPC服务器：

go run main.go

服务器将在端口8000上启动。

测试服务​

可以使用gRPC客户端测试服务。以下是使用grpcurl的示例：

  1. 安装 grpcurl：

    brew install grpcurl

  2. 列出可用的服务：

    grpcurl -plaintext localhost:8000 list

  3. 创建用户：

    grpcurl -plaintext -d '{"Passport":"user001","Password":"123456","Nickname":"测试用户"}' \
      localhost:8000 user.User/Create

  4. 根据 ID 查询用户：

    grpcurl -plaintext -d '{"Id":1}' \
      localhost:8000 user.User/GetOne

  5. 获取用户列表：

    grpcurl -plaintext -d '{"Page":1,"Size":10}' \
      localhost:8000 user.User/GetList

  6. 删除用户：

    grpcurl -plaintext -d '{"Id":1}' \
      localhost:8000 user.User/Delete

接口文档​

用户服务​

Create​

创建新用户。

请求：

message CreateReq {
    string Passport = 1; // 必填
    string Password = 2; // 必填
    string Nickname = 3; // 必填
}

响应：

message CreateRes {}

GetOne​

根据ID获取用户详情。

请求：

message GetOneReq {
    uint64 Id = 1; // 必填
}

响应：

message GetOneRes {
    pbentity.User User = 1;
}

GetList​

获取分页用户列表。

请求：

message GetListReq {
    int32 Page = 1;
    int32 Size = 2;
}

响应：

message GetListRes {
    repeated pbentity.User Users = 1;
}

Delete​

根据ID删除用户。

请求：

message DeleteReq {
    uint64 Id = 1; // 必填，最小值：1
}

响应：

message DeleteRes {}

实现细节​

Controller 层​

internal/controller/user/user.go实现了gRPC服务接口：

  • 处理传入的gRPC请求
  • 验证请求参数
  • 调用Service层处理业务逻辑
  • 返回格式化的响应

Service 层​

internal/service/user/user.go包含业务逻辑：

  • 根据ID查询用户
  • 删除用户
  • 可扩展更复杂的业务规则

DAO 层​

internal/dao/user.go提供数据库访问：

  • 从数据库Schema自动生成
  • 提供类型安全的数据库操作
  • 支持链式查询构建器

数据模型​

  • DO (Domain Object)： 用于数据库操作
  • Entity： 表示数据库表结构
  • PBEntity： 用于API响应的Protocol Buffer实体

开发指南​

生成所有代码​

# 生成 DAO 文件
make dao

# 生成 Service 文件
make service

# 生成 Protocol Buffer 文件
make pb

# 生成 Protocol Buffer Entity 文件
make pbentity

构建 Docker 镜像​

make image

部署到 Kubernetes​

make deploy

注意事项​

  • 启动应用前请确保MySQL已运行
  • 默认数据库凭据为root:12345678（生产环境请修改）
  • 服务默认使用端口8000
  • Protocol Buffer文件位于manifest/protobuf
  • SQL Schema位于manifest/sql/create.sql