企业官网建设流程全解析

• 数据库
• 关系型数据库
• 后端
• CLI

本文以 Dolt 仓库中的integration-tests/orm-tests/hibernate冒烟测试工程为主体，系统讲解如何用 Java + Hibernate + MySQL JDBC 驱动对 Dolt 的 sql-server 模式进行 CRUD 兼容性验证。读完本文，你将掌握该测试工程的连接配置机制、实体与 CRUD 代码结构、Maven 运行步骤，以及它如何被 bats/Docker 流水线自动执行。

测试工程的定位：ORM 兼容性验证体系中的一环

Dolt 是一个兼容 MySQL 协议的数据库，其 sql-server 模式对外暴露标准的 MySQL 网络协议，因此理论上任何支持 MySQL 的 ORM 框架（Hibernate、Prisma、TypeORM、MikroORM、Peewee 等）都能接入。为了持续验证这一兼容性，仓库在integration-tests/orm-tests/下维护了一套 ORM 客户端测试：正如 integration-tests/orm-tests/README.md 所述，这些测试"验证各种支持 MySQL 的 ORM 库与 Dolt 的兼容性"，理想情况下复用 ORM 自带的官方测试套件，但在部分场景下先从一个更小的冒烟测试（smoke test）起步，快速获得初步覆盖。

本文聚焦其中的 Hibernate 冒烟测试工程，即 integration-tests/orm-tests/hibernate/README.md 所描述的DoltHibernateSmokeTest：

• 测试形态：一个由 Maven 管理的 Java 工程，使用 MySQL JDBC 驱动连接 Dolt sql-server；
• 测试内容：向数据库插入记录、打印变更前数据、更新与删除行、再次打印变更后数据；
• 结果语义：全程无错误则以退出码 0 结束；任何异常都会被记录，并以非零退出码退出——这一语义让测试可被 CI 脚本直接断言。

工程结构与关键文件一览

DoltHibernateSmokeTest是一个标准的 Maven 单模块工程，其目录结构如下：

integration-tests/orm-tests/hibernate/DoltHibernateSmokeTest/ ├── pom.xml └── src/ └── main/ ├── java/com/dolt/hibernate/ │ ├── Test.java # 主入口，执行 CRUD 全流程 │ ├── Util.java # 构建 Hibernate SessionFactory │ └── model/Student.java # JPA 实体类 └── resources/ └── hibernate.cfg.xml # Hibernate 核心配置

四个文件各司其职：

依赖与构建配置：Hibernate 6 + MySQL Connector/J 8

pom.xml 是理解该工程运行环境的关键，其要点如下：

<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>11</maven.compiler.release> </properties> <dependencies> <!-- Hibernate --> <dependency> <groupId>org.hibernate.orm</groupId> <artifactId>hibernate-core</artifactId> <version>6.6.55.Final</version> </dependency> <!-- MySQL --> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <version>8.2.0</version> </dependency> </dependencies>

• Java 版本：通过maven.compiler.release锁定为 Java 11，并由maven-compiler-plugin（版本 3.10.1）配合--release参数强制执行；
• Hibernate 版本：org.hibernate.orm:hibernate-core6.6.55.Final。Hibernate 6 使用jakarta.persistence命名空间（后文的Student.java即为佐证），这也意味着实体类是基于 Jakarta Persistence 规范编写的；
• JDBC 驱动：com.mysql:mysql-connector-j8.2.0，即 MySQL Connector/J 8.x 系列，其驱动类为com.mysql.cj.jdbc.Driver（与 hibernate.cfg.xml 中的配置一致）；
• 运行插件：exec-maven-plugin（版本 3.1.0）将主类指定为com.dolt.hibernate.Test，这是mvn exec:java能直接启动测试的机制来源。

数据库连接配置：hibernate.cfg.xml 与环境变量覆盖

原文档明确指出：数据库设置位于hibernate.cfg.xml，并默认连接运行在默认端口上的 Dolt sql-server，用户名为dolt、无密码、数据库名为dolt。实际工程中的 hibernate.cfg.xml 内容如下：

<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE hibernate-configuration SYSTEM "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd"> <hibernate-configuration> <session-factory> <property name="hibernate.dialect">org.hibernate.dialect.MySQLDialect</property> <property name="hibernate.connection.driver_class">com.mysql.cj.jdbc.Driver</property> <property name="show_sql">true</property> <property name="format_sql">false</property> <mapping class="com.dolt.hibernate.model.Student"/> </session-factory> </hibernate-configuration>

逐项解读：

• hibernate.dialect：指定为org.hibernate.dialect.MySQLDialect，让 Hibernate 按 MySQL 方言生成 SQL（分页、类型映射、标识符生成策略等）；
• hibernate.connection.driver_class：com.mysql.cj.jdbc.Driver，即 MySQL Connector/J 8.x 的驱动类；
• show_sql/format_sql：控制是否在控制台输出生成的 SQL 及是否格式化，冒烟测试中开启show_sql=true，便于直接观察 Hibernate 发给 Dolt 的语句；
• <mapping class>：注册 JPA 实体com.dolt.hibernate.model.Student。

