# java数据访问工具

**Repository Path**: thelongestday/java-dbutils

## Basic Information

- **Project Name**: java数据访问工具
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 67
- **Created**: 2025-05-19
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DBUtils - 轻量级 Java 数据访问工具

DBUtils 是一个轻量级的 Java 数据访问框架，封装了 JDBC 的核心操作，简化数据库连接管理、SQL 执行、结果集映射和事务控制，帮助开发者以更少的代码完成常见的数据库 CRUD 操作。

## 项目特性

- **简洁的 JDBC 封装** — 通过 `JdbcTemplate` 提供统一的查询、更新、插入方法，无需手动管理 `PreparedStatement`
- **线程安全的连接管理** — 基于 `ThreadLocal` 实现数据库连接的线程绑定，确保并发安全
- **事务管理** — 通过 `TransactionManager` 轻松开启、提交和回滚事务
- **灵活的结果集映射** — 基于函数式接口 `RowMapper<T>`，支持将查询结果自动映射为 Java 对象
- **分页查询支持** — 内置 `Page<T>` 泛型分页组件，封装分页逻辑
- **参数化查询** — 支持 `Object...params` 可变参数和 `ParameterMap` 两种参数传递方式
- **自定义异常体系** — 提供 `AccessDbException` 和 `TransactionException` 统一异常处理
- **日志记录** — 基于 Log4j 记录数据库操作日志

## 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| JDK | 21 | 编译与运行环境 |
| MySQL Connector/J | 9.7.0 | MySQL 数据库驱动 |
| Lombok | 1.18.38 | 减少样板代码 |
| Log4j | 1.2.17 | 日志框架 |
| JUnit | 4.13.2 | 单元测试框架 |

## 项目结构

```
src/main/java/
├── com/yuhf/
│   ├── dbutils/
│   │   ├── exception/
│   │   │   ├── AccessDbException.java        # 数据库访问异常
│   │   │   └── TransactionException.java      # 事务异常
│   │   ├── iface/
│   │   │   └── RowMapper.java                 # 结果集映射函数式接口
│   │   ├── DBConnection.java                  # 数据库连接管理（ThreadLocal）
│   │   ├── JdbcTemplate.java                  # 核心模板类（CRUD 操作）
│   │   ├── ParameterMap.java                  # 查询参数封装
│   │   └── TransactionManager.java            # 事务管理器
│   └── page/
│       └── Page.java                          # 分页封装类
└── edu/yuhf/
    ├── dao/                                   # DAO 层（接口 + JDBC 实现）
    ├── domain/                                # 实体类 + RowMapper 实现
    ├── service/                               # Service 层（接口 + 实现）
    └── Constants.java                         # 常量定义
```

## 快速开始

### 1. 环境要求

- JDK 21+
- MySQL 数据库
- Maven 3.x

### 2. 配置数据库连接

在 `src/main/resources/jdbc.properties` 中配置你的数据库信息：

```properties
jdbc.driverClassName=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/db_school
jdbc.userName=root
jdbc.password=123456
```

### 3. 构建项目

```bash
mvn clean compile
```

### 4. 运行测试

```bash
mvn test
```

> 注：本项目测试为集成测试，依赖运行中的 MySQL 数据库（需先建好 `db_school` 库及对应表结构）。
> 如需跳过测试，可执行 `mvn clean install -DskipTests`。

## 核心用法

### JdbcTemplate — 核心模板类

`JdbcTemplate` 是框架的核心，提供以下静态方法：

| 方法 | 说明 |
|------|------|
| `query(sql, RowMapper, params...)` | 查询并映射为对象列表 |
| `query(sql, params...)` | 查询并返回 `List<Map<String, Object>>` |
| `update(sql, params...)` | 执行增/删/改操作，返回受影响行数 |
| `insertByGenerateKey(sql, params...)` | 插入数据并返回自增主键 |
| `getTotalRow(sql, params...)` | 查询总记录数（用于分页） |

### RowMapper — 结果集映射

实现 `RowMapper<T>` 接口，将 `ResultSet` 映射为 Java 对象：

```java
public class StudentMapper implements RowMapper<Student> {
    @Override
    public Student handler(ResultSet rs) throws SQLException {
        Student student = new Student();
        student.setId(rs.getInt("id"));
        student.setName(rs.getString("name"));
        // ...
        return student;
    }
}
```

### 事务管理

```java
TransactionManager.beginTransaction();  // 开启事务
try {
    JdbcTemplate.update(sql1, params1);
    JdbcTemplate.update(sql2, params2);
    TransactionManager.commit();        // 提交事务
} catch (Exception e) {
    TransactionManager.rollback();      // 回滚事务
}
```

### 分页查询

```java
Page<Student> page = new Page<>(1);     // 第 1 页，默认每页 10 条
page.setTotalPage(totalRow);            // 设置总记录数，自动计算总页数
List<Student> data = studentDao.queryStudentAll(page);
```

## 许可证

本项目基于 [LICENSE](LICENSE) 开源协议。