@Entity 里面的 JPA 注解

作者：Xiao8

2022 年 7 月 23 日
本文字数：4696 字
阅读完需：约 15 分钟

JPA 协议中关于 Entity 的相关规定

我们先看一下 JPA 协议里面关于实体做了哪些规定。（这里推荐一个查看 JPA 协议的官方地址：https://download.oracle.com/otn-pub/jcp/persistence-2_2-mrel-spec/JavaPersistence.pdf）

实体是直接进行数据库持久化操作的领域对象（即一个简单的 POJO，可以按照业务领域划分），必须通过 @Entity 注解进行标示。
实体必须有一个 public 或者 protected 的无参数构造方法。
持久化映射的注解可以标示在 Entity 的字段 field 上，如下所示：

@Column(length = 20, nullable = false)
private String userName;

复制代码

除此之外，也可以将持久化注解运用在 Entity 里面的 get/set 方法上，通常我们是放在 get 方法中，如下所示：

@Column(length = 20, nullable = false)
public String getUserName(){
    return userName;
}

复制代码

概括起来，就是 Entity 里面的注解生效只有两种方式：将注解写在字段上或者将注解写在方法上（JPA 里面称 Property）。

但是需要注意的是，在同一个 Entity 里面只能有一种方式生效，也就是说，注解要么全部写在 field 上面，要么就全部写在 Property 上面，因为我经常会看到有的同事分别在两种方式中加了注解后说：“哎呀，我的注解怎么没有生效呀！”因此这一点需要特别注意。

只要是在 @Entity 的实体里面被注解标注的字段，都会被映射到数据库中，除了使用 @Transient 注解的字段之外。
实体里面必须要有一个主键，主键标示的字段可以是单个字段，也可以是复合主键字段。

以上我只挑选了最关键的几条进行了介绍，如果你有兴趣可以读一读 Java Persistence API 协议，这样我们在做 JPA 开发的时候就会顺手很多，可以理解很多 Hibernate 里面实现方法。

这也为你提供了一条解决疑难杂症的思路，也就是当我们遇到解决不了的问题时，就去看协议、阅读官方文档，深入挖掘一下，可能就会找到答案。那么接下来我们看看实例里面常用的注解有哪些。

详细的注解都有哪些？

我们先通过源码看看 JPA 里面支持的注解有哪些。

首先，我们利用 IEDA 工具，打开 @Entity 所在的包，就可以看到 JPA 里面支持的注解有哪些。如下所示：

我们可以看到，在 jakarta.persistence-api 的包路径下面大概有一百多个注解，你在没事的时候可以到这里面一个一个地看，也可以到 JPA 的协议里面对照查看文档。

我在这里只提及一些最常见的，包括 @Entity、@Table、@Access、@Id、@GeneratedValue、@Enumerated、@Basic、@Column、@Transient、@Lob、@Temporal 等。

@Entity 用于定义对象将会成为被 JPA 管理的实体，必填，将字段映射到指定的数据库表中，使用起来很简单，直接用在实体类上面即可，通过源码表达的语法如下：

@Target(TYPE) //表示此注解只能用在class上面
public @interface Entity {
   //可选，默认是实体类的名字，整个应用里面全局唯一。
   String name() default "";
}

复制代码

@Table 用于指定数据库的表名，表示此实体对应的数据库里面的表名，非必填，默认表名和 entity 名字一样。

@Target(TYPE) //一样只能用在类上面
public @interface Table {
   //表的名字，可选。如果不填写，系统认为好实体的名字一样为表名。
   String name() default "";
   //此表所在schema，可选
   String schema() default "";
   //唯一性约束，在创建表的时候有用，表创建之后后面就不需要了。
   UniqueConstraint[] uniqueConstraints() default { };
   //索引，在创建表的时候使用，表创建之后后面就不需要了。
   Index[] indexes() default {};
}

复制代码

@Access 用于指定 entity 里面的注解是写在字段上面，还是 get/set 方法上面生效，非必填。在默认不填写的情况下，当实体里面的第一个注解出现在字段上或者 get/set 方法上面，就以第一次出现的方式为准；也就是说，一个实体里面的注解既有用在 field 上面，又有用在 properties 上面的时候，看下面的代码你就会明白。

@Id
private Long id;
@Column(length = 20, nullable = false)
public String getUserName(){
    return userName;
}

复制代码

那么由于 @Id 是实体里面第一个出现的注解，并且作用在字段上面，所以所有写在 get/set 方法上面的注解就会失效。而 @Access 可以干预默认值，指定是在 fileds 上面生效还是在 properties 上面生效。我们通过源码看下语法：

@Target( { TYPE, METHOD, FIELD })//表示此注解可以运用在class上(那么这个时候就可以指定此实体的默认注解生效策略了)，也可以用在方法上或者字段上(表示可以独立设置某一个字段或者方法的生效策略)；
@Retention(RUNTIME)
public @interface Access {
//指定是字段上面生效还是方法上面生效
    AccessType value();
}
public enum AccessType {
    FIELD,
    PROPERTY
}

复制代码

@Id 定义属性为数据库的主键，一个实体里面必须有一个主键，但不一定是这个注解，可以和 @GeneratedValue 配合使用或成对出现。
@GeneratedValue 主键生成策略，如下所示：

public @interface GeneratedValue {
    //Id的生成策略
    GenerationType strategy() default AUTO;
    //通过Sequences生成Id,常见的是Orcale数据库ID生成规则，这个时候需要配合@SequenceGenerator使用
    String generator() default "";
}

