简单查询和复杂查询？都能完美胜任！

万事开头不一定难，准备好ORM映射

Jimmer准备了一对一、一对多、多对多的各种业务连接的解决方式，具体内容可以参考对应的官方文档：映射篇 | A revolutionary ORM framework for both java & kotlin

例如我的这里，先定义一个EnergyType类，然后定义一个Energy类，Energy和EnergyType的关系是多对一，即一个EnergyType对应多个Energy，而EnergyType本身存在父子级的树状关系，因此实体映射类的代码组织如下：

@Entity
@Table(name = "my_tablename")
interface EnergyType {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @JsonConverter(LongToStringConverter::class) // 为了避免Long类型在前端作为Number时溢出，这里用JsonConverter转化为String返回给前端
    val id: Long

    val name: String?

    @IdView
    val parentId: Long? // 这里的一个id对应一个实体属性，因此要用IdView注解

    val cate: String? // 分类属性，下文会提到

    @ManyToOne
    @OnDissociate(DissociateAction.DELETE)
    val parent: EnergyType? // 上文的IdView对应的视图属性，命名规则为xxxId作为IdView,xxx作为视图属性

    @OneToMany(mappedBy = "parent", orderedProps = [OrderedProp("id")])
    val childNodes: List<EnergyType> // 所有的子节点

    @Column(name = "create_time")
    val createTime: LocalDateTime?

    @Column(name = "update_time")
    val updateTime: LocalDateTime?

}

@Entity
@Table(name = "my_tablename")
public interface Energy {

    /**
     *  id
     */
    @Id
    @GeneratedValue(generatorType = SnowflakeIdGenerator::class)
    @JsonConverter(LongToStringConverter::class)
    val id: Long

    /**
     *  能源名称
     */
    val name: String?

    /**
     *  type_id

     */
    @IdView
    val typeId: Long?

    @ManyToOne
    val type: EnergyType?


}

也许组织这样的代码存在一定的工作量，但是使用插件快速生成是一个更好的选择，我这里使用的插件为CodeGenX

但是CodeGenX虽然使用快捷，但是其完全基于数据库表的结构生成的代码，因此对于视图属性需要自己手动配置，但是对于已经了解业务的后端来说，也不是很难。

其自动生成映射代码和KRepository代码非常好用.

DTO？DO？Fetcher更好！

大多数程序接口的本质都是从数据库中查询数据后返回，或者给定一定的数据结构进行增删改。（程序？数据库的星怒罢了）

对于使用Mybatis或者衍生框架的项目而言，这其中一定会诞生DTO用于返回查询的数据结构。且由于部分接口可能过于复杂，需要进行多次查询拼接对象，这就会导致DTO和DO的分离，进一步造成DTO和DO的数量爆炸，项目复杂度飙升。

Jimmer所提供的Fetcher正是用于解决这个问题。

这里提及一个业务场景：对于EnergyType，我希望展示某一个EnergyType的父级对象及其祖宗对象，自下而上组成一个链状结构

例如，使用传统的Mybatis框架，对于树状接口的非CTE查询就会带来上述提到的DTO和DO的分离，尤其是对于MySQL5.6这种不支持CTE的数据库下的项目，这里不再展示传统的代码。

而对于Jimmer，在组织完成实体类映射之后，一切都很简单：

这里提一下上文由CodeGenX生成KRepository代码：

@Repository
interface EnergyTypeRepository : KRepository<EnergyType, Long> {
}

是的，就这么简单，而且原封不动

@GetMapping("/chain/{id}")
fun chain(@PathVariable id: Long): Mono<ApiResponse<@FetchBy("ENERGY_TYPE_CHAIN") EnergyType>> {
    return JimmerUtil.success(energyTypeRepository.findNullable(id, ENERGY_TYPE_CHAIN))
} // 查询后返回
companion object {
    private val ENERGY_TYPE_CHAIN =
        newFetcher(EnergyType::class).by{
            allScalarFields()
            `parent*`()
        }
} // 定义查询数据结构

Controller只需要这麽多代码

感谢Jimmer和Kt，一扫我对Java臃肿笨重的印象

简单查询，小菜一碟

对于简单查询，使用Jimmer的对象抓取器即可。

例如这里我需要查询所有的EnergyType

@GetMapping("/list")
fun list(): Mono<ApiResponse<List<Energy>>> =
        JimmerUtil.success(
            energyRepository.findAll(ENERGY)
        )

companion object {
        private val ENERGY = newFetcher(Energy::class).by {
            allScalarFields()
        }
    }

复杂条件查询，其实也很简单

上面展示了一次，这里展示一下其他的

连表查询

@GetMapping("/list")
fun list(): Mono<ApiResponse<List<Energy>>> =
        JimmerUtil.success(
            energyRepository.findAll(ENERGY)
        )    
companion object {
        private val ENERGY = newFetcher(Energy::class).by {
            allScalarFields()
            type {
                name()
            }
        }
    }

条件查询，视图和条件分工

这里需要注意，Fetcher只是对象抓取器，并不承担条件查询的职责，之所以用Fetcher后文会提到

例如，由上向下循环的的查询，找出一个树形结构，需要查询父节点为空的视图

Repository和Controller代码如下：

