跳到主要内容

框架源码指南

本文档面向需要维护、修改或扩展 DLZ-DB 框架的开发者

目录​

一、项目概览​

1.1 代码规模​

DLZ-DB 是一个轻量级的数据库操作框架，代码规模精简：

  • 纯生产代码：约 10000 行
  • 包含注释：注释占 30-40%
  • 核心业务逻辑：约 6000-7000 行
  • 测试用例：约 10000+ 行（不计入生产代码）

1.2 设计理念​

DLZ-DB 的设计理念是"不做你不需要的事"：

  • 不做 Mapper 接口和 XML 双向映射 → 省掉解析引擎
  • 不做 SqlSession / Executor 分层 → 调用栈直通 JDBC
  • 不做一二级缓存 → 交给 Redis / Caffeine，各司其职

1.3 技术栈​

  • JDK：8+
  • 构建工具：Maven
  • 数据库支持：MySQL、PostgreSQL、Oracle、达梦等（通过方言支持）
  • Spring Boot：2.x+

二、代码结构​

2.1 目录结构​

src/main/java/com/dlz/db/
├── modal/              # 统一入口 DB、条件构造器、包装器
│   ├── DB.java         # 统一入口类
│   ├── condition/      # 条件构造器
│   ├── wrapper/        # 查询包装器（14个文件）
│   └── para/           # 参数处理
├── helper/             # SQL 构建器
│   └── support/        # 多方言支持（MySQL、PostgreSQL、Oracle、达梦等）
├── dao/                # 数据访问层
├── ds/                 # 数据源管理
├── convertor/          # 类型转换器
├── holder/             # 缓存和元数据管理
├── service/            # 服务层
├── util/               # 工具类
├── annotation/         # 注解定义
├── config/             # 配置类
└── enums/              # 枚举定义

2.2 模块职责​

模块职责
modal/统一入口 DB、条件构造器、查询包装器
helper/SQL 构建器、多方言支持
dao/数据访问层、JDBC 操作封装
ds/数据源管理、动态数据源切换
convertor/类型转换器、数据库类型与 Java 类型映射
holder/缓存和元数据管理
service/服务层、业务逻辑封装
util/工具类、通用方法
annotation/注解定义（@TableName、@TableField 等）
config/配置类、Spring Boot 自动配置
enums/枚举定义

三、核心模块说明​

3.1 modal 模块​

DB.java​

统一入口类，提供静态方法访问所有功能：

DB.Pojo   // 基于 Bean 的 CRUD
DB.Table  // 基于表名的操作
DB.Jdbc   // 原生 SQL 操作
DB.Sql    // 预设 SQL 操作
DB.Batch  // 批量操作
DB.Dynamic  // 动态数据源切换

condition 包​

条件构造器，支持链式调用：

Condition.where()
    .eq("field", value)
    .gt("age", 18)
    .lk("name", "张");

wrapper 包​

查询包装器，封装不同类型的查询操作：

  • PojoQuery - Bean 查询包装器
  • TableQuery - 表名查询包装器
  • JdbcQuery - JDBC 查询包装器
  • SqlQuery - 预设 SQL 查询包装器
  • 等 14 个包装器类

3.2 helper 模块​

SqlHelper​

SQL 构建器，负责将条件构造器转换为可执行的 SQL 语句。

support 包​

多方言支持，不同数据库的 SQL 语法差异处理：

  • MysqlSupport - MySQL 方言
  • PostgresqlSupport - PostgreSQL 方言
  • OracleSupport - Oracle 方言
  • DamengSupport - 达梦数据库方言

3.3 dao 模块​

数据访问层，封装 JDBC 操作：

  • JdbcDao - JDBC 操作封装
  • BaseDao - 基础数据访问接口

3.4 ds 模块​

数据源管理：

  • DBDynamic - 动态数据源切换
  • DataSourceProperty - 数据源配置属性

四、开发环境搭建​

4.1 克隆项目​

git clone https://github.com/dingkui/dlz-db.git
cd dlz-db

4.2 配置数据库​

在 src/test/resources/application.yml 中配置测试数据库：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/test
    username: root
    password: 123456

4.3 运行测试​

mvn test

4.4 导入 IDE​

推荐使用 IntelliJ IDEA：

  1. 打开 IDEA
  2. File → Open → 选择项目根目录
  3. 等待 Maven 依赖下载完成
  4. 运行测试用例验证环境

五、修改指南​

5.1 上手时间​

根据不同需求，上手时间如下：

