跳到主要内容

6.4 API、SPI 与实现边界

Java 的 public 只表示语言可见性，不自动等于 DLZ-DB 的兼容性承诺。本页定义 8.x 系列的稳定业务 API、扩展 SPI 和实现边界。

1. 稳定业务 API​

下列入口及本参考手册明确展示的成员属于 8.x 稳定业务 API：

  • com.dlz.db.DB 及 DbPojo、DbTable、DbJdbc、DbSql、DbBatch、DBDynamic、DBTx、DbConfig。
  • com.dlz.db.wrapper 中的 Pojo、Table、JDBC 和预设 SQL Wrapper。
  • com.dlz.db.model 中的 Page、PageRequest、ResultMap、Order、Sort、BatchResult 和 BatchStatus。
  • com.dlz.db.core.anno 中的实体注解和 IdType。
  • com.dlz.db.option 中本手册列出的内置 CRUD 选项。
  • com.dlz.db.core.ds 中通过 DB.ds 使用的数据源属性和配置模型。
  • com.dlz.db.exception 中由稳定 API 明确抛出的异常类型。
  • core 的非 optional 传递依赖 DLZ-KIT 中，被公共签名直接使用的 com.dlz.kit.fn.DlzFn、com.dlz.kit.json.JSONMap，ResultMap 继承的 JSONMap 能力，以及 DbException 继承的 com.dlz.kit.exception.BaseException。升级 DLZ-KIT 时必须把这些外部类型和继承关系当作 8.x API/ABI 表面的一部分做兼容验证。

兼容承诺针对文档明确展示的调用方式，不包括 Wrapper 从实现层继承而来的未记录成员。

2. 扩展 SPI​

SPI 面向方言、SQL 构建插件和数据源创建器开发者，普通业务代码不需要依赖。

2.1 SQL 构建和操作选项​

  • com.dlz.db.interceptor.SqlBuildInterceptor
  • com.dlz.db.option.DbOption
  • com.dlz.db.option.point 中已经在 StandardOptionPoints 注册的 8 个桩点：
    • WherePoint
    • InsertFieldPoint
    • InsertNullFieldPoint
    • UpdateNullFieldPoint
    • DeleteModePoint
    • LogicDeleteValuePoint
    • DeletedDataPoint
    • SelectLockPoint
  • 上述桩点签名使用的 com.dlz.db.option.point.context 值对象。

只有“已经注册且执行路径真实调用”的桩点才算 SPI。路线图、注释或未来设计中的接口不属于当前能力。

2.2 方言和数据源​

  • com.dlz.db.dialect.DbDialect
  • SqlDialect、GeneratedKeyDialect、ResultMappingDialect
  • DialectRegistry
  • com.dlz.db.dialect.rowMapper.IRowMapper
  • com.dlz.db.core.ds.IDataSourceCreator

自定义方言必须在 DLZ-DB 初始化之前注册。“能被注册”只说明扩展入口存在，不代表该数据库的所有 DDL、分页、结果映射和主键回填路径均已验证。

3. 框架适配层​

ISqlExecutor、ITxExecutor 和 DlzDbAdapter 是 Spring、Solon 及原生 JDBC 适配器当前使用的底层抽象。不过 8.0 的部分签名仍引用实现层类型，因此它们暂时属于与具体 8.x 版本绑定的框架适配层，不按干净、独立的第三方 SPI 承诺。

SchemaDialect 同样存在返回实现层元数据类型的签名。只扩展 SQL 方言时可以不提供 schema 能力；需要扩展 DDL 能力时应锁定 DLZ-DB 小版本并做完整集成测试。

4. 实现包​

com.dlz.db.internal.* 是实现细节，包括条件树、SQL 参数对象、缓存、Holder、内部 Service 和执行接口。它具有以下规则：

  • 业务代码、教程和公开示例不得导入。
  • 不作为参数或返回类型出现在用户自己定义的公共接口中。
  • 可以在任意 8.x 版本中重构、移动或删除。
  • internal 类型即使声明为 public，也没有兼容性承诺。

当前 Wrapper 的继承关系和少数成员仍会把 internal 类型暴露到 IDE 补全中，例如显式条件树相关成员；Sort 实现 internal IChained，Page 又继承 Sort，模型继承链也存在同类泄漏。这是已知的代码边界问题，不代表这些 internal 类型成为稳定 API。业务代码应直接使用 Wrapper 的 eq、ands、ors、sql 以及模型自身文档化的方法，不显式引用 internal 父接口。

5. 其他公开类​

com.dlz.db.util、com.dlz.db.core.jdbc、内置方言实现和插件注册中心等类可能因框架自身复用而声明为 public。除非本参考手册或源码扩展契约明确列入，它们不属于稳定业务 API。

6. 8.x 兼容规则​

  • 稳定业务 API：后续以兼容新增为主，不删除、不改名、不改变已有参数和返回类型。
  • 已废弃 API：保留到下一个主版本；新代码不得继续采用。
  • 扩展 SPI：允许增加有默认实现的方法；不得让已有实现因新增抽象方法而无法编译。
  • 行为修复：安全问题、明显缺陷和数据库驱动兼容修复可以调整行为，但必须在变更记录中说明。
  • internal 和未列入契约的公开辅助类：不保证源码或二进制兼容。

发布前应对 8.0 基线执行 API 兼容性比较，并检查稳定 public/protected 签名没有新增 internal 类型泄漏。维护流程见 文档维护规范。