跳至主要內容

基于 SQL 创建 gRPC 服务开发指南

Vison2025/5/14大约 13 分钟开发指南gogRPCgormmysqlmongodbpostgresqlsqlite

概述

基于 sql 创建 gRPC 服务提供了一套从开发到部署的完整 gRPC 后端服务解决方案。该方案的核心特点是：开发者只需连接数据库，即可自动生成标准化的 CRUD API 接口，无需编写任何 Go 语言代码，实现了 gRPC 服务的"低代码开发"。

提示

另一种 gRPC 服务开发方案基于 protobuf 创建 gRPC 服务(参见 基于 Protobuf)可以选择使用内置 ORM 组件或自定义 ORM 组件，而本方案只使用内置 ORM 组件，这是两种方案的最大的区别。

适用场景： 适合以标准化 CRUD API 为主的 gRPC 服务项目开发。


前期准备

注

sponge 支持数据库类型 mysql、mongodb、postgresql、sqlite

下面操作以 mysql 为例介绍 gRPC 服务开发步骤，选用其他几种数据库类型的开发步骤一样。

环境要求：

  • 已安装 sponge
  • mysql 数据库服务
  • 数据库表结构

注

生成代码需要依赖 mysql 服务和数据库表，你可以通过 docker 脚本启动 mysql 服务，然后导入 示例 SQL。


创建 gRPC 服务

在终端执行命令sponge run进入生成代码 UI 界面：

  1. 点击左边菜单栏【SQL】→【创建 gRPC 服务】；
  2. 选择数据库mysql，填写数据库 dsn，然后点击按钮获取表名，选择表名(可多选)；
  3. 填写其他参数，鼠标放在问号?位置可以查看参数说明；

提示

如果填写参数启用了大仓库类型选项，后续所有相关代码生成都需保持此设置。

填写完参数后，点击按钮下载代码生成 gRPC 服务完整项目代码，如下图所示：

micro-rpc
micro-rpc

等价命令

sponge micro rpc --module-name=user --server-name=user --project-name=edusys --db-driver=mysql --db-dsn="root:123456@(192.168.3.37:3306)/school" --db-table=teacher

提示

  • 生成的 gRPC 服务代码目录默认命名为服务名称-类型-时间格式，您可根据实际需要自行修改该目录名称。

  • 系统会自动保存成功生成的代码记录。当您再次生成代码时，若数据库 DSN保持不变，页面刷新或重新打开后将自动加载可用表名列表，无需手动点击获取表名按钮即可直接选择表名。


目录结构

.
├─ api
│   ├─ types
│   └─ user
│       └─ v1
├─ cmd
│   └─ user
│       ├─ initial
│       └─ main.go
├─ configs
├─ deployments
│   ├─ binary
│   ├─ docker-compose
│   └─ kubernetes
├─ docs
├─ internal
│   ├─ cache
│   ├─ config
│   ├─ dao
│   ├─ ecode
│   ├─ model
│   ├─ server
│   └─ service
├─ scripts
└─ third_party

代码结构示意图

创建的 gRPC 服务代码采用经典的"鸡蛋模型"架构：

micro-rpc-pb-anatomy
micro-rpc-pb-anatomy

代码调用链路说明

sponge 生成的 gRPC 服务代码采用分层架构，完整调用链路如下：

cmd/user/main.go → internal/server/grpc.go → internal/service → internal/dao → internal/model

其中 service 层主要负责 API 处理，若需处理更复杂业务逻辑，建议在 service 和 dao 之间额外添加业务逻辑层（如internal/biz）。详情请点击查看 代码分层架构章节。


测试 gRPC 服务 API

解压代码文件，打开终端，切换到 gRPC 服务代码目录，执行命令：

# 生成与合并 api 相关代码
make proto

# 编译和运行服务
make run
make proto命令详解

  1. 使用建议
    仅当 proto 文件中 API 描述发生变更时才需执行该命令，否则跳过该命令，直接运行make run命令。

  2. 该命令会后台执行以下自动化操作

    • 生成*.pb.go文件
    • 生成错误码定义
    • 生成 gRPC 客户端测试代码
    • 生成 API 模板代码
    • 自动合并 API 模板代码

  3. 安全机制

  • 代码合并时会保留原有业务逻辑
  • 每次合并前会自动备份代码至：
    • Linux/Mac: /tmp/sponge_merge_backup_code
    • Windows: C:\Users\[用户名]\AppData\Local\Temp\sponge_merge_backup_code

