跳至主要內容

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

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

概述

基于 sql 创建 web 服务提供了一套从开发到部署的完整 web 后端服务解决方案。该方案的核心特点是：开发者只需连接数据库，即可自动生成标准化的 CRUD API 接口，无需编写任何 Go 语言代码，实现了 web 服务的"低代码开发"。然而，当需要添加自定义 API 时，则需采用传统开发方式，人工编写完整的 API 相关代码（包括定义请求/响应数据结构、注册路由、编写控制器、业务逻辑代码等）。

提示

另一种 web 开发方案基于 protobuf 创建 web 服务(参见 基于 Protobuf)弥补了这一不足，它支持自动生成自定义 API 代码，仅需手动编写或 AI 助手生成业务逻辑代码，为开发者提供了更高效的自定义 API 开发体验。

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


前期准备

注

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

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

环境要求：

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

注

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


创建 Web 服务

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

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

提示

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

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

web-http
web-http

等价命令

sponge web http --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

提示

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

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


目录结构

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

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

代码调用链路说明

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 服务代码目录，执行命令：

# 生成 swagger 文档
make docs

# 编译和运行服务
make run

提示

  • 每当添加新 API或修改现有 API的注解时，都需要重新执行make docs命令来更新 Swagger 文档
  • 如果 API 没有变化，则无需重复执行该命令

在浏览器打开 http://localhost:8080/swagger/index.html，可以在页面上测试 CRUD API，如下图所示：

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

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

生成 Handler CRUD 代码

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

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

web-http-handler
web-http-handler

等价命令

# 完整命令
sponge web handler --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

代码目录结构

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

.
└─ internal
    ├─ cache
    ├─ dao
    ├─ ecode
    ├─ handler
    ├─ model
    ├─ routers
    └─ types

测试 CRUD API

解压生成的代码包，将整个internal目录移动到 web 服务代码根目录，执行以下命令：

# 生成 swagger 文档
make docs

# 编译和运行服务
make run

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

提示

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


开发自定义 API

基于 sql 创建 web 服务方案目前不支持自动生成自定义 API 模板代码，开发者可以按下面步骤开发：

  1. 定义请求/响应数据结构，设置字段校验规则
  2. 定义 Handler 函数，添加 Swagger 注解
  3. 定义业务错误码(可选)
  4. 注册 API 路由
  5. 实现业务逻辑
  6. 测试验证

1. 定义数据结构

进入目录internal/types，打开文件teacher_types.go，添加登录的请求和返回结构体代码：

// LoginRequest login request params
type LoginRequest struct {
    Email      string `json:"email" binding:"email"`      // 邮件
    Password   string `json:"password" binding:"min=6"`   // 密码
}

// LoginReply login reply result
type LoginReply []struct {
    ID       uint64 `json:"id"`
    Token    string `json:"token"`
}

注

结构体字段 tag 中 bingding 是字段校验规则，点击查看更多validator 校验规则。


2. 定义 Handler 函数

进入目录internal/handler，打开文件teacher.go，定义一个登录方法，并添加 swagger 注解：

// Login 登录
// @Summary login
// @Description login by account and password
// @Tags teacher
// @accept json
// @Produce json
// @Param data body types.CreateLoginRequest true "login information"
// @Success 200 {object} types.Result{}
// @Router /api/v1/teacher/login [post]
func (h *teacherHandler) Login(c *gin.Context) {
    // 解析请求参数
    // 验证密码
    // 生成和存储 token

    response.Success(c, gin.H{
        "id": 1,
        "token": "xxxxxx",
    })
}

然后把 Login 方法添加到 TeacherHandler 接口：

type TeacherHandler interface {
    Create(c *gin.Context)
    // ...
    Login(c *gin.Context)
}

3. 定义错误码（可选）

进入目录internal/ecode，打开文件teacher_http.go，添加一行代码，定义登录错误码：

var (
    // ...
    ErrLoginTeacher        = errcode.NewError(teacherBaseCode+8, "failed to login "+teacherName)
    // for each error code added, add +1 to the previous error code
)

4. 注册路由

打开文件internal/routers/teacher.go，注册 Login 路由：

func teacherRouter(group *gin.RouterGroup, h handler.TeacherHandler) {
    // ...

    group.POST("/teacher/login", h.Login)
}

5. 实现业务逻辑

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

  • 人工编写业务逻辑代码

    打开代码文件internal/handler/user.go，编写登录的业务逻辑代码，例如验证密码、生成 token 等。

    注

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

  • 自动生成业务逻辑代码

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

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


6. 测试自定义 API

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

# 生成 swagger 文档
make docs

# 编译和运行服务
make run

在浏览器刷新 Swagger 界面 http://localhost:8080/swagger/index.html，然后测试自定义 API。


可以看到，添加自定义 API 相比添加标准化的 CRUD API（自动生成）要麻烦很多，因为自定义 API 的所有相关代码都需要手动编写。因此，基于 SQL 创建 Web 服务 的方式更适合大多数 API 都是标准化 CRUD 的 Web 项目。
如果项目中包含较多自定义 API，建议采用 基于 Protobuf 创建 Web 服务 的方式进行开发，但这需要开发者熟悉 Protobuf 规则。


服务配置说明

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

组件管理说明

自定义 gin 中间件：

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

默认启用的组件

组件功能说明配置文档
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