# fastdbsession

**Repository Path**: CheonSeongIm/fastdbsession

## Basic Information

- **Project Name**: fastdbsession
- **Description**: 基于原生java.sql.*实现的高性能dbsession！
适用于高性能、高可用、高频率、高并发的交易系统等！
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fastdbsession

基于原生 `java.sql.*` 实现的高性能数据库会话框架，使用 HikariCP 连接池，支持多数据源、事务管理、数据库方言和密码加密。
适用于高性能、高并发的交易、订单等系统。
正式环境请使用release版本~
后续功能持续迭代中，敬请期待！
如果您有需求，也可以私信联系我~

## 特性

- 基于原生 JDBC API，轻量高性能
- HikariCP 连接池，开箱即用
- 支持多数据源配置与切换
- ThreadLocal 线程级会话管理
- 内置事务管理（开启/提交/回滚）
- 数据库方言支持（目前支持 MySQL 分页）
- 实体查询：基于反射自动将 ResultSet 映射为实体对象（`snake_case` 自动转 `camelCase`）
- 自定义映射：通过 `IResultSetMapper<T>` 函数式接口支持自定义映射逻辑
- 密码加密：配置文件中密码以密文存储，支持 AES/SM4/BASE64 算法，可自定义扩展
- SQL 调试日志开关
- Spring Boot 自动配置

## 环境要求

- JDK 21+
- Maven 3.x
- Spring Boot（配置加载依赖）

## 安装

在 `pom.xml` 中添加依赖：

```xml
<dependency>
    <groupId>com.solomiao.fastdbsession</groupId>
    <artifactId>fastdbsession</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>
```

## 配置

在 Spring Boot 启动类上添加包扫描：

```java
@SpringBootApplication(scanBasePackages = "com.solomiao.fastdbsession")
```

在 Spring Boot 配置文件（`application.properties` 或 `application.yml`）中添加数据源配置：

```properties
# 数据源名称列表，多个用逗号分隔
solomiao.database.datasource.names=ds1

# 数据源 ds1 配置
solomiao.database.datasource.ds1.url=jdbc:mysql://localhost:3306/mydb
solomiao.database.datasource.ds1.userName=root
solomiao.database.datasource.ds1.passWord=<加密后的密文>
solomiao.database.datasource.ds1.driverClassName=com.mysql.cj.jdbc.Driver
solomiao.database.datasource.ds1.databaseType=mysql
solomiao.database.datasource.ds1.defaultDataSource=true
solomiao.database.datasource.ds1.maximumPoolSize=10
solomiao.database.datasource.ds1.minimumIdle=5
solomiao.database.datasource.ds1.connectionTimeout=30000
solomiao.database.datasource.ds1.validationTimeout=5000
solomiao.database.datasource.ds1.connectionTestQuery=SELECT 1
solomiao.database.datasource.ds1.debugLogSql=true

# 加密算法（可选，默认 AES）
solomiao.database.datasource.passwordEncryptAlgorithm=AES
```

### 配置项说明

| 配置项 | 说明 | 必填 |
|--------|------|------|
| url | 数据库连接地址 | 是 |
| userName | 用户名 | 是 |
| passWord | 密码（密文） | 是 |
| driverClassName | 驱动类名 | 是 |
| databaseType | 数据库类型（目前支持 mysql） | 是 |
| defaultDataSource | 是否为默认数据源 | 是 |
| maximumPoolSize | 最大连接数 | 是 |
| minimumIdle | 最小空闲连接数 | 是 |
| connectionTimeout | 连接超时时间（毫秒） | 是 |
| validationTimeout | 验证超时时间（毫秒） | 是 |
| connectionTestQuery | 连接测试语句 | 是 |
| debugLogSql | 是否打印 SQL 调试日志 | 是 |
| passwordEncryptAlgorithm | 密码加密算法（AES / SM4 / BASE64，默认 AES） | 否 |

### 密码加密

配置文件中的 `passWord` 必须填写加密后的密文，启动时自动解密。

**1. 设置密钥环境变量（必须）**

```bash
export DB_PASSWORD_ENCRYPT_KEY=your-secret-key-1
```

> 密钥长度要求：AES 和 SM4 均为 16 字节。

**2. 生成密文**

通过命令行工具生成：

```bash
java -cp fastdbsession.jar com.solomiao.fastdbsession.impl.encrypt.PasswordEncryptor <算法> <明文密码> <密钥>

# 示例：使用 AES 加密
java -cp fastdbsession.jar com.solomiao.fastdbsession.impl.encrypt.PasswordEncryptor AES 123456 your-secret-key-1
# 输出: G6N718UyPEPGbpVrQ9J5fA==
```

或通过代码生成：

```java
String cipherText = PasswordEncryptorFactory.getEncryptor(EncryptAlgorithm.AES)
    .encrypt("123456", "your-secret-key-1");
```

**3. 支持的算法**

| 算法 | 密钥长度 | 说明 |
|------|----------|------|
| AES | 16 字节 | 默认算法，JDK 原生支持 |
| SM4 | 16 字节 | 国密算法，需引入 BouncyCastle 依赖 |
| BASE64 | 无需密钥 | 仅编码非加密，仅供测试使用 |

**4. 自定义加解密**

实现 `IPasswordEncryptor` 接口即可自定义加解密逻辑：

```java
public class MyEncryptor implements IPasswordEncryptor {
    @Override
    public String encrypt(String plainText, String key) { ... }

    @Override
    public String decrypt(String cipherText, String key) { ... }

    @Override
    public EncryptAlgorithm getAlgorithm() { ... }
}
```

## 使用说明

### 获取会话

