Guide

qrqy-developer 是公司累积的 Java 开发框架，前人各种实施经验的累积（客观来说，是有点重的），这里面有快速生成代码的工具、方便快捷的 Tools、个性化/增强的注解，总之，一旦你熟悉这个框架，它带来的效率提升和开发体验一定会让你眼前一亮。

版本计划

版本	更新时间	备注
2.0.2	2022 年 1 月 1 日	原始版本，完成基础的增删改查业务，使用 yapi 进行接口管理
3.0.0	2022 年 7 月 21 日	与 2.x 不兼容，回归 Controller 进行接口管理，使用 swagger 进行接口维护，导入 ApiFox
3.0.2	2022 年 8 月 30 日	细节优化，重点解决了 JPA 打印 sql 的问题，打印 sql 带参数，优化日志的 traceId，确保日志 traceId 不重复
3.0.3	2022 年 8 月 31 日	CommonEntity 中，将 version 字段拿出来，避免 JPA 的@Version 锁不生效，JPA 中@Version 属于乐观锁，我理解并不是很好的方案，具体查看锁机制
3.0.4	2022 年 9 月 7 日	解决 JPA Mangaer _Null 和_NotNull 不能为空的问题，目前这两个操作符可以接收 null 为参数
3.0.5	2022 年 9 月 15 日	在阜新招商项目中，发现 createdBy、updatedBy 不一定是 Integer 类型，也可能是 String 类型，因此增加 Community2Entity，通过泛型来解决
3.0.5	2022 年 9 月 22 日	升级 jCoder 到 V4 版本，在 Qo 中增加了@NotNull 和@NotEmpty，减少书写时间
3.0.6	2022 年 9 月 25 日	升级框架，主要优化点： 1. BaseSqlQuery 增加了 groupBy 写法，可以支持分组点击查看 2. Manager 和 Repository 提供的 deleteBatch 的功能点击查看 3. 新增 SmartQuery 功能，强烈推荐！！！适合单表的统计查询点击查看，基于该功能，实现了综合统计平台 4. 配置文件增加 enum-convertor 参数和@DoNotSerialize，可以放置请求和响应被序列化点击查看
3.0.6	2022 年 10 月 9 日	在执行阜新招商项目时，新增了 Common2Entity 的基础 Entity 类，但是由于框架没有考虑该类的处理，所以封装的 Manager 和 Repository 的软删除部分都是不好用的，本版本进行了修复，大家直接升级就好。之所以没有提升版本号主要原因是考虑这次修复是一个 bug，没有功能升级，所以还维持在这个版本号。测试不一定很充分，大家有问题随时 Call TerryQi
3.0.6	2022 年 10 月 11 日	1. SmartFind 和 SmartQuery 提供了 DateFormat 操作，具体详见DateFormat 2. 新增补零工具，趋势图必然需要补零，那么提供一个增强补零工具，适合于各种类型的对象进行补零操作点击查看
3.0.7	2022 年 10 月 22 日	在 Manager 层提供 randomOne 和 randomList 方法，用于获取随机数据（比如说做测试数据就用的到），点击查看
3.0.7	2022 年 11 月 7 日	1. 发现 jCoder-v4.groovy 生成的 CreateQo 和 QueryQo 有问题，已经修复 2. fix 一个排序的缺陷，即 orderBy 由于使用 Map 是无序的，但是我们实际进进行多条件排序时，需要有顺序，所以改为 LinkedMap 3.上线 JPA 一个重要的功能——FindInSet点击查看
3.0.7	2022 年 11 月 8 日	原 3.0.7 版本中 BaseManager 的 query 方法排序有问题，进行修复，本质上 query 和 findAll 方法功能是一致的，未来可能废弃其中某一个
3.0.8	2022 年 11 月 13 日	框架自带一些对 Response 报文的过滤器，进行格式转化。其中针对枚举值过滤器为 EnumFilter，将枚举转化为{code:xxx,message:xxx}的形态，首先这个形态是不推荐的，在 3.0.6 版本中已经舍弃，详见枚举值的序列化，后续项目不建议再对枚举序列化操作。但在 EnumFilter 中存在缺陷，主要是如果 Vo 进行了继承，此类父类中有枚举值，就无法有效进行序列化。那么修改了 EnumFilter，会持续向父类找字段，直到找到为止
3.0.9	2022 年 11 月 24 日	在烟台城发项目中，进一步升级 SmartQuery 功能，优化了 SmartCount 和 SmartFind，详见点击查看，特别适合于出统计报表、趋势图等业务场景
3.0.10	2023 年 3 月 7 日	进行了小优化，主要是 SmartCount 返回 Number 值的处理，之前如果是未找到值，则返回 null，优化后范返回 Number(0)
3.0.11	2023 年 3 月 11 日	Manager 中提供 findFirstOne 方法，即根据条件检索，只获取一条数据，本质还是分页获取数据
3.0.11	2023 年 3 月 29 日	提供了 JCoder-v5.groovy 的版本，主要是生成的 Qo 中，在@ApiModelProperty 中，给了 required = xxx 的设置。那么规则是：QueryQo 的 required = false；其余的 Qo 的 required = true。之所以增加这个处理，是为了让 Swagger 接口更加规范一些，从而便于综合工具平台open in new window 来生成 TypeScript 的接口文件
3.0.12	2023 年 4 月 6 日	主要解决了 response 直接返回字符串被加了双引号的问题，主要原因是过了 fastJson 的 HttpMessageConvertor，在 qrq-web 的 configuration 下增加了一个 WebConfig 配置，通过 stringHttpMessageConverter 专门处理了 String，我理解这样的处理是好的，如果影响到哪些项目，请 call TerryQi；此外，优化了 application.yml，七牛、阿里、腾讯云的 OSS 配置不是必须的，之前的项目中，必须配置才能启动项目，这里是不正确的。java-dp-template 的阿里、腾讯、七牛的 OSS 配置只留下了配置项，取消了里面的值；再有就是 fastjson 增加了 WriteDateUseDateFormat，日期格式就直接显示；4 月 23 发现 swagger-ui 不好用，补充了 addResourceHandlers
3.1.0	2023 年 5 月 29 日	3.1.0 是一个实验版本，目前有三个项目接入，主要优化了框架，更好的适配 ChatGPT 等返回数据流的接口
3.0.12、3.1.0	2023 年 6 月 18 日	!!!!重要升级，接口可以加密了。此外，稍微调整了返回值报文，之前存在 null 值属性被删除的问题，请观察，如有问题请 call 一下 TerryQi
3.1.1	2023 年 7 月 13 日	在 Qo 中，增加了`orderByCustomSort`字段，用于指定字段排序，具体详见指定字段排序的说明
3.1.1	2023 年 7 月 16 日	deleteBatch 中，增加了 deleterId 字段，代表删除人，目前只能 Integer 字段代表 deleted_by，否则改造工作量较大，如果后续有项目使用 String 作为主键，可以联系 TerryQi 继续改造
3.1.0、3.1.1	2023 年 10 月 10 日	优化 CryptoRequestBodyAdvice，解决了请求日志打印的问题
3.1.2	2023 年 10 月 10 日	批量删除增加日志；Vo 的 LocalDatetime 在再也不用加注解了，可以直接打印 YYYY-MM-dd HH:mm:SS 的格式数据
3.1.1、3.1.2	2023 年 10 月 19 日	禁毒项目中，发现 request 的长报文解密失败，排查原因为 RequestBodyAdviceAdapter 的 inputStream 被截断导致，目前已经优化了 inputMessageBody 函数，目测 ok，需要持续观察
3.1.2	2023 年 11 月 2 日	禁毒和内蒙古大屏项目，都需要趋势图查询功能，发现大家不会使用，因此优优化文档，并提供 TrendNormalLongDo 通用的 class，用于增强补零操作
3.1.3	2023 年 11 月 2 日	BaseSqlQuery 新增 or 方法，可以支持单层的嵌套查询，也就是在例如 A and (B or C) and D and (E or F)
3.1.1、3.1.2、3.1.3	2023 年 11 月 10 日	3.1.1、3.1.2、3.1.3 的阿里云 OSS 的 policy 时间太短，之前只有 30 秒，本次进行了升级，可以达到 30000 秒，基本就够用了
3.1.4	2023 年 11 月 25 日	很多项目中是有获取 TopN 条数据需求，因此提供了 findFirstOne 和 findTopNList 方法，更加方便的获取列表数据
重要说明！！！	2023 年 12 月 11 日	Groovy 生成文件不乱码
3.1.4	2023 年 12 月 30 日	提供批量保存操作 batchSaveAll()，通过多线程的方式提升了插入和保存的操作效率
3.1.5	2024 年 1 月 17 日	在执行财务系统核算中台项目时，发现需要执行一些原生的 sql，映射到 Java 对象，那么提供 SchemaManager，可以执行 sql 并映射为 List
3.1.6	2024 年 2 月 24 日	修复 JPA 审计问题，补充 deletedBy 字段，因为我们使用软删除，因此 LastModifyBy 就是 deletedBy
3.1.7	2024 年 3 月 24 日	修复 batchSaveAll 的问题，当发生异常时，在该版本之前，程序多线程会 countDown 一直 wait，导致无法执行后续业务；本次修改后，错误保存会直接略过（例如数据库要求必填，但 entity 字段为 null，或者数据库是 unique key，但插入数据字段重复），这样的处理程序不会卡死，但业务存在保存失败的风险，需要观察抛出的异常
3.1.7	2024 年 4 月 7 日	BaseSqlQuery 新增 dataScope 属性，我以往进行查询时，默认都是搜索出软删除的数据，但一些场景是需要查询被软删除的数据和全量数据的，所以增加了 dataScope，可以设置数据的搜索范围。4 月 11 日，为了配置 dataScope，在通过 jDaoMySQL.groovy 生成脚 Vo 时，新增了 deletedAt、deletedBy、deletedFlag 字段，点击下载最新的jDaoMySQL.groovyopen in new window
3.1.8	2024 年 4 月 9 日	以往框架抛出 BizException 时，只有 code 和 message，没有 result 返回，一些场景下缺少数据支持。本版本扩展了 BizException，新增了 result 字段，可以存放异常数据。throw new BizException(ErrorCode.EQMJ_PAUSE_ERROR, "EQMJ 业务暂停", vo);
3.1.8	2024 年 5 月 10 日	manager 的 findById 新增 DataScope 参数，是一个枚举值，可以查询软删除的数据，在之前的版本中，将 findAll 增加了 DataScope 参数，可以查看被软删除的数据。大家反馈，findById 也需要查看软删除的数据，所以也增加了这个字段，另外外，特殊说明一下，DataScope 只适合 BaseSqlQuery，SmartQuery 不适用
3.1.9	2024 年 5 月 17 日	如果项目中，需要按照月份进行数据统计，怎么办？用 MonthFormat，与 DateFormat 类似，都是 groupby 的灵活操作
3.1.10	2024 年 5 月 22 日	在 XX 项目中，遇到获取文章 TopN 展示的需求，因此我们增强了 orderBy，可以用于 SmartQuery 根据 count 的结果，进行排序。同时，为了解决 topN 的问题，在 BaseSqlQuery 、SmartQuery 新增了 limit、offset 属性，这样就可以更加灵活的实现排序和获取数据条目的功能了
3.1.11	2024 年 6 月 22 日	修复了 randomOne 和 randomList 的操作，当然 3.1.10 也修复了，但是如果你的本地仓库中有这个版本的 jar，需要手动删除一下
3.1.12	2024 年 7 月 8 日	升级框架 Fastjson2 版本，解决反序列化漏洞，观察中。慎重升级，升级后如果你的项目没有 JSON、JSONObject，可以也同步引入 fastjson（1.2.83 版本），框架中已经删除了 fastjson1，项目中使用请自行在 pom 中引入
3.1.13	2024 年 8 月 31 日	请注意，该版本是在 3.1.11 上升级的版本，主要原因是 3.1.12 版本改造了底层，影响面还是比较大，继续观察。3.1.13 版本主要是针对支付回调等接口，不进行 fastjson 到 RequestQo 的映射，因为可能存在一些接口（例如微信的支付回调是 xml data）不是 json 的形式，强制使用 fastjson 进行映射会抛出错误，具体详见接口报文不进行 Qo 映射
3.1.14	2025 年 1 月 26 日	新增 HourFormat 方法，主要用于数据统计，例如按照小时进行统计的场景
3.1.15	2025 年 2 月 20 日	新增 YearFormat、WeekFormat、IOSWeekFormat 方法，主要用于数据统计，例如统计 WAU 场景，用法参考 DateFormat，详见说明
3.1.16	2025 年 4 月 15 日	SmartQuery 也可以用 SetDataScope ，统计的时候可以控制数据范围，具体详见dataScope

