13-12-17 Spring Data JPA中文文档[1.4.3] - 产品研发部Java架构组 - 产品研发部Wiki
192.168.0.242:8090/pages/viewpage.action?pageId=1802242 1/19
被 孙 瑞鸿添加，被 孙 瑞鸿最后更新于十二月 17, 2013
页面 / 产品研发部Java架构组 / 技术预研
Spring Data JPA中文文档[1.4.3]
前言
作者 & 译者
第一部分：文档
1.使用 Spring Data Repositories
1.1核心概念
1.2查询方法
1.2.1 声明Repository接口
1.2.2 定义查询方法
构建查询
属性表达式
特殊参数处理
1.2.3 创建Repository实体
XML配置
使用过滤器
JavaConfig
独立使用
1.3 自定义Repository实现
1.3.1 在repository中添加自定义方法
配置
人工装载
1.3.2 为所有的repository添加自定义方法
1.4 Spring Data扩展
1.4.1 Web支持
基本的web支持
DomainClassConverter
HandlerMethodArgumentResolver分页排序
超媒体分页
1.4.2 Repository填充
1.4.3 Legacy Web Support
在SpringMVC中绑定领域类(Domain class)
属性编辑器
转换服务
Web分页
表格1.2 请求参数
配置通用的默认参数
2.JPA Repositories
2.1介绍
2.1.1Spring命名空间
自定义命名空间属性
2.1.2 基于注解的配置
2.2 持久实体
2.2.1 保存实体
实体状态监测策略
表格2.2 监测方式
2.3 查询方法
2.3.1 查询策略
声明查询语句
2.3.2 查询创建器
表格2.3 支持的关键字
2.3.3 使用JPA命名查询
XML命名查询定义
注解方式
声明接口
2.3.4 使用@Query
LIKE查询
原生查询
2.3.5 使用命名参数
2.3.6 使用SpELl表达式
表格2.4 在SpELl中支持的变量
2.3.7 修改语句
2.3.8 使用QueryHints
2.4 Specifications
2.5 事务
2.5.1 事务性查询方法
2.6 锁
2.7 审计
2.7.1 基础知识
注解方式
基于接口的审计
审计织入
2.7.2 通用审计配置
前言
反正也没人看，省略吧！
本文档对应的是Spring Data JPA 1.4.3 RELEASE
作者 & 译者
作者：Oliver Gierke, Thomas Darimont
译者：大熊 QQ：304853988
13-12-17 Spring Data JPA中文文档[1.4.3] - 产品研发部Java架构组 - 产品研发部Wiki
192.168.0.242:8090/pages/viewpage.action?pageId=1802242 2/19
Copyright © 2008-2013
由于本人利用闲暇时间翻译，再加上本人水平有限，翻译可能过于粗糙，未能翻译出Spring Data JPA原文档的意思，请各位谅解，如果有什么问题，可以联系本人！
本翻译文档仍未做任何校对(PS:这是翻译第一版，先出炉)，请大家多多包含！
最后，请大家尊重本人的劳动成果，本译文可用户私人或者拷贝予他人免费使用，但不允许用于任何商业用途。
第一部分：文档
1.使用 Spring Data Repositories
Spring Data Repository的存在，是为了把你从大量重复、繁杂的数据库层操作中解放出来。
1.1核心概念
Spring Data Repository的核心接口是Repository(好像也没什么好惊讶的)。这个接口需要领域类(Domain Class)跟领域类的ID类型作为参数。这个接口主要是让你能知道继承这个类的接
口的类型。CrudRepository提供了对被管理的实体类的一些常用CRUD方法。
例1.1 CrudRepository接口
① 保存给定的实体。
②返回指定ID的实体。
③返回全部实体。
④返回实体的总数。
⑤删除指定的实体。
⑥判断给定的ID是否存在。
通常我们要扩展功能的方法，那么我们就需要在接口上做子接口。那么我们要添加功能的时候，就在CrudRepository的基础上去增加。
PagingAndSortingRepository 是一个继承CrudRepository的接口，他扩展了分页与排序的功能。
例1.2 PagingAndSortingRepository
如果我们需要查询第二页的用户数据(每页包含20条数据)，那么我们可以简单的这么做：
用户分页查询
1.2查询方法
一般的增删改查功能都会有一些查询语句去查询数据库，在Spring Data，你只需要简单的做四个步骤即可实现！
1.声明一个继承与Repository或者它的子接口的接口，并且输入类型参数，如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public interface CrudRepository<T, ID extends Serializable>
extends Repository<T, ID> {
<S extends T> S save(S entity);①
T findOne(ID primaryKey);②
Iterable<T> findAll();③
Long count();④
void delete(T entity);⑤
boolean exists(ID primaryKey);⑥
// … 省略其他方法
}
1
2
3
4
5
6
7
public interface PagingAndSortingRepository<T, ID extends Serializable>
extends CrudRepository<T, ID> {
Iterable<T> findAll(Sort sort);
Page<T> findAll(Pageable pageable);
}
1
2
PagingAndSortingRepository<User, Long> repository = // … get access to a bean
Page<User> users = repository.findAll(new PageRequest(1, 20));
13-12-17 Spring Data JPA中文文档[1.4.3] - 产品研发部Java架构组 - 产品研发部Wiki
192.168.0.242:8090/pages/viewpage.action?pageId=1802242 3/19
声明接口
2.声明查询的方法在接口上
声明方法
你没有看错，你只要声明，不需要些实现！SpringData会创建代理对象帮你完成那些繁琐的事情。
3.在Spring上配置
Spring配置
注意，上面的命名空间使用了JPA的命名空间
4.在业务中使用
调用数据操作
这部分的代码将在下部分中解释。
1.2.1 声明Repository接口
在上面的第一步操作中定义了接口，这些接口必须都继承与Repository或者其子类，并且标注领域类(Domain Class)以及ID类型。如果你想暴露CRUD方法，那么你可以直接继承
CrudRepository接口。
通常，我们的Repository会继承Repository, CrudRepository 或者PagingAndSortingRepository中的一个。但是你如果不想用SpringData的接口的话，你也可以把自己的接口声明
@Repository即可。继承CrudRepository接口可以让你暴露出很多方法去操作你的实体类。如果你仅仅想暴露几个接口给其他人使用，那么你只需要从CrudRepository中拷贝几
个需要的方法到自己的Repository中。
例1.3 选择性的暴露接口
在这里我们只暴露出findOne(...)跟save(...)两个方法出来。对于UserRepository，他除了有根据ID查询的方法、保存实体的方法之外，还有根据Email地址查询用户的方法。
public interface PersonRepository extends Repository<User, Long> { … }
List<Person> findByLastname(String lastname);
<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns:beans="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.springframework.org/schema/data/jpa"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/data/jpa
http://www.springframework.org/schema/data/jpa/spring-jpa.xsd">
<repositories base-package="com.acme.repositories" />
</beans>
public class SomeClient {
@Autowired
private PersonRepository repository;
public void doSomething() {
List<Person> persons = repository.findByLastname("Matthews");
}
}
1
2
3
4
5
6
7
8
9
interface MyBaseRepository<T, ID extends Serializable> extends Repository<T, ID> {
T findOne(ID id);
T save(T entity);
}
interface UserRepository extends MyBaseRepository<User, Long> {
User findByEmailAddress(EmailAddress emailAddress);
}
13-12-17 Spring Data JPA中文文档[1.4.3] - 产品研发部Java架构组 - 产品研发部Wiki
192.168.0.242:8090/pages/viewpage.action?pageId=1802242 4/19
1.2.2 定义查询方法
SpringData通过方法名有两种方式去解析出用户的查询意图：一种是直接通过方法的命名规则去解析，第二种是通过Query去解析，那么当同时存在几种方式时，SpringData怎么去选择这两
种方式呢？好了，SpringData有一个策略去决定到底使用哪种方式：
查询策略：
接下来我们将介绍策略的信息，你可以通过配置<repository>的query-lookup-strategy属性来决定。
CREATE
通过解析方法名字来创建查询。这个策略是删除方法中固定的前缀，然后再来解析其余的部分。
USE_DECLARED_QUERY
它会根据已经定义好的语句去查询，如果找不到，则会抛出异常信息。这个语句可以在某个注解或者方法上定义。根据给定的规范来查找可用选项，如果在方法被调用时没有找到定义的查
询，那么会抛出异常。
CREATE_IF_NOT_FOUND(默认)
这个策略结合了以上两个策略。他会优先查询是否有定义好的查询语句，如果没有，就根据方法的名字去构建查询。这是一个默认策略，如果不特别指定其他策略，那么这个策略会在项目
中沿用。
构建查询
查询构造器是内置在SpringData中的，他是非常强大的，这个构造器会从方法名中剔除掉类似find...By, read...By, 或者get...By的前缀，然后开始解析其余的名字。你可以在方法名中加入更
多的表达式，例如你需要Distinct的约束，那么你可以在方法名中加入Distinct即可。在方法中，第一个By表示着查询语句的开始，你也可以用And或者Or来关联多个条件。
例1.4 通过方法名字构建查询
根据方法名解析的查询结果跟数据库是相关，但是，还有几个问题需要注意：
多个属性的查询可以通过连接操作来完成，例如And，Or。当然还有其他的，例如Between，LessThan，GreaterThan，Like。这些操作时跟数据库相关的，当然你还需要看看相关的
数据库文档是否支持这些操作。
你可以使用IngoreCase来忽略被标记的属性的大小写，也可以使用AllIgnoreCase来忽略全部的属性，当然这个也是需要数据库支持才允许的。
你可以使用OrderBy来进行排序查询，排序的方向是Asc跟Desc，如果需要动态排序，请看后面的章节。
属性表达式
好了，将了那么多了，具体的方法名解析查询需要怎样的规则呢？这种方法名查询只能用在被管理的实体类上，就好像之前的案例。假设一个类Person中有个Address，并且Address还有
ZipCode，那么根据ZipCode来查询这个Person需要怎么做呢？
在上面的例子中，我们用x.address.zipCode去检索属性，这种解析算法会在方法名中先找出实体属性的完整部分(AddressZipCode)，检查这部分是不是实体类的属性，如果解析成功，则按
照驼峰式从右到左去解析属性，如：AddressZipCode将分为AddressZip跟Code，在这个时候，我们的属性解析不出Code属性，则会在此用同样的方式切割，分为Address跟ZipCode（如果
第一次分割不能匹配，解析器会向左移动分割点），并继续解析。
为了避免这种解析的问题，你可以用“_”去区分，如下所示：
特殊参数处理
上面的例子已经展示了绑定简单的参数，那么除此之外，我们还可以绑定一些指定的参数，如Pageable和Sort来动态的添加分页、排序查询。
在查询方法中使用分页和排序
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public interface PersonRepository extends Repository<User, Long> {
List<Person> findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname);
// 需要在语句中使用Distinct关键字，你需要做的是如下
List<Person> findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname);
List<Person> findPeopleDistinctByLastnameOrFirstname(String lastname, String firstname);
// 如果你需要忽略大小写，那么你要用IgnoreCase关键字，你需要做的是如下
List<Person> findByLastnameIgnoreCase(String lastname);
// 所有属性都忽略大小写呢？AllIgnoreCase可以帮到您
List<Person> findByLastnameAndFirstnameAllIgnoreCase(String lastname, String firstname);
// 同样的，如果需要排序的话，那你需要：OrderBy
List<Person> findByLastnameOrderByFirstnameAsc(String lastname);
List<Person> findByLastnameOrderByFirstnameDesc(String lastname);
}
List<Person> findByAddressZipCode(ZipCode zipCode);
List<Person> findByAddress_ZipCode(ZipCode zipCode);
1
2
Page<User> findByLastname(String lastname, Pageable pageable);
13-12-17 Spring Data JPA中文文档[1.4.3] - 产品研发部Java架构组 - 产品研发部Wiki
192.168.0.242:8090/pages/viewpage.action?pageId=1802242 5/19
第一个方法通过传递org.springframework.data.domain.Pageable来实现分页功能，排序也绑定在里面。如果需要排序功能，那么需要添加参数org.springframework.data.domain.Sort，如第
二行中，返回的对象可以是List，当然也可以是Page类型的。
1.2.3 创建Repository实体
创建已定义的Repository接口，最简单的方式就是使用Spring配置文件，当然，需要JPA的命名空间。
XML配置
你可以使用JPA命名空间里面的repositories去自动检索路径下的repositories元素：
XML配置
在本例中，Spring能够通过base-package检测出指定路径下所有继承Repository或者其子接口的接口(有点绕口)。每找到一个接口的时候，FactoryBean就会创建一个合适的代理去处理以及
调用里面的查询方法。每个注册的Bean的名称都是源于接口名称，例如：UserRepository将会被注册为userRepository。base-package允许使用通配符作为扫描格式。
使用过滤器
在默认的设置中，将使用全路径扫描的方式去检索接口，当然，你在业务上可能需要更细致的操作，这时候，你可以在<repositories>中使用<include-filter>或者<exclude-filter>。这样的话，
你可以指定扫描的路径包含或者不包含指定的路径。
例如我们现在想过滤掉一些指定的接口，那么你可以这么做：
例1.6 使用排除过滤
这个例子中，我们排除了所有以SomeRepository结尾的接口。
JavaConfig
你可以在JavaConfig中使用@Enable${store}Repositories注解来实现。那么代码就是如下：
例1.7 使用JavaConfig
独立使用
你可以不在Spring容器里面使用repository。但是你还需要Spring的依赖包在你的classpath中，你需要使用RepositoryFactory来实现，代码如下：
例1.8 独立模式下使用
1.3 自定义Repository实现
我们可以自己实现repository的方法。
3
4
5
List<User> findByLastname(String lastname, Sort sort);
List<User> findByLastname(String lastname, Pageable pageable);
<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns:beans="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.springframework.org/schema/data/jpa"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/data/jpa
http://www.springframework.org/schema/data/jpa/spring-jpa.xsd">
<repositories base-package="com.acme.repositories" />
</beans:beans>
<repositories base-package="com.acme.repositories">
<context:exclude-filter type="regex" expression=".*SomeRepository" />
</repositories>
1
2
3
4
5
6
7
8
9
@Configuration
@EnableJpaRepositories("com.acme.repositories")
class ApplicationConfiguration {
@Bean
public EntityManagerFactory entityManagerFactory() {
// …
}
}
1
2
RepositoryFactorySupport factory = … // 初始化
UserRepository repository = factory.getRepository(UserRepository.class);