测试方法一：IDE (推荐)

  1. 打开项目

    • 使用 Goland 或 VSCode 等 IDE 加载项目。

  2. 执行测试

    • 进入目录 internal/service，打开后缀为 _client_test.go 的文件。
    • 文件包含 proto 定义的每个 API 的测试和压测函数。
    • 修改请求参数（类似 Swagger 界面测试）
    • 通过 IDE 运行测试，如下图所示：
    micro-rpc-test
    micro-rpc-test

测试方式二：命令行

  1. 进入目录

    cd internal/service

  2. 修改参数

    • 打开 xxx_client_test.go 文件
    • 填写 gRPC API 的请求参数

  3. 执行测试

    go test -run "测试函数名/gRPC 方法名"

    示例：

    go test -run "Test_service_teacher_methods/GetByID"

添加 CRUD API

如果有新的 mysql 表需要生成 CRUD API 代码，sponge 生成的 CRUD API 可以无缝添加到 gRPC 服务代码中，无需编写任何 go 代码。

生成 service CRUD 代码

  1. 点击左边菜单栏【Public】→【生成 service CRUD 代码】；
  2. 选择数据库mysql，填写数据库 dsn，然后点击按钮获取表名，选择 mysql 表(可多选)；
  3. 填写其他参数。

填写完参数后，点击按钮下载代码生成 service CRUD 代码，如下图所示：

micro-rpc-service
micro-rpc-service

等价命令

# 完整命令
sponge micro service --module-name=user --db-driver=mysql --db-dsn="root:123456@(192.168.3.37:3306)/school" --db-table=course,teach

# 简化命令（使用 --out 指定服务代码目录，生成代码自动合并到指定服务目录）
sponge micro service --db-driver=mysql --db-dsn="root:123456@(192.168.3.37:3306)/school" --db-table=course,teach --out=user

代码目录结构

生成 service CRUD 代码的目录结构如下：

.
├─ api
│   └─ user
│       └─ v1
└─ internal
     ├─ cache
     ├─ dao
     ├─ ecode
     ├─ model
     └─ service

测试 CRUD API

解压代码，把目录internal和api移动到 gRPC 服务代码目录下，执行以下命令：

# 生成与合并 api 相关代码
make proto

# 编译和运行服务
make run

测试 CRUD API，请查看上面章节：测试 gRPC 服务 API。

提示

CRUD API 中的 List 接口支持强大的自定义条件分页查询功能，点击查看详细使用规则：自定义条件分页查询。


开发自定义 API

项目中通常不止有标准化的 CRUD api，还有自定义的 api，sponge 采用"定义即生成"的开发模式，可快速实现自定义 API 开发，主要分为以下三个步骤：

  1. 定义 API
    在 .proto 文件中声明 API 的请求/响应结构

  2. 编写业务逻辑

    • 在生成的代码模板中填充核心业务逻辑代码
    • 无需手动编写完整 gRPC 服务端/客户端代码

  3. 测试验证

    • 测试代码自动生成，可直接运行
    • 无需依赖 Postman 等第三方 gRPC 客户端工具

以下以添加"登录"API 为例，详细说明开发流程。


1. 定义 API

进入项目目录api/user/v1目录，编辑teacher.proto文件，添加登录 API 的描述信息：

service teacher {
  // ...

  // 登录，在这里描述实现具体实现逻辑，告诉 sponge 内置的 AI 助手生成的业务逻辑代码
  rpc Login(LoginRequest) returns (LoginReply) {}
}

message LoginRequest {
  string email = 1 [(validate.rules).string.email = true];
  string password = 2 [(validate.rules).string.min_len = 6];
}

message LoginReply {
  uint64 id = 1;
  string token = 2;
}

添加 api 描述信息后，在终端执行命令：

# 生成与合并 api 相关代码
make proto

2. 实现业务逻辑

