Java 后端 / 系统课时

设计实体与主键

设计实体与主键

本课将把业务中的用户对象设计成可持久化实体,重点处理表名、主键生成、字段约束、枚举存储与并发版本字段,最终得到可以被 JPA 正确建表和保存的模型。

学习目标

  • 使用 @Entity、@Table 和 @Column 定义实体及数据库约束
  • 根据数据库能力选择合适的主键生成策略
  • 使用字符串方式持久化枚举,并通过测试验证映射结果

从业务模型确定表结构

实体不是普通 DTO 的简单复制。持久化模型需要明确哪些字段不能为空、长度上限是多少、是否唯一,以及数据库中如何保存状态。约束应尽量同时体现在 Java 注解与数据库结构中,避免只依赖接口校验。

下面示例默认项目已经引入 spring-boot-starter-data-jpa 与 H2 数据库。User 使用数据库自增主键,用户名不可为空且唯一,状态枚举按字符串保存,@Version 用于后续实现乐观锁。

java
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;
    }
}
java
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。

java
package com.example.demo.user;

import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
}

再编写数据层测试,确认主键、枚举和版本字段能够正确写入。

java
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());
    }
}

执行测试:

bash
mvn -q -Dtest=UserEntityTest test

预期输出:

text
id=<ID>
status=ACTIVE

<ID> 由数据库生成,实际数值可能不同。测试通过说明实体可以写入、主键能够回填,并且枚举按预期恢复为 ACTIVE。

常见设计错误

不要给实体类使用包含所有字段的公开构造器,否则调用方可能绕过业务规则直接修改主键或版本号。也不要在实体中保存接口专用字段,例如验证码、确认密码或展示文本,这些字段应留在 DTO 中。

修改已上线表结构时,还应通过 Flyway 或 Liquibase 管理迁移脚本,而不是依赖 Hibernate 自动改表。生产环境通常使用 ddl-auto=validate 检查映射与表结构是否一致。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计实体与主键

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通