```java
// 获取会话工厂单例
DatabaseSessionFactory factory = DatabaseSessionFactory.getInstance();

// 获取当前线程的会话（默认数据源，同一线程复用）
IDatabaseSessionCommon session = factory.getSession();

// 获取当前线程的会话（指定数据源）
IDatabaseSessionCommon session = factory.getSession("ds1");

// 创建新的会话（不复用线程会话）
IDatabaseSessionCommon session = factory.getNewSession();
```

### 执行 SQL

```java
// 无参数执行
int rows = session.execute("DELETE FROM user WHERE id = 1");

// 带参数执行（PreparedStatement，防 SQL 注入）
int rows = session.execute("INSERT INTO user(name, age) VALUES(?, ?)", "张三", 25);

// 使用 List 传参
List<Object> params = Arrays.asList("李四", 30);
int rows = session.executeByList("INSERT INTO user(name, age) VALUES(?, ?)", params);
```

### 查询

```java
// 查询结果集
ResultSet rs = session.getResultSet("SELECT * FROM user");
ResultSet rs = session.getResultSet("SELECT * FROM user WHERE age > ?", 18);

// 分页查询
ResultSet rs = session.getResultSetForPage("SELECT * FROM user", 1, 10);

// 计数
int total = session.count("SELECT COUNT(*) FROM user");

// 使用完毕后关闭 ResultSet 和 Statement
session.closeResultSetAndStatement(rs);
```

### 实体查询

实体查询方法会自动关闭 `ResultSet` 和 `Statement`，无需手动调用 `closeResultSetAndStatement()`。

**默认映射（基于反射）：**

实体类需要有无参构造器和符合 JavaBean 规范的 setter 方法，数据库列名（`snake_case`）会自动转换为 Java 字段名（`camelCase`）。

```java
// 定义实体类
public class User {
    private Integer id;
    private String userName;  // 对应数据库列 user_name
    private Integer age;

    public Integer getId() { return id; }
    public void setId(Integer id) { this.id = id; }
    public String getUserName() { return userName; }
    public void setUserName(String userName) { this.userName = userName; }
    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }
}

// 查询单条记录
User user = session.getEntity("SELECT * FROM user WHERE id = ?", User.class, 1);

// 查询多条记录
List<User> users = session.getEntityList("SELECT * FROM user WHERE age > ?", User.class, 18);

// 使用 List 传参
List<Object> params = Arrays.asList(18);
List<User> users = session.getEntityListByList("SELECT * FROM user WHERE age > ?", User.class, params);
```

**自定义映射（IResultSetMapper）：**

通过 `IResultSetMapper<T>` 函数式接口自定义映射逻辑，支持 Lambda 表达式：

```java
// 使用 Lambda 自定义映射
User user = session.getEntity("SELECT * FROM user WHERE id = ?",
    rs -> {
        User u = new User();
        u.setId(rs.getInt("id"));
        u.setUserName(rs.getString("user_name"));
        u.setAge(rs.getInt("age"));
        return u;
    }, 1);

// 自定义映射查询列表
List<User> users = session.getEntityList("SELECT * FROM user",
    rs -> {
        User u = new User();
        u.setId(rs.getInt("id"));
        u.setUserName(rs.getString("user_name"));
        return u;
    });
```

### 事务管理

```java
try {
    session.onTransaction();           // 开启事务
    session.execute("UPDATE account SET balance = balance - 100 WHERE id = 1");
    session.execute("UPDATE account SET balance = balance + 100 WHERE id = 2");
    session.offTransaction();          // 提交事务
} catch (SQLException e) {
    session.rollbackTransaction();     // 回滚事务
}
```

### 关闭会话

```java
// 关闭指定会话
factory.closeDatabaseSession(session);

// 清理当前线程所有会话
factory.clearDatabaseSession();
```

## 软件架构

```
com.solomiao.fastdbsession
├── config/            # Spring 配置加载（DatabaseConfiguration）
├── constants/         # 常量定义（DatabaseType, DatasourceAttribute, EncryptAlgorithm）
├── exception/         # 异常体系
│   ├── abstracts/     # 基础异常类（BaseException, BaseRuntimeException）
│   ├── enums/         # 错误枚举（DatasourceErrorEnum）
│   ├── factory/       # 异常工厂（ExceptionFactory）
│   ├── impl/          # 业务异常实现
│   └── interfaces/    # 异常接口
├── impl/
│   ├── datasource/    # 数据源实现（HikariDataSourceImpl, DataSourceFactory）
│   ├── dialect/       # 方言实现（MysqlDialect, DialectFactory）
│   ├── encrypt/       # 密码加解密实现（AesPasswordEncryptor, Sm4PasswordEncryptor, Base64PasswordEncryptor, PasswordEncryptorFactory）
│   ├── mapper/        # 实体映射（ResultSetMapperImpl）
│   └── session/       # 会话实现（DatabaseSession, DatabaseSessionFactory）
├── interfaces/        # 核心接口（IDataSource, IDatabaseSessionCommon, IDatabaseSessionEntity, IPasswordEncryptor, IResultSetMapper, IDialect 等）
└── utils/             # 工具类（ColumnNameUtil 列名转换, StringUtil）
```

### 核心流程

1. `DatabaseConfiguration` 从 Spring Environment 加载配置，对 `passWord` 自动解密
2. `DataSourceFactory` 根据配置创建 `HikariDataSourceImpl` 实例
3. `DatabaseSessionFactory` 通过 ThreadLocal 管理线程级会话
4. `DatabaseSession` 封装 JDBC 操作，支持事务、分页、实体映射、参数化查询

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 修改代码，创建merge请求