# UniDB

**Repository Path**: protect-xiaozhou/uni-db

## Basic Information

- **Project Name**: UniDB
- **Description**: 通用数据库连接工具
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-12
- **Last Updated**: 2025-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringBoot, Spring-MVC, JDBC

## README

# UniDB

# 产品文档（V1.0）

**文档版本**：V1.0  
**编制日期**：2025-07-12  
**作者**：保护小胡

---

## 一、产品定位与价值

### 1.1 背景
在多数据库环境下，开发与运维人员常面临以下痛点：
- 不同数据库（MySQL、Oracle、ClickHouse等）的连接方式、SQL语法差异大
- 手动管理连接池繁琐，易出现资源泄露
- SQL执行结果格式不统一
- 事务管理等场景需重复开发
- 多数据库兼容性支持不足

### 1.2 项目定位
DB-Tools 是一款通用数据库中间件，通过标准化 API 接口实现对多类型数据库的统一管理与操作，屏蔽底层数据库差异，降低跨数据库开发/测试难度，提升系统可靠性与安全性。

### 1.3 核心价值
| 维度     | 价值描述                                                                                      |
|----------|-----------------------------------------------------------------------------------------------|
| 效率提升 | - 统一 API 接口，减少跨数据库测试工作量（据测算可降低 60% 重复代码）<br>- 批量操作性能优化，提升数据处理效率 |
| 兼容性强 | - 支持 20+ 主流数据库（关系型、数据仓库、内存数据库等）<br>- 新增数据库类型无需修改核心代码          |
| 安全可靠 | - 内置参数化 SQL 执行、连接池加密管理、事务原子性保障<br>- 符合企业级安全合规要求                    |
| 易于集成 | - 提供 RESTful API 与 SDK<br>- 支持 Java、Python 等多语言调用，无缝对接现有系统                        |

---

## 二、核心功能与技术特点

### 2.1 核心功能模块

#### 模块 1：连接管理
**功能描述**  
实现数据库连接的全生命周期管理，包括连接创建、池化维护、闲置清理、安全关闭。

**关键特性**
- **自动识别数据库类型**
  - 通过 JDBC URL 前缀（如 `jdbc:mysql://`）自动识别数据库类型，无需手动指定驱动；
  - 也支持显式指定驱动类型（如 `driverClassName=com.mysql.cj.jdbc.Driver`）以覆盖自动识别结果。

- **智能连接池**
  - 基于 **HikariCP** 实现，支持以下参数配置：
    - `maxActive`：最大连接数（默认 10）
    - `minIdle`：最小闲置连接数（默认 5）
    - `connectionTimeout`：连接超时时间（默认 30 秒）
  - 自动检测连接健康状态（心跳检测），异常连接自动剔除并重建。

- **闲置连接回收**
  - 定时任务（可配置间隔，默认 60 秒）清理超过 `idleTimeout`（默认 30 分钟）的闲置连接，释放系统资源。

- **连接加密**
  - **密码加密**：使用 AES-256 算法加密存储数据库密码，运行时解密使用；
  - **传输加密**：支持 SSL/TLS 加密连接数据库，需配置 `sslMode=REQUIRED`（如 MySQL）或 `ssl=true`（如 PostgreSQL）。

