跳到主要内容

8.1 架构与源码指南

本章面向需要阅读、扩展或维护 DLZ-DB 的开发者。目录和类名以当前源码为准；稳定性承诺以 API、SPI 与实现边界 为准。

1. 模块结构​

dlz-db/
├─ dlz-db-core/                    # 框架无关的核心 API 与 JDBC 实现
├─ dlz-db-spring-boot-starter/     # Spring Boot 2/3 自动装配
├─ dlz-db-solon-plugin/            # Solon SPI 适配
└─ dlz-db-web-demos/               # Solon 3、Spring Boot 2、Spring Boot 3 Demo
  • dlz-db-core 编译目标是 Java 8，不依赖 Spring/Solon。
  • Spring Boot 2 和 Solon Demo 目标 Java 8；Spring Boot 3 Demo 需要 JDK 17。

2. core 包的实际边界​

com.dlz.db
├─ DB / DbPojo / DbTable / DbJdbc / DbSql / DbBatch
├─ DBDynamic / DBTx / DbConfig
├─ wrapper/          # Pojo/Table/Jdbc/Sql 链式对象
├─ model/            # Page、PageRequest、ResultMap、BatchResult...
├─ option/           # CRUD 选项与 option points
├─ core/             # 框架适配抽象、配置、JDBC 执行器
│  ├─ anno/          # TableName、TableId、TableField、IdType
│  ├─ ds/            # DataSourceProperty/Config/Creator
│  ├─ ISqlExecutor / ITxExecutor / DlzDbAdapter
│  └─ jdbc/          # 原生 JDBC 适配实现
├─ dialect/          # SQL/结构方言与结果映射
├─ interceptor/      # SQL 构建拦截点
├─ sql/              # SqlFragment
├─ util/             # 公用工具
└─ internal/         # 非稳定实现细节

2.1 业务 API​

应用代码从 DB.* 入口进入，主要依赖：

  • com.dlz.db.DB 和各 Db* 门面。
  • com.dlz.db.wrapper.* 链式对象。
  • com.dlz.db.model.* 返回模型。
  • com.dlz.db.option.* 操作选项。
  • com.dlz.db.core.anno.* 实体注解。

2.2 框架扩展层​

新方言、执行器或框架适配层主要关注：

  • com.dlz.db.core.ISqlExecutor
  • com.dlz.db.core.ITxExecutor
  • com.dlz.db.core.DlzDbAdapter
  • com.dlz.db.dialect.DbDialect
  • com.dlz.db.dialect.DialectRegistry
  • com.dlz.db.interceptor.SqlBuildInterceptor

这些是框架适配和扩展入口，不是普通 CRUD 代码必需依赖的类。ISqlExecutor、ITxExecutor、DlzDbAdapter 和 SchemaDialect 的部分签名仍存在实现层泄漏，第三方适配器应锁定具体版本；干净、稳定的 SPI 范围以边界文档为准。

2.3 实现包​

com.dlz.db.internal.* 包含条件树、SQL 参数、缓存、Holder 和内部 Service。这些类可随实现需求变动，业务应用不应导入。

当前需注意的现实是：Wrapper 的公共签名会继承 internal 接口，并且 where(...) 涉及 internal 条件类型；Sort 实现 internal IChained，Page 又继承 Sort。在此边界完成代码层面的清理前，新的用户文档只展示 Wrapper 自身的 eq/ands/ors/sql 和模型自身文档化的方法，不直接声明或复用实现层类型。

3. 调用链​

3.1 Pojo 查询​

DB.pojo.selectWrapper(User.class)
  → PojoQuery
  → 条件/分页/排序构建
  → WrapperBuildUtil
  → DBHolder.doDb(...)
  → ISqlExecutor
  → 当前数据源和方言

PojoQuery 是当前类名，不是旧文档中的 PojoSelect。Table 对应 TableQuery，JDBC 对应 JdbcSelect，预设 SQL 对应 SqlQuery。

3.2 事务和数据源​

