# db-utils

**Repository Path**: Demitri/db-utils

## Basic Information

- **Project Name**: db-utils
- **Description**: 数据库连接工具
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-15
- **Last Updated**: 2025-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据库工具库 (DB-Utils)

这是一个基于Java 8的数据库操作工具库，可以打包成jar包并引入到其他Java项目中使用。它提供了常用的数据库操作功能，帮助开发者简化数据库访问代码。

## 功能特点

- 数据库连接池管理
- 通用JDBC操作封装
- 事务支持
- 实体对象映射
- 批量操作支持
- 灵活的查询结果处理机制
- **自动配置和初始化**（无需手动配置即可使用）
- **完整的UTF-8编码支持**（配置文件和数据库连接）

## 编码说明

整个工程采用UTF-8编码，确保中文等多语言环境下的正常运行：

1. 源代码文件采用UTF-8编码
2. 配置文件读取时使用UTF-8编码
3. 默认数据库连接带有UTF-8字符集设置
4. Maven编译时指定UTF-8编码

这样可以确保从配置文件到数据库连接的整个过程都能正确处理中文等特殊字符。

## 如何使用

### 1. 构建JAR包

使用Maven构建项目：

```bash
cd db-utils
mvn clean package
```

构建完成后，JAR包将在`target`目录中生成。

### 2. 在其他项目中引入

在你的项目的`pom.xml`中添加依赖：

```xml
<dependency>
    <groupId>com.example</groupId>
    <artifactId>db-utils</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>
```

如果你使用的是本地JAR包，可以通过以下方式引入：

```xml
<dependency>
    <groupId>com.example</groupId>
    <artifactId>db-utils</artifactId>
    <version>1.0-SNAPSHOT</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/db-utils-1.0-SNAPSHOT.jar</systemPath>
</dependency>
```

### 3. 数据库连接池初始化

#### 方式1：自动初始化（推荐）

添加依赖后，数据库工具库会在首次使用时自动尝试初始化。它会按以下顺序查找配置：

1. 应用根目录下的`application.properties`或`application.yml`
2. 类路径下的`application.properties`
3. 类路径下的`db.properties`
4. 环境变量和系统属性
5. 内置默认配置

你只需要在项目根目录或类路径下添加配置文件即可：

**application.properties 示例**：
```properties
# 数据库连接信息
db.driverClassName=com.mysql.cj.jdbc.Driver
db.jdbcUrl=jdbc:mysql://localhost:3306/mydb?useUnicode=true&characterEncoding=UTF-8
db.username=myuser
db.password=mypassword
db.maxPoolSize=10
```

**application.yml 示例**：
```yaml
db:
  driverClassName: com.mysql.cj.jdbc.Driver
  jdbcUrl: jdbc:mysql://localhost:3306/mydb?useUnicode=true&characterEncoding=UTF-8
  username: myuser
  password: mypassword
  maxPoolSize: 10
```

#### 方式2：手动初始化

如果你希望手动控制初始化过程，可以使用以下方法：

```java
// 方法1：直接传入连接参数
DatabaseManager.initialize(
    "jdbc:mysql://localhost:3306/mydb",
    "username",
    "password",
    10  // 最大连接数
);

// 方法2：使用Properties配置
Properties props = new Properties();
props.setProperty("jdbcUrl", "jdbc:mysql://localhost:3306/mydb");
props.setProperty("username", "username");
props.setProperty("password", "password");
props.setProperty("maximumPoolSize", "10");
DatabaseManager.initialize(props);

// 方法3：使用配置类
DbConfig config = new DbConfig()
    .setJdbcUrl("jdbc:mysql://localhost:3306/mydb")
    .setUsername("username")
    .setPassword("password")
    .setMaxPoolSize(10);
DatabaseManager.initialize(config);

// 方法4：从配置文件初始化
DatabaseManager.initializeFromFile("path/to/config.properties");  // 支持.properties和.yml文件
```

#### 禁用自动初始化

如果你不希望使用自动初始化功能：

```java
// 禁用自动初始化
DatabaseManager.setAutoInitFromConfig(false);
```

### 4. 使用JdbcUtils执行SQL操作