**使用流程**
1. **隐式驱动识别**（推荐）：
   ```properties
   jdbcUrl=jdbc:postgresql://host:5432/db
   username=admin
   password=ENC(加密的密码)
![使用流程](./images/使用流程.png)

#### 模块 2：SQL 执行引擎
**功能描述**  
支持各类 SQL 操作（查询、更新、批量执行），返回统一格式的结果集。

**关键特性**
- **查询操作**
  - **参数化查询**
    - 支持占位符语法：`SELECT * FROM t WHERE id = ?`，底层使用 `PreparedStatement` 绑定参数，彻底防止 SQL 注入。
  - **结果集转换**
    - 统一返回 `List<Map<String, Object>>`：
      - 字段名与数据库保持一致（大小写可配置）；
      - 自动解析复杂类型：
        - 数组 → `java.util.List`；
        - JSON → `com.fasterxml.jackson.databind.JsonNode`；
        - 日期 → `java.time.LocalDateTime`，保留时区信息。
  - **性能指标**
    - 返回 `totalCount`：满足条件的总记录数；
    - 返回 `executeTime`：SQL 执行耗时（毫秒），包含网络与数据库耗时。

- **更新操作**
  - 支持 `INSERT` / `UPDATE` / `DELETE` / `CREATE`，返回 `affectedRows`（整型）表示受影响行数。
  - **数据库特有语法适配**
    - Oracle：`INSERT INTO t (id, ...) VALUES (SEQUENCE.NEXTVAL, ...)`；
    - ClickHouse：`INSERT INTO t SELECT ... FROM ... SETTINGS ...`；
    - 通过方言（Dialect）插件扩展，新增数据库无需修改核心代码。

- **批量操作**
  - **同一 SQL + 多组参数**
    - 示例：`INSERT INTO t (c1, c2) VALUES (?, ?)` → 批量参数 `[[v1,v2], [v3,v4], ...]`；
    - 使用 JDBC 批处理或数据库原生批处理（如 MySQL `rewriteBatchedStatements=true`），网络 IO 减少 90%+。
  - **返回结果**
    - `batchAffectedRows`：整型数组，顺序对应每组参数，`-2` 表示成功但行数未知（JDBC 规范），`-3` 表示失败；
    - 部分成功时，失败行可通过异常 `BatchUpdateException.getUpdateCounts()` 定位。

**使用示例**
1. **单条查询**  
python
   ``` java 
   response = requests.post(
       f"{BASE_URL}/query/{connection_id}",
       json={"sql": f"SELECT * FROM {TEST_TABLE} WHERE id = ?", "params": [1]}
   )
#### 模块 3：事务管理
**功能描述**  
在一个事务中执行多条 SQL 语句，保证原子性（要么全成功，要么全回滚）。

**关键特性**
- **混合操作支持**
  - 事务中可同时包含查询（`SELECT`）与更新（`INSERT` / `UPDATE` / `DELETE`）操作，查询结果实时返回。
- **自动提交 / 回滚**
  - 所有语句执行成功 → 自动 **COMMIT**；
  - 任意语句失败 → 自动 **ROLLBACK**，确保数据一致性。
- **事务统计**
  - `transactionCommitted`：布尔值，`true` 表示已提交；
  - `transactionStatementCount`：事务内执行的 SQL 语句总数；

**事务流程图**
![事务流程](./images/事务流程图.png)

#### 模块 4：多数据库适配
**功能描述**  
通过数据库专属配置器（Dialect Configurator）实现对不同数据库特性的兼容支持，新增数据库类型时仅需扩展配置器，无需改动核心代码。

**已支持数据库类型**

| 类别         | 支持数据库列表                                               |
|--------------|--------------------------------------------------------------|
| 关系型数据库 | MySQL、Oracle、PostgreSQL、SQL Server、DB2、SQLite           |
| 数据仓库     | ClickHouse、Snowflake、Redshift、Presto、Trino               |
| 内存数据库   | H2、HSQLDB、Derby                                            |
| NoSQL 数据库 | MongoDB（JDBC 兼容）、Cassandra                              |

#### 适配机制
通过 `DBConfigurer` 接口实现数据库专属配置，保证“新增数据库类型只需实现一个配置器，零改动核心代码”。
例如:

| 数据库 | 自动生效的专属配置示例 |
|--------|------------------------|
| **MySQL** | • 字符集：`utf8mb4`（支持 Emoji）<br>• 时区：`serverTimezone=UTC`<br>• SSL：`useSSL=true&requireSSL=true` |
| **Oracle** | • 序列 ID：`SEQUENCE.NEXTVAL`<br>• 预取行数：`defaultRowPrefetch=50`<br>• 禁用 Nagle：`oracle.jdbc.TcpNoDelay=true` |
| **ClickHouse** | • 压缩传输：`compress=true`<br>• 长查询超时：`socket_timeout=300000` |

