# kunter-generator

**Repository Path**: nature/kunter-generator

## Basic Information

- **Project Name**: kunter-generator
- **Description**: 一款革新性的 MyBatis 全链路代码生成器。基于 Dynamic SQL 模式告别臃肿 XML；支持以 Excel 或 DB 为数据源，双向生成全套源码（Entity/DAO/Service/Controller）、建表 DDL 及数据字典；适配 MySQL、PG、Oracle、SQL Server。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: dynamic-sql
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 65
- **Forks**: 36
- **Created**: 2015-05-25
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: code-generator

**Tags**: None

## README

# Kunter Generator

---

**kunter-generator** 是一款企业级高可用的 MyBatis 代码脚手架生成工具。它旨在深度融合前沿后端技术，帮助研发团队瞬间构建出符合规范、优雅且极高性能的底层代码。

## 🌟 核心愿景与架构演进

当前项目主干分支 (`dynamic-sql`) 已经脱胎换骨，从一个基础的代码生成工具，升级为**高度约束与解放双手的开发引擎**。它最大的亮点在于实现了“代码”与“数据库”之间的**双向解析生成链路**：

> 📖 **架构深度解析**：如果您想了解底层生成器引擎的全景图，以及运行时 Eo/Vo/Dto 的数据流转奥秘，请参阅我们的 [核心架构白皮书 (Architecture)](docs/architecture.md)。

1. **“代码优先 (Excel 驱动)”模式**：
   - 输入：整理好的 Excel 数据字典。
   - 输出：全套 Java 代码模型（Controller、Service、Dao、Entity、Vo、Dto） + 数据库 `schema.sql` 建表脚本。
2. **“库优先 (DB 驱动)”模式**：
   - 输入：MySQL 等结构化关系型数据库。
   - 输出：全套 Java 代码模型 + 逆向生成的全量 Excel 格式数据字典（`表结构一览.xlsx`），极大地便利了接手老项目时的文档补充工作。

### 技术栈全面革新
- **全面拥抱 MyBatis Dynamic SQL**：摒弃传统 XML 的 `<if>` 条件拼接，通过生成强类型的 `DynamicSqlSupport` 和 Provider，支持原生的 Java Lambda 安全链式查询。
- **严格的实体与职责分层**：
  - **Eo** (Entity Object)：持久层专属实体，安全收敛。
  - **Vo** (View Object)：入参传输视图对象。
  - **Dto** (Data Transfer Object)：出参响应对象。
- **MapStructPlus 深度集成**：生成出的 Vo 和 Dto 自带 `@AutoMapper` 映射注解，结合注入 `Converter`，无需编写任何映射接口与 `BeanUtils` 拷贝逻辑。
- **Lombok 最佳实践**：原生内置 `@SuperBuilder` 构建器体系，天然支持 `BaseEo/BaseVo/BaseDto` 的继承与公共属性追溯。

## 🚀 快速开始 (Quick Start)

我们提供了一个演示工程 `kunter-generator-demo` 供您直接体验。您可以选择两种方式生成代码。

### 方式一：通过 Main 方法直启（适合调试开发）
在 `kunter-generator-demo` 模块中，找到 `CoreRunnerDemo.java` 并直接运行其 `main` 方法，代码将生成在 `target/generated-sources/` 目录下。

### 方式二：通过 Maven Plugin 触发（适合项目集成）

为了在业务项目中自动读取配置并生成代码，您可以引入我们发布在 GitHub Packages 上的 Maven 插件。

**第一步：在业务项目的 `pom.xml` 中引入插件**
```xml
<build>
    <plugins>
        <plugin>
            <groupId>cn.kunter</groupId>
            <artifactId>kunter-generator-maven-plugin</artifactId>
            <version>3.0.0-SNAPSHOT</version> <!-- 请替换为发布的真实版本 -->
        </plugin>
    </plugins>
</build>
```

**第二步：配置拉取权限 (GitHub Packages)**
由于我们使用了 GitHub Packages 作为发布源，拉取插件需要在您本地的 `~/.m2/settings.xml` 中配置 Personal Access Token (PAT)，并声明插件仓库：

```xml
<settings>
  <profiles>
    <profile>
      <id>github</id>
      <pluginRepositories>
        <pluginRepository>
          <id>github</id>
          <url>https://maven.pkg.github.com/yangziran/kunter-generator</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>github</activeProfile>
  </activeProfiles>
  <servers>
    <server>
      <id>github</id>
      <username>您的GitHub用户名</username>
      <password>ghp_xxx您的PAT口令xxx</password>
    </server>
  </servers>
</settings>
```

配置完毕后，在目标业务模块下直接执行即可生成代码：
```bash
mvn clean kunter-generator:all
```

## ⚙️ 进阶配置速查

在执行代码生成前，您可以在 `generatorConfig.properties` 中配置极其丰富的开关特性：