@GetMapping("/tree")
fun tree(): Mono<ApiResponse<List<@FetchBy("ENERGY_TYPE_TREE") EnergyType>>> =
        JimmerUtil.success(
            energyTypeRepository.findByParentIsNull(ENERGY_TYPE_TREE)
        )
companion object {
        private val ENERGY_TYPE_TREE =
            newFetcher(EnergyType::class).by {
                allScalarFields()
                parent()
                `childNodes*`()
            }
    }

interface EnergyTypeRepository : KRepository<EnergyType, Long> {

    fun findByParentIsNull(fetcher: Fetcher<EnergyType>): List<EnergyType> = sql.createQuery(EnergyType::class) {
        where(table.parentId.isNull())
        orderBy(table.id.asc())
        select(table.fetch(fetcher))
    }.execute()

}

为什么推荐Fetcher

因为对于Fetcher承担了查询业务中的两个职能：定义查询内容和数据结构。

复杂函数聚合查询？退而求其次，但是仍然比Mybatis简单！

首先需要说明的是，Jimmer本身是为了动态查询，且专门为了复杂的动态查询而生，因此对象抓取器在复杂函数聚合查询方面存在一定的不适应性。（笔者在2025/3/3的体验）

不过这并不意味着Jimmer对此类情况存在缺陷，我们可以选择退而求其次，自己先使用动态查询功能查询出数据，而后新建一个自己的DTO数据模型承接数据并返回。

例如这里我需要知道不同Energy的type的各个cate下的Energys数量，如果用SQL表达的话：

SELECT
et.cate ,
COUNT(e.id)
FROM energy e
JOIN energy_type et ON e.type_id = et.id 
GROUP BY et.cate

但是可以先定义一下dto数据结构

class EnergyDTO {
    data class EnergyCateOverView(
        val cate: String,
        val count: Long
    )
}

然后使用Jimmer的动态查询+map实现

@Repository
public interface EnergyRepository : KRepository<Energy, Long> {

    // 查看各个分类下的能源数量
    fun energyCateOverview(): List<EnergyDTO.EnergyCateOverView> {
        return sql.createQuery(Energy::class) {
            groupBy(table.type.cate)
            select(
                table.type.cate,
                count(table.id)
            )
        }.map{
            EnergyDTO.EnergyCateOverView(it._1.toString(), it._2)
        }
    }

}

这虽然和Mybatis的使用原理类似，但是比起Mybatis的Mapper接口和SQL的解耦（尤其是在面对动态join和where时，无法使用注解快速直接实现动态SQL），减少了手动编写SQL，使得项目组织的复杂程度有效下降！

前端对接？简单快速，一键对接！

Jimmer提供了openapi的文档，也许你会觉得很简单，毕竟Swagger也能实现

但是Jimmer也提供了前端接口和数据结构的RPA流程代码，具体操作在官方文档中：生成客户端API | A revolutionary ORM framework for both java & kotlin

按照官方文档，首先在应用启动类上添加注解：

@SpringBootApplication
@EnableImplicitApi
class BackendApplication

fun main(args: Array<String>) {
    runApplication<BackendApplication>(*args)

}

随后配置一下配置文件，定义openapi文档和ts代码的下载地址

jimmer:
  client:
    ts:
      path: /ts.zip
    openapi:
      path: /openapi.yml
      ui-path: /openapi.html

随后在前端根目录（和src目录平齐的目录）创建scripts，里面新建一个js文件，内容如下

import http from 'http'; 
import fs from 'fs';
import fse from 'fs-extra';
import { v4 as uuidv4 } from 'uuid';
import tempDir from 'temp-dir';
import AdmZip from 'adm-zip';

const sourceUrl = "http://localhost:8000/ts.zip"; // 这里基于自定义的ip/端口号/路径修改
const tmpFilePath = tempDir + "/" + uuidv4() + ".zip";
const generatePath = "src/__generated";

console.log("Downloading " + sourceUrl + "...");

const tmpFile = fs.createWriteStream(tmpFilePath);

const request = http.get(sourceUrl, (response) => {
    response.pipe(tmpFile);
    tmpFile.on("finish", () => {
        tmpFile.close();
        console.log("File save success: ", tmpFilePath);

        // Remove generatePath if it exists
        if (fs.existsSync(generatePath)) {
            console.log("Removing existing generatePath...");
            fse.removeSync(generatePath);
            console.log("Existing generatePath removed.");
        }

        // Unzip the file using adm-zip
        console.log("Unzipping the file...");
        const zip = new AdmZip(tmpFilePath);
        zip.extractAllTo(generatePath, true);
        console.log("File unzipped successfully.");

        // Remove the temporary file
        console.log("Removing temporary file...");
        fs.unlink(tmpFilePath, (err) => {
            if (err) {
                console.error("Error while removing temporary file:", err);
            } else {
                console.log("Temporary file removed.");
            }
        });
    });
});

然后，在package.json中的scripts代码块中添加一行：

"scripts": {
    "api": "node scripts/generate-api.js"
  }

这样，在每次后端代码变更后启动时，使用包管理工具运行api命令如npm run api 或者yarn api即可

这样在src目录下会生成一个__generate目录，这个目录包含一些定义的工具、model目录和service目录

model目录中时定义的数据结构和枚举，service目录下时基于Controller下的接口生成的前端对接方法，名称和方法与后端一一对应，只用在使用时导入调用即可。