zishuo/sponge
1
0
Fork 0
mirror of https://github.com/zhufuyi/sponge.git synced 2025-09-26 20:51:14 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README

Browse Source
This commit is contained in:
zhuyasen
2025-05-18 23:24:03 +08:00
parent fed822c5b7
commit 7d7d60e5e3
13 changed files with 231 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
README.md
View File

@@ -15,28 +15,27 @@
</div>
**Sponge** is a powerful `Go` development framework. Its core concept is to generate modular code by parsing `SQL`, `Protobuf`, or `JSON` files in reverse, these modular codes can be flexibly combined into various types of complete backend services (`similar to the characteristics of sponge cells, where disassembled sponge cells can automatically recombine into a new sponge`).
Sponge offers outstanding project engineering capabilities, providing an all-in-one project development solution that covers code generation, development, testing, API documentation generation, and deployment. Sponge deeply integrates a modular architecture with an AI assistant to significantly enhance development efficiency and reduce technical barriers, empowering developers to easily build stable and reliable backend systems using a "low-code" approach.
**Sponge** is a powerful and easy-to-use `Go` development framework. Its core concept is to reverse-generate modular code by parsing `SQL`, `Protobuf`, and `JSON` files. These modular components can be flexibly combined into various types of complete backend services. Featuring a modular architecture and deeply integrated AI assistant, sponge significantly improves development efficiency and lowers the technical barrier, enabling the effortless construction of high-performance, highly available backend systems through a low-code approach.
<br>
### Applicable Scenarios
Sponge is suitable for rapidly building various types of high-performance backend services, including but not limited to:
**Sponge** is ideal for rapidly building various types of high-performance backend services. Applicable scenarios include:
- `RESTful API` services
- `Web` services (Gin-based)
- `gRPC` services
- `HTTP+gRPC` hybrid services
- `gRPC Gateway API` services
- `cloud-native` microservices
* Developing internal enterprise API services
* Quickly building microservices
* Creating APIs for backend management systems
* Building gRPC services for inter-service communication
* Serving as a starting point for Go beginners or teams to learn Go project structure and best practices
* Supporting teams that need to improve development efficiency and standardize coding practices
* Cloud-native development
Additionally, developers can use custom templates to generate various types of code to meet specific business needs.
In addition, developers can generate business-specific code by customizing templates.
<br>
### Core Advantages
### Key Features
1. **One-click generation of complete backend service code**
For `Web` or `gRPC` services that only require `CRUD APIs`, no `Go` code needs to be written. Simply connect to a database (e.g., `MySQL`, `MongoDB`, `PostgreSQL`, `SQLite`) to one-click generate complete backend service code and easily deploy it to Linux servers, Docker, or Kubernetes.
@@ -71,7 +70,7 @@ Additionally, developers can use custom templates to generate various types of c
1. **Install sponge**
Sponge supports installation on Windows, macOS, and Linux. Click to view the [**sponge installation guide**](https://github.com/go-dev-frame/sponge/blob/main/assets/install-en.md).
Sponge supports installation on Windows, macOS, Linux and Docker. Click to view the [**sponge installation guide**](https://github.com/go-dev-frame/sponge/blob/main/assets/install-en.md).
2. **Open the code generation UI**
@@ -87,7 +86,7 @@ Additionally, developers can use custom templates to generate various types of c
<img width="1500px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/en_sponge-ui.png">
</p>
> To access from a browser on a different host, specify the host IP or domain when starting the UI, e.g., `sponge run -a http://your_host_ip:24631`. Alternatively, you can run the UI service in Docker to support cross-host access. Click to view the guide on [running the sponge UI service in Docker](https://github.com/go-dev-frame/sponge/blob/main/assets/install-en.md#Docker%E7%8E%AF%E5%A2%83).
> To access from a browser on a different host, specify the host IP or domain when starting the UI, e.g., `sponge run -a http://your_host_ip:24631`.
<br>
@@ -97,7 +96,7 @@ Sponge has built-in rich components (for on-demand use):
| Components | Examples |
| :--- | :-------- |
| Web framework [gin](https://github.com/gin-gonic/gin) | [gin example](https://github.com/go-dev-frame/sponge/blob/main/internal/routers/routers.go#L35)<br>[gin middleware examples](https://github.com/go-dev-frame/sponge/blob/main/pkg/gin/middleware/README.md) |
| Web framework [gin](https://github.com/gin-gonic/gin) | [gin example](https://github.com/go-dev-frame/sponge/blob/main/internal/routers/routers.go#L32)<br>[gin middleware examples](https://github.com/go-dev-frame/sponge/blob/main/pkg/gin/middleware/README.md) |
| RPC framework [gRPC](https://github.com/grpc/grpc-go) | [gRPC example](https://github.com/go-dev-frame/sponge/blob/main/internal/server/grpc.go#L312)<br>[gRPC interceptor examples](https://github.com/go-dev-frame/sponge/blob/main/pkg/grpc/interceptor/README.md) |
| Configuration parsing [viper](https://github.com/spf13/viper) | [example](https://github.com/go-dev-frame/sponge/blob/main/pkg/conf/README.md#example-of-use) |
| Logging [zap](https://github.com/uber-go/zap) | [example](https://github.com/go-dev-frame/sponge/blob/main/pkg/logger/README.md#example-of-use) |
@@ -118,20 +117,20 @@ Sponge has built-in rich components (for on-demand use):
| Service registration and discovery [etcd](https://github.com/etcd-io/etcd), [consul](https://github.com/hashicorp/consul), [nacos](https://github.com/alibaba/nacos) | [service registration example](https://github.com/go-dev-frame/sponge/blob/main/pkg/servicerd/registry/README.md#example-of-use)<br>[service discovery example](https://github.com/go-dev-frame/sponge/blob/main/pkg/servicerd/discovery/README.md#example-of-use) |
| Adaptive collecting [profile](https://go.dev/blog/pprof) | [example](https://github.com/go-dev-frame/sponge/blob/main/pkg/prof/go-profile-en.md) |
| Resource statistics [gopsutil](https://github.com/shirou/gopsutil) | [example](https://github.com/go-dev-frame/sponge/tree/main/pkg/stat#example-of-use) |
| Configuration cente [nacos](https://github.com/alibaba/nacos) | [example](https://go-sponge.com/components?id=configuration-center) |
| Configuration center [nacos](https://github.com/alibaba/nacos) | [example](https://go-sponge.com/component/config-center.html) |
| Code quality checking [golangci-lint](https://github.com/golangci/golangci-lint) | - |
| Continuous integration and deployment CI/CD [kubernetes](https://github.com/kubernetes/kubernetes), [docker](https://www.docker.com/), [jenkins](https://github.com/jenkinsci/jenkins) | [example](https://go-sponge.com/deployment?id=continuous-integration-and-deployment) |
| Continuous integration and deployment CI/CD [kubernetes](https://github.com/kubernetes/kubernetes), [docker](https://www.docker.com/), [jenkins](https://github.com/jenkinsci/jenkins) | [example](https://go-sponge.com/deployment/kubernetes.html) |
| Generate project business architecture diagram [spograph](https://github.com/go-dev-frame/spograph) | [example](https://github.com/go-dev-frame/spograph?tab=readme-ov-file#example-of-use) |
| Custom template generation code [go template](https://pkg.go.dev/text/template@go1.23.3) | [json example](https://go-sponge.com/custom-template-field)<br>[sql example](https://go-sponge.com/custom-template-sql)<br>[protobuf example](https://go-sponge.com/custom-template-protobuf) |
| Custom template generation code [go template](https://pkg.go.dev/text/template@go1.23.3) | [json example](https://go-sponge.com/guide/customize/template-json.html)<br>[sql example](https://go-sponge.com/guide/customize/template-sql.html)<br>[protobuf example](https://go-sponge.com/guide/customize/template-protobuf.html) |
| AI assistant [DeepSeek](https://deepseek.com), [ChatGPT](https://chatgpt.com), [Gemini](https://gemini.google.com) | [example](https://github.com/go-dev-frame/sponge/blob/main/cmd/sponge/commands/assistant/generate.go#L44) |
<br>
### Code Generation Engine
The code generation engine of sponge supports two methods for generating the required project code: **built-in templates** and **custom templates**. Below are the framework diagrams for both approaches.
**Sponge** offers powerful code generation capabilities, supporting both `built-in templates` and `custom templates` to quickly generate the code required for your project. It also integrates an `AI assistant` to help generate business logic code.
1. The framework for code generation based on built-in templates in sponge is shown below, supporting both SQL and Protobuf formats.
1. Sponge generates a code framework based on built-in templates, as shown in the diagram below:
<p align="center">
<img width="1500px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/sponge-framework.png">
@@ -139,7 +138,7 @@ The code generation engine of sponge supports two methods for generating the req
<br>
2. The framework for code generation based on custom templates in sponge is shown below, supporting JSON, SQL, and Protobuf formats.
2. Sponge generates a code framework based on custom templates, as shown in the diagram below:
<p align="center">
<img width="1200px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/template-framework.png">
@@ -147,7 +146,7 @@ The code generation engine of sponge supports two methods for generating the req
<br>
3. Sponge generates business logic code framework based on function description information, as shown in the following figure:
3. Sponge generates a business logic code framework based on functions and comments, as shown in the diagram below:
<p align="center">
<img width="1200px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/ai-assistant-framework.png">
@@ -157,10 +156,10 @@ The code generation engine of sponge supports two methods for generating the req
### Microservice framework
Back-end services created by sponge are typical microservice architectures. The diagram below illustrates a typical layered microservice structure, featuring high performance, scalability, and built-in service governance capabilities.
**Sponge** is a modern Go microservice framework that adopts a typical layered microservice architecture. It comes with a rich set of built-in service governance features, enabling developers to quickly build and maintain complex microservice systems. The structure of the framework is shown in the diagram below:
<p align="center">
<img width="1000px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/microservices-framework.png">
<img width="1000px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/en_microservices-framework.png">
</p>
<br>
@@ -175,6 +174,12 @@ Click to view the [**test code**](https://github.com/zhufuyi/microservices_frame
<br>
### sponge Development Guide
You're welcome to explore the [complete technical documentation for the Sponge project](https://go-sponge.com/), which provides in-depth coverage of core topics such as code generation, development workflows, system configuration, and deployment strategies.
<br>
### Project Code Directory Structure
The project code directory structure created by sponge follows the [project-layout](https://github.com/golang-standards/project-layout).
@@ -191,11 +196,11 @@ Sponge supports creating three types of project code structures: `Monolithic app
├── configs # Directory for configuration files
├── deployments # Bare metal, docker, k8s deployment script directory.
├── docs # Directory for API interface Swagger documentation.
├── internal # Directory for business logic code.
├── internal # Directory for project internal code.
│ ├── cache # Cache directory wrapped around business logic.
│ ├── config # Directory for Go structure configuration files.
│ ├── dao # Data access directory.
│ ├── database # database directory.
│ ├── database # Directory for database initialization and migration.
│ ├── ecode # Directory for system error codes and custom business error codes.
│ ├── handler # Directory for implementing HTTP business functionality (specific to web services).
│ ├── model # Database model directory.
@@ -235,15 +240,9 @@ Sponge supports creating three types of project code structures: `Monolithic app
<br>
### Sponge Development Documentation
### Examples
Click to view [the detailed documentation](https://go-sponge.com/) for Sponge development project, including code generation, development, configuration, and deployment instructions, and more.
<br>
### Examples of use
#### Examples of create services
#### Sponge Create Server Code Examples
- [Create **web** service based on **sql** (including CRUD)](https://github.com/go-dev-frame/sponge_examples/tree/main/1_web-gin-CRUD)
- [Create **grpc** service based on **sql** (including CRUD)](https://github.com/go-dev-frame/sponge_examples/tree/main/2_micro-grpc-CRUD)
@@ -252,20 +251,20 @@ Click to view [the detailed documentation](https://go-sponge.com/) for Sponge de
- [Create **grpc gateway** service based on **protobuf**](https://github.com/go-dev-frame/sponge_examples/tree/main/5_micro-gin-rpc-gateway)
- [Create **grpc+http** service based on **protobuf**](https://github.com/go-dev-frame/sponge_examples/tree/main/_10_micro-grpc-http-protobuf)
#### Examples of develop complete project
- [Simple community web backend service](https://github.com/go-dev-frame/sponge_examples/tree/main/7_community-single)
- [Simple community web service broken down into microservice](https://github.com/go-dev-frame/sponge_examples/tree/main/8_community-cluster)
#### Distributed transaction examples
#### Sponge+DTM Distributed Transaction Examples
- [Simple distributed order system](https://github.com/go-dev-frame/sponge_examples/tree/main/9_order-grpc-distributed-transaction)
- [Flash sale](https://github.com/go-dev-frame/sponge_examples/tree/main/_12_sponge-dtm-flashSale)
- [E-Commerce system](https://github.com/go-dev-frame/sponge_examples/tree/main/_14_eshop)
#### Sponge+AI assistant collaborative development
#### Sponge+AI Assistant Collaborative Development Examples
- [Home appliance retail management platform](https://github.com/go-dev-frame/sponge_examples/tree/main/_15_appliance_store)
- [Home appliance retail management](https://github.com/go-dev-frame/sponge_examples/tree/main/_15_appliance_store)
#### Sponge Development Project Examples
- [Community backend services](https://github.com/go-dev-frame/sponge_examples/tree/main/7_community-single)
- [Monolithic service split into microservices](https://github.com/go-dev-frame/sponge_examples/tree/main/8_community-cluster)
<br>
<br>

BIN
assets/ai-assistant-framework.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 66 KiB

BIN
assets/en_microservices-framework.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 115 KiB

BIN
assets/en_sponge-ui.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 179 KiB

After

Width:  |  Height:  |  Size: 169 KiB

178
assets/install-cn.md
View File

@@ -1,7 +1,9 @@
要求 [Go 1.23+](https://studygolang.com/dl) 版本。
要求使用go 1.23以上版本： [https://studygolang.com/dl](https://studygolang.com/dl)
> 注：如果不能科学上网，获取github的库可能会遇到超时失败问题，建议设置为国内代理，执行命令 **go env -w GOPROXY=https://goproxy.cn,direct**
> **提示**：Go下载第三方包时可能会遇到依赖下载超时问题，建议设置国内代理：
> ```bash
> go env -w GOPROXY=https://goproxy.cn,direct
> ```
<br>
@@ -9,99 +11,48 @@
<br>
### Windows环境
### Windows 环境
安装sponge之前确保已安装go语言环境，并把`GOBIN`添加到系统环境变量**path**，如果已经设置过可以跳过此步骤：
#### 前置准备
确保已安装 Go 并配置 `GOBIN` 环境变量：
```bash
# 检查GOBIN目录是否存在
go env GOBIN
# 如果为空，设置GOBIN(例如：D:\go\bin)，可能需要管理员权限
go env -w GOBIN=D:\go\bin
# 然后并把GOBIN目录添加到系统path环境变量
```
<br>
> 因为sponge依赖一些linux命令，因此在windows环境中需要安装git bash、make来支持linux命令环境。
为了安装方便，已经把sponge及其依赖的程序打包在一起，下载地址(选择一个下载即可)：
- 百度云：[**sponge-install.zip**](https://pan.baidu.com/s/1adMIlUyQlH6vRK2UIN7MRg?pwd=3fja)。
- 蓝奏云：[**sponge安装文件**](https://wwm.lanzoue.com/b049fldpi) 密码:5rq9，共下载4个文件，安装前先看`安装说明.txt`文件。
下载文件后：
(1) 解压文件，双击 **install.bat** 进行安装，安装git过程一直默认即可(如果已经安装过git，可以跳过安装git这个步骤)。
(2) 在任意文件夹下右键(显示更多选项)，选择【Open Git Bash here】打开git bash终端：
```bash
# 初始化sponge
sponge init
```
注意：
- 使用sponge开发项目时，请使用git bash终端，不要使用系统默认的cmd，否则会出现找不到命令的错误。
- 不要在`GOBIN`目录(sponge可执行文件所在的目录)下打开终端来执行命令`sponge run`。
- 如果当前使用sponge的版本低于`v1.11.1`，并且需要升级，请执行命令更新到最新版本的sponge： `go install github.com/go-dev-frame/sponge/cmd/sponge@latest && sponge init`。
在windows除了上面安装sponge方式，还提供了原生安装，点击查看【安装 sponge】 --> 【windows环境】[安装文档](https://go-sponge.com/zh-cn/quick-start?id=%e5%ae%89%e8%a3%85-sponge)。
<br>
---
<br>
### Linux或MacOS环境
(1) 把`GOBIN`添加到系统环境变量**path**，如果已经设置过可以跳过此步骤。
```bash
# 打开 .bashrc 文件
vim ~/.bashrc
# 复制下面命令到.bashrc
export GOROOT="/opt/go" # 你的go安装目录
export GOPATH=$HOME/go # 设置 go get 命令下载第三方包的目录
export GOBIN=$GOPATH/bin # 设置 go install 命令编译后生成可执行文件的存放目录
export PATH=$PATH:$GOBIN:$GOROOT/bin # 把GOBIN目录添加到系统环境变量path
# 保存 .bashrc 文件后，使设置生效
source ~/.bashrc
# 查看GOBIN目录，如果输出不为空，说明设置成功
# 检查 GOBIN 是否已设置（输出为空表示未设置）
go env GOBIN
# 若未设置，请配置（根据实际修改示例路径）
go env -w GOBIN=D:\go\bin
# 然后将 GOBIN 路径添加到系统 PATH 环境变量
```
<br>
(2) 把sponge及其依赖的插件安装到 `GOBIN` 目录。
#### 快速安装 sponge
**✅ 安装 protoc**
我们提供了包含所有依赖的集成安装包：
- 百度云盘：[sponge-install.zip](https://pan.baidu.com/s/1adMIlUyQlH6vRK2UIN7MRg?pwd=3fja)
- 蓝奏云：[sponge 安装文件](https://wwm.lanzoue.com/b049fldpi) 密码:5rq9，*需下载全部4个文件，安装前请阅读`安装说明.txt`*
下载protoc地址： [https://github.com/protocolbuffers/protobuf/releases/tag/v25.2](https://github.com/protocolbuffers/protobuf/releases/tag/v25.2)
<br>
根据系统类型下载对应的 **protoc** 可执行文件，把 **protoc** 可执行文件移动到`GOBIN`目录下。
**安装步骤**：
```bash
# 安装sponge
go install github.com/go-dev-frame/sponge/cmd/sponge@latest
1. 解压后运行 `install.bat`
- 安装 Git 时保持默认选项即可（已安装可跳过）
2. 打开 Git Bash 终端，鼠标右键 → 【Open Git Bash here】
```bash
sponge init # 初始化并安装依赖
sponge plugins # 查看已安装的插件
sponge -v # 查看版本
```
# 初始化sponge，自动安装sponge依赖插件
sponge init
**注意**：请始终使用 Git Bash，不要使用 Windows 默认的 cmd 终端，否则可能出现找不到命令的错误。
# 查看插件是否都安装成功，如果发现有插件没有安装成功，执行命令重试 sponge plugins --install
sponge plugins
<br>
# 查看sponge版本
sponge -v
```
> 注：不要在`GOBIN`目录下打开终端来执行命令`sponge run`。
> 上面是集成安装包的安装方式，另支持原生安装 sponge 方式，详见：
> 👉 [【安装 Sponge】→【Windows 环境】](https://go-sponge.com/zh/getting-started/install.html#安装-sponge)
<br>
@@ -109,39 +60,80 @@ sponge -v
<br>
### Docker环境
### Linux/MacOS 环境
> ⚠ 使用docker启动的sponge UI服务，只支持在界面操作来生成代码功能，如果需要在生成的服务代码基础上进行开发，还是需要根据上面的安装说明，在本地安装sponge和依赖插件。
#### 环境配置
**方式一：Docker启动**
配置环境变量（已配置可跳过）：
```bash
docker run -d --name sponge -p 24631:24631 zhufuyi/sponge:latest -a http://你的宿主机ip:24631
vim ~/.bashrc
```
添加以下内容（根据实际情况修改路径）：
```bash
export GOROOT="/opt/go" # Go 安装目录
export GOPATH=$HOME/go # Go 模块下载目录
export GOBIN=$GOPATH/bin # 可执行文件存放目录
export PATH=$PATH:$GOBIN:$GOROOT/bin
```
生效配置：
```bash
source ~/.bashrc
go env GOBIN # 验证是否配置成功，如果输出不为空，说明设置成功
```
<br>
**方式二：docker-compose启动**
#### 安装步骤
docker-compose.yaml 文件内容如下：
1. 安装 protoc：
- 下载地址：[protoc v25.2](https://github.com/protocolbuffers/protobuf/releases/tag/v25.2)
- 将 `protoc` 可执行文件放入 `GOBIN` 目录
2. 安装 sponge：
```bash
go install github.com/go-dev-frame/sponge/cmd/sponge@latest
sponge init # 初始化并安装依赖
sponge plugins # 查看已安装的插件
sponge -v # 查看版本
```
<br>
---
<br>
### Docker 环境
> ⚠ 注意：Docker 版仅支持 UI 代码生成功能，如需在生成的服务代码基础上进行开发，仍需在本地安装 sponge 完整环境。
#### 快速启动
**方案一：Docker 命令**
```bash
docker run -d --name sponge -p 24631:24631 zhufuyi/sponge:latest -a http://<宿主机IP>:24631
```
<br>
**方案二：docker-compose**
```yaml
version: "3.7"
services:
sponge:
image: zhufuyi/sponge:latest
container_name: sponge
restart: always
command: ["-a","http://你的宿主机ip:24631"]
command: ["-a","http://<宿主机IP>:24631"]
ports:
- "24631:24631"
```
启动服务：
启动命令：
```bash
docker-compose up -d
```
在docker部署成功后，在浏览器访问 `http://你的宿主机ip:24631`。
访问地址：`http://<宿主机IP>:24631`

135
assets/install-en.md
View File

@@ -1,5 +1,4 @@
Recommended to use go version 1.23 or above, [https://go.dev/doc/install](https://go.dev/doc/install)
Requires [Go 1.23+](https://go.dev/doc/install) version.
<br>
@@ -9,41 +8,44 @@ Recommended to use go version 1.23 or above, [https://go.dev/doc/install](https:
### Windows Environment
Make sure the go locale is installed before installing sponge, and add `GOBIN` to the system environment variable **path**. If it is already set, skip this step:
#### Preparations
```bash
#Check if GOBIN directory exists
go env GOBIN
#If empty, GOBIN needs to be set (e.g. D:\go\bin), administrator privileges may be required
go env -w GOBIN=D:\go\bin
#Then add GOBIN directory to system path environment variable
```
Ensure Go is installed and the `GOBIN` environment variable is configured:
```bash
# Check if GOBIN is set (empty output means not set)
go env GOBIN
# If not set, configure it (modify the example path according to your actual setup)
go env -w GOBIN=D:\go\bin
# Then add the GOBIN path to the system PATH environment variable
```
<br>
> Because sponge depends on some linux commands, git bash and make need to be installed in windows to support the linux command environment.
#### Quick Install sponge
For installation convenience, sponge and its dependent programs have been packaged together, download address: [**sponge-install.zip**](https://drive.google.com/drive/folders/1T55lLXDBIQCnL5IQ-i1hWJovgLI2l0k1?usp=sharing)
We provide an integrated installation package that includes all dependencies, download address: [**sponge-install.zip**](https://drive.google.com/drive/folders/1T55lLXDBIQCnL5IQ-i1hWJovgLI2l0k1?usp=sharing)
After downloading the file:
<br>
1. Unzip the file, double-click **install.bat** to install, the installation process of git is always the default (if you have installed git, you can skip this step)
**Installation Steps**:
2. Right-click any folder (Show more options) and select **Open Git Bash here** to open the git bash terminal:
1. After unzipping, run `install.bat`
- Keep default options during Git installation (skip if already installed)
2. Open Git Bash terminal, right-click → [Open Git Bash here]
```bash
sponge init # Initialize and install dependencies
sponge plugins # View installed plugins
sponge -v # View version
```
```bash
# Initialize sponge, automatically install sponge's dependency plugins
sponge init
```
**Note**: Always use Git Bash. Do not use the default Windows cmd terminal, otherwise you may encounter 'command not found' errors.
Note:
<br>
- When using sponge development, please use git bash terminal, do not use the system default cmd, otherwise there will be an error that cannot find the command.
- Do not open a terminal in the `GOBIN` directory (the directory where the sponge executable is located) to execute the command `sponge run`.
- If you are using a version of Sponge earlier than `v1.11.1` and need to upgrade, execute the command to update to the latest version of Sponge: `go install github.com/go-dev-frame/sponge/cmd/sponge@latest && sponge init`.
In addition to the above installation of sponge in windows, it also provides native installation, click to view **Installing Sponge** --> **Windows Environment** [installation documentation](https://go-sponge.com/quick-start?id=installing-sponge).
> The above is the installation method for the integrated package. Native installation of sponge is also supported, see details at:
> 👉 **[[Install Sponge] → [Windows Environment]](https://go-sponge.com/getting-started/install.html#install-sponge)**
<br>
@@ -51,52 +53,46 @@ In addition to the above installation of sponge in windows, it also provides nat
<br>
### Linux or macOS Environment
### Linux/MacOS Environment
1. Add `GOBIN` to the system environment variable path, skip this step if already set.
#### Environment Configuration
Configure environment variables (skip if already configured):
```bash
# Open .bashrc file
vim ~/.bashrc
```
# Copy the following command to .bashrc file
export GOROOT="/opt/go" # your go installation directory
export GOPATH=$HOME/go # Set the directory where the "go get" command downloads third-party packages
export GOBIN=$GOPATH/bin # Set the directory where the executable binaries are compiled by the "go install" command.
export PATH=$PATH:$GOBIN:$GOROOT/bin # Add the GOBIN directory to the system environment variable path.
Add the following content (modify paths according to your actual setup):
```bash
export GOROOT="/opt/go" # Go installation directory
export GOPATH=$HOME/go # Go module download directory
export GOBIN=$GOPATH/bin # Directory for executable files
export PATH=$PATH:$GOBIN:$GOROOT/bin
```
# Save .bashrc file, and make the settings take effect
Apply configuration:
```bash
source ~/.bashrc
# View the GOBIN directory, if the output is not empty, the setting is successful.
go env GOBIN
go env GOBIN # Verify configuration success, non-empty output indicates success
```
<br>
2. Install sponge and its dependent plugins into the `GOBIN` directory.
#### Installation Steps
**✅ Install protoc**
1. Install protoc:
- Download link: [protoc v25.2](https://github.com/protocolbuffers/protobuf/releases/tag/v25.2)
- Place the `protoc` executable file into the `GOBIN` directory
Download protoc from: [https://github.com/protocolbuffers/protobuf/releases/tag/v25.2](https://github.com/protocolbuffers/protobuf/releases/tag/v25.2)
Download the corresponding **protoc** executable file according to the system type, and move the **protoc** executable file to the same directory as the **go** executable file.
```bash
# Install Sponge
go install github.com/go-dev-frame/sponge/cmd/sponge@latest
# Initialize Sponge, automatically install Sponge's dependency plugins
sponge init
# Check if all plugins have been successfully installed. If any plugins fail to install, retry with the command: sponge plugins --install
sponge plugins
# Check Sponge version
sponge -v
```
> Note: Do not open the terminal in the `GOBIN` directory to execute the command `sponge run`.
2. Install sponge:
```bash
go install github.com/go-dev-frame/sponge/cmd/sponge@latest
sponge init # Initialize and install dependencies
sponge plugins # View installed plugins
sponge -v # View version
```
<br>
@@ -106,37 +102,32 @@ sponge -v
### Docker Environment
> ⚠ Sponge UI service started by docker only supports code generation function. If you need to develop based on the generated service code, you also need to install Sponge and the required plugins locally according to the installation instructions above.
> ⚠ Warning: The Docker version only supports UI code generation. If you need to develop based on the generated service code, you still need to install the full sponge environment locally.
**Docker Run**
#### Quick Start
**Option 1: Docker Command**
```bash
docker run -d --name sponge -p 24631:24631 zhufuyi/sponge:latest -a http://your_host_ip:24631
docker run -d --name sponge -p 24631:24631 zhufuyi/sponge:latest -a http://<Host IP>:24631
```
<br>
**Docker Compose**
The content of the `docker-compose.yaml` file is as follows:
**Option 2: docker-compose**
```yaml
version: "3.7"
services:
sponge:
image: zhufuyi/sponge:latest
container_name: sponge
restart: always
command: ["-a","http://your_host_ip:24631"]
command: ["-a","http://<Host IP>:24631"]
ports:
- "24631:24631"
```
Start the service:
Start command:
```bash
docker-compose up -d
```
After a successful Docker deployment, access `http://your_host_ip:24631` in your browser.
Access URL: `http://<Host IP>:24631`

BIN
assets/logo.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 90 KiB

After

Width:  |  Height:  |  Size: 84 KiB

BIN
assets/microservices-framework.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 58 KiB

After

Width:  |  Height:  |  Size: 117 KiB

77
assets/readme-cn.md
View File

@@ -2,26 +2,27 @@
<br>
**sponge** 是一个强大的 `Go` 开发框架，其核心理念是通过解析 `SQL`、`Protobuf`、`JSON` 文件逆向生成模块化的代码，这些模块代码可灵活组合成多种类型的完整后端服务（`类似海绵细胞的特性，打散的海绵细胞能自动重新组合成新的海绵`）。sponge 拥有出色的项目工程化能力，提供一站式项目开发解决方案，涵盖代码生成、开发、测试、API 文档生成和部署。sponge 通过模块化架构与AI助手深度融合，大幅提升开发效率、降低技术门槛，助力开发者以"低代码"方式轻松构建稳定可靠的后端系统。
**sponge** 是一个强大且易用的 `Go` 开发框架，其核心理念是通过解析 `SQL`、`Protobuf`、`JSON` 文件逆向生成模块化的代码，这些模块代码可灵活组合成多种类型的完整后端服务。sponge 采用模块化架构并深度集成 AI 助手，显著提升开发效率、降低技术门槛，以"低代码"方式轻松构建高性能、高可用的后端服务体系。
<br>
### 适用场景
sponge 适用于快速构建多种类型的高性能后端服务，包括但不限于：
sponge 适用于快速构建多种类型的高性能后端服务，适用场景如下：
- `RESTful API` 服务
- `Web` 服务 (基于Gin)
- `gRPC` 服务
- `HTTP+gRPC` 混合服务
- `gRPC Gateway API` 服务
- 云原生微服务
- 开发企业内部 API 服务。
- 快速构建微服务 (Microservices)。
- 搭建后台管理系统 API。
- 构建 gRPC 服务进行服务间通信。
- 作为 Go 初学者或团队学习 Go 项目结构和最佳实践的起点。
- 需要提高开发效率、统一开发规范的团队。
- 云原生开发。
此外，开发者还可以通过自定义模板，生成满足业务需求的各类代码。
<br>
### 核心优势
### 主要特点
1. **一键生成完整后端服务代码**
对于仅需 `CRUD API` 的 `Web` 或 `gRPC` 服务，无需编写任何 `Go` 代码。只需连接数据库(如 `MySQL`、`MongoDB`、`PostgreSQL`、`SQLite`)，即可一键生成完整后端服务代码，并轻松部署到 Linux 服务器、Docker 或 Kubernetes 上。
@@ -56,7 +57,7 @@ sponge 适用于快速构建多种类型的高性能后端服务，包括但不
1. **安装 sponge**
支持在 windows、mac、linux 环境下安装 sponge，点击查看 [**安装 sponge 说明**](https://github.com/go-dev-frame/sponge/blob/main/assets/install-cn.md)。
支持在 windows、mac、linux、docker 环境下安装 sponge，点击查看 [**安装 sponge 说明**](https://github.com/go-dev-frame/sponge/blob/main/assets/install-cn.md)。
2. **打开生成代码 UI 页面**
@@ -72,17 +73,17 @@ sponge 适用于快速构建多种类型的高性能后端服务，包括但不
<img width="1500px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/sponge-ui.png">
</p>
> 如果想要在跨主机的浏览器上访问，启动UI时需要指定宿主机ip或域名，示例 `sponge run -a http://your_host_ip:24631`。 也可以在 docker 上启动UI服务来支持跨主机访问，点击查看 [在 docker 运行 sponge UI 服务说明](https://github.com/go-dev-frame/sponge/blob/main/assets/install-cn.md#Docker%E7%8E%AF%E5%A2%83)。
> 如果想要在跨主机的浏览器上访问，启动UI时需要指定宿主机ip或域名，示例 `sponge run -a http://your_host_ip:24631`。
<br>
### 主要功能
### 组件
sponge 内置了丰富的组件(按需使用)：
| 组件 | 使用示例 |
| :--- | :-------- |
| Web 框架 [gin](https://github.com/gin-gonic/gin) | [gin 示例](https://github.com/go-dev-frame/sponge/blob/main/internal/routers/routers.go#L35)<br>[gin 中间件示例](https://github.com/go-dev-frame/sponge/blob/main/pkg/gin/middleware/README.md) |
| Web 框架 [gin](https://github.com/gin-gonic/gin) | [gin 示例](https://github.com/go-dev-frame/sponge/blob/main/internal/routers/routers.go#L32)<br>[gin 中间件示例](https://github.com/go-dev-frame/sponge/blob/main/pkg/gin/middleware/README.md) |
| RPC 框架 [gRPC](https://github.com/grpc/grpc-go) | [gRPC 示例](https://github.com/go-dev-frame/sponge/blob/main/internal/server/grpc.go#L312)<br>[gRPC 拦截器示例](https://github.com/go-dev-frame/sponge/blob/main/pkg/grpc/interceptor/README.md) |
| 配置解析 [viper](https://github.com/spf13/viper) | [示例](https://github.com/go-dev-frame/sponge/blob/main/pkg/conf/README.md#example-of-use) |
| 日志 [zap](https://github.com/uber-go/zap) | [示例](https://github.com/go-dev-frame/sponge/blob/main/pkg/logger/README.md#example-of-use) |
@@ -103,20 +104,20 @@ sponge 内置了丰富的组件(按需使用)：
| 服务注册与发现 [etcd](https://github.com/etcd-io/etcd), [consul](https://github.com/hashicorp/consul), [nacos](https://github.com/alibaba/nacos) | [服务注册示例](https://github.com/go-dev-frame/sponge/blob/main/pkg/servicerd/registry/README.md#example-of-use)<br>[服务发现示例](https://github.com/go-dev-frame/sponge/blob/main/pkg/servicerd/discovery/README.md#example-of-use) |
| 自适应采集 [profile](https://go.dev/blog/pprof) | [示例](https://github.com/go-dev-frame/sponge/blob/main/pkg/prof/go-profile-cn.md) |
| 资源统计 [gopsutil](https://github.com/shirou/gopsutil) | [示例](https://github.com/go-dev-frame/sponge/tree/main/pkg/stat#example-of-use) |
| 配置中心 [nacos](https://github.com/alibaba/nacos) | [示例](https://go-sponge.com/zh-cn/components?id=%e9%85%8d%e7%bd%ae%e4%b8%ad%e5%bf%83) |
| 配置中心 [nacos](https://github.com/alibaba/nacos) | [示例](https://go-sponge.com/zh/component/config-center.html) |
| 代码质量检查 [golangci-lint](https://github.com/golangci/golangci-lint) | - |
| 持续集成部署 CI/CD [kubernetes](https://github.com/kubernetes/kubernetes), [docker](https://www.docker.com/), [jenkins](https://github.com/jenkinsci/jenkins) | [示例](https://go-sponge.com/zh-cn/deployment?id=%e6%8c%81%e7%bb%ad%e9%9b%86%e6%88%90%e9%83%a8%e7%bd%b2) |
| 持续集成部署 CI/CD [kubernetes](https://github.com/kubernetes/kubernetes), [docker](https://www.docker.com/), [jenkins](https://github.com/jenkinsci/jenkins) | [示例](https://go-sponge.com/zh/deployment/kubernetes.html) |
| 生成项目业务架构图 [spograph](https://github.com/go-dev-frame/spograph) | [示例](https://github.com/go-dev-frame/spograph?tab=readme-ov-file#example-of-use) |
| 生成自定义代码 [go template](https://pkg.go.dev/text/template@go1.23.3) | [json 示例](https://go-sponge.com/zh-cn/custom-template-field)<br>[sql 示例](https://go-sponge.com/zh-cn/custom-template-sql)<br>[protobuf 示例](https://go-sponge.com/zh-cn/custom-template-protobuf) |
| 生成自定义代码 [go template](https://pkg.go.dev/text/template@go1.23.3) | [json 示例](https://go-sponge.com/zh/guide/customize/template-json.html)<br>[sql 示例](https://go-sponge.com/zh/guide/customize/template-sql.html)<br>[protobuf 示例](https://go-sponge.com/zh/guide/customize/template-protobuf.html) |
| AI助手 [DeepSeek](https://deepseek.com), [ChatGPT](https://chatgpt.com), [Gemini](https://gemini.google.com) | [示例](https://github.com/go-dev-frame/sponge/blob/main/cmd/sponge/commands/assistant/generate.go#L44) |
<br>
### 代码生成引擎
sponge 的代码生成引擎支持**内置模板**和**自定义模板**两种方式生成项目所需的代码，支持 AI 助手生成业务逻辑代码。
sponge 提供强大的代码生成能力，支持基于`内置模板`和`自定义模板`两种方式快速生成项目所需代码，同时集成`AI 助手`辅助生成业务逻辑代码。
1. sponge 基于内置模板生成代码框架如下图所示，支持 sql 和 protobuf 两种方式。
1. sponge 基于内置模板生成代码框架，如下图所示：
<p align="center">
<img width="1500px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/sponge-framework.png">
@@ -124,7 +125,7 @@ sponge 的代码生成引擎支持**内置模板**和**自定义模板**两种
<br>
2. sponge 基于自定义模板生成代码框架如下图所示，支持 json、sql、protobuf 三种方式。
2. sponge 基于自定义模板生成代码框架，如下图所示：
<p align="center">
<img width="1200px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/template-framework.png">
@@ -132,7 +133,7 @@ sponge 的代码生成引擎支持**内置模板**和**自定义模板**两种
<br>
3. sponge 基于函数描述信息生成业务逻辑代码框架，如下图所示：
3. sponge 基于函数及注释生成业务逻辑代码框架，如下图所示：
<p align="center">
<img width="1200px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/ai-assistant-framework.png">
@@ -142,7 +143,7 @@ sponge 的代码生成引擎支持**内置模板**和**自定义模板**两种
### 微服务框架
sponge 创建的后端服务属于典型的微服务架构，下图展示了典型的微服务分层结构，具备高性能、高扩展性，并内置常用的服务治理功能。
sponge 是一个现代化的 Go 微服务框架，它采用典型的微服务分层架构，内置了丰富的服务治理功能，帮助开发者快速构建和维护复杂的微服务系统，框架结构如下图所示：
<p align="center">
<img width="1000px" src="https://raw.githubusercontent.com/go-dev-frame/sponge/main/assets/microservices-framework.png">
@@ -150,7 +151,7 @@ sponge 创建的后端服务属于典型的微服务架构，下图展示了典
<br>
创建的http和grpc服务代码的性能测试： 50个并发，总共100万个请求。
创建的 HTTP 和 gRPC 服务代码的性能测试： 50个并发，总共100万个请求。
![http-server](https://raw.githubusercontent.com/zhufuyi/microservices_framework_benchmark/main/test/assets/http-server.png)
@@ -160,6 +161,12 @@ sponge 创建的后端服务属于典型的微服务架构，下图展示了典
<br>
### sponge 开发指南
欢迎查阅 [Sponge 开发项目的完整技术文档](https://go-sponge.com/zh/)，该文档详尽涵盖了代码生成、开发流程、系统配置及部署方案等核心内容。
<br>
### 目录结构
sponge 创建的服务代码目录结构遵循 [project-layout](https://github.com/golang-standards/project-layout)。
@@ -176,7 +183,7 @@ sponge 支持创建 `单体应用单体仓库(monolith)`、`微服务多仓库(m
├── configs # 配置文件的目录
├── deployments # 裸机、docker、k8s部署脚本目录
├── docs # 设计文档和界面文档目录
├── internal # 业务逻辑代码目录
├── internal # 项目内部代码目录
│ ├── cache # 基于业务包装的缓存目录
│ ├── config # Go结构的配置文件目录
│ ├── dao # 数据访问目录
@@ -200,7 +207,7 @@ sponge 支持创建 `单体应用单体仓库(monolith)`、`微服务多仓库(m
<br>
2. 创建`微服务单体仓库(mono-repo)`代码目录结构(大仓库代码目录结构)如下：
2. 创建`微服务单体仓库(mono-repo)`(大仓库)代码目录结构如下：
```bash
.
@@ -220,15 +227,9 @@ sponge 支持创建 `单体应用单体仓库(monolith)`、`微服务多仓库(m
<br>
### sponge 开发文档
### 代码示例
点击查看 [sponge 开发项目的详细文档](https://go-sponge.com/zh-cn/)，包括代码生成、开发、配置、部署说明等。
<br>
### 使用示例
#### 使用 sponge 创建服务示例
#### sponge 创建服务代码示例
- [基于sql创建web服务(包括CRUD)](https://github.com/go-dev-frame/sponge_examples/tree/main/1_web-gin-CRUD)
- [基于sql创建grpc服务(包括CRUD)](https://github.com/go-dev-frame/sponge_examples/tree/main/2_micro-grpc-CRUD)
@@ -237,11 +238,6 @@ sponge 支持创建 `单体应用单体仓库(monolith)`、`微服务多仓库(m
- [基于protobuf创建grpc网关服务](https://github.com/go-dev-frame/sponge_examples/tree/main/5_micro-gin-rpc-gateway)
- [基于protobuf创建grpc+http服务](https://github.com/go-dev-frame/sponge_examples/tree/main/_10_micro-grpc-http-protobuf)
#### 使用 sponge 开发完整项目示例
- [简单的社区web后端服务](https://github.com/go-dev-frame/sponge_examples/tree/main/7_community-single)
- [简单的社区web后端服务拆分为微服务](https://github.com/go-dev-frame/sponge_examples/tree/main/8_community-cluster)
#### 分布式事务示例
- [简单的分布式订单系统](https://github.com/go-dev-frame/sponge_examples/tree/main/9_order-grpc-distributed-transaction)
@@ -250,7 +246,12 @@ sponge 支持创建 `单体应用单体仓库(monolith)`、`微服务多仓库(m
#### sponge+AI 助手协同开发示例
- [家电零售管理平台](https://github.com/go-dev-frame/sponge_examples/tree/main/_15_appliance_store)
- [家电零售管理](https://github.com/go-dev-frame/sponge_examples/tree/main/_15_appliance_store)
#### sponge 开发项目示例
- [社区后端服务](https://github.com/go-dev-frame/sponge_examples/tree/main/7_community-single)
- [单体服务拆分为微服务](https://github.com/go-dev-frame/sponge_examples/tree/main/8_community-cluster)
<br>
<br>

BIN
assets/sponge-framework.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 109 KiB

After

Width:  |  Height:  |  Size: 124 KiB

BIN
assets/sponge-ui.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 172 KiB

After

Width:  |  Height:  |  Size: 163 KiB

BIN
assets/template-framework.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 60 KiB

After

Width:  |  Height:  |  Size: 60 KiB

3
codecov.yml
View File

@@ -16,3 +16,6 @@ coverage:
ignore:
- "vendor/**/*"
- "**.pb.go"
- "configs/**/*"
- "test/**/*"
- "third_party/**/*"