```properties
# 核心数据源选择（可选 mysql, oracle, postgresql, sqlserver, excel）
sourceType=excel

# --- 如果是 EXCEL 模式，填写此项 ---
excel.filePath=../docs/表结构一览.xlsm

# --- 如果是 数据库 模式，填写以下信息 ---
#jdbc.driverClass=com.mysql.cj.jdbc.Driver
#jdbc.url=jdbc:mysql://127.0.0.1:3306/your_db?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
#jdbc.username=root
#jdbc.password=123456

# 【核心特性】前缀过滤。支持逗号分隔多前缀精准剔除（如剔除 t_ 和 sys_）
table.prefix.ignore=t_,sys_

# 【核心特性】全局忽略字段。指定在生成代码时自动剔除的公共物理字段名
table.column.remove=create_time,update_time

# 【核心特性】生成 RESTful 规范控制层
# 默认为 true。如果您公司的安全网关/WAF 拦截了 PUT 和 DELETE 等方法，
# 请将其设置为 false，生成器将自动降级为 POST 方法（如 @PostMapping("/update")）。
controller.restful=true

# 当 controller.restful=false 时，是否允许查询类接口 (get, list) 继续使用 @GetMapping (默认为 true)
# true: 查询类接口使用 @GetMapping, 增删改使用 @PostMapping
# false: 所有接口严格使用 @PostMapping
controller.allowGet=true

# 【核心特性】覆盖保护策略
# 如果为 false，对于已存在的文件（如手写了扩展逻辑的 Service/Controller）生成器将跳过写入，
# 仅对 Dto、Vo、Eo、Dao 等基础模型进行强制更新覆盖。
file.override=false

# 【核心架构特性】无痕开发模式 (与 dynamic-sql-plus 结合)
# 开启后，将彻底改变持久层架构：
# 1. 实体层 (Eo) 自动追加 @DynamicMapper 等元数据注解
# 2. 彻底跳过冗长的 DynamicSqlSupport 生成，保持极度清爽的代码库
# 3. Dao 层蜕变为业务防腐层，强制跳过覆盖逻辑，仅生成一次供开发者扩展
# 需要项目中引入 cn.kunter.dynamic:dynamic-sql-plus-spring-boot-starter
dynamic.plus.enable=false

# 目标包名配置
target.project=src/main/java
base.package=cn.kunter.example
```

## 📦 依赖引入与配置指南

当您的项目使用 `kunter-generator` 生成代码后，为了让生成的代码正常编译运行，您必须在业务项目中按照以下顺序和配置引入对应的依赖。

### 1. 业务环境依赖 (Maven 示例)

```xml
<dependencies>
    <!-- MyBatis Dynamic SQL 核心依赖 -->
    <dependency>
        <groupId>org.mybatis.dynamic-sql</groupId>
        <artifactId>mybatis-dynamic-sql</artifactId>
        <version>1.5.0</version> <!-- 建议使用最新版本 -->
    </dependency>

    <!-- dynamic-sql-plus 增强框架 (如开启了 dynamic.plus.enable 则必须引入) -->
    <dependency>
        <groupId>cn.kunter</groupId>
        <artifactId>dynamic-sql-plus-spring-boot-starter</artifactId>
        <version>v1.0.0</version>
    </dependency>

    <!-- MapStructPlus Spring Boot Starter (必须) -->
    <dependency>
        <groupId>io.github.linpeilie</groupId>
        <artifactId>mapstruct-plus-spring-boot-starter</artifactId>
        <version>1.5.1</version>
    </dependency>

    <!-- Lombok (必须，建议1.18.30以上) -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.30</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

### 2. 编译插件顺序配置 (核心关键)

因为 Lombok 和 MapStructPlus 均使用了 JSR 269 编译期注解处理器 (Annotation Processor)，必须通过配置 `maven-compiler-plugin` 来保证 **先让 Lombok 生成 getter/setter -> MapStructPlus 根据注解生成 Mapper 接口 -> MapStruct 原生引擎生成最终实现类**。

请务必在 `<build><plugins>` 节点下配置：

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.8.1</version>
    <configuration>
        <source>1.8</source>
        <target>1.8</target>
        <encoding>UTF-8</encoding>
        <annotationProcessorPaths>
            <!-- 1. Lombok 优先执行 -->
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.30</version>
            </path>
            <!-- 2. MapStructPlus 拦截注解并生成 Mapper 接口 -->
            <path>
                <groupId>io.github.linpeilie</groupId>
                <artifactId>mapstruct-plus-processor</artifactId>
                <version>1.5.1</version>
            </path>
            <!-- 3. Lombok与MapStruct绑定器 -->
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok-mapstruct-binding</artifactId>
                <version>0.2.0</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>
```

## 联系我们
---
- Email：mail@yangziran.com
- QQ群：325980480

## License
---
[Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt)