← 课程目录 🚀 从零到一
📐 学习维度 阶段7 · 第28章 开源项目源码精读 🚀 从零到一 📚 课程目录 🏠 首页 🛤️ 学习路径

28.11.1 easy-es vs MyBatis-Plus:树形条件模型与启动链

审校 2026-09-26 · 素材来源:zcode会话#7《项目与MyBatis-Plus架构分析》(easy-es v3.0.x源码)
📑 本篇章节导航 (共7节,点击直达)
表层形似:API 对照内核神离:字符串拼接 vs 参数森林模块分层:六边形架构的活样本启动链:Spring 生态标准玩法一条龙优雅代码三则踩坑清单面试怎么问

easy-es 长得像 MyBatis-Plus(下称 MP):LambdaEsQueryWrapper、BaseEsMapper,链式调用几乎一样。但看进内核会发现根本分歧——MP 拼的是一维 SQL 字符串,easy-es 造的是一棵查询树。看透这点,才算读懂这个框架。

前置阅读:第 15 章用过 MyBatis-Plus。这篇看 easy-es 怎么把同一套思想搬到 ES。

表层形似:API 对照

概念MyBatis-Pluseasy-es
条件构造器LambdaQueryWrapperLambdaEsQueryWrapper
工厂入口Wrappers.lambdaQuery()EsWrappers.lambdaQuery()
Mapper 契约BaseMapperBaseEsMapper(约 80 方法)
字段引用SFunctionSFunction(同名同设计)

差异远不止条件模型一处,一张全景表看齐:

维度MyBatis-Pluseasy-es
列类型QueryWrapper(String 列)+ Lambda 双轨只有 Lambda 一种,R 永远绑定 SFunction
底层客户端JDBC DataSourceES 官方 ElasticsearchClient
注入面SQL 注入要防 ${} 拼接无 SQL,但留 executeSQL 逃生舱
索引生命周期无,DDL 归 DBA 管全自动索引托管(MP 完全没有的能力)
特有能力逻辑删除/乐观锁/数据权限高亮/分词/Geo/父子 join/向量检索/聚合/searchAfter 深分页
拦截器InnerInterceptor 链MyBatis 原生 @Intercepts/@Signature 风格

「只有 Lambda」这条值得多想一步:MP 的 String 列 QueryWrapper 是 Lambda 出现前的历史包袱,easy-es 起步晚,直接砍掉旧轨只留新轨——没有历史包袱时,别把别人的包袱捡回来。索引托管那一行才是真正的护城河:MP 把 DDL 交给 DBA,easy-es 把 DDL 变成了框架行为,细节下一篇展开。BaseEsMapper 约八十个方法把 CRUD、分页、高亮、聚合都约定成契约,官方实测相比原生 client 节省三到八十倍代码量。

内核神离:字符串拼接 vs 参数森林

SQL 的 WHERE 是线性一维的,MP 的 eq 就是往字符串追加 column = ?。但 ES 的 BoolQuery 是嵌套 JSON 树——must/should/must_not 可以任意嵌套,扁平字符串表达不了。举个具体例子:(a=1 OR b=2) AND c=3 在 SQL 里靠括号还能勉强表达,但 ES 里 filter 套 should 套 nested 再套 filter 的任意组合,一维字符串连括号配对都写不出来——数据结构决定了 API 的形状。

easy-es 的 AbstractWrapper 里藏着四个字段:


protected int level;                      // 树的高度
protected String parentId;                // 当前父节点
protected Stack<String> parentIdStack;    // 栈:存嵌套的父 id
protected LinkedList<EsQueryTypeEnum> prevQueryTypeQueue;

每个 eq/match/nested(consumer) 调用不是追加字符串,而是往队列塞一个带 parentId/children 的 Param 节点。最终 WrapperProcessor 用 TreeBuilder.buildTree 把扁平队列重建成树,再深度优先递归翻译成 BoolQuery.Builder。

走一遍嵌套的完整过程:调 and(w -> w.eq(...).or(...)) 时,外层把当前 parentId 压栈、生成新的 parentId 交给 lambda 里的子 wrapper;子条件全部入队后出栈、恢复父节点。TreeBuilder 重建时按 parentId 把子节点挂回父节点的 children——栈就是递归调用的手动展开版。

一句话总结差异:MP 是字符串模板,easy-es 是 AST 解释器。「线性存储 + 重建」这个技巧还顺带解决了序列化和克隆的麻烦。

翻译入口在 WrapperProcessor.initBoolQueryBuilder,关键就两行:TreeBuilder.buildTree(paramList) 把扁平队列还原成树,getBool(tree, rootBool, ...) 深度优先递归填充 BoolQuery.Builder——每层递归产出一个嵌套的 bool JSON 节点,节点落 must 还是 should,由 Param 自带的 EsQueryTypeEnum 决定。

