Java 后端 / 系统课时
配置数据源与 JPA
配置数据源与 JPA
本课将完成关系型数据库连接、HikariCP 连接池、Hibernate 方言和实体扫描配置,并通过一个事务示例观察 EntityManager 的持久化上下文,确认实体何时被管理、何时写入数据库。
学习目标
- 配置 JDBC 数据源、连接池参数与 JPA 方言
- 正确限定实体扫描和仓库扫描范围
- 通过事务代码理解 EntityManager 的一级缓存与脏检查
准备依赖与数据库
示例使用 MySQL 8、Spring Data JPA 和 Java 21。数据库驱动只负责建立 JDBC 连接,JPA starter 提供 EntityManager、Hibernate 和仓库基础设施。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>先创建独立数据库和最小权限账号,不要直接让应用使用管理员账号。下面 SQL 需要由具备建库和授权权限的运维账号执行。
CREATE DATABASE user_service
CHARACTER SET utf8mb4
COLLATE utf8mb4_0900_ai_ci;
CREATE USER 'user_app'@'%' IDENTIFIED BY '<PASSWORD>';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX
ON user_service.* TO 'user_app'@'%';预期结果
Query OK
Query OK
Query OK不同客户端显示的受影响行数可能不同。生产环境应通过密钥管理系统注入密码,并按迁移工具需要进一步收紧 DDL 权限。
配置连接池与 JPA
Spring Boot 默认使用 HikariCP。连接超时、最大连接数和最小空闲连接数应结合数据库上限与实例副本数计算,不能简单把池子调得越大越好。
spring:
datasource:
url: jdbc:mysql://localhost:3306/user_service?useUnicode=true&characterEncoding=utf8&serverTimezone=UTC
username: user_app
password: ${DB_PASSWORD}
hikari:
pool-name: user-service-pool
maximum-pool-size: 10
minimum-idle: 2
connection-timeout: 3000
validation-timeout: 1000
jpa:
open-in-view: false
hibernate:
ddl-auto: validate
properties:
hibernate:
dialect: org.hibernate.dialect.MySQLDialect
format_sql: true
show-sql: falseddl-auto: validate 只校验实体与表结构,不自动改表,适合配合 Flyway 或 Liquibase。Hibernate 通常能从 JDBC 元数据推断方言;这里显式配置是为了让环境行为清晰,升级数据库或 Hibernate 时仍应重新验证。

限定实体与仓库扫描
默认情况下,Spring Boot 会从启动类所在包向下扫描。企业项目经常按模块拆分,若实体或仓库不在启动类子包中,应显式限定范围,避免启动时遗漏或扫描到不属于当前应用的模块。
package com.example;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.domain.EntityScan;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
@SpringBootApplication
@EntityScan(basePackages = "com.example.user.domain")
@EnableJpaRepositories(basePackages = "com.example.user.repository")
public class UserServiceApplication {
public static void main(String[] args) {
SpringApplication.run(UserServiceApplication.class, args);
}
}包名应指向稳定的模块边界。若启动类已经位于所有业务包的共同父包下,可以省略这两个注解,减少重复配置。
定义实体并观察 EntityManager
下面实体使用数据库自增主键。@Entity 只表示持久化类型,真正决定对象是否受管理的是它是否进入当前 EntityManager 的持久化上下文。
package com.example.user.domain;
import jakarta.persistence.*;
@Entity
@Table(name = "app_user")
public class UserEntity {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, length = 100)
private String name;
protected UserEntity() {
}
public UserEntity(String name) {
this.name = name;
}
public Long getId() {
return id;
}
public String getName() {
return name;
}
public void rename(String name) {
this.name = name;
}
}先通过迁移脚本创建与实体一致的表。
CREATE TABLE app_user (
id BIGINT NOT NULL AUTO_INCREMENT,
name VARCHAR(100) NOT NULL,
PRIMARY KEY (id)
);预期结果
Query OK, 0 rows affected随后编写一个事务服务,验证 persist 后实体进入 managed 状态,以及修改字段后无需再次调用 update。
package com.example.user.application;
import com.example.user.domain.UserEntity;
import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
@Service
public class UserPersistenceService {
@PersistenceContext
private EntityManager entityManager;
@Transactional
public Long createAndRename() {
UserEntity user = new UserEntity("Alice");
entityManager.persist(user);
// persist 后对象进入当前持久化上下文
boolean managedAfterPersist = entityManager.contains(user);
if (!managedAfterPersist) {
throw new IllegalStateException("实体未进入 managed 状态");
}
// 事务提交时,Hibernate 通过脏检查生成 UPDATE
user.rename("Alice Zhang");
return user.getId();
}
}在同一事务中,多次按主键查找同一实体通常会复用一级缓存中的对象;事务结束后,该对象脱离当前持久化上下文。不要把 managed 实体长期保存在单例对象或跨线程传递。
启动与验证
设置环境变量后启动应用。数据库必须可访问,账号权限和表结构也必须与配置一致。
export DB_PASSWORD='<PASSWORD>'
mvn spring-boot:run预期输出
HikariPool-<ID> - Start completed.
Initialized JPA EntityManagerFactory for persistence unit 'default'
Started UserServiceApplication in <TIME> seconds连接池编号和启动耗时会因环境不同而变化。若出现 Access denied,先检查账号、密码和来源主机;若出现 Schema-validation 错误,比较实体列定义与迁移脚本;若找不到实体或仓库,则检查包路径与扫描范围。