##### 1) 配置器接口
```java
/**
 * 数据库配置器接口
 * <p>
 * 定义数据库类型专属的配置方法，用于适配不同数据库的特性：
 * - 获取驱动类名
 * - 配置数据库特有属性
 * - 提供连接验证查询语句
 * </p>
 */
private interface DBConfigurer {
  /**
   * 获取数据库驱动类名
   * @param url 数据库连接URL
   * @return 驱动类全限定名（如com.mysql.cj.jdbc.Driver）
   */
  String getDriverClass(String url);

  /**
   * 配置数据库特有属性
   * @param info 连接信息实体
   * @param config Hikari连接池配置对象
   */
  void configureSpecificProperties(ConnectionInfo info, HikariConfig config);

  /**
   * 获取连接验证查询语句
   * @return 用于验证连接有效性的SQL（如SELECT 1）
   */
  String getValidationQuery();
}
```
##### 2) 实现示例（Oracle）
``` java
// 例:
DB_CONFIGURERS.put("oracle", new DBConfigurer() {
    @Override
    public String getDriverClass(String url) { return "oracle.jdbc.OracleDriver"; }
    @Override
    public void configureSpecificProperties(ConnectionInfo info, HikariConfig config) {
        if (info.getUrl() != null && info.getUrl().contains("/")) {
            config.addDataSourceProperty("oracle.jdbc.TcpNoDelay", "true");  // 禁用Nagle算法，优化小数据包传输
        } else {
            config.addDataSourceProperty("oracle.jdbc.defaultRowPrefetch", "50");  // 默认预取行数，优化查询性能
        }
    }
    @Override
    public String getValidationQuery() { return "SELECT 1 FROM DUAL"; }  // Oracle特有验证语句
});
```

### 2.2 技术特点
#### 1. 统一结果格式**  
   所有操作统一返回 `ExecuteResult` 对象，前端“零适配”直接解析即可。

   | 字段名               | 类型                     | 说明 |
   |----------------------|--------------------------|------|
   | `success`            | `boolean`                | 操作是否成功；`true` 成功，`false` 失败 |
   | `message`            | `String`                 | 成功或失败的描述信息 |
   | `errorCode`          | `String`                 | 失败时的错误编码（如 `CONNECT_FAILED`、`DUPLICATE_KEY`） |
   | `data`               | `Object`                 | 通用数据载体，可存储任意结构数据 |
   | `executeTime`        | `long`                   | 操作执行耗时（毫秒） |
   | `connectionId`       | `String`                 | 本次操作使用的数据库连接唯一标识 |
   | `totalCount`         | `int`                    | 查询结果总记录数（用于分页场景） |
   | `affectedRows`       | `int`                    | 更新操作（INSERT/UPDATE/DELETE）影响的行数 |
   | `batchAffectedRows`  | `int[]`                  | 批处理中每条语句的影响行数 |
   | `transactionCommitted`| `boolean`               | 事务是否已提交（仅事务操作有效） |
   | `transactionStatementCount`| `int`            | 事务中执行的 SQL 语句总数 |
   | `queryData`          | `List<Map<String,Object>>`| 查询结果集，外层 List 为多条记录，内层 Map 为单条记录 |
   | `extraInfo`          | `Object`                 | 扩展信息（分页参数、执行计划、警告等） |



#### 2. 异常标准化
所有运行时异常统一封装为 `CustomException`，通过 **错误码 + 描述信息** 实现快速定位与差异化处理。

#### 异常类定义
```java
package com.db_tools.exception;

import lombok.Getter;

/**
 * 自定义业务异常
 *
 * <p>统一封装运行时异常，支持错误码与错误信息分离，便于前端或调用方按错误码分类处理。</p>
 *
 * <p>错误码规范：
 * <ul>
 *   <li>系统级：SYS-001、SYS-002 …</li>
 *   <li>数据库：DB-001、DB-002 …</li>
 *   <li>业务级：BUS-001、BUS-002 …</li>
 * </ul>
 * </p>
 */
@Getter
public class CustomException extends RuntimeException {
    /** 错误码，全局唯一标识 */
    private final String errorCode;

    public CustomException(String message, String errorCode) {
        super(message);
        this.errorCode = errorCode;
    }

    public CustomException(String message, String errorCode, Throwable cause) {
        super(message, cause);
        this.errorCode = errorCode;
    }
}
```
#### 3. 高性能设计
| 优化点         | 实现方式                                      | 收益                     |
|----------------|-----------------------------------------------|--------------------------|
| **连接池复用** | 基于 HikariCP 维护长连接，默认最小/最大池化   | 避免频繁创建/销毁连接的开销，毫秒级响应 |
| **批量操作**   | 使用 JDBC `addBatch()` + `executeBatch()`     | 网络往返次数从 N → 1，性能提升 10-100 倍 |
| **结果集懒加载** | 利用 JDBC 流式结果集 (`setFetchSize`)，边读边处理 | 内存占用随数据量线性增长，避免一次性加载大表 |