需要特别注意的是：连接 URL、用户名、密码并不写死在此 XML 中，而是由 Util.java 在运行时从环境变量读取并覆盖：

Configuration config = new Configuration(); config.setProperty("hibernate.connection.url", "jdbc:" + System.getenv("DB_URL")); config.setProperty("hibernate.connection.username", System.getenv("DB_USER")); config.setProperty("hibernate.connection.password", System.getenv("DB_PASSWORD")); sessionFactory = config.configure().buildSessionFactory();

实现细节：

• config.configure()会先加载 classpath 下的hibernate.cfg.xml（提供方言、驱动、SQL 日志与实体映射等静态配置）；
• 随后以编程方式setProperty覆盖 URL/用户名/密码三项连接参数；
• 连接 URL 由环境变量DB_URL拼上前缀jdbc:得到。参考 bats 测试中的构造方式（见下文），其形态如jdbc:mysql://127.0.0.1:PORT/REPO_NAME，即最终完整的 JDBC URL 为jdbc:mysql://host:port/dbname；
• DB_USER对应连接用户名，DB_PASSWORD对应密码；
• 静态块中若buildSessionFactory()抛错，会打印 "Session Factory could not be created." 并抛出ExceptionInInitializerError，使进程以失败状态终止——这符合冒烟测试"遇错即失败"的语义。

这一"环境变量注入连接参数"的设计，使同一个工程可以被 bats 测试、Docker 流水线以不同的端口、用户和数据库复用，而无需改动 XML。

实体与 CRUD 主流程：Test.java 全链路剖析

JPA 实体：Student

Student.java 是一个标准 Jakarta Persistence 实体：

