跳至主要內容

基于 Protobuf 创建 web 服务开发指南

Vison2025/5/14大约 10 分钟开发指南gowebginprotobufmysqlmongodb

概述

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

注

另一种 web 开发方案基于 sql 创建 web 服务（参见基于 SQL）不同，本方案支持通过 protobuf 自动生成自定义 API 代码，同时支持内置 ORM 和自定义 ORM 组件，这是两者的核心差异。从功能范围来看，基于 sql 创建 web 服务可视为基于 protobuf 创建 web 服务的功能子集。

适用场景：通用型 web 后端服务项目开发，特别是需要灵活定义 API 接口的复杂业务场景。


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

提示

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

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


前期准备

环境要求：

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

注

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


创建 Web 服务

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

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

提示

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

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

web-http-pb
web-http-pb

等价命令

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

提示

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

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


目录结构

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

.
├─ api
│   └─ user
│       └─ v1
├─ cmd
│   └─ user
│       ├─ initial
│       └─ main.go
├─ configs
├─ deployments
│   ├─ binary
│   ├─ docker-compose
│   └─ kubernetes
├─ docs
├─ internal
│   ├─ config
│   ├─ ecode
│   ├─ handler
│   ├─ routers
│   └─ server
├─ scripts
└─ third_party

代码结构示意图

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

web-http-pb-anatomy
web-http-pb-anatomy

代码调用链路说明

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

cmd/user/main.go → internal/server/http.go → internal/routers/router.go → internal/handler → internal/dao → internal/model

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


测试 Web 服务 API

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

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

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

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

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

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

  3. 安全机制

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

在浏览器打开 http://localhost:8080/apis/swagger/index.html，可以在页面上查看 API 文档，如下图所示：

注意

在未实现业务逻辑前，Swagger 请求将返回500错误。这是因为生成的模板代码（internal/handler/xxx.go）中每个方法都包含panic("implement me")代码，提示开发者自行实现或内置的 AI 助手生具体业务逻辑。

web-http-swagger
web-http-swagger
Swagger 配置说明

如果您在configs/服务名称.yml配置文件中修改了 HTTP 端口（例如从8080改为9090），必须同步完成以下操作：

  1. 修改代码文件cmd/服务名/main.go中的@host值为新端口（如 localhost:9090）
  2. 重新执行make docs生成文档

否则会因端口不一致导致 API 请求失败。


添加 CRUD API

项目中常常需要标准化的 CRUD API，sponge 生成的 CRUD API 可以无缝添加到 web 服务代码中，无需编写任何 go 代码。

生成 Handler CRUD 代码

  1. 点击左边菜单栏【Public】→【生成 handler CRUD 代码】；
  2. 选择数据库mysql，填写数据库 dsn，然后点击按钮获取表名，选择 mysql 表(可多选)；
  3. 开启protobuf 类型;
  4. 填写module 名称、服务名称等参数。

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

web-http-handler-pb
web-http-handler-pb

等价命令

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

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

代码目录结构

生成的 CRUD handler 代码目录如下：

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

测试 CRUD API

在启动服务之前进行简单的配置(只需一次)

  • 修改configs/服务名称.yml中的 MySQL 地址
  • 取消cmd/服务名称/initial/initApp.go中 MySQL 和 cache 的初始化代码注释
  • 取消registerClose.go中相关资源的释放代码注释

解压代码，把目录internal和api移动到 web 服务代码目录下，在终端执行命令：

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

# 编译和运行服务
make run

注

如遇make proto错误，请查看 常见问题解答 章节。

刷新 Swagger 页面 http://localhost:8080/apis/swagger/index.html，即可查看和测试新增的 CRUD API。

提示

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


开发自定义 API

随着业务需求增长，开发者可能需要添加新的自定义 API。sponge 采用"定义即生成"的开发模式，可快速实现自定义 API 开发，主要分为以下三个步骤：

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

  2. 实现逻辑
    在自动生成的代码模板中填充核心业务逻辑代码

  3. 测试验证
    在内置的 Swagger 测试 API，无需依赖 Postman 等第三方工具

以下以添加"修改密码"API 为例，详细说明开发流程。


1. 定义 API

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

import "validate/validate.proto";
import "tagger/tagger.proto";

service user {
  // ...

  // 修改密码，在这里描述实现具体实现逻辑，告诉 sponge 内置的 AI 助手生成的业务逻辑代码
  rpc ChangePassword(ChangePasswordRequest) returns (ChangePasswordReply) {
    option (google.api.http) = {
      post: "/api/v1/user/change_password"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "修改密码",
    };
  }
}

message ChangePasswordRequest {
  uint64 id = 1 [(validate.rules).uint64.gte  = 1, (tagger.tags) = "uri:\"id\"" ];
  string password = 2 [(validate.rules).string.min_len = 6];
}

message ChangePasswordReply {
}

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

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

2. 实现业务逻辑

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

  • 人工编写业务逻辑代码

    打开代码文件internal/handler/user.go，在 ChangePassword 方法函数下参考模板代码编写业务逻辑代码。

    注

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

  • 自动生成业务逻辑代码

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

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


3. 测试自定义 API

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

# 编译和运行服务
make run

在浏览器刷新 Swagger 界面 http://localhost:8080/apis/swagger/index.html，在页面上进行测试自定义 API。


服务配置说明

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

组件管理说明

自定义 gin 中间件：

  • 可在internal/routers/routers.go中添加、替换中间件。
  • 如需 API 鉴权，在internal/routers/表名.go中添加middleware.Auth()。

默认启用的组件

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

默认关闭的组件

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

配置更新流程

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

# 重新生成配置代码
make config

注

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

提示

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


Copyright © 2025 Vison