#### 4. 可扩展性
- **开闭原则落地**：新增数据库仅需实现 `DBConfigurer` 接口，注册到 `DB_CONFIGURERS` 即可。
- **零侵入核心**：无需改动 SQL 执行引擎、连接管理等核心逻辑，满足 **对扩展开放，对修改关闭**。

# 三、技术架构

## 3.1 整体架构
![性能对比图](./images/整体架构.png)
### 关键分层说明

| 层级     | 组件 / 功能                            | 核心职责                           |
| -------- | -------------------------------------- | ---------------------------------- |
| 客户端层 | Web 前端、Java/Python 服务、第三方系统 | 发起 HTTP 请求，调用接口层         |
| 接口层   | REST API（Swagger 文档化）             | 接收请求、参数校验、路由到服务层   |
| 服务层   | DatabaseService + 子模块               | 业务逻辑处理（连接池、SQL、事务）  |
| 适配层   | DBConfigurer（多数据库适配）           | 数据库差异化配置（方言、连接参数） |
| 数据源层 | MySQL / Oracle / ClickHouse 等         | 最终数据存储与查询执行             |

## 3.2 核心技术栈

| 类别       | 选型                              | 说明                                   |
| ---------- | --------------------------------- | -------------------------------------- |
| 开发语言   | Java (JDK 8)                      | 保持与旧系统兼容                       |
| 框架       | Spring Boot 2.7.15                | 最后一个官方支持 JDK 8 的 LTS 版本     |
| Web 框架   | Spring Web (Spring MVC)           | RESTful 接口                           |
| 连接池     | HikariCP                          | 高性能、低延迟连接池                   |
| API 文档   | SpringDoc OpenAPI                 | 基于 Swagger 3，自动生成在线文档       |
| 日志框架   | SLF4J + Logback                   | 统一日志门面与实现                     |
| 构建工具   | Maven                             | 依赖管理与自动化构建                   |

#### 接口文档依赖（SpringDoc OpenAPI）
在 `pom.xml` 中加入以下依赖，即可自动生成并暴露 Swagger-UI 接口文档（默认地址：`/swagger-ui.html`）。
本项目: `url/db_tool/swagger-ui.html` 可查看接口文档
```xml
<!-- SpringDoc OpenAPI 核心依赖（适配 Spring Boot 2.7+） -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.15</version>
</dependency>

<!-- 支持 JSR-303 参数校验注解（如 @Valid）的文档生成 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-data-rest</artifactId>
    <version>1.6.15</version>
</dependency>
```
---

## 四、使用指南

###
- **运行环境**：JDK 8，内存 ≥ 2 GB  
- **依赖组件**：无（已内置所有主流数据库驱动）  
- **部署方式**：Spring boot 内置Tomcat ( http )服务器
  - 独立服务：直接运行 `java -jar database-service.jar`
  - 嵌入式：作为依赖包引入现有 Spring Boot 应用

---

### 4.2 接口调用示例

#### 示例 1：创建连接

##### 请求
```http
POST /api/database/connect
Content-Type: application/json

{
  "url": "jdbc:mysql://10.245.44.100:3306/testdb",
  "username": "root",
  "password": "xxxxxx",
  "maxActive": 20,
  "minIdle": 5,
  "idleTimeout": 1800000
}
```
## 五、附录
### 错误码表
| 错误码            | HTTP 状态码 | 处理建议                                               |
|-------------------|-------------|--------------------------------------------------------|
| `CONNECT_ERROR`   | 500         | 检查连接 URL / 账号密码，或确认数据库服务可用性        |
| `QUERY_ERROR`     | 400         | 使用 SQL 语法检查工具修正语句，或联系 DBA              |
| `TRANSACTION_ERROR`| 500        | 系统已自动回滚，建议拆分事务或重试                     |
| `UNSUPPORTED_DB`  | 400         | 不支持的数据库类型，如需扩展请联系技术支持             |

### 支持的数据库
详见 **二、核心功能与技术特点 → 模块 4：多数据库适配** 中的“已支持数据库类型”表格。

### 技术支持
- 邮箱：**protectXH@163.com**