复制代码

其中，GenerationType 一共有以下四个值：

public enum GenerationType {
    //通过表产生主键，框架借由表模拟序列产生主键，使用该策略可以使应用更易于数据库移植。
    TABLE,
    //通过序列产生主键，通过 @SequenceGenerator 注解指定序列名， MySql 不支持这种方式；
    SEQUENCE,
    //采用数据库ID自增长， 一般用于mysql数据库
    IDENTITY,
//JPA 自动选择合适的策略，是默认选项；
    AUTO
}

复制代码

@Enumerated 这个注解很好用，因为它对 enum 提供了下标和 name 两种方式，用法直接映射在 enum 枚举类型的字段上。请看下面源码。

@Target({METHOD, FIELD}) //作用在方法和字段上
public @interface Enumerated {
//枚举映射的类型，默认是ORDINAL（即枚举字段的下标）。
    EnumType value() default ORDINAL;
}
public enum EnumType {
    //映射枚举字段的下标
    ORDINAL,
    //映射枚举的Name
    STRING
}

复制代码

再来看一个 User 里面关于性别枚举的例子，你就会知道 @Enumerated 在这里没什么作用了，如下所示：

//有一个枚举类，用户的性别
public enum Gender {
    MAIL("男性"), FMAIL("女性");
    private String value;
    private Gender(String value) {
        this.value = value;
    }
}
//实体类@Enumerated的写法如下
@Entity
@Table(name = "tb_user")
public class User implements Serializable {
    @Enumerated(EnumType.STRING)
    @Column(name = "user_gender")
    private Gender gender;
    .......................
}

复制代码

这时候插入两条数据，数据库里面的值会变成 MAIL/FMAIL，而不是“男性” / 女性。

经验分享： 如果我们用 @Enumerated（EnumType.ORDINAL），这时候数据库里面的值是 0、1。但是实际工作中，不建议用数字下标，因为枚举里面的属性值是会不断新增的，如果新增一个，位置变化了就惨了。并且 0、1、2 这种下标在数据库里面看着非常痛苦，时间长了就会一点也看不懂了。

@Basic 表示属性是到数据库表的字段的映射。如果实体的字段上没有任何注解，默认即为 @Basic。也就是说默认所有的字段肯定是和数据库进行映射的，并且默认为 Eager 类型。

public @interface Basic {
    //可选，EAGER（默认）：立即加载；LAZY：延迟加载。（LAZY主要应用在大字段上面）
    FetchType fetch() default EAGER;
    //可选。这个字段是否可以为null，默认是true。
    boolean optional() default true;
}

复制代码

@Transient 表示该属性并非一个到数据库表的字段的映射，表示非持久化属性。JPA 映射数据库的时候忽略它，与 @Basic 有相反的作用。也就是每个字段上面 @Transient 和 @Basic 必须二选一，而什么都不指定的话，默认是 @Basic。
@Column 定义该属性对应数据库中的列名。

public @interface Column {
    //数据库中的表的列名；可选，如果不填写认为字段名和实体属性名一样。
    String name() default "";
    //是否唯一。默认flase，可选。
    boolean unique() default false;
    //数据字段是否允许空。可选，默认true。
    boolean nullable() default true;
    //执行insert操作的时候是否包含此字段，默认，true，可选。
    boolean insertable() default true;
    //执行update的时候是否包含此字段，默认，true，可选。
    boolean updatable() default true;
    //表示该字段在数据库中的实际类型。
    String columnDefinition() default "";
   //数据库字段的长度，可选，默认255
    int length() default 255;
}

复制代码

@Temporal 用来设置 Date 类型的属性映射到对应精度的字段，存在以下三种情况：

@Temporal(TemporalType.DATE)映射为日期 // date （只有日期）
@Temporal(TemporalType.TIME)映射为日期 // time （只有时间）
@Temporal(TemporalType.TIMESTAMP)映射为日期 // date time （日期+时间）

我们看一个完整的例子，感受一下上面提到的注解的完整用法，如下：

package com.example.jpa.example1;
import lombok.Data;
import javax.persistence.*;
import java.util.Date;
@Entity
@Table(name = "user_topic")
@Access(AccessType.FIELD)
@Data
public class UserTopic {
   @Id
   @Column(name = "id", nullable = false)
   @GeneratedValue(strategy = GenerationType.IDENTITY)
   private Integer id;
   @Column(name = "title", nullable = true, length = 200)
   private String title;
   @Basic
   @Column(name = "create_user_id", nullable = true)
   private Integer createUserId;
   @Basic(fetch = FetchType.LAZY)
   @Column(name = "content", nullable = true, length = -1)
   @Lob
   private String content;
   @Basic(fetch = FetchType.LAZY)
   @Column(name = "image", nullable = true)
   @Lob
   private byte[] image;
   @Basic
   @Column(name = "create_time", nullable = true)
   @Temporal(TemporalType.TIMESTAMP)
   private Date createTime;
   @Basic
   @Column(name = "create_date", nullable = true)
   @Temporal(TemporalType.DATE)
   private Date createDate;
   @Enumerated(EnumType.STRING)
   @Column(name = "topic_type")
   private Type type;
   @Transient
   private String transientSimple;
   //非数据库映射字段，业务类型的字段
   public String getTransientSimple() {
      return title + "auto:jack" + type;
   }
   //有一个枚举类，主题的类型
   public enum Type {
      EN("英文"), CN("中文");
      private final String des;
      Type(String des) {
         this.des = des;
      }
   }
}