Java 后端 / 系统课时
设计实体与主键
设计实体与主键
本课将把业务中的用户对象设计成可持久化实体,重点处理表名、主键生成、字段约束、枚举存储与并发版本字段,最终得到可以被 JPA 正确建表和保存的模型。
学习目标
- 使用
@Entity、@Table和@Column定义实体及数据库约束 - 根据数据库能力选择合适的主键生成策略
- 使用字符串方式持久化枚举,并通过测试验证映射结果
从业务模型确定表结构
实体不是普通 DTO 的简单复制。持久化模型需要明确哪些字段不能为空、长度上限是多少、是否唯一,以及数据库中如何保存状态。约束应尽量同时体现在 Java 注解与数据库结构中,避免只依赖接口校验。
下面示例默认项目已经引入 spring-boot-starter-data-jpa 与 H2 数据库。User 使用数据库自增主键,用户名不可为空且唯一,状态枚举按字符串保存,@Version 用于后续实现乐观锁。
package com.example.demo.user;
import jakarta.persistence.*;
@Entity
@Table(
name = "app_user",
uniqueConstraints = @UniqueConstraint(
name = "uk_app_user_username",
columnNames = "username"
)
)
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, length = 50)
private String username;
@Enumerated(EnumType.STRING)
@Column(nullable = false, length = 20)
private UserStatus status;
@Version
private Long version;
protected User() {
// JPA 通过无参构造器创建实体
}
public User(String username, UserStatus status) {
this.username = username;
this.status = status;
}
public Long getId() {
return id;
}
public String getUsername() {
return username;
}
public UserStatus getStatus() {
return status;
}
public Long getVersion() {
return version;
}
}package com.example.demo.user;
public enum UserStatus {
ACTIVE,
DISABLED
}这两个文件属于同一实体模型。@Column 描述列级约束,@Table 中的唯一约束提供稳定的数据库约束名称,便于生产环境定位重复数据异常。
选择主键策略
GenerationType.IDENTITY 依赖数据库自增列,适合 MySQL 等常见场景,但插入前通常拿不到主键。SEQUENCE 适合支持序列的数据库,并且更利于批量插入。UUID 适合分布式系统,但索引空间和写入局部性需要单独评估。
业务编号不宜直接作为主键。手机号、订单号或用户名可能发生规则调整,而主键应保持无业务含义、不可变且只负责唯一标识。对外暴露的编号可以作为独立唯一字段保存。
正确映射枚举与字段约束
枚举应优先使用 EnumType.STRING。如果使用默认的序号存储,调整枚举常量顺序后,历史数据会被解释成错误状态。字符串虽然多占少量空间,但可读性和演进安全性更高。
nullable = false、length 和唯一约束会影响数据库结构,但它们不能替代请求参数校验。接口层仍应使用 Bean Validation 提前返回清晰错误,数据库约束负责守住最终一致性。
验证实体映射
先创建仅用于测试保存行为的 Repository。
package com.example.demo.user;
import org.springframework.data.jpa.repository.JpaRepository;
public interface UserRepository extends JpaRepository<User, Long> {
}再编写数据层测试,确认主键、枚举和版本字段能够正确写入。
package com.example.demo.user;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import static org.assertj.core.api.Assertions.assertThat;
@DataJpaTest
class UserEntityTest {
@Autowired
private UserRepository userRepository;
@Test
void shouldPersistEntityWithGeneratedId() {
User saved = userRepository.saveAndFlush(
new User("alice", UserStatus.ACTIVE)
);
assertThat(saved.getId()).isNotNull();
assertThat(saved.getStatus()).isEqualTo(UserStatus.ACTIVE);
assertThat(saved.getVersion()).isNotNull();
System.out.println("id=" + saved.getId());
System.out.println("status=" + saved.getStatus());
}
}执行测试:
mvn -q -Dtest=UserEntityTest test预期输出:
id=<ID>
status=ACTIVE<ID> 由数据库生成,实际数值可能不同。测试通过说明实体可以写入、主键能够回填,并且枚举按预期恢复为 ACTIVE。
常见设计错误
不要给实体类使用包含所有字段的公开构造器,否则调用方可能绕过业务规则直接修改主键或版本号。也不要在实体中保存接口专用字段,例如验证码、确认密码或展示文本,这些字段应留在 DTO 中。
修改已上线表结构时,还应通过 Flyway 或 Liquibase 管理迁移脚本,而不是依赖 Hibernate 自动改表。生产环境通常使用 ddl-auto=validate 检查映射与表结构是否一致。