# template-code-generator

**Repository Path**: w823901622/template-code-generator

## Basic Information

- **Project Name**: template-code-generator
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-22
- **Last Updated**: 2026-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# template-code-generator

一个**配置驱动、模板化、零业务逻辑侵入**的代码自动生成工具。  
只需配置数据库连接和生成规则，配合 Freemarker 模板，即可一键生成 MyBatis-Plus 风格（或其他任意框架）的 Java 持久层、服务层及接口层代码。

---

## ✨ 功能特性

- **纯配置驱动**：所有生成规则（类型映射、文件命名、输出路径、模板变量）均通过 YAML 配置，生成器本身不包含任何特定于框架或业务的逻辑。
- **多数据库兼容**：内置对 MySQL、Oracle、达梦（DM DBMS）的支持，可自动查询表结构与注释。
- **灵活的类型映射**：支持数据库类型标准化（如 `VARCHAR2` → `VARCHAR`）和数据库类型到 Java 类型的自定义映射。
- **模板变量系统**：可在配置文件中定义任意变量并注入模板，适应不同项目的包路径、公共包、前缀等约定。
- **多模板支持**：可切换不同模板目录（如 `mybatisplus`、`notable`），一套代码即可适配不同技术栈。
- **字段过滤**：支持配置 VO 排除字段（如审计字段），灵活控制生成内容。
- **零业务逻辑核心**：生成器只负责读取元数据、增强元数据、渲染模板，不做任何框架假设。

---

## 🛠️ 技术栈

- **Java 17**
- **Spring Boot 3.5.15**
- **Freemarker** – 模板引擎
- **MySQL / Oracle / 达梦** – 数据库
- **Lombok** – 简化代码
- **Hutool** – 工具库
- **Apache Commons Lang3 & IO**
- **Maven** – 构建管理

---

## 🚀 快速开始

### 环境要求

- JDK 17+
- Maven 3.6+
- 可访问的目标数据库（如 MySQL）

### 1. 配置数据源与生成规则

修改 `src/main/resources/application-demo.yaml`（或创建新的 profile 配置文件）：

```yaml
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/your_db?useUnicode=true&characterEncoding=utf-8&...
    username: root
    password: your_pwd
```

