Querydsl中文文档翻译.pdf
0122.12.2目錄引言介绍教程QueryingJPAQueryingSQLQuerydsl中文文档翻译2引言Querydsl是一个能使用静态类型构建类似于SQL的查询的框架。Querydsl通过流畅的API调用来构建原本需要用字符串连接或外部XML文件配置的查询。相比于简单的字符串，使用级联API方法调用的好处在于IDE的代码提示几乎没有语法来允许无效的查询领域类和属性可以线程安全的引用变更领域类时可以更好的重构Querydsl中文文档翻译3引言1.介绍1.1.背景Querydsl能够诞生，是因为需要在类型安全的方式下进行HQL查询。构造的HQL查询需要拼接字符串，并且会导致代码难以阅读。通过纯字符串对领域类型和属性的不安全引用是基于字符串构建HQL的另一个问题。随着类型安全的领域模型的不断的发展，给软件开发带了巨大的好处。领域最大的改变直接反应在查询和自动查询的构建，它使查询构建更快且安全。Querydsl最先支持的是Hibernate的HQL语言，现如今，Querydsl已经支持JPA，JDO，JDBC，Lucene，HibernateSearch，MangoDB，Collections和RDF(RelationalDataFormat)Bean作为后端。1.2.原则类型安全是Querydsl的核心原则。查询是基于与领域类型的属性映射生成的查询类型构建的。同时，函数/方法的调用也是使用完全的类型安全的方式构建的。保持一致是另一个重要的原则。查询路径(Path)和操作在所有实现中都是相同的，它们都具有一个公用的基本接口。要想获得更多Querydsl查询和表达式的说明，请查看javadoc中的 com.querydsl.core.Query， com.querydsl.core.Fetchable和 com.querydsl.core.types.Expression类的文档。Querydsl中文文档翻译4介绍教程与一般的入门指南不同，我们提供了以Querydsl为主后端的综合教程。QueryingJPAQueryingSQLQuerydsl中文文档翻译5教程2.1.QueryingJPAQuerydsl定义了一个通用静态类型的语法用于查询持久化的领域模型数据。JDO和JPA是Querydsl主要的集成技术。这篇手册介绍了如何让Querydsl与JPA整合使用。QuerydslJPA是JPQL和标准条件查询（Criteriaqueries）的新的使用方式。它结合了条件查询的动态性和JPQL的表达能力，并且使用了完全的类型安全方式。2.1.1.Maven集成在你的maven项目中添加下面的依赖：com.querydslquerydsl-apt$querydsl.versionprovidedcom.querydslquerydsl-jpa$querydsl.versionorg.slf4jslf4j-log4j121.6.1现在，来配置mavenAPT插件：Querydsl中文文档翻译6QueryingJPA.com.mysema.mavenapt-maven-plugin1.1.3processtarget/generated-sources/javacom.querydsl.apt.jpa.JPAAnnotationProcessor. JPAAnnotationProcessor查找带有 javax.persistence.Entity注解的领域类型并为其生成查询类型。如果你在领域类型中使用的是Hibernate的注解，那应该使用APT处理器 com.querydsl.apt.hibernate.HibernateAnnotationProcessor来代替 JPAAnnotationProcessor。运行 cleaninstall命令后，在 target/generated-sources/java目录下将生成相应的查询类型。如果你使用Eclipse，运行 mvneclipse:eclipse更新你的Eclipse项目，将 target/generated-sources/java作为源目录。现在，你就可以构建JPA查询实例和查询领域模型的实例了。Querydsl中文文档翻译7QueryingJPA2.1.2.Ant集成将Querydsl的所有依赖包(jar)放到你的classpath目录下，使用并执行下面的Querydsl代码生成的任务：将 src替换为你的主要的源代码目录， generated替换为你需要生成的源代码的目标目录。2.1.3.在Roo中使用QuerydslJPA如果你正在使用QuerydslJPA和SpringRoo，你可以使用 com.querydsl.apt.roo.RooAnnotationProcessor替换 com.querydsl.apt.jpa.JPAAnnotationProcessor，它将解析并处理 RooJpaEntity和 RooJpaActiveRecord注解，而不是Entity。基于APT的代码生成器不支持与AspectJIDTs整合。2.1.4.从hbm.xml文件中生成模型如果你使用的Hibernate是基于XML配置的，那么你可以使用XML元数据来生成Querydsl模型。 com.querydsl.jpa.codegen.HibernateDomainExporter提供了这样的功能：Querydsl中文文档翻译8QueryingJPAHibernateDomainExporterexporter=newHibernateDomainExporter(Q,/名称前缀newFile(target/gen3),/生成的目标文件夹configuration);/org.hibernate.cfg.Configuration实例exporter.export(); HibernateDomainExporter需要在领域类型可见的 classpath中执行，因为属性类型是通过反射机制获得的。所有的JPA注解都会被忽略，但是Querydsl的注解不会被忽略，比如 QueryInit和 QueryType。2.1.5.使用查询类型TocreatequerieswithQuerydslyouneedtoinstantiatevariablesandQueryimplementations.Wewillstartwiththevariables.Letsassumethatyourprojecthasthefollowingdomaintype:Querydsl中文文档翻译9QueryingJPAEntitypublicclassCustomerprivateStringfirstName;privateStringlastName;publicStringgetFirstName()returnfirstName;publicStringgetLastName()returnlastName;publicvoidsetFirstName(Stringfn)firstName=fn;publicvoidsetLastName(Stringln)lastName=ln;Querydsl会在 Customer类的同一个包内生成一个名称为 QCustomer的查询类。 QCustomer的静态实例变量可在Querydsl查询中作为 Customer类的代表。 QCustomer有一个默认的静态实例变量：QCustomercustomer=QCustomer.customer;或者你可以像下面列子一样定义查询类实例变量：QCustomercustomer=newQCustomer(myCustomer);2.1.6.查询QuerydslJPA模块同时支持JPA和HibernateAPI。Querydsl中文文档翻译10QueryingJPA当使用JPA时，需要用到 JPAQuery实例，就像下面的例子：/whereentityManagerisaJPAEntityManagerJPAQueryquery=newJPAQuery(entityManager);如是你使用的是HibernateAPI，你可以实例化一个 HibernateQuery：/wheresessionisaHibernatesessionHibernateQueryquery=newHibernateQuery(session); JPAQuery和 HibernateQuery都实现了JPQLQuery这个接口。本章中的例子中的查询是通过 JPAQueryFactory实例创建的。最佳实践是通过 JPAQueryFactory来获取 JPAQuery实例。如需HibernateAPI，可以使用 HibernateQueryFactory。构造一个获取名字为Bob的一个customer的信息的查询：/queryFactory=JPAQueryFactoryQCustomercustomer=QCustomer.customer;Customerbob=queryFactory.selectFrom(customer).where(customer.firstName.eq(Bob).fetchOne();调用 selectFrom方法是定义查询的来源与映射， where则定义查询的过滤器， fetchOne则要告诉Querydsl返回单个元素（ SQLQuery中的泛型指定元素类型）。很简单，不是吗！创建多资源（表）查询：QCustomercustomer=QCustomer.customer;QCompanycompany=QCpany;query.from(customer,company);使用多个查询条件过滤器：Querydsl中文文档翻译11QueryingJPAqueryFactory.selectFrom(customer).where(customer.firstName.eq(Bob),customer.lastName.eq(Wilson);或者：queryFactory.selectFrom(customer).where(customer.firstName.eq(Bob).and(customer.lastName.eq(Wilson);使用原生的JPQL查询语句：selectcustomerfromCustomerascustomerwherecustomer.firstName=Bobandcustomer.lastName=Wilson如果你想使用 or来组合条件过滤器，可以使用下面的方式：queryFactory.selectFrom(customer).where(customer.firstName.eq(Bob).or(customer.lastName.eq(Wilson);2.1.7.联合查询Querydsl在JPQL中支持的联合查询： innerjoin,join,leftjoin,rightjoin。联合查询是类型安全的，并且遵循下面的模式：QCatcat=QCat.cat;QCatmate=newQCat(mate);QCatkitten=newQCat(kitten);queryFactory.selectFrom(cat).innerJoin(cat.mate,mate).leftJoin(cat.kittens,kitten).fetch();下面是原生的JPQL查询的语句：Querydsl中文文档翻译12QueryingJPAselectcatfromCatascatinnerjoincat.mateasmateleftouterjoincat.kittensaskitten再来一个例子：queryFactory.selectFrom(cat).leftJoin(cat.kittens,kitten).on(kitten.bodyWeight.gt(10.0).fetch();上述最终生成的原生的JPQL的语句：selectcatfromCatascatleftjoincat.kittensaskittenonkitten.bodyWeight10.02.1.8.一般用法 JPQLQuery接口可以进行级联调用的方法说明： select:设置查询的映射（如果由查询工厂创建查询，则不需要调用） from:添加查询的源（表） innerJoin,join,leftJoin,rightJoin,on:使用这些方法添加要 join的元素。连接方法的第一个参数是要连接的源，第二个参数是源目标（别名）。 where:添加查询过滤器，以逗号分隔的可变参数传入，或是使用 and或or操作连接。 groupBy:以可变参数形式添加查询的分组。 having:添加具有 GROUPBY分组作为断言（Predicate）表达式的可变参数数组的 HAVING过滤器 orderBy:添加结果的排序方式的排序表达式。使用 asc()和desc()方法获取基于数字、字符串或其他可进行比较的表达式的 OrderSpecifier实例 limit,offset,restrict:设置分页查询的结果。 limit为结果的最大行数， offset是偏移的行数， restrict则是两者的限定约束Querydsl中文文档翻译13QueryingJPA2.1.9.结果排序(Ordering)声明结果排序：QCustomercustomer=QCustomer.customer;queryFactory.selectFrom(customer).orderBy(customer.lastName.asc(),customer.firstName.desc().fetch();等效于下面的原生JPQL语句：selectcustomerfromCustomerascustomerorderbycustomer.lastNameasc,customer.firstNamedesc2.1.10.分组(Grouping)下面的是对结果分组：queryFactory.select(customer.lastName).from(customer).groupBy(customer.lastName).fetch();等效于下面的原生JPQL语句：selectcustomer.lastNamefromCustomerascustomergroupbycustomer.lastName2.1.11.删除语句在QuerydslJPA中，删除语句是简单的 delete-where-execute形式。下面是一个例子：Querydsl中文文档翻译14QueryingJPAQCustomercustomer=QCustomer.customer;/deleteallcustomersqueryFactory.delete(customer).execute();/deleteallcustomerswithalevellessthan3queryFactory.delete(customer).where(customer.level.lt(3).execute();调用 where方法是可选的，调用 execute方法是执行删除操作并返回被删除实体的数量。JPA中的DML语句并不考虑JPA级联规则，也不提供细粒度二级缓存的交互。2.1.12.更新语句在QuerydslJPA中，更新语句是简单的 update-set/where-execute形式。下面是一个例子：QCustomercustomer=QCustomer.customer;/renamecustomersnamedBobtoBobbyqueryFactory.update(customer).where(customer.name.eq(Bob).set(customer.name,Bobby).execute();调用 set方法以 SQL-Update-style方式定义要更新的属性，execute调用指行更新操作并返回被更新的实体的数量。JPA中的DML语句并不考虑JPA级联规则，也不提供细粒度二级缓存的交互。2.1.13.子查询使用 JPAExpressions的静态工厂方法创建一个子查询，并且通过调用 from， where等定义查询参数。Querydsl中文文档翻译15QueryingJPAQDepartmentdepartment=QDepartment.department;QDepartmentd=newQDepartment(d);queryFactory.selectFrom(department).where(department.size.eq(JPAExpressions.select(d.size.max().from(d).fetch();再来一个例子：QEmployeeemployee=QEmployee.employee;QEmployeee=newQEmployee(e);queryFactory.selectFrom(employee).where(employee.weeklyhours.gt(JPAExpressions.select(e.weeklyhours.avg().from(employee.department.employees,e).where(e.manager.eq(employee.manager).fetch();2.1.14.使用原始查询如果你在查询执行前需要调整原有的查询，则可以像下面这样暴露她：QueryjpaQuery=queryFactory.selectFrom(employee).createQuery();/.Listresults=jpaQuery.getResultList();2.1.15.JPA查询中使用本地SQL查询Querydsl支持通过 JPASQLQuery类在JPA中执行本地SQL查询。要使用它，你必须为SQLschema生成Querydsl查询类。通过下列所述的maven配置来完成：Querydsl中文文档翻译16QueryingJPA.com.querydslquerydsl-maven-plugin$querydsl.versionexportorg.apache.derby.jdbc.EmbeddedDriverjdbc:derby:target/demoDB;create=truecom.mycompany.mydomain$project.basedir/target/generated-sources/javaorg.apache.derbyderby$derby.version.当查询类已经成功生成在你所选的位置，就可以在查询中使用他们了。单列查询：Querydsl中文文档翻译17QueryingJPA/serializationtemplatesSQLTemplatestemplates=newDerbyTemplates();/查询类(S*-SQL,Q*-领域类)SAnimalcat=newSAnimal(cat);SAnimalmate=newSAnimal(mate);QCatcatEntity=QCat.cat;JPASQLQueryquery=newJPASQLQuery(entityManager,templates);Listnames=query.select(cat.name).from(cat).fetch();如果在你的查询中混合引用了实体（如：QCat）和表（如：SAnimal），你要确保他们使用变量名称一致。 SAnimal.animal的变量名称是 animal，因此使用了一个新的实例（ newSAnimal(cat)）另一种模式可以是：QCatcatEntity=QCat.cat;SAnimalcat=newSAnimal(catEntity.getMetadata().getName();查询多列：query=newJPASQLQuery(entityManager,templates);Listrows=query.select(cat.id,cat.name).from(cat).fetch();查询所有列:Listrows=query.select(cat.all().from(cat).fetch();SQL中查询，但是映射为实体：query=newJPASQLQuery(entityManager,templates);Listcats=query.select(catEntity).from(cat).orderBy(cat.name.asc().fetch();联合查询:Querydsl中文文档翻译18QueryingJPAquery=newJPASQLQuery(entityManager,templates);cats=query.select(catEntity).from(cat).innerJoin(mate).on(cat.mateId.eq(mate.id).where(cat.dtype.eq(Cat),mate.dtype.eq(Cat).fetch();查询并映射为DTO（DataTransformObject）:query=newJPASQLQuery(entityManager,templates);ListcatDTOs=query.select(Projections.constructor(CatDTO.class,cat.id,cat.name).from(cat).orderBy(cat.name.asc().fetch();如果你正在使用HibernateAPI，而不是JPA的API，替换为 HibernateSQLQuery即可。Querydsl中文文档翻译19QueryingJPA2.3.QueryingSQL本章节主要讲述使用 Querydsl-SQL模块生成查询类型和进行查询的功能。2.3.1.Maven整合在你的 Maven项目中添加下列依赖：com.querydslquerydsl-sql$querydsl.versioncom.querydslquerydsl-sql-codegen$querydsl.versionprovidedorg.slf4jslf4j-log4j121.6.1如果已经使用Maven插件生成了代码，则可以不需要 querydsl-sql-codegen这个依赖包。2.3.2.通过Maven生成代码这个功能主要通过Maven插件的方式来使用，例如：Querydsl中文文档翻译20QueryingSQL.com.querydslquerydsl-maven-plugin$querydsl.versionexportorg.apache.derby.jdbc.EmbeddedDriverjdbc:derby:target/demoDB;create=truecom.myproject.domain$project.basedir/target/generated-sources/javaorg.apache.derbyderby$derby.version.Usethegoaltest-exporttotreatthetargetfolderasatestsourcefolderforusewithtestcode.表2.1.参数说明Querydsl中文文档翻译21QueryingSQL名称说明 jdbcDriverJDBC驱动支持的类名 jdbcUrlJDBCurl jdbcUserJDBCuser jdbcPasswordJDBCpassword namePrefix生成查询类类名的前缀，默认： Q nameSuffix生成查询类类名的后缀，默认： beanPrefix生成的 Bean类类名的前缀 beanSuffix生成的 Bean类类名的前缀 packageName生成的源文件的包名称 beanPackageName生成的 Bean文件的包名称，默认： packageName beanInterfaces生成的 Bean类实现的一组接口的类全名，默认： beanAddToString设置 true时，生成的类中将自动添加 toString()方法的实现，默认： false beanAddFullConstructor设置 true时，除了原始的默认构造方法外，还额外生成一个全参数完整的构造方法，默认： false beanPrintSupertype设置 true时，将同时打印出超类，默认： false schemaPattern使用 LIKE模式中的 schema名称模式；它必须匹配数据库存储中的 schema名称 tableNamePattern使用 LIKE模式中表名称模式；它必须匹配数据库中的表名称，多个模式使用逗号 ,分隔，默认： null targetFolder生成源文件的目标目录 beansTargetFolder生成的 Bean源文件的目标目录，默认与 targetFolder设置的目录相同 namingStrategyClass命名策略的实现类类名，默认： DefaultNamingStrategy beanSerializerClass Bean序列化的实现类类名，默认： BeanSerializer serializerClass序列化实现类类名，默Querydsl中文文档翻译22QueryingSQL serializerClass认： MetaDataSerializer exportBeans设置为 true时，同时导出 Bean类，请参与第 2.14.13部份，默认： false innerClassesForKeys设置为 true时，会为主键生成一个内部类，默认： false validationAnnotations设置为 true时，序列化时将加入 validation验证标签，默认： false columnAnnotations导出列标签，默认： false createScalaSources是否导出 Scala源文件，而不是 Java源文件，默认： false schemaToPackage追加 schema名称至包名称，默认： false lowerCase是否转换为小写名称，默认： false exportTables导出数据表，默认： true exportViews导出视图，默认： true exportPrimaryKeys导出主键，默认： true tableTypesToExport导出使用逗号分隔的表类型的列表（可能的值取决于JDBC驱动）。允许导出任意的类型，例如： TABLE,MATERIALIZEDVIEW。如果此值被设置，那么 exportTables和 exportViews的设置将会无效 exportForeignKeys是否导出外键设置，默认： true customTypes用户自定义类型，默认： none typeMappings table.column和 JavaType的映射设置，默认： none numericMappings size/digits和 JavaType的映射设置，默认： none imports生成的查询类中要引入的一组类： com.bar(引入包，不要加 .*标识)， com.bar.Foo(引入类)自定义类型转换的实现可以被额外添加：Querydsl中文文档翻译23QueryingSQLcom.querydsl.sql.types.InputStreamType可以注册指定的 table.column与 JavaType的类型映射：IMAGECONTENTSjava.io.InputStream默认的数值映射：表2.2.数值映射总位数(Totaldigits)小数位数(Decimaldigits)类型180 BigInteger90 Long40 Integer20 Short00 Byte00 BigDecimal它们还可以用以下列方式定制：10java.lang.ByteQuerydsl中文文档翻译24QueryingSQL Schema、表名和列名能够使用插件来重新命名，下面给出几个例子： schema的重命名PRODTEST表的重命名：PRODCUSTOMERCSTMR列的重命名：PRODCUSTOMERIDIDX注：当表和列重命名时， fromSchema可以被省略，相比于APT（包管理工具）生成的代码，某此功能将不可用，例如， QueryDelegate注解功能2.3.3.使用Ant生成代码Querydsl中文文档翻译25QueryingSQL使用Querydsl-SQL模块的 com.querydsl.sql.codegen.ant.AntMetaDataExporter作为ANT任务支持，提供了相同的功能，Ant的task配置与Maven配置基本相同，作了复合型类型外。复合类型要使用没有包装的元素（ANT:withoutwrapperelement）2.3.4.编码方式生成代码下面是JAVA编码方式生成相关的查询类：java.sql.Connectionconn=.;MetaDataExporterexporter=newMetaDataExporter();exporter.setPackageName(com.myproject.mydomain);exporter.setTargetFolder(newFile(target/generated-sources/java);exporter.export(conn.getMetaData();上面的代码说明，生成的查询类将会被生成至 target/generated-sources/java作为源目录的 com.myproject.mydomainJAVA包目录中。生成的查询类中，下划线连接的表名使用驼峰式命名作为查询类类名（ USER_PROFILE= QUserProfile），下划线连接的列名使用驼峰式命名作Querydsl中文文档翻译26QueryingSQL为查询类型路径( Path)属性的名称（ user_id=userId）。另外，还生成了 PrimaryKey和 ForeignKey(如果有)作为查询类属性，可用于进行 join查询。2.3.5.配置使用 Querydsl-SQL的方言实现作为参数，构造一个 com.querydsl.sql.Configuration作为配置信息。如果H2作为数据库，则可以这样做：SQLTemplatestemplates=newH2Templates();Configurationconfiguration=newConfiguration(templates);Querydsl使用SQL方言来定制实现不同的关系数据库的SQL的序列化，目前可用的SQL方言实现有：CUBRIDTemplates(testedwithCUBRID8.4)DB2Templates(testedwithDB210.1.2)DerbyTemplates(testedwithDerby10.8.2.2)FirebirdTemplates(testedwithFirebird2.5)HSQLDBTemplates(testedwithHSQLDB2.2.4)H2Templates(testedwithH21.3.164)MySQLTemplates(testedwithMySQL5.5)OracleTemplates(testwithOracle10and11)PostgreSQLTemplates(testedwithPostgreSQL9.1)SQLiteTemplates(testedwithxerialJDBC3.7.2)SQLServerTemplates(testedwithSQLServer)SQLServer2005Templates(forSQLServer2005)SQLServer2008Templates(forSQLServer2008)SQLServer2012Templates(forSQLServer2012andlater)TeradataTemplates(testedwithTeradata14)为了构建 SQLTemplates实例，可以使用如下面中的 builder模式：Querydsl中文文档翻译27QueryingSQLH2Templates.builder().printSchema()/toincludetheschemaintheoutput.quote()/toquotenames.newLineToSingleSpace()/toreplacenewlineswithsinglespaceintheoutput.escape(ch)/tosettheescapechar.build();/togetthecustomizedSQLTemplatesinstance通过 Configuration.setUseLiterals(true)方法来设置直接使用常量来序列化SQL语句，而不是使用参数式绑定的预编译语句，并且覆盖 schema、 table和自定义的类型，具体的说明请参见Configuration类的javadoc文档。2.3.6.查询下面的例子中，我们将使用工厂类 SQLQueryFactory来创建 SQLQuery对象，它比使用 SQLQuery的构造方法来创建实例更简便：SQLQueryFactoryqueryFactory=newSQLQueryFactory(configuration,dataSource);使用QuerydslSQL进行查询就是这么简单：QCustomercustomer=newQCustomer(c);ListlastNames=queryFactory.select(customer.lastName).from(customer).where(customer.firstName.eq(Bob).fetch();假设关系数据库中表名为 customer，列为 first_name和last_name，则上述代码将转换为下列的SQL语句：SELECTc.last_nameFROMcustomercWHEREc.first_name=Bob2.3.7.一般用法Querydsl中文文档翻译28QueryingSQL使用 SQLQuery类的级联方法调用 select:设置查询的映射（如果是通过 SQLQueryFactory创建，则不是必须的） from:添加查询的源（ Q开头的查询映射对象） innerJoin,join,leftJoin,rightJoin,fullJoin,on:添加要 join的查询元素， join方法的第一个参数是 join的查询元素，第二个参数是 join的查询元素的目标（别名） where:添加查询过滤器，以 and操作符连接的，或是以逗号分隔的可变参数 groupBy:以可变参数的方式添加 GROUPBY参数 having:添加具有 GROUPBY分组作为断言（Predicate）表达式的可变参数数组的 HAVING过滤器 orderBy:添加结果的排序方式的排序表达式。使用 asc()和desc()方法获取基于数字、字符串或其他可进行比较的表达式的 OrderSpecifier实例 limit,offset,restrict:设置分页查询的结果。 limit为结果的最大行数， offset是偏移的行数， restrict则是两者的限定约束2.3.8.联合查询联合查询使用下面给出的语法来构建：QCustomercustomer=QCustomer.customer;QCompanycom