@Entity @Table(name = "STUDENT") public class Student implements Serializable { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private int id; @Column(name = "FIRST_NAME", nullable = false) private String firstName; @Column(name = "LAST_NAME", nullable = false) private String lastName; @Column(name = "SECTION", nullable = false) private String section; // getter / setter / hashCode / equals / toString ... }

要点：

• @Table(name = "STUDENT")映射到数据库表STUDENT；注意 bats 测试中手工建表用的正是全大写的表名STUDENT与全大写的列名FIRST_NAME、LAST_NAME、SECTION（见下文自动化运行一节）；
• @GeneratedValue(strategy = GenerationType.IDENTITY)使用自增主键，对应 Dolt/MySQL 的AUTO_INCREMENT；
• @Column(nullable = false)声明三列非空，与建表语句中的NOT NULL约束一致；
• 实现Serializable、hashCode、equals与toString，是 Hibernate 实体管理（一级缓存、脏检查）的常规要求。

主入口：CRUD 冒烟流程

Test.java 的main方法串起完整流程，其操作与输出与文档描述完全对应：

1. 插入（Save）：调用saveStudent依次写入 4 名学生（Sam、Joshua、Peter、Bill），session.save()返回自增 id；
2. 变更前读取（Read before）：getAllStudents用 HQLFROM Student s ORDER BY s.firstName ASC查询全部记录，并打印 "List of all persisted students >>>"；
3. 更新（Update）：updateStudent(studentId4, "ARTS")取出 id=4 的学生，把 section 改为 "ARTS"。代码中特意注释了//session.update(student)无需手动调用——因为在事务提交（commit）时 Hibernate 的脏检查会自动把对受管实体（persistent object）的修改刷写（flush）到数据库；
4. 删除（Delete）：deleteStudent(studentId2)删除 Joshua 那条记录；
5. 变更后读取（Read after）：再次查询并打印 "List of all remained persisted students >>>"。

每个方法都遵循标准的 Hibernate 事务模板：openSession()→beginTransaction()→ 执行操作 →commit()→close()。这份代码本身就是"如何用 Hibernate 对 Dolt 做增删改查"的最小可运行示例：插入、带排序查询、按主键加载并修改、按主键加载并删除。

运行步骤：四步完成冒烟测试

原文档给出的运行方式如下，进入工程目录后依次执行：

cd DoltHibernateSmokeTest mvn clean install mvn clean package mvn exec:java

• 前置条件：系统需已安装 Maven（原文档提示参考 Maven 官方安装文档）；同时需要一个正在运行、可连接的 Dolt sql-server，且按前文所述准备好DB_URL、DB_USER、DB_PASSWORD环境变量；
• mvn clean install：清理并构建、安装到本地仓库（含编译与测试阶段，工程本身无单元测试）；
• mvn clean package：清理并打包成 jar（生成target/产物）；
• mvn exec:java：由 exec-maven-plugin 启动com.dolt.hibernate.Test主类，输出上述 CRUD 全流程日志。

关于"默认端口"与 Dolt sql-server：原文档说该配置默认命中"默认端口上的 Dolt sql-server"。从 Dolt 服务端源码看，Dolt sql-server 的默认端口即为 MySQL 惯例端口 3306——go/libraries/doltcore/servercfg/serverconfig.go 中定义了DefaultPort = 3306，并在无显式配置时使用该默认值。也就是说，若不通过环境变量覆盖，连接将落在本机 3306 端口；实际运行时（如 bats 流水线）通常会为每个测试实例分配一个动态端口并通过DB_URL注入。启动 Dolt sql-server 的一般方式是在仓库目录下运行dolt sql-server（亦可通过dolt sql-server --port <port>指定端口）。

自动化执行：bats 测试与 Docker 流水线

该冒烟测试并非只能手动运行，它已被纳入仓库的自动化测试体系。

bats 测试用例

在 integration-tests/orm-tests/orm-tests.bats 中，Hibernate 冒烟测试对应如下用例：

@test "Hibernate smoke test" { # need to create tables for it before running the test mysql -D "$DB_NAME" -e "create table STUDENT (id INT NOT NULL auto_increment PRIMARY KEY, first_name VARCHAR(30) NOT NULL, last_name VARCHAR(30) NOT NULL, section VARCHAR(30) NOT NULL);" cd $BATS_TEST_DIRNAME/hibernate/DoltHibernateSmokeTest mvn clean install mvn clean package mvn exec:java }

关键细节：

• 先建表再跑测试：因为该工程不使用 Hibernate 的hbm2ddl自动建表，而是要求数据库预先存在STUDENT表，其 DDL 为id INT NOT NULL auto_increment PRIMARY KEY+ 三个VARCHAR(30) NOT NULL列，与实体映射完全对齐；
• 连接注入：bats 的setup()中会启动一个 Dolt sql-server（start_sql_server_with_args_no_port，绑定 0.0.0.0 与随机端口），并导出DB_HOST、DB_PORT、DB_USER=root、DB_PASSWORD=""、DB_NAME，再通过export_DB_URL组装出DB_URL="mysql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}"——这些正是Util.java所依赖的三个环境变量，由此完成"每轮测试一个独立数据库实例"的隔离；
• 失败语义：Test.main中任何未捕获异常都会导致非零退出码，bats 会据此判定用例失败。

Docker 一键运行

仓库层面还提供了统一的 Docker 化运行方式（见 integration-tests/orm-tests/README.md）：

docker build -t orm-tests -f dolt/integration-tests/orm-tests/Dockerfile . docker run orm-tests:latest

该 Dockerfile 采用多阶段构建：先在dolt_build阶段编译出dolt二进制，再在 ORM 测试运行时阶段复用缓存产物，从而加速首次镜像构建、并在仅改动 ORM 测试时命中缓存。镜像内通过 orm-tests-entrypoint.sh 先完成 Dolt 全局配置（关闭 metrics、设置 user.name/user.email），再调用bats /orm-tests/orm-tests.bats批量执行包括 Hibernate 在内的全部 ORM 用例。若需基于本地源码构建 go-mysql-server 等 Dolt 依赖，可在 Dockerfile 的dolt_build阶段的build/目录中追加COPY指令，并同步在本地dolt/的go.mod中维护replace指令。

预期输出与结果判定

成功运行时，程序会依次打印：

List of all persisted students >>> Persisted Student :[Student 记录列表（按 first_name 升序）] List of all remained persisted students >>> Persisted Student :[删除与更新后的剩余记录列表]

由于show_sql=true，标准输出中还会伴随 Hibernate 生成的 SQL（INSERT、SELECT、UPDATE、DELETE）。验证要点：

• 插入：4 条记录全部落库且拿到自增 id；
• 变更前查询：返回 4 条，排序生效；
• 更新：id=4 的 section 变为 "ARTS"，且无需显式session.update()，事务提交即生效；
• 删除：id=2 的记录消失，最终只剩 3 条；
• 退出码：全流程无异常则进程以 0 退出，可被脚本/CI 直接断言；出现任何连接失败、SQL 错误或映射异常时，异常被记录且进程以非零码退出。

小结

DoltHibernateSmokeTest是一个麻雀虽小、五脏俱全的兼容性验证样本：它以 Hibernate 6 + MySQL Connector/J 8 连接 Dolt 的 sql-server，通过hibernate.cfg.xml提供方言与驱动配置、通过环境变量注入连接参数，用Student实体与Test主类完成插入、查询、更新、删除的完整闭环。它既可以被mvn clean install / clean package / exec:java手工驱动，也被 orm-tests.bats 与 Docker 流水线自动执行，是研究"Dolt 如何兼容 Java 生态 ORM"以及"如何自建 ORM 冒烟测试"的一份可直接复用的参考工程。

• 数据库
• 关系型数据库
• 后端
• CLI