实现模块与成熟度

SmartAccess 仓库包含 JDBC、JPA/Hibernate 与 reactive 多条模块线，但“Gradle 模块存在”不表示已经具备可运行实现。本页按当前源码说明真实状态。

状态总表

模块	当前状态	说明
core	核心可读	Access Loader、ASM Maker、事务协议、查询解释器
jdbc-core	未完成	Hikari DataSource 可创建，但 DBContext 与 createAccess 是 TODO
jdbc-jpa	主要实现	JpaAccess、生成器、JpaContext、分页和查询
hibernate	公共桥接	依赖 jdbc-jpa
hibernate5	可集成验证	构建 EntityManagerFactory，测试含 H2 示例
hibernate6	可集成验证	增加 AppClassloader 配置，测试含 H2 示例
reactive-core	空壳	只有依赖声明，无主源码
reactive-r2dbc	空壳	只有依赖声明，无 R2DBC 实现
reactive-vertx	空壳	只有依赖声明，无 Vert.x 实现
hibernate-reactive	空壳	只依赖 reactive-vertx，无实现

推荐路径：Hibernate 6

implementation("com.IceCreamQAQ.SmartAccess:hibernate6:1.0.0-DEV11")
runtimeOnly("com.h2database:h2:<version>")

implementation 'com.IceCreamQAQ.SmartAccess:hibernate6:1.0.0-DEV11'
runtimeOnly 'com.h2database:h2:<version>'

配置：

db.provider=smartaccess.hibernate.HibernateService
db.driver=org.h2.Driver
db.url=jdbc:h2:./db/app
db.username=sa
db.password=
db.dialect=org.hibernate.dialect.H2Dialect
db.ddl=update
db.poolMax=10
db.poolIdle=2

HibernateService 使用 Rain 扫描到的 @Entity / @Table 类构建 PersistenceUnitInfo，再建立 EntityManagerFactory。无需 persistence.xml。

Hibernate 6 额外把 AppClassloader 列入 AvailableSettings.CLASSLOADERS 和 TC_CLASSLOADER，以便 Hibernate 能识别 Rain 类加载器中的实体。

Hibernate 5

implementation("com.IceCreamQAQ.SmartAccess:hibernate5:1.0.0-DEV11")

implementation 'com.IceCreamQAQ.SmartAccess:hibernate5:1.0.0-DEV11'

它依赖 hibernate-core-jakarta:5.6.15.Final，实体使用 jakarta.persistence。配置方式与 Hibernate 6 相同。

不要在同一应用同时引入 Hibernate 5 和 6 实现：两者提供同包名、同类名 smartaccess.hibernate.HibernateService，会产生 classpath 冲突。

实体发现

SmartAccess 同时作为 ClassRegister 接收所有扫描类：

1. 类标记 @Database("name")，加入指定数据库模型列表。
2. 类标记 SmartAccess @Model，加入 default。
3. DBService isModel(clazz) 返回 true，加入 default。

JPAService 的 isModel 识别 @Entity 或 @Table：

@Entity
@Database("analytics")
data class Event(...)

@Entity
@Database("analytics")
public class Event {
    // fields and accessors
}

实体和 Access 都应使用同一数据库名称，否则 Access 可能连接一个 EntityManagerFactory，而实体未注册到该 Persistence Unit。

HikariCP

JPAService 通过 JDBCPool.supportPool 自动探测支持的连接池。当前只有 HikariCP：检测到 com.zaxxer.hikari.HikariDataSource 就选择 HikariPool。

映射：

SmartAccess 配置	Hikari 设置
url	jdbcUrl
username	username
password	password
driver	driverClassName
poolMax	maximumPoolSize，默认 10
poolIdle	minimumIdle，默认 2

源码固定：connectionTimeout 30 秒、autoCommit false、readOnly false、隔离级别 READ_COMMITTED。

当前 close 主要关闭 EntityManagerFactory，DataSource/HikariDataSource 没有明确 close 路径。测试或应用停服后应观察连接池线程；框架后续应补上 DataSource 生命周期。

JpaContext 同步模型

同步 EntityManager 使用：

database name → ThreadLocal<EntityManager>

首次访问创建 EntityManager，关闭后下次重建。它要求一次业务调用在稳定线程中完成；跨线程后会使用不同 EntityManager。

@Transactional 调用 beginTransactionSync，从当前线程 EntityManager 取得 transaction 并 begin。

JpaAsyncAccess 不是 Reactive Driver

JpaAsyncAccess 方法是 suspend，JpaContext 也提供 CoroutineContext 中的 EntityManager。但底层仍是 Jakarta EntityManager，同步数据库调用只是放在协程结构中，并不自动变成非阻塞 I/O。

jpaContext.transaction("default") {
    // 在 EntityManagerCoroutineContext 中执行
}

jpaContext.transaction("default", () -> {
    // 在 EntityManagerCoroutineContext 中执行
    return null;
});

runWithDatabaseContext 创建上下文并在结束时关闭其中 EntityManager。只有使用对应异步 Access/上下文 API 时才成立。

不要把 JpaAsyncAccess 等同 Hibernate Reactive 或 R2DBC；当前 reactive 模块没有实现。

纯 JDBC 当前不可用入口

JdbcService 能用 Hikari 创建 DataSource，但：

• context getter 是 TODO。
• createAccess 是 TODO。
• startDatabase 为空。

因此不能只引入 jdbc-core 后期待 JDBCAccess 自动生成并注入。需要纯 JDBC 时，应先实现这些入口和 JDBC AccessMaker，并增加端到端测试。

Reactive 模块当前为空

reactive-core、reactive-r2dbc、reactive-vertx 和 hibernate-reactive 只有 Gradle 依赖结构，没有 src/main 实现。README 中列出的方向属于规划，不是当前可使用 API。

文档不会给出虚假的 R2DBC/Vert.x 示例。后续实现至少需要：

• Reactive DBService/DBContext。
• Access 基类与 Maker。
• 协程上下文和事务传播。
• 连接释放与取消语义。
• 对应驱动的集成测试。

版本选择

• 新项目优先验证 hibernate6。
• 依赖旧 Hibernate 行为时使用 hibernate5。
• 不要选择空壳 reactive 模块。
• 不要单独选择未完成的 jdbc-core 作为生产 Access 实现。
• 每次升级 Rain/SmartAccess/Hibernate 都执行真实数据库集成测试，尤其类加载和 ASM 生成部分。