实现业务逻辑代码有两种方式：

  • 人工编写业务逻辑代码

    打开代码文件internal/service/teacher.go，在 Login 方法函数里填充具体的业务逻辑代码。

    注

    在开发自定义 API 中，可能需要对数据库增删改查或缓存操作，可复用以下代码：

  • 自动生成业务逻辑代码

    sponge 提供了内置 AI 助手生成业务逻辑代码，点击查看 AI 助手生成代码章节。

    AI 助手生成的业务逻辑代码可能不完全符合实际需求，需要根据实际情况进行修改。


3. 测试自定义 API

实现业务逻辑代码后，在终端执行命令：

# 编译和运行服务
make run

测试自定义 API，请查看上面章节：测试 gRPC 服务 API。


跨服务 gRPC API 调用

在微服务架构中，当前服务可能需要调用其他 gRPC 服务提供的 API。这些目标服务可能采用不同语言实现，但都需使用 Protocol Buffers 协议。以下是完整的调用流程说明：

生成 gRPC 服务连接代码

操作步骤：

  1. 访问 sponge UI 界面
  2. 导航至【Public】→【生成 gRPC 服务连接代码】
  3. 填写参数：
    • Module 名称（必填）
    • gRPC 服务名称（支持多个服务，用逗号分隔）

点击按钮【下载代码】生成 gRPC 服务连接代码，如下图所示：

micro-rpc-conn
micro-rpc-conn

等价命令

# 完整命令
sponge micro rpc-conn --module-name=user --rpc-server-name=community

# 简化命令（使用 --out 指定服务代码目录，生成代码自动合并到指定服务目录）
sponge micro rpc-conn --rpc-server-name=community --out=edusys

生成代码结构：

.
└─ internal
    └─ rpcclient  # 包含服务发现、负载均衡等完整客户端配置

解压代码，把目录internal移动到本服务代码目录下。

在代码中使用生成的 gRPC 连接代码示例：

实际使用中有可能需要从多个 gRPC 服务中调用 API 获取数据，初始化示例代码如下：

package service

import (
    userV1 "edusys/api/user/v1"
    relationV1 "edusys/api/relation/v1"
    creationV1 "edusys/api/creation/v1"
    // ......
)

type user struct {
    userV1.UnimplementedTeacherServer

    relationCli relationV1.RelationClient
    creationCli creationV1.CreationClient
}

// NewUserClient create a client
func NewUserServer() edusysV1.UserLogicer {
    return &user{
        // 实例化多个 gRPC 服务 client 接口
        relationCli: userV1.NewRelationClient(rpcclient.GetRelationRPCConn()),
        creationCli: userV1.NewCreationClient(rpcclient.GetCreationRPCConn()),
    }
}

// ......

配置目标 gRCP 服务连接参数

在配置文件 configs/服务名称.yml 中添加以下配置：

grpcClient:
  - name: "user"        # grpc 服务名称
    host: "127.0.0.1"   # grpc 服务地址，如果开启服务发现，此字段值无效
    port: 8282          # grpc 服务端口，如果开启服务发现，此字段值无效
    registryDiscoveryType: ""  # 服务发现，默认关闭，支持 consul, etcd, nacos

多服务配置示例：

grpcClient:
  - name: "user"
    host: "127.0.0.1"
    port: 18282
    registryDiscoveryType: ""
  - name: "relation"
    host: "127.0.0.1"
    port: 28282
    registryDiscoveryType: ""
  - name: "creation"
    host: "127.0.0.1"
    port: 38282
    registryDiscoveryType: ""

提示

完整配置选项可参考配置文件configs/[服务名称].yml的 grpcClient 字段说明。


调用目标 gRPC 服务的 API

成功连接到目标 gRPC 服务后，为了明确可调用的 API 接口，需要引入由 proto 文件生成的 Go 语言桩代码。根据服务架构的不同，调用方式主要分为以下两种情况：

  • 单仓库（Mono-repo）架构
    如果目标 gRPC 服务由 sponge 创建，并且与本服务同属一个微服务单仓库（创建服务时选择"大仓库"类型），则可以直接调用其 API，不存在跨服务依赖问题。

  • 多仓库（Multi-repo）架构
    如果目标 gRPC 服务位于独立的代码仓库，则需要解决跨服务引用 proto 文件和 Go 桩代码的问题。以下是两种常用解决方案：

    方案一：使用公共 Protobuf 仓库

    对于多仓库架构的微服务系统，建议创建专门的公共 Git 仓库（如 public_protobuf）集中管理 proto 文件及其生成的 Go 桩代码。典型目录结构如下：

    ·
