一页纸的需求

产品经理小王给我发了一张原型图。很普通的后台管理页面：

• 表格分页展示
• 顶部四个筛选条件：姓名、年龄区间、部门、入职时间
• 可以按任意列排序
• 底部统计这方面，总人数、平均年龄

"这个简单吧？下午能上线吗，" 他问。

我说这方面，"能。"

接下来默默打开 IDEA，开始写代码。

如果你也用 MyBatis，接下来 5~10 分钟会发生什么

// 你要写一条动态 SQL

SELECT u.*。d.name as deptName
FROM user u LEFT JOIN dept d ON u.dept_id = d.id


AND u.name LIKE CONCAT


AND u.age>= #{ageMin}


AND u.age <= #{ageMax}
        

AND d.name = #{dept}


AND u.entry_date>= #{entryDateStart}


AND u.entry_date <= #{entryDateEnd}
        


ORDER BY ${sortField} ${sortOrder}

LIMIT #{offset},#{size}

还没完。说到你还需要，

• 一个统计 SQL
• Controller 方法解析参数
• Service 层做分页计算
• Mapper 接口声明方法
• VO 类专门承接查询结果
• 手动防止 ${} 注入风险

痛点：

• 代码量爆炸：仅四个筛选条件。XML 已经超过 100 行。
• 需求变更时全线重构："把部门筛选改成多选。再加性别筛选"，又得改 XML、Mapper、VO…其实，每改一次都要重新编译部署。
• 维护成本高：If‑else 地狱让新同事望而却步。

If you switch to JPA,you’ll face same nightmare:

Specification spec = -> {
List predicates = new ArrayList<>;其实，Join deptJoin = root.join;if ) {
predicates.add,"%" + name + "%"));}
if {
predicates.add,ageMin));}
if {
predicates.add,ageMax));}
if ) {
predicates.add,dept));}
// ... 一样的 if 地狱，只是换了语法
return cb.and);}，// 排序、分页、总条数、字段统计，每一项都需要你不断堆砌代码 …

The core issue:

If you change your mindset

The database schema is fixed. Front‑end just tells you what it wants.

Pain point:

• You spend hours writing repetitive conditional logic instead of focusing on业务价值。
• You fear new filter fields will force a cascade of code changes.
• You worry about SQL 注入、深度分页等安全隐患，因为每次都是手工处理。

A smarter middle layer can do translation for you. It only needs to know three things:

• Your entity’s fields → 检索边界
• The incoming HTTP 参数 → 检索意图
• The combination → 自动生成安全的 SQL

This idea already exists in API world as GraphQL: 客户端声明返回哪些字段，服务端按需返回。

The REST‑style “GraphQL for list queries” – Bean Searcher

维度	GraphQL	Bean Searcher
协议层面	POST + GraphQL body 标准化请求体	GET/POST + URL 参数
主要思想	声明要返回哪些字段	声明检索边界 + 参数驱动查询
接入成本	改 API 层。引入 Schema 定义	a single dependency,zero code change after定义实体

A single line of code can replace dozens of XML/Java 条件拼装.

The Bean Searcher solution – 一行代码搞定列表检索全部需求

Create a searchable entity bean once:

@SearchBean
public class UserVO {
private Long id;其实，private String name;按理说，private Integer age;private String gender;@DbField
private String deptName;private LocalDate entryDate;// getters & setters...
}

Add an endpoint – 只剩下一领域务代码：

@GetMapping
public SearchResult search {
return beanSearcher.search;}

The front‑end call becomes extremely simple:

# 查询张姓使用者，按年龄倒序
GET /user/search?name=张&name-op=sw&sort=age&order=desc&page=1&size=20
# 多选部门示例
GET /user/search?dept=技术部,产品部&gender=F
# 区间筛选示例
GET /user/search?话说回来，ageMin=20&ageMax=30&entryDateStart=2020-01-01&entryDateEnd=2024-12-31
# 统计示例
GET /user/search?summary=true

The response you get back:

{
"dataList":,"totalCount": 57。
"summaries":
}

No XML. No manual if‑else. No extra VO mapping layer. No injection worries – Bean Searcher 自动转义所有参数。

The magic behind Bean Searcher – 它到底做了什么？

	传统方式	Bean Searcher
# 筛选条件怎么定义?	XML里写  / Java里拼 Predicate/QueryWrapper	参数名直接映射字段名。无需改代码，只要前端传新参数即可
# 多表联查?	手写 SQ L JOIN …	在实体上使用 @SearchBean  一次声明，多表自动关联。
# 返回结果需要 VO 转换?	需要单独写 Mapper/DTO 转换层。	SearchBean 本身就是 VO。直接返回，无额外转换，
# 安全性如何保障?	手动校验注入风险、分页上限、防深度偏移等。	框架默认开启防注入、防大页、防深度偏移，可自行细化注解控制。
：传统是“命令式”，每一步都要告诉框架怎么做；Bean Searcher 是“声明式”，只声明能查什么由框架根据请求自动执行。		**主要不是省代码，而是改变思维**——从“写 SQL”转向“建模 + 声明”。

A common objection – 前端会不会乱传参数？

I’ve been asked this dozens of times.

• If product only needs a simple fuzzy search,front‑end sends ?name=张. No need for extra operators.
• You can even go annotation‑free: a plain POJO’s field names default map to column names。
• Anotation 是用来*约束*和*细化控制*的，而不是强制必须使用。按理说，单表实体根本不需要任何注解就可以被搜索。说起来，
* **防止滥用**：框架提供全局配置。如最大页码、最大偏移量还有白名单过滤，确保即使前端传很多参数也不会危害程序安全。* **可 **这方面，如果业务真的需要更细粒度的控制。只需在对应字段上加上 @Filterable 等注解即可。

Toger with MyBatis/JPA?— Not enemies but teammates!

• MyBatis still负责增删改还有复杂事务逻辑。
• Bean Searcher 专注于列表检索、多条件过滤与统计。
• 两者可以共存。一个项目里同时引入两套依赖，仅增加几行配置代码即可。老实说，

适用场景对比
C​ondition​s​t​a​​c​k​e​​r​​l​​i​​​t​​​​​e​​s​t​​​​  or ​J​P​A​​?` ` ` ` --- Apologies - There appears an error in formatting due to excessive table complexity. Let's simplify: MyBatis/JPA 增删改、事务性业务、大型聚合操作" Bean Searcher 后台管理列表、报表导出、多条件动态筛选" "When to Use"Description" 两者互补。不是替代，仅需添加一个依赖就可以完成。"Strong"

---