Sponge 脚手架快速创建后端API及接口使用完整教程

一、什么是 Sponge

Go-Sponge 是一款 Go 低代码后端脚手架，最大的优势是：只需提供 MySQL 数据表，全自动生成整套 CRUD 接口代码。包含路由、控制器、数据库操作、请求结构体、Swagger 文档，无需手动写任何增删改查代码，极大提升开发效率。

本文详细讲解：如何用 Sponge 创建项目、自动生成 API、以及每个自动生成接口的详细作用与调用方式。

二、Sponge 创建 API 流程（标准流程）

1. 启动可视化面板

终端执行命令开启网页可视化开发面板：

复制代码

sponge run

浏览器访问：http://localhost:24631

2. 基于数据库表生成完整 Web 项目

左侧选择：SQL → 创建 Web 服务

填写数据库 DSN 连接信息、获取数据表、勾选需要生成接口的表，填写项目名称、模块名称，点击下载代码。

Sponge 会一次性自动生成：

数据库 Model 模型
DAO 数据库操作层
Handler 接口控制器
请求/响应结构体
完整路由注册代码
自动 Swagger 接口文档

3. 项目启动（Mac 稳定方案）

Mac 不兼容自带 Makefile 脚本，放弃 make 命令，使用原生启动方式：

复制代码

go mod tidy
swag init -g cmd/test/main.go
go run cmd/test/main.go

启动成功后，服务默认运行在 8080 端口。

Swagger 接口文档地址：http://localhost:8080/swagger/index.html

三、Sponge 自动生成的所有 API 详解（可直接用于业务）

以数据表 test 为例，Sponge 自动生成9 个标准业务接口，覆盖后台所有常用场景。

基础请求前缀：http://localhost:8080/api/v1/test

1. 新增数据 POST /api/v1/test

作用：新增单条数据，最常用的添加接口。

调用方式：POST 提交 JSON 结构体参数，自动入库。

2. 根据ID查询 GET /api/v1/test/{id}

作用：查询单条详情，适用于详情页、编辑回显。

示例：/api/v1/test/1

3. 根据ID修改 PUT /api/v1/test/{id}

作用：更新单条数据，适用于后台编辑功能。

4. 根据ID删除 DELETE /api/v1/test/{id}

作用：删除单条数据，逻辑删除/物理删除由框架配置控制。

5. 条件分页列表 POST /api/v1/test/list

作用：后台核心接口，支持分页、模糊查询、条件筛选，适配所有列表页面。

5. 条件分页列表（支持标题模糊搜索）POST /api/v1/test/list

这是后台最核心、最常用 的分页列表接口，同时支持 分页 + 排序 + 多字段模糊搜索，日常后台表格列表、标题检索全部使用这个接口，无需写任何 SQL。

核心场景：根据 Title 标题模糊搜索 + 分页查询

请求方式 POST，通过 columns 数组配置查询规则，支持 like 模糊匹配、eq 精准匹配，下面是可直接复用的标准 curl 示例（以 article 标题搜索为例）：

复制代码

curl -X POST 'http://localhost:8080/api/v1/article/list' \
-H 'Content-Type: application/json' \
-d '{
  "page": 0,
  "limit": 10,
  "columns": [
    {
      "name": "title",
      "exp": "like",
      "value": "%测试%"
    }
  ]
}'

参数详细说明：

page：页码，从 0 开始
limit：每页条数
name：数据库字段名（如 title、name、content）
exp：查询表达式，like 模糊查询 /eq 精准查询
value：搜索关键词，模糊查询必须包裹 %关键词%

优势：前端表格搜索、分页、筛选全部适配，是项目对接最多的查询接口。

7. 批量ID查询 POST /api/v1/test/list/ids

作用：传入多个 ID，批量查询多条数据。

8. 批量删除 POST /api/v1/test/delete/ids

作用：批量删除勾选数据，后台表格批量删除必备接口。

9. 游标分页列表 GET /api/v1/test/list

作用：LastID 分页，适合大数据量滚动加载。

四、API 通用使用方法

1. 在线调试方式（推荐新手）

直接打开 Swagger 文档，无需 Postman，可在线：

查看所有接口参数说明
自动补全请求结构体
一键发送请求、查看返回结果

2. 前后端对接方式

前端只需按照固定前缀/api/v1/表名 即可完成所有 CRUD 对接，无需后端手写接口。

3. 新增自定义 API 方法

如果自动生成接口不满足业务，可手动开发自定义接口：

在 internal/types 定义请求、返回结构体
在 internal/handler 编写业务方法
在 routers 注册路由
重新执行swag init 刷新文档

五、总结

Sponge 彻底解放了 Go 后端重复性 CRUD 开发工作，只需依托数据表，即可全自动生成全套标准化 RESTful API，接口覆盖新增、删除、修改、单查、列表、批量操作、条件查询等所有后台常用场景。开发者只需专注复杂业务逻辑开发，非常适合快速迭代项目、中小型后台、管理系统开发。

（注：部分内容可能由 AI 生成）