Skip to content

Commit 22f0841

Browse files
zhufuyizhufuyi
committed
docs: update README
1 parent 9dc1aa2 commit 22f0841

13 files changed

+239
-9
lines changed

‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,7 @@ Here are some examples of using sponge to develop go projects. [Sponge](https://
3131
### DeepSeek+Sponge collaborative development examples
3232

3333
- [Appliance store](https://github.com/go-dev-frame/sponge_examples/tree/main/_15_appliance_store)
34+
35+
### Sponge+AI collaborative development examples
36+
37+
- [Home appliance retail management platform (Sponge+DeepSeek R1)](https://github.com/zhufuyi/sponge_examples/tree/main/_15_appliance_store)

‎_15_appliance_store/README.md

+116-9
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,118 @@
1-
## store
1+
## Project Practical Example —— Building a Home Appliance Retail Management Platform from Scratch
22

3-
| Feature | Value |
4-
| :----------------: | :-----------: |
5-
| Server name | `store` |
6-
| Server type | `http-pb` |
7-
| Go module name | `store` |
8-
| Repository type | `multi-repo` |
3+
Below is an example of building a product management platform for an offline home appliance store, illustrating how to use Sponge and DeepSeek to collaboratively develop backend services. The backend technology stack chosen for this example is **Web Service (Gin + Gorm + Protobuf)**.
94

10-
- [requirements document](https://github.com/go-dev-frame/sponge_examples/blob/main/_15_appliance_store/docs/requirements-document.md)
11-
- [mysql table DDL](https://github.com/go-dev-frame/sponge_examples/blob/main/_15_appliance_store/docs/store.sql)
5+
> **Tip:** Here, the request and response data structures of the API interfaces are defined in Protobuf files, taking full advantage of Protobuf's benefits—parsing Protobuf to generate the necessary framework code and API interface documentation.
6+
7+
<br>
8+
9+
### 1. Generate Functional Requirements Document
10+
11+
First, generate a detailed functional requirements document using DeepSeek R1. Input the following prompt:
12+
13+
> "Now, we need to implement the backend service for a product management platform of an offline home appliance store. Please list the detailed functional requirements."
14+
15+
DeepSeek R1 will generate a comprehensive requirements document. Developers can remove unnecessary functions based on actual needs, retain the required functional modules, or add additional functional modules. Click to view the [Home Appliance Retail Management Platform Functional Requirements Document](https://github.com/go-dev-frame/sponge_examples/blob/main/_15_appliance_store/docs/requirements-document.md).
16+
17+
<br>
18+
19+
### 2. Generate MySQL Table Structure DDL
20+
21+
Next, generate the DDL for all MySQL table structures based on the functional requirements document. Input the following prompt:
22+
23+
> "Based on the functional requirements document, generate the DDL for all MySQL table structures required by the backend service. The generated SQL should be directly importable into MySQL to create tables, and each column in the tables should include English comments."
24+
25+
DeepSeek R1 will generate the corresponding MySQL table structure DDL based on the requirements document. Developers need to verify whether it fully meets the requirements and make manual adjustments if necessary. Click to view the [Home Appliance Retail Management Platform Table Structure DDL](https://github.com/go-dev-frame/sponge_examples/blob/main/_15_appliance_store/docs/store.sql).
26+
27+
After importing the MySQL table structure DDL into MySQL, it provides data structure support for subsequent code generation. Sponge can generate various module codes based on these table structures, such as CRUD API code and CRUD Protobuf definitions.
28+
29+
<br>
30+
31+
### 3. API Interface Definition
32+
33+
#### 3.1 Generate CRUD API Protobuf
34+
35+
On Sponge's code generation page, select: 【Public】→【Generate Protobuf CRUD Code】, fill in the parameters, and click the 【Download Code】 button to generate the code, as shown below:
36+
37+
![Protobuf CRUD Code](https://raw.githubusercontent.com/zhufuyi/sponge_examples/main/assets/en_store-protobuf.png)
38+
39+
> **Tip:** If there are many generated proto files, it is recommended to merge them into one file because DeepSeek R1 has a limit on the number of files that can be uploaded.
40+
41+
#### 3.2 Generate Custom API Protobuf
42+
43+
Standard CRUD APIs cannot cover all business requirements, so it is necessary to generate custom API Protobuf definitions based on the CRUD API Protobuf file and the functional requirements document.
44+
Upload the CRUD API proto file and the home appliance retail management platform functional requirements document to DeepSeek R1, and input the following prompt:
45+
46+
```
47+
All MySQL table standard CRUD API Protobuf definitions have been determined. These APIs only cover part of the backend service functions of the home appliance retail management platform. To cover all functions, please supplement custom API Protobuf definitions based on the CRUD API Protobuf definitions and the home appliance retail management platform functional requirements document. The requirements are as follows:
48+
1. Each rpc method must include option (google.api.http).
49+
2. The rpc method and its message fields must include English comments, and the rpc method must describe the logical implementation process in detail (as the basis for AI-generated business logic code).
50+
3. The supplemented APIs need to identify their belonging Protobuf service.
51+
```
52+
53+
> **Tip:** If the rpc method comments in the generated Protobuf description are not detailed enough (e.g., logical implementation process, specified technology stack), they can be manually supplemented and improved.
54+
55+
The generated custom API Protobuf, together with the CRUD API Protobuf, constitutes the complete API interface definition of the service, providing the basis for subsequent Sponge code generation.
56+
57+
<br>
58+
59+
### 4. Create Service Code
60+
61+
Take the Web service as an example (technology stack: Gin + Gorm + Protobuf) for subsequent code generation and integration.
62+
63+
#### 4.1 Generate Service Base Code
64+
65+
On Sponge's code generation page, select: 【Protobuf】→【Create Web Service】, fill in the parameters, and click the 【Download Code】 button to generate the code. As shown below:
66+
67+
![Create Service Based on Protobuf](https://raw.githubusercontent.com/zhufuyi/sponge_examples/main/assets/en_store-http-pb.png)
68+
69+
The generated code package includes the basic framework of the service. After decompressing, enter the code directory.
70+
71+
#### 4.2 Generate CRUD API Code
72+
73+
Similarly, on Sponge's code generation page, select: 【Public】→【Generate Handler CRUD Code】, fill in the parameters, and click the 【Download Code】 button to generate the code, as shown below:
74+
75+
![Generate Handler-PB Code](https://raw.githubusercontent.com/zhufuyi/sponge_examples/main/assets/en_store-handler-pb.png)
76+
77+
Decompress the file and move the generated `api` and `internal` directories to the service code directory.
78+
79+
Open the project code using VS Code or Goland, and manually merge the custom API Protobuf files generated earlier by DeepSeek R1 into the corresponding proto files in the `api/store/v1` directory.
80+
Then, execute the following command in the project root directory to generate the code:
81+
82+
```bash
83+
make proto
84+
```
85+
86+
> **Tip:** Whenever the proto file is modified, the `make proto` command needs to be re-executed. Code generation can be specified by the proto file name.
87+
88+
<br>
89+
90+
### 5. Business Logic Code Completion
91+
92+
Sponge integrates the DeepSeek API, which can automatically locate the method functions that need to be supplemented with business logic, allowing the AI assistant to generate business logic implementation code. Execute the following command:
93+
94+
```bash
95+
sponge assistant generate --type=deepseek --model=deepseek-reasoner --api-key=xxxx --dir=.
96+
```
97+
98+
The generated business logic code will be saved in the corresponding directory with a `.assistant` suffix. Developers only need to copy it into the corresponding method functions. The reason for not using automatic filling here is that DeepSeek R1 output may include markdown and other non-pure Go code, so manual verification and copying are required.
99+
100+
<br>
101+
102+
### 6. Test and Verify API Functions
103+
104+
At this point, most of the code has been automatically generated through the collaboration of Sponge and DeepSeek. If the AI assistant cannot meet the requirements based on detailed prompts to generate business logic implementation code, manual coding is required. The complete web service code egg model is as follows:
105+
106+
![web-http-pb-anatomy](https://raw.githubusercontent.com/zhufuyi/sponge_examples/main/assets/en_web-http-pb-anatomy.png)
107+
108+
Next, developers debug and verify the API functions, start the service:
109+
110+
```bash
111+
make run
112+
```
113+
114+
Use a browser to access the Swagger interface for API debugging: [http://localhost:8080/apis/swagger/index.html](http://localhost:8080/apis/swagger/index.html)
115+
116+
![Swagger Debug Interface](https://raw.githubusercontent.com/zhufuyi/sponge_examples/main/assets/store-swagger.png)
117+
118+
> This is the [backend service example code](https://github.com/go-dev-frame/sponge_examples/tree/main/_15_appliance_store) generated by Sponge and DeepSeek collaboration.

‎_15_appliance_store/docs/readme-cn.md

+119
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
## 项目实战示例 —— 从零开始构建家电零售管理平台
2+
3+
下面以构建一个线下家电实体店的产品管理平台为例，说明如何利用 Sponge 与 DeepSeek 协同开发后端服务。本示例后端技术栈选择 **Web 服务 (Gin + Gorm + Protobuf)**。
4+
5+
> **提示：** 这里把 API 接口的请求和返回数据结构定义在 Protobuf 文件中，充分利用 Protobuf 的优势——解析Protobuf来生成框架所需的代码和API接口文档。
6+
7+
<br>
8+
9+
### 1. 生成功能需求文档
10+
11+
首先，通过 DeepSeek R1 生成详细的功能需求文档。输入以下提示：
12+
13+
> “现在需要实现线下家电实体店铺的产品管理平台的后台服务，请列出详细的功能需求。”
14+
15+
DeepSeek R1 会生成一个较为全面的需求文档，开发者可以根据实际需要删减不必要的功能，保留真正需要的功能模块，或额外添加补充功能模块。点击查看[家电零售管理平台功能需求文档](https://github.com/go-dev-frame/sponge_examples/blob/main/_15_appliance_store/docs/requirements-document.md)。
16+
17+
<br>
18+
19+
### 2. 生成 MySQL 表结构 DDL
20+
21+
接下来，根据功能需求文档生成所有 MySQL 表结构的 DDL。输入以下提示：
22+
23+
> “根据功能需求文档，生成后台服务所需的所有 MySQL 表结构的 DDL，要求生成的 SQL 可直接导入 MySQL 创建表，表的每列均需附带中文注释。”
24+
25+
DeepSeek R1 会根据需求文档生成对应的 Mysql 表结构 DDL，开发者需要校验判断是否完全满足要求，如果不满足可以人工调整。点击查看[家电零售管理平台表结构DDL](https://github.com/go-dev-frame/sponge_examples/blob/main/_15_appliance_store/docs/store.sql)。
26+
27+
把 Mysql 表结构 DDL 导入 MySQL 后，即可为后续代码生成提供数据结构支持。Sponge 可以根据这些表结构生成各种模块代码，如 CRUD API 代码 和 CRUD Protobuf 定义等。
28+
29+
<br>
30+
31+
### 3. API 接口定义
32+
33+
#### 3.1 生成 CRUD API Protobuf
34+
35+
在 Sponge 的生成代码页面中，依次选择：【Public】→【生成 Protobuf CRUD 代码】，填写参数后点击【下载代码】按钮生成代码，如下图所示：
36+
37+
![Protobuf CRUD 代码](https://raw.githubusercontent.com/zhufuyi/sponge_examples/main/assets/store-protobuf.png)
38+
39+
> **提示：** 如果生成的 proto 文件较多，建议将它们合并到一个文件中，因为 DeepSeek R1 上传文件数量有限制。
40+
41+
#### 3.2 生成自定义 API Protobuf
42+
43+
标准的 CRUD API 并不能涵盖所有业务需求，因此需要根据 CRUD API Protobuf 文件和功能需求文档生成自定义 API 的 Protobuf 定义。
44+
在 DeepSeek R1 中上传 CRUD API 的 proto 文件和家电零售管理平台功能需求文档，并输入如下提示：
45+
46+
```
47+
已确定所有 MySQL 表的标准 CRUD API 的 Protobuf 定义，这些 API 仅涵盖家电零售管理平台后台服务的一部分功能，为了涵盖所有的功能，请依据CRUD API 的 Protobuf 定义和家电零售管理平台的功能需求文档，进行补充自定义API Protobuf，要求如下：
48+
1. 每个 rpc 方法必须包含 option (google.api.http)。
49+
2. rpc 方法及其 message 字段需附带中文注释，rpc 方法需详细描述逻辑实现过程（作为 AI 生成业务逻辑代码的依据）。
50+
3. 补充的 API 需要标识其所属的 Protobuf service。
51+
```
52+
53+
> **提示：** 若生成结果中 Protobuf 描述里的 rpc 方法注释不够详细(例如逻辑实现过程、指定技术栈)，可以适当人工补充完善。
54+
55+
生成的自定义 API Protobuf 与 CRUD API Protobuf 共同构成了服务完整功能的API接口定义，为后续 Sponge 提供生成代码依据。
56+
57+
<br>
58+
59+
### 4. 创建服务代码
60+
61+
以 Web 服务为例（技术栈：Gin + Gorm + Protobuf）进行后续代码生成和集成。
62+
63+
#### 4.1 生成服务基础代码
64+
65+
在 Sponge 代码生成的页面中，选择：【Protobuf】→【创建 Web 服务】，填写参数后点击【下载代码】按钮生成代码。如下图所示：
66+
67+
![基于protobuf创建服务](https://raw.githubusercontent.com/zhufuyi/sponge_examples/main/assets/store-http-pb.png)
68+
69+
生成的代码包中包含服务的基本框架，解压后进入代码目录。
70+
71+
#### 4.2 生成 CRUD API 代码
72+
73+
同样在 Sponge 代码生成的页面中，选择：【Public】→【生成 Handler CRUD 代码】，填写参数后点击【下载代码】按钮生成代码，如下图所示：
74+
75+
![生成handler-pb代码](https://raw.githubusercontent.com/zhufuyi/sponge_examples/main/assets/store-handler-pb.png)
76+
77+
解压文件，将生成的 `api` 和 `internal` 目录移动至服务代码目录中。
78+
79+
使用 VS Code 或 Goland 打开项目代码，并将在前面由 DeepSeek R1 生成的自定义 API 的 Protobuf 文件人工合并到 `api/store/v1` 目录下对应的 proto 文件中。
80+
接着，在项目根目录下执行以下命令生成代码：
81+
82+
```bash
83+
make proto
84+
```
85+
86+
> **提示：** 每当修改 proto 文件后，都需重新执行 `make proto` 命令，可通过指定 proto 文件名生成代码。
87+
88+
<br>
89+
90+
### 5. 业务逻辑代码补全
91+
92+
Sponge 集成了 DeepSeek API，可自动定位到需要补充业务逻辑的方法函数，让 AI 助手生成业务逻辑实现代码，执行如下命令：
93+
94+
```bash
95+
sponge assistant generate --type=deepseek --model=deepseek-reasoner --api-key=xxxx --dir=.
96+
```
97+
98+
生成的业务逻辑代码会以 `.assistant` 为后缀保存在相应目录下，开发者只需将其复制到对应方法函数中即可。这里不采用自动填充的方式，是因为 DeepSeek R1 输出可能包含 markdown 等非纯 Go 代码，故需人工校验复制。
99+
100+
<br>
101+
102+
### 6. 测试和验证 API 功能
103+
104+
至此，通过 Sponge 与 DeepSeek 的协同工作，绝大部分代码均已自动生成。如果AI助手根据详细的提示生成业务逻辑实现代码也无法满足要求，则需要人工编写代码。完整的web服务代码鸡蛋模型如下：
105+
106+
![web-http-pb-anatomy](https://raw.githubusercontent.com/zhufuyi/sponge_examples/main/assets/web-http-pb-anatomy.png)
107+
108+
接着开发者调试与验证 API 功能，启动服务：
109+
110+
```bash
111+
make run
112+
```
113+
114+
使用浏览器访问 Swagger 界面进行 API 调试：http://localhost:8080/apis/swagger/index.html
115+
116+
![Swagger 调试界面](https://raw.githubusercontent.com/zhufuyi/sponge_examples/main/assets/store-swagger.png)
117+
118+
> 这是 Sponge 与 DeepSeek协同生成的[后端服务示例代码](https://github.com/go-dev-frame/sponge_examples/tree/main/_15_appliance_store)。
119+

‎assets/en_store-handler-pb.png

186 KB
Loading

‎assets/en_store-http-pb.png

109 KB
Loading

‎assets/en_store-protobuf.png

178 KB
Loading

‎assets/en_web-http-pb-anatomy.png

-55.7 KB
Loading

‎assets/sponge-framework.png

109 KB
Loading

‎assets/store-handler-pb.png

171 KB
Loading

‎assets/store-http-pb.png

99.4 KB
Loading

‎assets/store-protobuf.png

164 KB
Loading

‎assets/store-swagger.png

253 KB
Loading

‎assets/web-http-pb-anatomy.png

-77.3 KB
Loading

0 commit comments

Comments
 (0)