注解功能概述
@Entity 用于将普通的Java类声明为JPA实体，使其受持久化上下文（EntityManager）管理。被@Entity标注的类：
- 具备持久化能力（可进行增删改查、级联、缓存、延迟加载、脏检查等）
- 必须定义主键（@Id 或复合主键）
- 在JPQL/Criteria中通过“实体名”进行引用（默认为类名简单名，或通过参数name自定义）
- 与数据库表的物理映射通常结合 @Table、@Column、@OneToMany 等注解完成
核心参数说明
| 参数名 |
类型 |
默认值 |
描述 |
| name |
String |
类名的简单名称 |
实体名，用于JPQL/EntityGraph/Metamodel等处的逻辑命名。未显式指定时等同于类的简单类名；不影响物理表名（物理表名由@Table或默认命名策略决定）。 |
使用场景分析
- 领域模型持久化：将领域对象建模为JPA实体，以获得ORM映射、关联关系、生命周期回调、缓存与乐观锁等能力。
- 自定义实体名避免冲突：当类名与数据库保留字冲突，或跨包存在同名类时，通过 @Entity(name="Alias") 为JPQL/EntityGraph提供唯一实体名。
- JPQL查询与实体图：使用实体名进行 JPQL 查询（如 SELECT c FROM Customer c），并结合 @NamedEntityGraph 指定抓取策略，控制性能与N+1问题。
- 进阶特性整合：与 @MappedSuperclass、@Version（乐观锁）、@Cacheable（二级缓存）、@Converter（值对象映射）、@Embedded（值对象内联）等配合，构建健壮的实体模型。
完整代码示例
说明：
- 采用 Jakarta Persistence (jakarta.persistence.*) 命名空间
- 使用内存数据库 H2，Java SE 环境下通过 persistence.xml 启动
- 展示 @Entity 的 name 参数、JPQL 查询、实体图加载、乐观锁、值对象与转换器、双向关联、生命周期回调等
文件：src/main/java/com/example/jpa/domain/BaseEntity.java
package com.example.jpa.domain;
import jakarta.persistence.*;
import java.time.Instant;
@MappedSuperclass
public abstract class BaseEntity {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Version
private long version;
@Column(name = "created_at", nullable = false, updatable = false)
private Instant createdAt;
@Column(name = "updated_at", nullable = false)
private Instant updatedAt;
@PrePersist
protected void onCreate() {
Instant now = Instant.now();
this.createdAt = now;
this.updatedAt = now;
}
@PreUpdate
protected void onUpdate() {
this.updatedAt = Instant.now();
}
public Long getId() {
return id;
}
public long getVersion() {
return version;
}
public Instant getCreatedAt() {
return createdAt;
}
public Instant getUpdatedAt() {
return updatedAt;
}
}
文件：src/main/java/com/example/jpa/domain/Address.java
package com.example.jpa.domain;
import jakarta.persistence.Embeddable;
@Embeddable
public class Address {
private String street;
private String city;
private String zipCode;
private String country;
public Address() {}
public Address(String street, String city, String zipCode, String country) {
this.street = street;
this.city = city;
this.zipCode = zipCode;
this.country = country;
}
public String getStreet() { return street; }
public String getCity() { return city; }
public String getZipCode() { return zipCode; }
public String getCountry() { return country; }
public void setStreet(String street) { this.street = street; }
public void setCity(String city) { this.city = city; }
public void setZipCode(String zipCode) { this.zipCode = zipCode; }
public void setCountry(String country) { this.country = country; }
}
文件：src/main/java/com/example/jpa/domain/Money.java
package com.example.jpa.domain;
import java.math.BigDecimal;
import java.util.Currency;
import java.util.Objects;
public class Money {
private final BigDecimal amount;
private final Currency currency;
public Money(BigDecimal amount, Currency currency) {
if (amount == null || currency == null) {
throw new IllegalArgumentException("amount and currency must not be null");
}
this.amount = amount;
this.currency = currency;
}
public static Money of(String currencyCode, String amount) {
return new Money(new BigDecimal(amount), Currency.getInstance(currencyCode));
}
public BigDecimal getAmount() { return amount; }
public Currency getCurrency() { return currency; }
@Override
public String toString() {
return currency.getCurrencyCode() + " " + amount.toPlainString();
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof Money)) return false;
Money money = (Money) o;
return amount.compareTo(money.amount) == 0 &&
currency.equals(money.currency);
}
@Override
public int hashCode() {
return Objects.hash(amount.stripTrailingZeros(), currency);
}
}
文件：src/main/java/com/example/jpa/domain/MoneyAttributeConverter.java
package com.example.jpa.domain;
import jakarta.persistence.AttributeConverter;
import jakarta.persistence.Converter;
import java.math.BigDecimal;
import java.util.Currency;
@Converter(autoApply = false)
public class MoneyAttributeConverter implements AttributeConverter<Money, String> {
// 存储格式：<CURRENCY_CODE>:<AMOUNT> 例如 "USD:123.45"
@Override
public String convertToDatabaseColumn(Money attribute) {
if (attribute == null) return null;
return attribute.getCurrency().getCurrencyCode() + ":" + attribute.getAmount().toPlainString();
// 注意：实际生产可考虑两列存储（币种/数值）或DECIMAL+外键，便于查询与校验
}
@Override
public Money convertToEntityAttribute(String dbData) {
if (dbData == null || dbData.isEmpty()) return null;
String[] parts = dbData.split(":");
if (parts.length != 2) throw new IllegalArgumentException("Invalid Money format: " + dbData);
Currency currency = Currency.getInstance(parts[0]);
BigDecimal amount = new BigDecimal(parts[1]);
return new Money(amount, currency);
}
}
文件：src/main/java/com/example/jpa/domain/OrderStatus.java
package com.example.jpa.domain;
public enum OrderStatus {
NEW, PAID, SHIPPED, CANCELLED
}
文件：src/main/java/com/example/jpa/domain/Customer.java
package com.example.jpa.domain;
import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
@Entity(name = "Customer") // 自定义实体名（用于JPQL），等同于默认简单类名，这里显式声明便于演示
@Table(
name = "customers",
uniqueConstraints = {
@UniqueConstraint(name = "uk_customer_email", columnNames = "email")
}
)
@NamedQuery(
name = "Customer.findByEmail",
query = "SELECT c FROM Customer c WHERE c.email = :email"
)
@NamedEntityGraph(
name = "Customer.withOrders",
attributeNodes = {
@NamedAttributeNode("orders")
}
)
@Cacheable(true)
public class Customer extends BaseEntity {
@Column(nullable = false, length = 100)
private String name;
@Column(nullable = false, length = 120, unique = true)
private String email;
@Embedded
private Address address;
@OneToMany(
mappedBy = "customer",
cascade = CascadeType.ALL,
orphanRemoval = true,
fetch = FetchType.LAZY
)
private List<PurchaseOrder> orders = new ArrayList<>();
public Customer() {}
public Customer(String name, String email, Address address) {
this.name = name;
this.email = email;
this.address = address;
}
// 双向关系维护
public void addOrder(PurchaseOrder order) {
order.setCustomer(this);
this.orders.add(order);
}
public void removeOrder(PurchaseOrder order) {
order.setCustomer(null);
this.orders.remove(order);
}
public String getName() { return name; }
public String getEmail() { return email; }
public Address getAddress() { return address; }
public List<PurchaseOrder> getOrders() { return orders; }
public void setName(String name) { this.name = name; }
public void setEmail(String email) { this.email = email; }
public void setAddress(Address address) { this.address = address; }
// 以业务唯一键（email）实现 equals/hashCode，避免使用瞬时id
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof Customer)) return false;
Customer other = (Customer) o;
return Objects.equals(email, other.email);
}
@Override
public int hashCode() {
return Objects.hash(email);
}
@Override
public String toString() {
return "Customer{name='" + name + "', email='" + email + "'}";
}
}
文件：src/main/java/com/example/jpa/domain/PurchaseOrder.java
package com.example.jpa.domain;
import jakarta.persistence.*;
import java.util.Objects;
@Entity(name = "PurchaseOrder")
@Table(name = "purchase_orders")
public class PurchaseOrder extends BaseEntity {
@ManyToOne(fetch = FetchType.LAZY, optional = false)
@JoinColumn(
name = "customer_id",
nullable = false,
foreignKey = @ForeignKey(name = "fk_order_customer")
)
private Customer customer;
@Column(name = "order_number", nullable = false, unique = true, length = 64)
private String orderNumber;
@Enumerated(EnumType.STRING)
@Column(nullable = false, length = 16)
private OrderStatus status = OrderStatus.NEW;
@Convert(converter = MoneyAttributeConverter.class)
@Column(name = "total_amount", nullable = false, length = 64)
private Money totalAmount;
public PurchaseOrder() {}
public PurchaseOrder(String orderNumber, OrderStatus status, Money totalAmount) {
this.orderNumber = orderNumber;
this.status = status;
this.totalAmount = totalAmount;
}
public Customer getCustomer() { return customer; }
public String getOrderNumber() { return orderNumber; }
public OrderStatus getStatus() { return status; }
public Money getTotalAmount() { return totalAmount; }
public void setCustomer(Customer customer) { this.customer = customer; }
public void setOrderNumber(String orderNumber) { this.orderNumber = orderNumber; }
public void setStatus(OrderStatus status) { this.status = status; }
public void setTotalAmount(Money totalAmount) { this.totalAmount = totalAmount; }
// 以业务唯一键（orderNumber）实现 equals/hashCode
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof PurchaseOrder)) return false;
PurchaseOrder that = (PurchaseOrder) o;
return Objects.equals(orderNumber, that.orderNumber);
}
@Override
public int hashCode() {
return Objects.hash(orderNumber);
}
@Override
public String toString() {
return "PurchaseOrder{orderNumber='" + orderNumber + "', status=" + status +
", total=" + totalAmount + "}";
}
}
文件：src/main/java/com/example/jpa/JpaApplication.java
package com.example.jpa;
import com.example.jpa.domain.*;
import jakarta.persistence.*;
public class JpaApplication {
public static void main(String[] args) {
EntityManagerFactory emf = Persistence.createEntityManagerFactory("demoPU");
EntityManager em = emf.createEntityManager();
try {
// 初始化数据
em.getTransaction().begin();
Customer c = new Customer(
"Alice",
"alice@example.com",
new Address("1 Main St", "Metropolis", "10001", "US")
);
PurchaseOrder po = new PurchaseOrder(
"PO-1001",
OrderStatus.NEW,
Money.of("USD", "199.99")
);
c.addOrder(po);
em.persist(c); // 由于 cascade = ALL，订单将级联持久化
em.getTransaction().commit();
// 使用实体名进行JPQL查询，并结合实体图抓取orders
EntityGraph<?> graph = em.getEntityGraph("Customer.withOrders");
TypedQuery<Customer> q = em.createNamedQuery("Customer.findByEmail", Customer.class)
.setParameter("email", "alice@example.com")
.setHint("jakarta.persistence.loadgraph", graph);
Customer found = q.getSingleResult();
System.out.println("Found: " + found);
System.out.println("Orders: " + found.getOrders());
} finally {
em.close();
emf.close();
}
}
}
文件：src/main/resources/META-INF/persistence.xml
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="https://jakarta.ee/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
version="3.1"
xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_1.xsd">
<persistence-unit name="demoPU" transaction-type="RESOURCE_LOCAL">
<!-- 列出实体类，便于在Java SE环境下被发现 -->
<class>com.example.jpa.domain.Customer</class>
<class>com.example.jpa.domain.PurchaseOrder</class>
<properties>
<!-- JDBC配置（H2内存数据库） -->
<property name="jakarta.persistence.jdbc.driver" value="org.h2.Driver"/>
<property name="jakarta.persistence.jdbc.url" value="jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1;MODE=LEGACY"/>
<property name="jakarta.persistence.jdbc.user" value="sa"/>
<property name="jakarta.persistence.jdbc.password" value=""/>
<!-- 自动建表 -->
<property name="jakarta.persistence.schema-generation.database.action" value="drop-and-create"/>
<!-- Hibernate常用调试参数 -->
<property name="hibernate.show_sql" value="true"/>
<property name="hibernate.format_sql" value="true"/>
</properties>
</persistence-unit>
</persistence>
运行说明：
- 确保引入依赖（示例：Hibernate ORM 6.x、H2 数据库、Jakarta Persistence API）
- 在 IDE 或命令行直接运行 JpaApplication.main()
示例Maven依赖参考（供集成时使用）：
<!-- 关键依赖（版本根据项目实际选择） -->
<dependency>
<groupId>org.hibernate.orm</groupId>
<artifactId>hibernate-core</artifactId>
<version>6.5.0.Final</version>
</dependency>
<dependency>
<groupId>jakarta.persistence</groupId>
<artifactId>jakarta.persistence-api</artifactId>
<version>3.1.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>2.2.224</version>
<scope>runtime</scope>
</dependency>
技术要点说明
- 实体名与表名的区别
- @Entity(name="...") 定义JPQL/EntityGraph/元模型使用的“实体名”
- @Table(name="...") 定义物理表名；两者互不影响
- 主键与构造器
- 实体必须有主键（@Id），且需要一个public/protected无参构造器
- 类/字段修饰
- 避免将实体类或其延迟加载的方法声明为final，以支持代理与延迟加载
- 持久化字段不应为final（除非只读快照语义且由provider支持）
- 关系维护
- 双向关联需在两端维护一致性（示例中的 addOrder/removeOrder）
- 合理设置 cascade 与 orphanRemoval，结合数据库外键约束的命名
- 抓取策略与性能
- 关联默认LAZY，按需使用 @NamedEntityGraph + loadgraph/hint 控制抓取，避免N+1
- 乐观锁
- @Version 字段用于并发控制；更新时自动校验版本，冲突将抛出 OptimisticLockException
- 值对象映射
- 通过 @Embedded 映射值对象（Address），通过 @Converter 映射复杂值对象（Money）
- 转换器存储格式需与查询/审计需求匹配，生产中推荐结构化列设计
- equals/hashCode
- 优先使用业务唯一键（如email、orderNumber），避免基于未持久化id引发集合行为不一致
- 命名查询与校验
- 使用 @NamedQuery 在启动时进行语法校验，降低运行期风险
- 兼容性
- 本示例基于 Jakarta Persistence 3.x（jakarta.），如项目仍使用 javax.，请替换对应包名与依赖版本
- 放置位置
- persistence.xml 必须放在类路径的 META-INF 目录下（资源路径）以便JPA发现
以上示例展示了 @Entity 在进阶JPA实体映射中的综合用法，包括实体命名、JPQL、实体图、生命周期回调、乐观锁、值对象与转换器、以及双向关联等。