模块分层:六边形架构的活样本


easy-es-parent(BOM)
 ├── annotation   纯注解层,零依赖
 ├── common       枚举/工具/SPI 接口
 ├── core         【内核】Wrapper 条件树 + BaseEsMapper + 代理
 ├── extension    拦截器内核(Interceptor/Chain/Invocation)
 ├── spring       Spring 适配
 ├── solon-plugin Solon 适配(不依赖 Spring!)
 └── boot-starter 自动装配

依赖方向严格单向:annotation → common → core → extension。Spring 和 Solon 两个适配层并列站在 core 之上——core 是领域内核,容器是可替换的适配器(六边形架构思想)。这就是同一套内核能同时支持两个 IoC 容器的原因。对照大量「框架主动融入 Spring」的常见写法,这种「容器可插拔」的姿势在中间件里更值得抄——中间件的生命周期往往比容器长。Solon 适配层全量不 import Spring 的类,这是能直接写进架构评审报告的证据。

启动链:Spring 生态标准玩法一条龙


boot-starter(spring.factories + AutoConfiguration.imports 双注册)
 → EsAutoConfiguration 绑定 EasyEsProperties
 → @EsMapperScan @Import → MapperScannerRegister(ImportBeanDefinitionRegistrar)
 → 对每个 Mapper 接口 MapperFactoryBean.getObject():
    1. 解析泛型实体类型
    2. 初始化 EntityInfo 反射元数据缓存
    3. JDK 动态代理 EsMapperProxy
    4. 收集所有 @Intercepts Bean → InterceptorChain.pluginAll 包代理
    5. 异步处理索引(非 MANUAL 模式)
    6. 包好的代理对象注入容器

链路里有三个细节值得单独点名。@EsDS 多数据源:注解打在 Mapper 接口上,MapperFactoryBean 解析后从 EsClientUtils 取对应集群的 client,每个数据源缓存一个实例,一套代码连多套 ES 集群。双扫描器:@EsMapperScan 走 Registrar 之外,还有一个 MapperScannerConfigurer(BeanDefinitionRegistryPostProcessor)兜着扫描,这是从 MyBatis 原样搬来的双保险姿势。缓存三件套:GlobalConfigCache、BaseCache、EntityInfoHelper.ENTITY_INFO_CACHE 都是静态 ConcurrentHashMap 注册表,反射元数据只解析一次、后续零反射开销——享元思想的落地。

自动装配 → FactoryBean → Registrar → 动态代理——每一环都是面试高频点。插件体系照搬 MyBatis:Plugin implements InvocationHandler 命中签名才拦截,InterceptorChain 层层嵌套形成责任链。EsMapperProxy 的 methodCache 还把方法分成 PlainMethodInvoker(普通方法反射)和 DefaultMethodInvoker(MethodHandle 调接口 default 方法)两类——MyBatis MapperProxy 的翻版,两个对照着读收获翻倍。

优雅代码三则

自引用泛型(CRTP)实现类型安全链式调用:


public abstract class AbstractWrapper<T, R, Children extends AbstractWrapper<T, R, Children>> {
    protected final Children typedThis = (Children) this;
    public Children eq(R column, Object val) { addParam(...); return typedThis; }
}

这招的收益是 IDE 补全永远返回最具体的类型,子类链上不会出现「返回父类型丢方法」的尴尬。

SerializedLambda 反解字段名:wrapper.eq(Document::getTitle, "es") 零字符串、零魔法值,重构改字段名编译期报错——比写字符串 "title" 安全得多。

MethodHandle 兼容垫片:为调接口 default 方法同时兼容 JDK 8/9+,写了 privateLookupIn 和反射构造 Lookup 两套路径——和 MyBatis 官方同款。这种垫片平时看不见,JDK 升级时它就是那道不让你返工的墙。

踩坑清单

面试怎么问

「easy-es 和 MyBatis-Plus 有什么本质区别?」——答:API 形似,内核模型不同——SQL 是一维字符串拼接,ES 查询是嵌套 BoolQuery 树,所以 easy-es 用 parentId+栈把条件压平存储、再重建树、递归翻译成 DSL;架构上是六边形分层,core 不依赖 Spring,Solon 适配层证明了这一点。

追问「为什么只支持 Lambda 列」——答:String 列是 MP 的历史包袱,新框架直接砍旧轨,R 永远绑定 SFunction 换来纯粹。再问「多套 ES 集群怎么连」——@EsDS 打在 Mapper 上按数据源取缓存的 client 实例。最后一问「拦截器能用来干什么」——租户隔离、审计日志、慢查询监控,写法从 MyBatis 原样平移即可。

一句话总结:形似是设计借鉴,神离是数据模型使然——树形查询注定要树形条件模型。