任务预计时间说明
熟悉 API 使用半天了解 DB.Pojo、DB.Table 等基本用法
看懂 wrapper 构建逻辑1-2 天理解条件构造器的实现原理
修改底层功能2-3 天修改 SQL 构建器、类型转换器等核心模块

5.2 修改流程​

  1. Fork 项目：将项目 fork 到自己的仓库
  2. 了解结构：阅读本文档和源码，了解项目结构
  3. 运行测试：运行现有测试用例，确保环境正常
  4. 修改代码：根据需求修改相应模块
  5. 验证功能：运行测试用例，验证修改正确性
  6. 提交 PR：如果修改有价值，可以提交 PR 回社区

5.3 常见修改场景​

场景1：添加新的数据库方言支持​

  1. 在 helper/support/ 下创建新的方言类
  2. 继承 AbstractSupport 或实现相应接口
  3. 实现数据库特定的 SQL 语法
  4. 在配置中注册新方言

场景2：添加新的条件方法​

  1. 在 modal/condition/Condition.java 中添加新方法
  2. 在 helper/SqlHelper.java 中实现 SQL 生成逻辑
  3. 编写测试用例验证功能

场景3：修改类型转换逻辑​

  1. 在 convertor/ 包中找到对应的转换器
  2. 修改转换逻辑
  3. 编写测试用例验证转换正确性

5.4 代码规范​

  • 命名规范：遵循 Java 命名规范
  • 注释规范：关键逻辑必须添加注释
  • 测试覆盖：新增功能必须编写测试用例
  • 向后兼容：修改公共 API 时保持向后兼容

六、测试指南​

6.1 测试结构​

src/test/java/com/dlz/test/db/
├── cases/              # 测试用例
│   ├── db/            # 数据库操作测试
│   ├── dao/           # DAO 层测试
│   └── helper/        # SQL 构建器测试
└── util/              # 测试工具类

6.2 运行测试​

# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=PojoQueryTest

# 运行特定测试方法
mvn test -Dtest=PojoQueryTest#testSelect

6.3 编写测试用例​

@Test
public void testSelect() {
    // 准备数据
    User user = new User();
    user.setName("张三");
    DB.Pojo.insert(user);
    
    // 执行测试
    User result = DB.Pojo.select(User.class)
        .eq(User::getId, user.getId())
        .queryBean();
    
    // 验证结果
    assertNotNull(result);
    assertEquals("张三", result.getName());
    
    // 清理数据
    DB.Pojo.delete(User.class).eq(User::getId, user.getId()).execute();
}

七、发布流程​

7.1 版本号规范​

遵循语义化版本规范：主版本号.次版本号.修订号

  • 主版本号：不兼容的 API 修改
  • 次版本号：向下兼容的功能性新增
  • 修订号：向下兼容的问题修正

7.2 发布步骤​

  1. 更新版本号：修改 pom.xml 中的版本号
  2. 更新文档：更新相关文档和 CHANGELOG
  3. 运行测试：确保所有测试通过
  4. 提交代码：提交到主分支
  5. 打标签：创建 Git 标签
  6. 发布到仓库：发布到 Maven 中央仓库

7.3 CHANGELOG 维护​

在每次发布时更新 CHANGELOG.md：

## [版本号] - 日期

### 新增
- 新功能描述

### 修复
- 修复的问题描述

### 变更
- 不兼容的变更描述

八、贡献指南​

8.1 提交 Issue​

遇到问题时，请提交 Issue 并包含以下信息：

  • JDK 版本
  • 数据库类型和版本
  • 重现步骤
  • 期望行为
  • 实际行为
  • 错误日志

8.2 提交 PR​

提交 PR 时请遵循以下规范：

  1. 分支命名：feature/功能描述 或 fix/问题描述
  2. 提交信息：清晰描述修改内容
  3. 代码审查：确保代码符合项目规范
  4. 测试通过：确保所有测试通过

8.3 代码审查​

代码审查关注点：

  • 代码质量和可读性
  • 测试覆盖率
  • 向后兼容性
  • 文档完整性

九、常见问题​

Q1：如何调试 SQL 生成过程？​

在 helper/SqlHelper.java 中设置断点，查看 SQL 构建过程。

Q2：如何添加新的注解？​

在 annotation/ 包中创建新注解，并在相应的转换器中处理。

Q3：如何优化性能？​

  • 使用批量操作减少数据库往返
  • 合理使用缓存
  • 避免 N+1 查询

十、联系方式​

DLZ-DB：简单、可控、可定制