# 启动服务时按实体自动建表，注解零改动复用



![image](https://developer.qcloudimg.com/http-save/yehe-2879928/4874f188bc4b65a3ea4108940614cab4.png)



实体驱动建表听起来不新鲜——Hibernate 的 `ddl-auto`、不少脚手架都能干。真正卡住的人，多半不是"会不会生成 CREATE TABLE"，而是：

- 项目根本不在 Hibernate / JPA Provider 体系里，却已经有一套带 `@Entity` 的类；
- 只要 **DDL 文本** 给 DBA，不想应用一启动就改库；
- 同一套实体要出 MySQL、PostgreSQL、达梦、Oracle，乃至 Hive / ClickHouse 好几份，注释和自增写法全不一样。

`jkit-sql` 的切入点是：**从实体扫出模型，按方言生成 DDL（以及增删改查）**；需要连库执行时，再交给 `jkit-sql-auto`。它认 jkit 自己的注解，也认 MyBatis-Plus、以及 `javax.persistence` / `jakarta.persistence` 里的标准映射注解——**没有对这些 API 的编译依赖**。

---

## 一、先澄清：`@Entity` 不是"Hibernate 专属"

文里常说"JPA 注解"，容易让人以为必须上 Hibernate / EclipseLink 全套。更准确的说法是：

`@Entity` / `@Table` / `@Column` / `@Id` / `@GeneratedValue` 等定义在 **Jakarta Persistence API**（历史包名 `javax.persistence`，现为 `jakarta.persistence`）里，也就是大家说的 **persistence-api**。Hibernate、EclipseLink 是它的实现（Provider）；Spring Data JPA、各种脚手架只是在用这套 API。

所以你会看到三种很常见、却容易被混为一谈的情况：

1. **有 persistence-api 注解，但没有 JPA Provider**——类上挂着 `@Entity`，持久化却走 MyBatis / JdbcTemplate；
2. **只有 MyBatis-Plus 注解**——`@TableName` / `@TableId`，和 persistence-api 无关；
3. **两边都有**——存量实体两套注解混用，迁移期最麻烦。

jkit 的做法是：`@Entity` / `@Table` / `@Column` / `@Id` 等按**全限定名**认 `javax.persistence.*` 与 `jakarta.persistence.*`；MyBatis-Plus 同理认其包名下的注解。只有表/列注释那类 `Comment` 注解，才按**简单类名**匹配（不绑包名）。全程**无编译依赖**——不引入 Hibernate / Spring Data / MyBatis-Plus。你不用为了"能 ddl-auto"硬塞一个 Provider，也不用为了生成 DDL 把实体改写成 jkit 注解。

---

## 二、为什么还要单独搞"生成建表 SQL / 自动建表"

![2ca0bd30-c64b-4946-92be-34705bc31716_0](https://developer.qcloudimg.com/http-save/yehe-2879928/5d978f59c8647f4a1d156381405bfe62.png)下面这些痛点，比"再写一遍 CREATE TABLE"更常见：

### 1. 只要脚本，不要启动改库

测试库可以自动建；生产往往要求：生成 DDL → DBA 评审 → 进 Flyway / Liquibase。很多工具绑死了"启动时连库执行"，缺一截"只出文本"的能力。

### 2. 同一套实体，多套库

信创迁移、双写验证、本地 MySQL + 预发达梦，都要**同一模型、不同方言**的注释 / 自增 / 序列。手写两份 DDL 很快漂移。

### 3. 开发环境想快，生产环境要稳

本地希望改实体就出表；生产只允许"追加列"，禁止默默改类型、删列。缺"只追加不收缩 + dryRun"时，自动建表不敢开。

### 4. 集成测试要临时库表

Testcontainers / 嵌入式库每次拉起都要 schema。从实体生成 DDL，比维护一份永远过期的 `schema.sql` 省心。

### 5. 微服务 / 多模块实体分散

实体散落在多个 jar，建表顺序还要顾外键。需要按包扫描，并按外键依赖排序后再出脚本。

### 6. 注释和命名要给 DBA 看

中文表注释、列注释、索引名长度（经典 Oracle 30 字符）——生成器如果不管，评审轮次会明显变多。

### 7. 已经有注解，不想为了建表换栈

类上已是 persistence-api 或 MP 注解。为了 ddl-auto 引入 Hibernate，或把注解全部改成另一套，成本都高于"读现有注解生成 SQL"。

这些场景里，你要的通常是两截能力拆开：**SqlEntities 负责生成；sql-auto 负责（可选地）执行。**

![为什么还要单独搞自动建表](https://developer.qcloudimg.com/http-save/yehe-2879928/00e747044fa4690a483e5e0a45a34268.png)

---

## 三、注解兼容性：一张表说清

| 来源                                   | 典型注解                                                     | 说明                       |
| -------------------------------------- | ------------------------------------------------------------ | -------------------------- |
| jkit 原生                              | `@SqlTable` / `@SqlId` / `@SqlColumn` / `@SqlGenerated`      | 无第三方语义依赖           |
| persistence-api（`javax` / `jakarta`） | `@Entity` / `@Table` / `@Column` / `@Id` / `@GeneratedValue` 等 | 按全限定名识别，无编译依赖 |
| MyBatis-Plus                           | `@TableName` / `@TableId` / `@TableField`                    | 同上；`exist=false` 会跳过 |

另外还认：任意简单名为 `Comment` 的注释注解、Hibernate `@ColumnDefault`（有则读，无则忽略），以及 persistence-api 的 `@Index`（含 `@Table(indexes=…)`）、`@Enumerated` / `@Embedded` 等（详见文档）。`List` / `Set` / `@OneToMany` 默认不建列。

![三套注解同一套扫描](https://developer.qcloudimg.com/http-save/yehe-2879928/0fca7046923fbc925b3c3b4a9c2f6dbf.png)

原生注解示例：

```java
import com.alianga.jkit.sql.entity.SqlEntities;
import com.alianga.jkit.sql.entity.SqlTable;
import com.alianga.jkit.sql.entity.SqlId;
import com.alianga.jkit.sql.entity.SqlGenerated;
import com.alianga.jkit.sql.entity.SqlColumn;
import com.alianga.jkit.sql.SqlDialect;

@SqlTable(name = "demo_user")
public class DemoUser {
    @SqlId @SqlGenerated Long id;
    @SqlColumn(name = "user_name", length = 32, nullable = false) String name;
    Integer age;
}

String ddl = SqlEntities.createTable(DemoUser.class, SqlDialect.POSTGRES);
// CREATE TABLE demo_user (id BIGINT NOT NULL GENERATED ALWAYS AS IDENTITY PRIMARY KEY, ...)
```

存量 persistence-api 实体则不必改注解，直接：

```java
// 类上已是 jakarta.persistence.Entity / Table / Id / Column …
String ddl = SqlEntities.createTable(OrderEntity.class, SqlDialect.MYSQL);
List<Class<?>> all = SqlEntities.scan("com.example.entity");
String batch = SqlEntities.createTables(all, SqlDialect.DAMENG);
```

---

## 四、一套实体，多方言 DDL 形态自适应

注释、自增、序列的写法因库而异，生成器要一次处理：

```java
@SqlTable(name = "t_member", comment = "会员表")
class Member {
    @SqlId Long id;
    @SqlColumn(comment = "昵称") String nick;
}

SqlEntities.createTable(Member.class, SqlDialect.MYSQL);
// MySQL：内联 COMMENT

SqlEntities.createTable(Member.class, SqlDialect.POSTGRES);
// PG：CREATE TABLE + COMMENT ON TABLE/COLUMN
```

`SqlDialect` 目前有 **13 个一等方言**：`MYSQL`、`POSTGRES`、`ORACLE`、`ORACLE12`、`SQLSERVER`、`ANSI`、`H2`、`DB2`、`SQLITE`、`HIVE`、`CLICKHOUSE`、`PRESTO`、`DAMENG`。另有一批别名可直接 `fromName(...)`——例如 `tidb` / `mariadb` / `gbase` / `doris` / `starrocks`→MySQL，`opengauss` / `gaussdb` / `kingbase`→Postgres，`dm`→达梦，`trino`→Presto——信创和衍生库不必各写一套实体。

自增形态差异大的，先看这几类：

| 方言                                        | 自增形态（差异明显）             |
| ------------------------------------------- | -------------------------------- |
| MySQL（含 TiDB / MariaDB / GBase 等别名）   | `AUTO_INCREMENT`                 |
| PostgreSQL（含 openGauss / GaussDB 等别名） | `GENERATED … AS IDENTITY`        |
| Oracle ≤11g                                 | `SEQUENCE + TRIGGER`（附录输出） |
| Oracle 12c+                                 | `GENERATED … AS IDENTITY`        |
| 达梦（`dm`）                                | 列上 `IDENTITY`                  |
| SQL Server                                  | `IDENTITY(1,1)`                  |

其余一等方言（`ANSI` / `H2` / `DB2` / `SQLITE` / `HIVE` / `CLICKHOUSE` / `PRESTO` 等）建表走同一套 `SqlDialect`，**类型、引号、注释按方言适配**，不必再维护多份实体。注释写法也会跟着变：MySQL 常内联 `COMMENT`，PostgreSQL / Oracle 一路多是 `COMMENT ON`，SQL Server 走扩展属性——生成器一并处理。

边界也要管：字符串 / UUID 主键不应生成 `IDENTITY`；经典 Oracle 索引名超长要截断。这些是手写多方言 DDL 时最容易漏的点。

![一套实体多方言 DDL](https://developer.qcloudimg.com/http-save/yehe-2879928/641e2cd802600d2d21663026ce2f741f.png)

---

## 五、jkit-sql-auto：可选的"启动时连库"

`SqlEntities` 只生成 SQL。要对比元数据并执行，用 `jkit-sql-auto`：

```java
SqlAuto.run(SqlAutoOptions.defaults()
        .url("jdbc:mysql://localhost:3306/shop")
        .username("root").password("secret")
        .packages("com.example.entity")
        .mode(SqlAutoMode.UPDATE));
```

Spring Boot 可加 starter：

```yaml
jkit:
  sql:
    auto:
      enabled: true
      mode: update
      packages: com.example.entity
      show-sql: true
```

（`jkit-sql-auto-spring-boot-2` / `-3` 分别对应 Boot 2 / Boot 3。）

常见用法拆开选：

| 目标                | 做法                                                  |
| ------------------- | ----------------------------------------------------- |
| 只给 DBA 脚本       | `SqlEntities.createTable` / `createTables`，不引 auto |
| 本地 / 测试自动对齐 | auto + `UPDATE`，可开 `show-sql`                      |
| 先看再执行          | `dryRun(true)`，打印 `plan.sql()`                     |
| 生产受控变更        | 生成文本 → 写入 Flyway；生产勿与 auto UPDATE 双开     |



![d84b5af6-f608-44b4-abef-40dd761e5ef6_0](https://developer.qcloudimg.com/http-save/yehe-2879928/ab1c35beb20b1d743f7376b5dc28b020.png)

---

## 六、生产默认 UPDATE：只追加不收缩

`SqlAutoMode`：`NONE / VALIDATE / UPDATE(默认) / CREATE / CREATE_DROP`。

- **UPDATE 默认只追加**：新列 `ALTER TABLE … ADD`；**不删列、默认不改类型、不改主键**；
- 改类型需显式 `alter-column: true`；
- 删多余列需显式 `drop-extra-columns: true`；
- `dryRun(true)` 只出计划不执行。

```java
SqlAutoPlan plan = SqlAuto.run(options.dryRun(true));
System.out.println(plan.sql());
```

自动建表最怕"自作主张弄丢数据"。破坏性操作默认关、显式开，是底线。

![10 信息图：实体驱动建表全流程](https://developer.qcloudimg.com/http-save/yehe-2879928/100c9a460ed6510cbd2685b41ea62c47.png)

---

## 七、和 Hibernate ddl-auto、Flyway 怎么分工

- **已有 Hibernate + ddl-auto**：开发期可以继续用；jkit 更适合"多方言脚本 / 无 Provider 的工程 / 只生成不执行"。
- **MyBatis / 裸 JDBC / 只有 persistence-api 注解**：不必为了建表引入 Provider；用 SqlEntities + 可选 sql-auto。
- **Flyway / Liquibase**：管版本化变更与协作；jkit 管"从实体推导结构"。常见组合是开发/测试用 auto，上线前 `dryRun` 或 `createTable` 产出交给迁移脚本。两套同时在生产改表，容易冲突。

原则就一句：**代码即 schema 的阶段用实体驱动提效；变更必须受控的阶段用版本化脚本。**

建议试用顺序：① `createTable` 只生成看差异 → ② 测试库 `dryRun` → ③ 再开 `update`（只追加）→ ④ 产物进评审，DBA 知情。

---

## 

定位没变：SQL 文本与 AST、实体与 DDL 之间的轻量工具层——不绑架框架，不替代你的 ORM，把"出 DDL / 对齐表结构"这类脏活收拢。

你那边是更需要"只生成脚本"，还是"测试环境自动建、生产走 Flyway"？评论区可以说一下栈（MP / persistence-api / 多库）。

> 文档：[https://jkit.alianga.com/](https://jkit.alianga.com/) · 源码：[jkit](https://github.com/zhengmingliang/jkit)

实体驱动建表听起来不新鲜——Hibernate 的 ddl-auto、不少脚手架都能干。真正卡住的人，多半不是"会不会生成 CREATE TABLE"，而是：

不想为了自动建表硬塞一个 Hibernate？这套方案零编译依赖、注解都不用改

编程语言

数据库

开发工具

jkit-sql是一款轻量级实体建表工具，零改动复用现有@Entity或MyBatis-Plus注解，支持生成MySQL、PostgreSQL、达梦、Oracle等13种方言DDL，无需Hibernate依赖。可按需输出脚本或执行自动建表，生产环境默认只追加不收缩，适配多库信创迁移场景，提升开发与运维效率。

集成测试

代码解释

PostgreSQL

Presto

MySQL

Hive

腾讯云数据库特惠，新用户首单0.5折起


sqlserver

2026上云采购 | AI焕新·智启新局

tchousec

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

不想为了自动建表硬塞一个 Hibernate？这套方案零编译依赖、注解都不用改-腾讯云开发者社区-腾讯云

不想为了自动建表硬塞一个 Hibernate？这套方案零编译依赖、注解都不用改

不想为了自动建表硬塞一个 Hibernate？这套方案零编译依赖、注解都不用改

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