跳至主要內容

基于 Protobuf 创建 gRPC+HTTP 服务开发指南

Vison2025/5/14大约 7 分钟开发指南gogingrpcprotobufgormmysqlmongodbpostgresqlsqlite

为什么选择 HTTP + gRPC 服务？

点击查看 为什么选择 HTTP + gRPC 服务？


概述

基于 protobuf 创建 gRPC+HTTP 服务为通用的 gRPC+HTTP 混合服务开发提供了一套完整的解决方案。该方案让开发者只需专注于业务逻辑的实现，而其他基础代码（如框架代码、接口定义等）均由 sponge 自动生成。值得一提的是，业务逻辑代码还可借助 sponge 内置的 AI 助手生成，进一步降低人工编码工作量。

提示

另一种 gRPC+HTTP 服务开发方案基于 sql 创建 gRPC+HTTP 服务(参见 基于 SQL)只使用内置 ORM 组件，而本方案支持使用内置 ORM 组件或自定义 ORM 组件，这是两种方案创建 gRPC+HTTP 混合服务的区别，其他都一样。

适用场景：适合同时支持 gRPC 和 http 协议的通用后端服务项目。


基于 protobuf 创建 gRPC+HTTP 服务 默认无 ORM 组件，支持使用内置 ORM 组件或自定义 ORM 组件进行开发，以下将以内置 ORM 组件 gorm 为例，详细介绍 gRPC+HTTP 服务的开发步骤。

提示

内置 ORM 组件：gorm、mongo，支持数据库类型 mysql、mongodb、postgresql、sqlite。

自定义 ORM 组件：例如 sqlx、xorm、ent 等。选用自定义 ORM 组件时，需要开发者自行实现相关代码，点击查看章节：使用自定义 ORM 组件说明。


前期准备

环境要求：

  • 已安装 sponge
  • mysql 数据库服务
  • 数据库表结构
  • proto 文件，例如 user.proto。

提示

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

  • 快速熟悉 Protobuf 基本语法规则，请查看 Protobuf 文档。


创建 gRPC+HTTP 服务

操作步骤

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

  1. 点击左边菜单栏【Protobuf】 → 【创建 gRPC+HTTP 服务】；
  2. 选择 proto 文件(可多选)；
  3. 接着填写其他参数，鼠标放在问号?位置可以查看参数说明。

提示

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

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

micro-grpc-http-pb
micro-grpc-http-pb

等价命令

sponge micro grpc-http-pb --module-name=user --server-name=user --project-name=edusys --protobuf-file=./user.proto

提示

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

  • 系统会自动保存成功生成的代码记录，方便下一次生成代码使用，刷新或重新打开页面时显示上一次部分参数。


目录结构

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

.
├─ api                          # API 协议定义目录(proto/OpenAPI 等)
│   └─ user                     # 服务名称(user 服务)
│       └─ v1                   # API 版本 v1(存放 proto 文件和生成的 pb.go 等)
├─ cmd                          # 应用程序入口目录
│   └─ user                     # 服务名称(user 服务)
│       ├─ initial              # 初始化逻辑(如配置加载、服务初始化等)
│       └─ main.go              # 主程序入口文件
├─ configs                      # 配置文件目录(yaml 格式配置模板)
├─ deployments                  # 部署相关文件
│   ├─ binary                   # 二进制部署脚本/配置
│   ├─ docker-compose           # Docker Compose 编排文件
│   └─ kubernetes               # Kubernetes 部署清单
├─ docs                         # 项目文档(API 文档、设计文档等)
├─ internal                     # 内部实现代码(对外不可见)
│   ├─ config                   # 配置解析和结构体定义
│   ├─ ecode                    # 错误码定义
│   ├─ handler                  # 业务逻辑处理层(类似 Controller)
│   ├─ routers                  # 路由定义和中间件
│   ├─ server                   # 服务启动和生命周期管理
│   └─ service                  # 业务逻辑处理层
├─ scripts                      # 实用脚本(如代码生成、构建、运行、部署等)
├─ third_party                  # 第三方 Protobuf 依赖/工具
├─ go.mod                       # Go 模块定义文件(声明依赖)
├─ go.sum                       # Go 模块校验文件(自动生成)
├─ Makefile                     # 项目构建自动化脚本
└─ README.md                    # 项目说明文档

代码调用链路说明:

  1. gRPC 主要调用链路：
    cmd/user/main.go → internal/server/grpc.go → internal/service → internal/dao → internal/model

  2. http 主要调用链路：
    cmd/user/main.go → internal/server/http.go → internal/routers/router.go → internal/handler → internal/service → internal/dao → internal/model

从调用链路上可以看出，http 调用链路与 gRPC 调用链路共用业务逻辑层 service，不需要写两套代码与协议转换。

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


代码结构示意图

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

micro-grpc-http-pb-anatomy
micro-grpc-http-pb-anatomy

测试 gRPC+HTTP 服务 API

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

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

# 打开生成的代码文件(例如 internal/service/user.go)
# 填充业务逻辑代码，支持人工编写或使用内置 AI 助手生成

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

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

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

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

  3. 安全机制

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

测试 gRPC API

  • 测试方式一：使用 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"

测试 HTTP API

在浏览器访问 http://localhost:8080/apis/swagger/index.html，测试 http api。


添加 CRUD API

点击查看章节：添加 CRUD API。


开发自定义 API

点击查看章节：开发自定义 API。


跨服务 gRPC API 调用

点击查看章节：跨服务 gRPC API 调用。


服务配置说明

点击查看章节：服务配置说明。


Copyright © 2025 Vison