特殊说明，在 java 框架由 2.x 升级到 3.x 的时候，发现一个严重错误，即接口加密功能失效，那么整个 3.x 的接口都存在这个问题，原因是 2.x 的接口只有一个 Controller，通过接口中最后一个方法来映射 Service，进行 RequestQo 到 Bean 的转换，但是在 3.x 中，舍弃了这个方案，更好的与 Swagger 结合，主要是修改框架中 CryptoRequestBodyAdvice.java，将 afterBodyRead 的逻辑提前到 beforeBodyRead 中，即在 Http 接口进行参数映射前完成解密

那么，如果你的项目在使用 3.x 的接口，且需要加密，请联系 TerryQi 升级对应版本的框架，或者你升级到 3.0.12 以上

系统要求

JDK >= 1.8
MySQL >= 5.7
Maven >= 3.0

主要引用

SpringBoot2.6
JPA，数据库 ORM 框架
Swagger 3.0，接口文档工具
Spring Security，权限管理

使用前准备

你需要在本机安装 Groovy，Groovy 是与 Java 结合最好的脚本语言，我们生成代码的工具就是通过 Groovy 脚本来执行的

C:\Users\Lenovo>groovy -version
Groovy Version: 3.0.9 JVM: 1.8.0_291 Vendor: Oracle Corporation OS: Windows 10