更多配置项请参考 [配置文件说明](#-配置文件说明)。

### 2. 准备模板

模板文件默认放置在 `templates/mybatisplus` 目录下。项目已内置一套 MyBatis-Plus 完整模板（Controller、Service、ServiceImpl、MapperJava、MapperXml、Entity、VO 等）。你也可以添加自己的模板目录（如 `templates/my-grpc`），并在配置中指定路径。

### 3. 运行生成

通过测试类启动生成任务：

```bash
mvn test -Dtest=RunTest#testSomething
```

或在 IDE 中运行 `RunTest.testSomething()` 方法。

生成的目标代码默认输出在 `target/dist_code1` 目录下。

---

## 📁 项目结构

```
template-code-generator/
├── pom.xml
├── README.md
├── src/
│   ├── main/
│   │   ├── java/com/example/generator/
│   │   │   ├── Application.java                      # 启动类
│   │   │   ├── config/
│   │   │   │   ├── DataSourceConfig.java             # 数据源配置读取
│   │   │   │   ├── GeneratorProperties.java          # 生成任务配置
│   │   │   │   └── CodeStyleProperties.java          # 代码风格配置
│   │   │   ├── core/
│   │   │   │   ├── GeneratorService.java             # 生成主控制器
│   │   │   │   ├── MetaDataEnricher.java            # 元数据增强器
│   │   │   │   └── TemplateRender.java              # Freemarker 渲染引擎封装
│   │   │   ├── model/
│   │   │   │   ├── TableMetaData.java               # 原始表元数据
│   │   │   │   ├── ColumnMetaData.java              # 原始列元数据
│   │   │   │   ├── EnhancedTableMetaData.java       # 增强表元数据
│   │   │   │   └── EnhancedColumnMetaData.java      # 增强列元数据
│   │   │   ├── parser/
│   │   │   │   ├── TableParser.java                 # 表解析器接口
│   │   │   │   └── JdbcTableParser.java             # JDBC 实现
│   │   │   └── util/
│   │   │       └── CaseUtil.java                    # 驼峰命名工具
│   │   └── resources/
│   │       ├── application.yaml                     # 主配置
│   │       ├── application-demo.yaml                 # 生成规则配置 ★
│   │       └── logback.xml
│   └── test/
│       └── java/com/example/generator/
│           ├── RunTest.java                         # 生成任务启动测试
│           └── TemplateCodeGeneratorApplicationTests.java
└── templates/                                        # 模板文件根目录
    ├── mybatisplus/                                  # MyBatis-Plus 全套模板
    │   ├── Controller.ftl
    │   ├── Service.ftl
    │   ├── ServiceImpl.ftl
    │   ├── ModelEntity.ftl
    │   ├── MapperJava.ftl
    │   ├── MapperXml.ftl
    │   ├── VOEntity.ftl
    │   ├── VORequest.ftl
    │   └── VOResponse.ftl
    └── notable/                                      # 空壳模板（旧版占位）
        └── ...
```

---

## 📝 配置文件说明

全部生成规则集中在 `application-demo.yaml`（或其他 profile 文件）中。以下为关键配置项详解：

### 1. 生成任务 `generator`

```yaml
generator:
  author: MyName                    # 代码注释中的 @author
  template-path: templates/mybatisplus  # 模板目录相对路径
  table-entity-mapping:             # 数据库表名 → 实体类名
    users: SysUser
    orders: Order
```

### 2. 代码风格 `code-style`

#### 2.1 类型标准化与映射

```yaml
code-style:
  db-type-mappings:                # 数据库类型标准化（例如 VARCHAR2 → VARCHAR）
    VARCHAR2: VARCHAR
    CHAR: VARCHAR
    DATE: TIMESTAMP
    INT: INTEGER
  db-to-java-type-mappings:        # 标准化后的数据库类型 → Java 类型
    VARCHAR: String
    INTEGER: Integer
    BIGINT: Long
    DECIMAL: BigDecimal
    DATE: Date
    # ... 可无限扩展
```

#### 2.2 VO 字段过滤

```yaml
  vo-exclude-fields:               # 生成 VO 时排除的字段
    - deleteFlag
    - createBy
    - updateBy
    - createTime
    - updateTime
```

#### 2.3 输出路径变量

```yaml
  output: "target/dist_code1"           # 主输出目录
  output-res: "target/dist_code1/xml"   # 资源类文件输出目录
```

#### 2.4 模板 → 文件名 / 模板 → 输出路径

```yaml
  template-to-file-mappings:       # 模板文件名 → 输出文件名（支持 ${className} 占位符）
    Controller.ftl: "${className}Controller.java"
    Service.ftl: "${className}Service.java"
    # ...

  file-to-path-mappings:           # 模板文件名 → 输出目录（可使用 ${code-style.output} 引用路径变量）
    Controller.ftl: ${code-style.output}/controller
    Service.ftl: ${code-style.output}/service
    MapperXml.ftl: ${code-style.output-res}/mapper
    # ...
```

> **注意**：`${code-style.output}` 等占位符由程序在运行时解析，并非 YAML 原生语法，实现了配置内的动态路径组合。

#### 2.5 全局模板变量

```yaml
  variables:                        # 注入模板的全局变量，可任意扩展
    basePackage: org.example
```

这些变量在模板中可直接使用 `${basePackage}`、`${common}` 等。

---

## 🧩 模板编写指南

模板使用 **Freemarker** 语法。生成器会将增强后的表信息（`EnhancedTableMetaData`）、列信息列表（`enhancedColumnList`）、配置中的 `variables` 以及额外的 `author`、`date` 等数据传递给模板。

常用数据模型变量：

| 变量名 | 说明 | 示例值 |
|--------|------|--------|
| `${tableName}` | 数据库表名 | `sys_user` |
| `${tableComment}` | 表注释 | 用户表 |
| `${className}` | 实体类名（大驼峰） | `SysUser` |
| `${varName}` | 实体变量名（小驼峰） | `sysUser` |
| `${author}` | 配置的作者 | `MyName` |
| `${date}` | 生成日期 | `2026/06/22` |
| `${columnList}` | 列信息列表 | 包含 `name`, `varName`, `varType`, `comment` 等 |
| `${voExcludeFields}` | VO 排除字段列表 | 直接在模板中使用 Freemarker 集合判断 |
| `${basePackage}` 等 | 配置文件 `variables` 中定义的所有变量 | 自由引用 |

**扩展自定义模板**：
1. 在 `templates` 下新建目录，放入 `.ftl` 模板文件。
2. 在 `application-demo.yaml` 中配置 `generator.template-path` 指向该目录。
3. 在 `code-style.template-to-file-mappings` 和 `file-to-path-mappings` 中添加对应模板的映射规则。

---

## 🔧 扩展与定制

- **适配其他数据库**：在 `JdbcTableParser.parse()` 中添加对应 SQL 查询分支。
- **增加模板变量**：在 `GeneratorService.generateSingle()` 的 `model` Map 中放入新的数据，或在 `application-demo.yaml` 的 `variables` 中添加。
- **修改文件命名规则**：直接调整 `code-style.template-to-file-mappings`，支持 Freemarker 占位符。
- **切换模板风格**：更换 `generator.template-path` 指向新模板目录，并调整映射规则。

---

## ⚠️ 注意事项

1. **配置文件中的反斜杠**：`template-path` 等路径请使用正斜杠 `/`，避免 YAML 转义问题。
2. **数据库驱动**：`pom.xml` 中只引入了 MySQL 驱动，若使用 Oracle 或达梦，需自行添加对应驱动依赖。
3. **重复生成覆盖**：生成的目标目录（如 `target/dist_code1`）会被直接覆盖，注意备份。
4. **模板中的 `${}` 冲突**：Freemarker 与 `${}` 占位符冲突时，可使用 `<#noparse>` 包裹。
5. **多表生成**：`generator.table-entity-mapping` 支持配置多组映射，生成时会逐一处理。

---

## 📄 许可

本项目为内部工具，无特定开源许可证。

---

## 🙋 设计理念

本项目始终遵循 **“程序只做渲染工具，业务规则全部配置化”** 的原则。所有包路径、命名规范、类型映射、模板变量等均由配置文件定义，生成器核心保持极其纯净的元数据读取与模板渲染逻辑。这意味着：
> **换一个技术栈 = 换一套模板 + 一份配置文件，无需改动 Java 代码。**

---