├── api
│    ├── serverName1
│    │   └── v1
│    │       ├── serverName1.pb.go
│    │       └── serverName1_grpc.pb.go
│    └── serverName2
│        └── v1
│            ├── serverName2.pb.go
│            └── serverName2_grpc.pb.go
├── protobuf
│    ├── serverName1 
│    │   └── serverName1.proto
│    └── serverName2
│        └── serverName2.proto
├── go.mod
└── go.sum

    调用步骤：

    1. 将公共仓库中的 protobuf 目录复制到本地服务的 third_party 目录

      .
├── third_party
│    └── protobuf
│        ├── serviceA 
│        │   └── serviceA.proto
│        └── serviceB
│            └── serviceB.proto

    2. 在本地 proto 文件中通过 import 引入目标 proto（如 import "protobuf/serviceA/serviceA.proto";）

    3. 在本地服务的 service 中调用目标 gRPC 服务的 API。

    注

    需确保 third_party/protobuf 下的 proto 文件与公共仓库保持同步。


    方案二：将目标服务的 proto 文件复制到本服务中，并生成 Go 语言桩代码

    根据目标服务的创建方式，采用不同处理流程：

    1. 非 sponge 创建的服务

      • 手动将目标服务的 proto 文件复制到 api/目标服务名/v1 目录
      • 需人工修改 proto 文件中的 go_package 路径定义

    2. sponge 创建的服务

      通过自动化命令完成集成：

      # 复制目标服务的 proto 文件（支持多服务目录，用逗号分隔）
make copy-proto SERVER=../target_service_dir

# 生成 Go 桩代码
make proto

      高级选项：

      • 指定 proto 文件：PROTO_FILE=file1,file2
      • 自动备份：被覆盖的文件可在 /tmp/sponge_copy_backup_proto_files 找回

测试跨服务调用 gRPC API

  1. 启动依赖服务：

    • sponge 创建的 gRPC 服务：执行 make run
    • 其他 gRPC 服务：按实际启动命令运行

  2. 启动本服务，执行命令：

    # 生成与合并 api 相关代码
make proto

# 编译和运行服务
make run

测试跨服务 gRPC API，请查看上面章节：测试 gRPC 服务 API。


服务配置说明

sponge 创建的 gRPC 服务提供了丰富的可配置组件，您可以通过修改configs/服务名称.yml配置文件来灵活管理这些组件。

组件管理说明

可在internal/server/grpc.go中添加、替换自定义 gRPC 拦截器。


默认启用的组件

组件功能说明配置文档
logger日志组件
• 默认终端输出
• 支持 console/json 格式
• 支持日志文件分割和保留		日志配置
enableMetricsPrometheus 指标采集
• 默认路由/metrics		监控配置
enableStat资源监控
• 每分钟记录 CPU/内存使用率
• 超过阈值自动保存 profile		资源统计
database数据库支持
• MySQL/MongoDB/PostgreSQL/SQLite		gorm 配置
mongodb 配置

默认关闭的组件

组件功能说明配置文档
cacheType缓存支持(Redis/内存)redis 配置
enableHTTPProfile性能分析(pprof)
• 默认路由/debug/pprof/		-
enableLimit自适应请求限流限流配置
enableCircuitBreaker服务熔断保护熔断配置
enableTrace分布式链路追踪链路追踪配置
registryDiscoveryType服务注册与发现
• Consul/Etcd/Nacos		服务注册与发现配置

配置更新流程

如果添加或更改配置文件configs/服务名称.yml字段名，需要更新对应的 Go 代码，在终端执行命令：

# 重新生成配置代码
make config

注

如果只修改配置文件的字段值，不需要执行make config命令，只需重新编译运行即可。

提示

如需了解更多组件与配置的详细信息，点击查看 组件与配置章节。


Copyright © 2025 Vison