框架结构

qrqy-developer 框架主要适用于中小型的单体项目，通过一定通用能力的封装和自动生成代码的工具，快速构建基础业务，让小伙伴把精力放在理解需求、提升开发水平和流程穿越测试上，远离重复、枯燥的 CRUD

qrqy-developer 的主要模块如下

developer-common：通用模块，主要存储了常量、Entity/Qo 的结构、基础的枚举和一些常用的 Utils 工具
developer-sql-jpa：核心模块，在 JPA 之上封装的 QueryMapper 和 Repostory
developer-web：web 应用模块，常用的注解、Redis 锁、Controller 接口、Vo 的封装、基础请求/响应拦截都在这里实现

上面三个是基础包，在实施项目时都应该引入。

developer-user：用户模块，包含了用户注册（微信小程序）/登陆、管理员登陆/增删改查管理、权限配置等能力，一般通用小项目可以直接引入该模块，但是很多情况下用户模块也是个性化的，那么可以将该模块 copy 到自己的项目中，改一下报名即可

developer-common

通用模块，逐步丰富

├─src
│  └─main
│      └─java
│          └─com
│              └─qrqy
│                  └─developer
│                      └─common
│                          ├─constant           //常量模块
│                          ├─entity             //基础Entity
│                          ├─enums              //基础枚举值
│                          ├─exception
│                          ├─log
│                          ├─qo                 //基础Qo
│                          └─utils

