1.1 项目介绍

适用版本：DLZ-DB 8.0。

本页只说明产品定位、能力地图和使用边界。具体写法请进入快速开始或使用指南。

一句话认识 DLZ-DB

DLZ-DB 是一个面向同步 JDBC 应用的轻量数据库访问框架。它用统一的 DB.* 门面提供实体 CRUD、动态表操作、原生 SQL、预设 SQL、批量处理、本地事务和多数据源上下文。

它不是完整 ORM，也不试图替代数据库本身：

轻量 JDBC 执行层
    + 单表 CRUD Wrapper
    + 类型安全的实体操作
    + 原生 SQL / 预设 SQL
    + 本地事务和数据源上下文

产品定位

DLZ-DB 适合下面这些需求：

常规单表 CRUD 不希望反复创建 Mapper、DAO 和 XML；
有实体类时希望使用 Lambda 字段引用，减少字符串字段名；
没有实体类或表名动态时，仍希望直接操作表；
复杂 SQL 需要自己掌控，但希望统一参数绑定、结果映射和日志；
Spring Boot、Solon 和非 Spring 环境希望复用同一套核心 API；
需要显式切换或运行时注册数据源；
希望数据库调用路径保持短小、可读、便于排查。

DLZ-DB 不以这些能力为核心目标：

JPA/Hibernate 风格的完整对象关系映射；
自动生成复杂 JOIN、CTE、UNION 或窗口函数；
数据库结构版本迁移；
分布式事务；
响应式或异步数据库访问；
自动读写路由、故障转移和连接池治理；
业务缓存、租户模型、权限模型；
完整的存储过程和厂商特殊 JDBC 类型抽象。

复杂 SQL 可以交给 DB.jdbc 或 DB.sql，但上述系统能力需要由应用或专门组件承担。

八个统一入口

入口	职责	典型场景
`DB.pojo`	实体类和 Lambda 单表 CRUD	有稳定实体模型的业务表
`DB.table`	字符串表名和字段名 CRUD	动态表、通用后台、无实体场景
`DB.jdbc`	使用 `?` 参数的原生 SQL	一次性 SQL、方言 SQL、复杂查询
`DB.sql`	使用 `#{name}` 参数的预设 SQL	可复用、集中维护的复杂 SQL
`DB.batch`	批量插入、更新和 JDBC 执行	数据同步、ETL、批量写入
`DB.ds`	数据源注册、查询、切换和删除	多数据源、报表库、租户路由
`DB.tx`	编程式本地事务	显式事务边界
`DB.config`	方言、插件和底层执行配置	初始化阶段的高级扩展

门面字段区分大小写，当前入口全部使用小写。

如何选择入口

实体类单表操作？
├─ 是 -> DB.pojo
└─ 否
   动态表名或无实体的单表操作？
   ├─ 是 -> DB.table
   └─ 否
      SQL 需要复用、命名参数或集中管理？
      ├─ 是 -> DB.sql
      └─ 否 -> DB.jdbc

批量写入       -> DB.batch
切换数据源     -> DB.ds
显式本地事务   -> DB.tx
初始化扩展配置 -> DB.config

Wrapper 主要面向单表。JOIN、CTE、UNION、窗口函数和复杂聚合不要勉强拼接，直接选择 DB.jdbc 或 DB.sql。

核心设计特点

类型安全与 SQL 控制权并存

DB.pojo 支持 User::getName 这样的字段引用；复杂查询仍然允许完整手写 SQL。两种方式共用参数绑定、结果映射、日志和事务能力。

构建与执行边界明确

selectWrapper、insertWrapper、updateWrapper、deleteWrapper 返回可继续构建的 Wrapper；
insert、selectById、updateById、deleteById 等快捷方法会直接执行；
写 Wrapper 通常以 .execute() 结束。

单条查询语义明确

queryOne / queryBean：严格单条，多条时抛出非唯一结果异常；
queryFirst / queryFirstBean：允许多条，只取第一条。

使用“第一条”语义时应显式排序，避免结果依赖数据库执行计划。

显式控制流

动态条件由三参数重载直接控制；
DB.ds.use(...) 明确表示数据源作用域；
DB.tx.run(...) 明确表示事务边界；
数据源切换不会隐式开启事务。

当前能力边界

SQL 与数据库

内置方言覆盖 MySQL/MariaDB、PostgreSQL、Oracle、达梦 DM8、SQLite、H2/HSQLDB 和 SQL Server。方言解决标识符、分页、DDL 和结果映射差异，不代表每个厂商特性都被统一抽象。

原生 JDBC 分页的自动 count 改写较为朴素。复杂 GROUP BY、DISTINCT、UNION 等查询应使用经过验证的显式 SQL。

事务与多数据源

DB.tx 只承诺单数据源本地事务，不提供跨数据源原子提交。切换到另一数据源意味着另一条连接和独立事务边界。

Spring Boot 可使用 @Transactional，Solon 可使用 @Tran；传播语义以各自集成文档为准。

逻辑删除与写安全

逻辑删除会自动补充查询条件，并把删除改写为更新。写 Wrapper 仍必须显式提供业务条件。

当最终 WHERE 完全为空时，构建器会生成 WHERE false；但逻辑删除注入的 deleted = 0 已经算作 WHERE，因此不能把该兜底视为“无业务条件一定拒绝”的强安全保证。

配置生命周期

DB.config 主要服务于只依赖 core 的手动启动；调用它自己的 init() 后，该配置对象不可修改。Spring Boot 和 Solon 会直接使用容器 DataSource 与 dlz.db.* 初始化，不把 DB.config setter 当作自动配置入口。自定义扩展仍应在应用启动阶段、首次数据库调用之前完成注册。

日志与性能

框架可以输出 SQL、参数、耗时、结果和慢 SQL 信息。开启 show-caller 时，调用方信息写入 MDC，是否显示取决于应用日志 pattern。

展开 SQL、序列化大结果和采集调用栈都有成本。仓库没有提供可复现的跨框架性能倍数，性能结论应以真实 SQL、数据库、连接池和负载测试为准。

扩展与包边界

业务代码应优先使用公共 API。新的业务项目不应依赖 com.dlz.db.internal.*；该包属于实现细节，即使部分公共签名当前仍会暴露内部类型，也不代表这些类型获得稳定性承诺。

一句话认识 DLZ-DB​

产品定位​

八个统一入口​

如何选择入口​

核心设计特点​

类型安全与 SQL 控制权并存​

构建与执行边界明确​

单条查询语义明确​

显式控制流​

当前能力边界​

SQL 与数据库​

事务与多数据源​

逻辑删除与写安全​

配置生命周期​

日志与性能​

扩展与包边界​

推荐阅读路径​