DB.ds.use(name, callback)
  → DBDynamic 保存线程当前 DataSourceConfig
  → callback 结束后恢复上一层上下文

DB.tx.run([name], callback)
  → DBTx
  → DBHolder.getTxExecutor(DataSourceConfig)
  → DlzDbAdapter.createTxExecutor(config) 或手动初始化提供的 txExecutorMaker
  → Spring、Solon或原生 JDBC 事务实现

DB.ds.use 只切换数据源，不自动创建事务。

4. Spring Boot Starter​

实际结构：

com.dlz.db.spring
├─ SpringSqlExecutorAdapter.java
├─ SpringTxExecutorAdapter.java
└─ config/
   ├─ SpringDlzDbAutoConfiguration.java
   └─ DynamicJdbcTemplate.java

SpringDlzDbAutoConfiguration 是当前自动装配入口：

  1. 从 Spring 环境绑定 dlz.db.* 到 core 的 DlzDbProperties。
  2. 获取容器中的 DataSource。
  3. 注册 Spring SQL/事务适配器并直接调用 core 的 DBHolder.init(...)；这条路径不会推进 DB.config 自身的状态机。

Spring Boot 2 使用 META-INF/spring.factories，Spring Boot 3 使用 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。应用无需继承 SpringDlzDbConfig；该类在 8.0 当前源码中不存在。

5. Solon Plugin​

实际结构：

com.dlz.db.solon
├─ DlzDbSolonPlugin.java
├─ DynamicDataSource.java
├─ SolonSqlExecutorAdapter.java
├─ SolonTxExecutorAdapter.java
└─ TranUtilsBridge.java

DlzDbSolonPlugin 通过 Solon SPI 启动。插件等待容器中的 DataSource Bean，然后初始化 SQL 和事务适配器。因此应用需要自己或借助其他插件提供 DataSource Bean。

6. 方言与结构能力​

  • BuiltinDialects 注册 MySQL/MariaDB、PostgreSQL、Oracle、DM8、SQLite、H2/HSQL 和 MSSQL 的产品名映射。
  • DbDialect 聚合 SQL 方言、结果映射和 SchemaDialect。
  • “已注册方言”不等于“已在所有版本上完成集成验证”，发行说明应分开表述。
  • SchemaDialect 提供建表、加列、修改列等方言能力，当前没有 listTables() 公共方法。

7. 本地构建与测试​

# 只验证三个库模块（Java 8 基线）
mvn -B -pl dlz-db-core,dlz-db-spring-boot-starter,dlz-db-solon-plugin -am clean verify -Denforcer.skip=true

# 验证根聚合项目与三个 Demo（使用 JDK 17）
mvn -B clean verify

测试的具体说明见根目录 TESTING.md。默认构建跳过 JaCoCo 和 SpotBugs；CI 通过 -Djacoco.skip=false 在完整 reactor 中启用已经接入生命周期的 JaCoCo 报告和门槛检查。

8. 修改指引​

增加公共 CRUD 能力​

  1. 先判断功能属于 Pojo/Table/Jdbc/Sql 哪个门面。
  2. 保持直接 API 与 Wrapper API 的命名一致。
  3. 在 core 添加 Java 8 兼容测试，并核对 Spring/Solon 适配。
  4. 按 事实来源 和 文档维护规范 更新唯一事实页；不要在多个概览文件复制完整签名。

增加方言​

  1. 实现 DbDialect 需要的 SQL/结果/结构组件。
  2. 在 DialectRegistry 注册，或在手动 core 启动的 DB.config.init() 之前调用 DB.config.registerDialect(...)。Spring/Solon 适配场景应在应用启动阶段、首次 SQL 之前完成注册。
  3. 补充真实数据库集成测试，并在文档中区分“代码映射”与“已验证”。

增加框架适配​

  1. 优先依赖边界文档列出的 SPI；若当前签名迫使适配层接触 internal，明确锁定版本并建立待清理项，不继续扩大泄漏。
  2. 实现 SQL/事务执行器与生命周期初始化。
  3. 明确自动发现机制、DataSource 来源、事务语义和最低 JDK。