说明如下：

常量模块：不要在代码里面写 0、1，应该用常量，生效/失效=COMMON_VALID/COMMON_INVALID、删除/未删除=IS_DELETED/NOT_DELETE；CommonResponseCode，已经提供了基础的响应代码，个性化的响应报文应该在本地实现...
JCoder 生成的 Entity 都继承于 CommonEntity，例如 status、note、deleteFlag 等通用字段都在这个类中定义，因此必须参考数据库规范，在全部库表中都要设定通用字段

developer-sql-jpa

基于 JPA 封装的框架，核心模块，帮助你快速 CRUD

├─src
│  └─main
│      └─java
│          └─com
│              └─qrqy
│                  └─developer
│                      ├─sql                //核心模块，快速生成CRUD
│                      └─utils

developer-sql-jpa 是灵魂，具体参考JPA 的使用

developer-web

基础的 Web 封装

├─src
│  └─main
│      └─java
│          └─com
│              └─qrqy
│                  └─developer
│                      └─web
│                          ├─annocation
│                          ├─configuration
│                          ├─controller         //接口
│                          │  └─upload
│                          ├─converter
│                          │  └─filter
│                          ├─model          //qo是请求，vo是响应
│                          │  ├─qo
│                          │  │  └─upload
│                          │  └─vo
│                          │      └─upload
│                          ├─result         //封装的返回报文样式
│                          ├─secret
│                          ├─security
│                          ├─service            //基本Service
│                          └─utils

响应报文中：

CommonObjectResult：通用报文样式
CommonPagingResult：通用分页数据样式

主要脚本

主要使用：

jDaoMySQL-v3.groovy 根据数据库生成基础脚本

2022-08-31 进行优化，将 version 放出来，主要解决 JPA @Version 锁不生效的问题

jCoder.groovy 根据 Entity 生成 Controller 和 Qo

2022-09-22 进行优化，升级到 V4 版本，Qo 中增加@NotNull 和@NotEmpty 注解

# Guide

# 版本计划

# 系统要求

# 主要引用

# 使用前准备

# 框架结构

# developer-common

# developer-sql-jpa

# developer-web

# 主要脚本