```java
// 执行查询
List<Map<String, Object>> results = JdbcUtils.query("SELECT * FROM users WHERE age > ?", 18);

// 查询单行数据
Map<String, Object> user = JdbcUtils.queryForMap("SELECT * FROM users WHERE id = ?", 1);

// 查询单个值
Long count = JdbcUtils.queryForObject("SELECT COUNT(*) FROM users");

// 执行更新
int affectedRows = JdbcUtils.update("UPDATE users SET name = ? WHERE id = ?", "新名称", 1);

// 执行批量更新
List<Object[]> batchParams = new ArrayList<>();
batchParams.add(new Object[]{"用户1", "user1@example.com"});
batchParams.add(new Object[]{"用户2", "user2@example.com"});
int[] results = JdbcUtils.batchUpdate("INSERT INTO users (name, email) VALUES (?, ?)", batchParams);

// 在事务中执行操作
JdbcUtils.executeTransaction(conn -> {
    // 执行多个数据库操作
    PreparedStatement stmt1 = conn.prepareStatement("INSERT INTO orders (product_id, amount) VALUES (?, ?)");
    stmt1.setInt(1, 100);
    stmt1.setDouble(2, 99.99);
    stmt1.executeUpdate();
    
    PreparedStatement stmt2 = conn.prepareStatement("UPDATE inventory SET stock = stock - ? WHERE product_id = ?");
    stmt2.setInt(1, 1);
    stmt2.setInt(2, 100);
    stmt2.executeUpdate();
    
    return true; // 返回操作结果
});
```

### 5. 使用通用查询方法

库中新增了通用查询方法，可以根据需要处理查询结果：

```java
// 查询并返回所有结果
List<Map<String, Object>> users = JdbcUtils.queryForList(
    "SELECT * FROM users WHERE active = ?", 
    true
);

// 查询并返回实体列表
List<User> activeUsers = JdbcUtils.queryForEntityList(
    "SELECT * FROM users WHERE active = ?", 
    User.class, 
    true
);

// 查询并返回单个实体
User user = JdbcUtils.queryForEntity(
    "SELECT * FROM users WHERE id = ?", 
    User.class, 
    1
);

// 使用自定义结果处理器
List<String> usernames = JdbcUtils.executeQuery(
    "SELECT username FROM users", 
    rs -> {
        List<String> names = new ArrayList<>();
        while (rs.next()) {
            names.add(rs.getString("username"));
        }
        return names;
    }
);

// 处理复杂查询结果
List<UserDTO> userDTOs = JdbcUtils.executeQuery(
    "SELECT u.id, u.username, o.order_count FROM users u " +
    "LEFT JOIN (SELECT user_id, COUNT(*) as order_count FROM orders GROUP BY user_id) o " +
    "ON u.id = o.user_id WHERE u.active = ?",
    rs -> {
        List<UserDTO> result = new ArrayList<>();
        while (rs.next()) {
            UserDTO dto = new UserDTO();
            dto.setId(rs.getLong("id"));
            dto.setUsername(rs.getString("username"));
            dto.setOrderCount(rs.getInt("order_count"));
            result.add(dto);
        }
        return result;
    },
    true
);
```

### 6. 使用EntityMapper映射实体对象

```java
// 定义实体类
public class User {
    private Long id;
    private String username;
    private String email;
    // getter和setter方法
}

// 查询并映射到实体对象
JdbcUtils.executeTransaction(conn -> {
    PreparedStatement stmt = conn.prepareStatement("SELECT * FROM users");
    ResultSet rs = stmt.executeQuery();
    
    // 映射到实体对象列表
    List<User> users = EntityMapper.mapToList(rs, User.class);
    return users;
});
```

## 配置参数说明

以下是配置文件（properties或yml）中可用的配置参数：

| 参数名 | 说明 | 默认值 |
|-------|------|-------|
| db.driverClassName | JDBC驱动类名 | com.mysql.cj.jdbc.Driver |
| db.jdbcUrl | 数据库连接URL | jdbc:mysql://localhost:3306/test?useSSL=false&serverTimezone=UTC |
| db.username | 数据库用户名 | root |
| db.password | 数据库密码 | root |
| db.maxPoolSize | 连接池最大连接数 | 10 |
| db.connectionTimeout | 连接超时时间（毫秒） | 30000 |
| db.idleTimeout | 空闲连接超时时间（毫秒） | 600000 |
| db.autoCommit | 是否自动提交 | false |
| db.prop.* | 其他数据源属性，如`db.prop.cachePrepStmts=true` | - |

## 注意事项

- 引入JAR包后，框架会自动尝试初始化数据库连接池
- 如果自动初始化失败，可以手动初始化或提供自定义配置
- 在应用关闭时调用`DatabaseManager.close()`释放连接池资源
- 默认情况下，所有操作都在事务中执行
- 使用`EntityMapper`时，实体类的字段名应与数据库列名匹配（不区分大小写）
- 使用通用查询方法时，可以自定义结果集处理逻辑，灵活处理查询结果

## 示例代码

参见以下示例代码，展示了如何使用此库进行数据库操作：
- `com.example.dbutils.example.User` - 实体类示例
- `com.example.dbutils.example.UserDao` - 数据访问对象示例
- `com.example.dbutils.example.QueryExample` - 通用查询方法使用示例
- `com.example.dbutils.example.AutoConfigExample` - 自动配置与初始化示例