JPA 注解 + Spring Data JPA 方法 中文速查表

JPA 注解 + Spring Data JPA 方法 中文速查表

适配 Spring Boot 2.7.x（javax.persistence 包），日常开发直接查阅使用

---

一、JPA 核心实体注解（ORM 映射）

1. 类级别注解

注解	作用	示例
@Entity	标记当前类为数据库实体类，被JPA托管	@Entity
@Table(name = "表名")	绑定对应数据库表，表名与类名不一致时必加	@Table(name = "iot_user")
@Comment	给表添加注释（部分数据库/版本支持）	@Comment("用户数据表")

2. 主键相关注解

注解	作用	常用配置
@Id	标记当前字段为数据库主键	主键字段必备
@GeneratedValue	主键生成策略	配合 strategy 使用
GenerationType.IDENTITY	数据库自增主键（MySQL 首选）	@GeneratedValue(strategy = GenerationType.IDENTITY)
GenerationType.AUTO	JPA自动选择策略（默认）	不推荐MySQL使用
GenerationType.SEQUENCE	序列自增（Oracle 等数据库使用）	搭配 @SequenceGenerator

3. 普通字段映射 @Column

@Column(
    name = "数据库字段名",  // 映射库中列名
    nullable = false,      // 是否允许为null，默认true
    unique = false,        // 是否唯一约束
    length = 64,           // 字符长度（仅字符串生效）
    columnDefinition = "varchar(255) COMMENT '头像'" // 自定义字段类型+注释
)

示例

@Column(name = "iot_openid", length = 64, nullable = true)
private String iotOpenid;

4. 其他高频注解

注解	用途
@Transient	临时字段，不映射到数据库，仅程序内使用
@Temporal(TemporalType.DATE)	日期类型映射：DATE(仅日期) / TIME(仅时间) / TIMESTAMP(日期+时间)
@Lob	标记大文本/大二进制字段（长文本、文件流）
@Enumerated	枚举类型映射数据库字段

---

二、关联关系注解（表与表关联）

1. 一对一 @OneToOne

// 主表关联从表
@OneToOne
@JoinColumn(name = "关联外键字段")
private UserInfo userInfo;

2. 一对多 @OneToMany / 多对一 @ManyToOne

• 多方（外键所在表）使用 @ManyToOne（开发最常用）

@ManyToOne
@JoinColumn(name = "parent_id") // 外键列
private Parent parent;

• 一方使用 @OneToMany

@OneToMany(mappedBy = "parent") // mappedBy：交由多方维护关联
private List<Child> childList;

3. 多对多 @ManyToMany

需中间表，可通过 @JoinTable 指定中间表名、关联字段。

---

三、Spring Data JPA 内置通用方法（继承 JpaRepository 直接调用）

接口定义参考：

// 泛型：实体类, 主键类型
public interface IotUserRepository extends JpaRepository<IotUser, Integer>

1. 增/改

方法	功能说明
<S extends T> S save(S entity)	新增/修改：主键有值则更新，无值则新增
<S extends T> List<S> saveAll(Iterable<S> entities)	批量新增/修改

2. 查询

方法	功能说明
Optional<T> findById(ID id)	根据主键查询，返回 Optional（空安全）
List<T> findAll()	查询全表所有数据
List<T> findAllById(Iterable<ID> ids)	根据主键集合批量查询
long count()	统计表总数据条数
boolean existsById(ID id)	判断指定主键数据是否存在

3. 删除

方法	功能说明
void deleteById(ID id)	根据主键删除单条数据
void delete(T entity)	传入实体对象删除
void deleteAll()	清空整张表（谨慎使用）
void deleteAll(Iterable<? extends T> entities)	批量删除

4. 分页&排序（高频）

// 分页：Pageable(页码, 每页条数)，页码从 0 开始
Page<T> findAll(Pageable pageable);

// 排序：Sort
List<T> findAll(Sort sort);

// 分页+排序 组合使用
Page<T> page = repository.findAll(PageRequest.of(0, 10, Sort.by("iotUserId").descending()));

---

四、方法名命名规则（无需写SQL，自动生成查询）

Spring Data JPA 核心特性：按规则写方法名，框架自动解析SQL

1. 基础关键字

关键字	作用	示例方法	对应SQL含义
findBy	条件查询	findByIotOpenid(String openid)	where iot_openid = ?
readBy	同 findBy，语义区分	readByIotNickname(String name)	条件查询
countBy	按条件统计数量	countByIotNickname(String name)	count(1) where 昵称=?
existsBy	按条件判断是否存在	existsByIotOpenid(String openid)	判断数据是否存在
deleteBy	按条件删除	deleteByIotOpenid(String openid)	按openid删除数据

2. 多条件与逻辑符

• And（并且）
  List<IotUser> findByIotNicknameAndIotOpenid(String name, String openid)

  where 昵称=? and openid=?

• Or（或者）
  List<IotUser> findByIotNicknameOrIotOpenid(String name, String openid)

  where 昵称=? or openid=?

3. 模糊查询

写法	说明
Containing	包含（%关键词%）
StartingWith	开头匹配（关键词%）
EndingWith	结尾匹配（%关键词）

4. 范围比较

关键字	含义
GreaterThan	大于
LessThan	小于
Between	区间范围（闭区间）
IsNull / IsNotNull	为空 / 非空

示例：

// 主键大于指定值
List<IotUser> findByIotUserIdGreaterThan(Integer id);
// 主键在区间内
List<IotUser> findByIotUserIdBetween(Integer start, Integer end);

5. 排序后缀

方法末尾加 Asc（升序）/ Desc（降序）

// 根据昵称查询，按ID倒序
List<IotUser> findByIotNicknameDesc(String name);

---

五、自定义SQL（@Query 注解）

内置方法无法满足复杂查询时使用，支持 JPQL 和 原生SQL

1. JPQL（面向对象，默认）

// 查询指定openid的用户
@Query("select u from IotUser u where u.iotOpenid = :openid")
IotUser getByOpenid(@Param("openid") String openid);

2. 原生SQL（操作数据库表，加 nativeQuery = true）

@Query(value = "select * from iot_user where iot_openid = :openid", nativeQuery = true)
IotUser getByOpenidNative(@Param("openid") String openid);

3. 原生删除/修改（必须加 @Modifying）

@Modifying
@Query(value = "delete from iot_user where iot_openid = :openid", nativeQuery = true)
void deleteByOpenid(@Param("openid") String openid);

---

六、配套配置（application.yml 常用）

spring:
  jpa:
    hibernate:
      ddl-auto: none  # 表已存在：none；自动建表：create；更新表结构：update
    show-sql: true     # 控制台打印执行SQL
    properties:
      hibernate:
        format_sql: true  # 格式化SQL（换行缩进）

• ddl-auto 取值说明：
  1. create：启动重建表（数据清空，测试用）
  2. update：启动更新表结构（保留数据，开发常用）
  3. none：不操作表（生产环境必用）

---

七、快速示例（结合你的 iot_user 表）

Repository 完整示例

public interface IotUserRepository extends JpaRepository<IotUser, Integer> {

    // 1. 方法名查询：根据openid查用户
    IotUser findByIotOpenid(String iotOpenid);

    // 2. 模糊查询昵称
    List<IotUser> findByIotNicknameContaining(String nickname);

    // 3. 自定义JPQL
    @Query("select u from IotUser u where u.otHeadimg is not null")
    List<IotUser> findUserWithHeadImg();
}