Update README.md

2025-07-03 00:52:41 +00:00 · 2025-07-03 00:52:41 +00:00 · 2cbcbab877
parent 83c61e9c42
commit 2cbcbab877
1 changed files with 129 additions and 321 deletions
--- a/README.md
+++ b/README.md
@ -1,259 +1,149 @@
-# 🚀 Bunny Code Generator 代码生成器系统文档

-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)[![Java Version](https://img.shields.io/badge/JDK-17-green.svg)]()[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.4.3-6DB33F.svg)]()

-## 1. 系统架构 🏗️
+🚀 Bunny Code Generator 代码生成器系统文档

-### 1.1 架构图
+### 🌟 项目简介
+Bunny Code Generator 是一个高效、灵活的代码生成工具，支持从数据库表或SQL语句生成前后端代码，适用于多种数据库和前端框架。该项目采用现代化架构，具有良好的扩展性和维护性。

-```mermaid
-graph TD
-    A[🖥️ 前端界面] -->|HTTP请求| B[🌐 WebController]
-    A -->|API调用| C[⚙️ GeneratorController]
-    A -->|SQL解析| D[🔍 SqlParserController]
-    A -->|元数据查询| E[🗃️ TableController]
-    A -->|模板管理| F[📂 VmsController]
-    
-    B -->|页面跳转| G[📝 Thymeleaf模板]
-    C -->|生成请求| H[🏭 GeneratorService]
-    D -->|SQL解析| I[✂️ SqlMetadataProvider]
-    E -->|数据库查询| J[🔗 DatabaseMetadataProvider]
-    F -->|模板扫描| K[🗃️ VmsService]
-    
-    H -->|模板渲染| L[🌀 Velocity引擎]
-    H -->|打包下载| M[📦 ZipFileUtil]
-    I & J -->|数据源| N[💾 MySQL数据库]
-    J -->|连接池| O[🛟 HikariCP]
-```
+### 📦 技术栈
+- **后端**：Java 17+, Spring Boot 3.4.3, Apache Velocity, HikariCP
+- **前端**：Vue.js, Bootstrap, Axios, Day.js
+- **构建工具**：Maven
+- **模板引擎**：Velocity
+- **数据库支持**：MySQL 8.0+, 可扩展至 Oracle, PostgreSQL <20>
+- **代码质量**：后端代码质量评分 85/100，前端代码质量评分 78/100

-### 1.2 核心分层 🔍
+### 🧩 核心功能模块
+#### 1. 核心控制器
+- `GeneratorController`：主控制器，提供生成代码和下载ZIP文件的接口
+- `TableController`：获取数据库元数据信息
+- `SqlParserController`：解析SQL语句提取表和列信息
+- `WebController`：页面路由控制器
+- `VmsController`：获取前端代码模板路径

-| 层级         | 组件            | 技术实现             |
-| ------------ | --------------- | -------------------- |
-| **接入层** 🚪 | Controllers     | Spring Web, Swagger  |
-| **业务层** ⚙️ | Services        | 并行流, 设计模式     |
-| **核心层** 🧠 | 模板生成/元数据 | Velocity, JSqlParser |
-| **数据层** 💾 | 数据源/连接池   | HikariCP, JDBC       |
+#### 2. 元数据解析
+- `DatabaseMetadataProvider`：数据库元数据提取器
+- `SqlMetadataProvider`：SQL语句元数据提取器
+- `DatabaseDialect`：数据库方言接口，支持多数据库扩展
+- `MySqlDialect`：MySQL方言实现，提取注释等信息

---
+#### 3. 代码生成引擎
+- `AbstractTemplateGenerator`：抽象模板生成器，定义模板方法
+- `VmsTBaseTemplateGenerator`：具体模板实现，负责上下文填充和模板合并
+- `ZipFileUtil`：生成ZIP文件并下载
+- `MysqlTypeConvertUtil`：类型转换工具（SQL → Java/JS）

-## 2. 核心控制器详解 🎯
+### 🛠️ 核心设计模式
+- **模板方法模式**：用于定义统一的代码生成流程
+- **策略模式**：用于数据库方言的灵活切换
+- **工厂模式**：用于生成不同类型的代码
+- **建造者模式**：用于构建元数据对象

-### 2.1 GeneratorController ⚡
-
-**核心业务流：**
-
-```mermaid
-flowchart TB
-    A[接收VmsArgumentDto] --> B{判断生成方式}
-    B -->|SQL生成| C[调用generateCodeBySql]
-    B -->|数据库生成| D[调用generateCodeByDatabase]
-    C/D --> E[模板渲染]
-    E --> F{是否打包下载}
-    F -->|是| G[生成ZIP响应]
-    F -->|否| H[返回代码预览]
-```
-
-**关键方法说明：**
-
-1. `generator()` 方法：
-
-   - 🔄 根据`sql`参数判断生成方式
-
-   - 📊 使用`VmsArgumentDto`接收模板选择、包名等参数
-
-   - 🌟 核心逻辑：
-
-     ```java
-     Strings.isEmpty(sql) 
-         ? generatorService.generateCodeByDatabase(dto)
-         : generatorService.generateCodeBySql(dto);
-     ```
-
-2. `downloadByZip()` 方法：
-
-   - 🗜️ 使用`ZipFileUtil`进行内存压缩
-
-   - ⚡ 响应头设置：
-
-     ```java
-     headers.add("Content-Disposition", "attachment; filename=" + zipFilename);
-     ```
-
-### 2.2 TableController 🗃️
-
-**元数据查询体系：**
-
-```mermaid
-classDiagram
-    TableController --> TableService : 依赖
-    TableService --> DatabaseMetadataProvider : 调用
-    DatabaseMetadataProvider --> HikariDataSource : 使用
-    
-    class TableController{
-        +databaseInfoMetaData() 数据库基础信息
-        +databaseTableList() 表清单
-        +tableMetaData() 单表结构
-        +tableColumnInfo() 列详情
-    }
-```
-
-**典型调用链：**
-
-1. 获取数据库信息：
-
-   ```java
-   DatabaseMetaData metaData = connection.getMetaData();
-   return DatabaseInfoMetaData.builder()
-       .databaseProductName(metaData.getDatabaseProductName())
-       .driverVersion(metaData.getDriverVersion())
-       .build();
-   ```
-
-2. 查询表结构：
-
-   ```java
-   ResultSet tables = metaData.getTables(dbName, null, "%", new String[]{"TABLE"});
-   while(tables.next()){
-       // 构建TableMetaData对象
-   }
-   ```
-
-## 3. 关键技术实现 🔧
-
-### 3.1 模板生成流程 🌀
-
-**抽象模板方法模式：**
-
-```java
-public abstract class AbstractTemplateGenerator {
-    // 模板方法
-    public final StringWriter generateCode() {
-        prepareContext();  // 准备数据
-        return mergeTemplate(); // 渲染模板
-    }
-    protected abstract void addContext(); // 子类实现
-}
-```
-
-**Velocity上下文示例：**
-
-```java
-context.put("classLowercaseName", "userInfo"); 
-context.put("columns", columnList);
-context.put("date", "2023-01-01");
-```
-
-### 3.2 类型转换策略 🔄
-
-**MySQL类型映射：**
-
-| 数据库类型 | Java类型        | 转换方法                                   |
-| ---------- | --------------- | ------------------------------------------ |
-| `varchar`  | `String`        | `MysqlTypeConvertUtil.convertToJavaType()` |
-| `datetime` | `LocalDateTime` | 同上                                       |
-| `tinyint`  | `Integer`       | 同上                                       |
-
-**命名转换示例：**
-
-```java
-// 下划线转驼峰
-convertToCamelCase("user_name", true);  // → "UserName"
-convertToCamelCase("user_name", false); // → "userName"
-```
-
-## 4. 核心业务逻辑说明
-
-### 4.1 代码生成流程
-
-#### 4.1.1 简洁流畅
+### 📁 项目结构说明
+- `src/main/java/cn/bunny/controller`：包含所有控制器
+- `src/main/java/cn/bunny/core`：核心模块，包含元数据提取、数据库方言等
+- `src/main/java/cn/bunny/domain`：数据模型定义
+- `src/main/java/cn/bunny/exception`：异常处理模块
+- `src/main/java/cn/bunny/service`：接口定义
+- `src/main/java/cn/bunny/service/impl`：接口实现
+- `src/main/java/cn/bunny/utils`：工具类
+- `src/main/resources/static/src`：前端组件和视图
+- `src/main/resources/vms`：Velocity 模板文件
+- `src/main/resources/templates`：前端页面模板

+### 📄 代码生成流程
 ```mermaid
 sequenceDiagram
    participant F as 前端
    participant C as Controller
    participant S as Service
+    participant G as Generator
    participant T as Template
-    
-    F->>C: 提交生成请求(VmsArgumentDto)
-    C->>S: 调用generateCodeBy[Sql/Database]
-    S->>T: 准备Velocity上下文
-    T->>S: 返回渲染结果
-    S->>C: 返回Map<String, List<GeneratorVo>>
-    C->>F: 返回结果或ZIP包
+
+    F->>C: 提交生成请求
+    C->>S: 调用 GeneratorService
+    S->>G: 根据SQL或数据库表生成代码
+    G->>T: 使用 Velocity 模板合并代码
+    T-->>G: 返回生成的代码
+    G-->>S: 返回生成的代码列表
+    S-->>C: 返回生成结果
+    C-->>F: 返回代码/ZIP
 ```

-### 4.1.2 详细流程
-
-```mermaid
-sequenceDiagram
-    participant 前端
-    participant GeneratorController
-    participant GeneratorService
-    participant MetadataProvider
-    participant TemplateEngine
-    
-    前端->>GeneratorController: 提交生成请求
-    GeneratorController->>GeneratorService: 调用生成方法
-    GeneratorService->>MetadataProvider: 获取表/列元数据
-    MetadataProvider-->>GeneratorService: 返回元数据
-    GeneratorService->>TemplateEngine: 填充模板
-    TemplateEngine-->>GeneratorService: 生成代码
-    GeneratorService-->>GeneratorController: 返回生成结果
-    GeneratorController-->>前端: 返回代码/ZIP包
-```
-
-### 4.2 关键类协作
-
+### 🧱 核心类协作
 ```mermaid
 classDiagram
    class GeneratorController {
-        +generateCode()
+        +generate()
        +downloadByZip()
    }
-    
+
    class GeneratorService {
        +generateCodeByDatabase()
        +generateCodeBySql()
    }
-    
+
    class AbstractTemplateGenerator {
        +generateCode()
        #addContext()
        #templateMerge()
    }
-    
+
    class VmsTBaseTemplateGenerator {
        +addContext()
        +templateMerge()
    }
-    
+
    GeneratorController --> GeneratorService
    GeneratorService --> AbstractTemplateGenerator
    AbstractTemplateGenerator <|-- VmsTBaseTemplateGenerator
 ```

-## 5. 扩展指南 🛠️
+### 📚 快速使用指南

-### 5.1 添加新数据库支持
+#### 1. 启动项目
+```bash
+mvn spring-boot:run
+```

-1. 实现`DatabaseDialect`接口 ✏️
+#### 2. 生成代码
+```bash
+curl -X POST http://localhost:8080/api/generator \
+  -H "Content-Type: application/json" \
+  -d '{"database": "test_db", "table": "user", "package": "com.example"}'
+```

-2. 配置新的`IMetadataProvider` ⚙️
+#### 3. 打包下载代码
+```bash
+curl -X POST http://localhost:8080/api/generator/downloadByZip \
+  -H "Content-Type: application/json" \
+  -d '{"database": "test_db", "table": "user", "package": "com.example"}'
+```

-3. 示例代码结构：
+### 🧩 扩展指南

-   ```java
-   @Component
-   public class OracleDialect implements DatabaseDialect {
-       // 实现提取注释等方法
-   }
-   ```
+#### 添加新数据库支持
+1. 实现 `DatabaseDialect` 接口
+2. 创建 `IMetadataProvider` 实现
+3. 注册为Spring Bean

-### 5.2 依赖管理 📦
+示例：
+```java
+@Component
+public class OracleDialect implements DatabaseDialect {
+    @Override
+    public String extractTableComment(String tableOptions) {
+        return "提取Oracle表注释逻辑";
+    }

-**关键依赖说明：**
+    @Override
+    public String extractColumnComment(List<String> columnSpecs) {
+        return "提取Oracle列注释逻辑";
+    }
+}
+```

+#### 依赖管理
 ```xml
 <!-- SQL解析 -->
 <dependency>
@ -270,131 +160,49 @@ classDiagram
 </dependency>
 ```

-## 6. 注意事项 ⚠️
-
-### 6.1 性能优化点 🚀
-
- `parallelStream()` 用于批量生成
-
- `HikariCP` 配置：
-
+### ⚙️ 性能优化点
+- 使用 `parallelStream()` 并行处理多表生成
+- HikariCP 配置：
  ```yaml
  hikari:
    maximum-pool-size: 20
    connection-timeout: 30000
  ```

-### 6.2 版本兼容性 🔗
+### 🔄 类型转换策略
+| SQL 类型     | Java 类型   | JS 类型     |
+|-------------| ------------| ------------|
+| VARCHAR     | String       | string       |
+| INT         | Integer      | number       |
+| DATETIME    | LocalDateTime| Date         |
+| BOOLEAN     | Boolean      | boolean      |

-| 组件        | 已验证版本 |
-| ----------- | ---------- |
-| MySQL       | 8.0+       |
-| JDK         | 17+        |
-| Spring Boot | 3.4.3      |
+### 📌 注意事项
+- 确保数据库连接池配置合理
+- 多数据库支持时注意方言实现
+- 避免模板文件命名冲突（建议使用 `$className` 作为模板目录）

-### 6.3 文件名重复问题解决方案⚠️
+### 📝 版本兼容性
+| 组件        | 支持版本     |
+|-------------| -------------|
+| JDK         | 17+         |
+| MySQL       | 8.0+        |
+| Spring Boot | 3.4.3       |
+| Vue.js      | 3.x           |

-```mermaid
-graph TD
-    A[用户选择模板] --> B{是否包含$className}
-    B -->|是| C[替换为表名的小驼峰格式]
-    B -->|否| D[保持原文件名]
-    C --> E[生成唯一文件路径]
-    D --> E
-```
+### 📎 代码质量评估
+- **后端代码评分**：85/100
+  - ✅ 合理使用设计模式（模板方法模式）
+  - ✅ 完善的异常处理体系
+  - ✅ 类型转换工具类封装良好

-**核心逻辑实现**（位于`VmsGeneratorPathHelper.java`）：
-
-```java
-public static String processVmPath(VmsArgumentDto dto, String path, String tableName) {
-    String className = removeTablePrefixes(dto, tableName);
-    String lowerCamelCase = MysqlTypeConvertUtil.convertToCamelCase(tableName, false);
-    // 关键替换逻辑👇
-    String[] pathParts = path.replace("$className", lowerCamelCase).split("/");
-    ...
-}
-```
-
-**必须遵守的规则**：
-
-> [!Note]
->
-> 如果不想使用`$className`可自己修改源码，进行更改。
-
-1. 前端文件必须使用`$className`作为动态目录名（如：`web/$className/api.ts`）
-2. 相同基础名称的文件必须放在不同目录下
-3. Java/XML文件会自动添加类型后缀（如`UserController.java`）
-
-### 6.4 文件命名冲突场景示例
-
-| 错误案例                | 正确方案                   | 原因                       |
-| ----------------------- | -------------------------- | -------------------------- |
-| `web/index.vue`         | `web/$className/index.vue` | 多表生成时会冲突           |
-| `mapper/UserMapper.xml` | 自动处理                   | 系统会自动添加表名前缀     |
-| `service/Service.java`  | 自动处理                   | 会转换为`UserService.java` |
-
-## 7. 代码质量评估 🔍
-
-### 7.1 后端代码评估（85/100）
-
-**优势**：
-
- ✅ 清晰的层次划分（Controller/Service/Provider）
- ✅ 合理使用设计模式（模板方法模式）
- ✅ 完善的异常处理体系
- ✅ 类型转换工具类封装良好
-
-**待改进**：
-
- ⚠️ 部分SQL解析逻辑可抽取为策略模式
- ⚠️ 元数据提供者接口可进一步抽象
- ⚠️ ZIP打包逻辑与业务耦合稍紧
-
-**坏味道检测**：
-
-```mermaid
-pie
-    title 后端代码坏味道分布
-    "重复代码" : 15
-    "过长方法" : 10
-    "过度耦合" : 5
-    "其他" : 70
-```
-
-### 7.2 前端代码评估（78/100）
-
-**亮点**：
-
- ✅ 组件化设计合理（表单/表格分离）
- ✅ 响应式状态管理有效
- ✅ 良好的用户交互反馈
- ✅ 类型提示完善
-
-**问题点**：
-
- ⚠️ 部分表单验证逻辑重复
- ⚠️ 表格分页逻辑可抽取为独立组件
-
-**复杂度分析**：
-
-| 文件                | 方法数 | 平均行数 | 复杂度 |
-| ------------------- | ------ | -------- | ------ |
-| DatabaseTable.js    | 12     | 18       | 中等   |
-| DatabaseForm.js     | 25     | 12       | 较高   |
-| AppGeneratorPage.js | 8      | 15       | 低     |
-
-### 7.3 总结评价
-
-**整体评分**：82/100  
-
-**可维护性**：⭐️⭐️⭐️⭐️  
-
-**扩展性**：⭐️⭐️⭐️⭐️  
-
-**代码规范**：⭐️⭐️⭐️⭐️⭐️  
-
-## 8. 支持项目☕ 
+- **前端代码评分**：78/100
+  - ✅ 组件化设计合理
+  - ✅ 响应式状态管理有效
+  - ⚠️ 部分表单验证逻辑重复
+  - ⚠️ 表格分页逻辑可抽取为独立组件

+### 💚 支持项目 ☕
 如果这个项目对您有帮助，可以考虑支持我们：

 ![WeChat & Alipay](./images/wx_alipay.png)