我被列表查询折磨了 7 年，直到有一天我发现它不是 ORM 的事！

一个后端工程师的自白：为什么你写了 100 行 Java 代码，其实只做了一件事------把前端传进来的几个参数，拼成一条 SQL。

一页纸的需求

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

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

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

我说："能。"

然后默默打开 IDEA，开始写代码。

如果你也用 MyBatis，接下来 30 分钟你会做什么

java 复制代码

// 首先，你要写一条动态 SQL
<select id="searchUsers" resultType="UserVO">
    SELECT u.*, d.name as deptName
    FROM user u LEFT JOIN dept d ON u.dept_id = d.id
    <where>
        <if test="name != null and name != ''">
            AND u.name LIKE CONCAT('%', #{name}, '%')
        </if>
        <if test="ageMin != null">
            AND u.age >= #{ageMin}
        </if>
        <if test="ageMax != null">
            AND u.age &lt;= #{ageMax}
        </if>
        <if test="dept != null and dept != ''">
            AND d.name = #{dept}
        </if>
        <if test="entryDateStart != null">
            AND u.entry_date >= #{entryDateStart}
        </if>
        <if test="entryDateEnd != null">
            AND u.entry_date &lt;= #{entryDateEnd}
        </if>
    </where>
    <if test="sortField != null and sortOrder != null">
        ORDER BY ${sortField} ${sortOrder}
    </if>
    LIMIT #{offset}, #{size}
</select>

还没完。你还需要一个统计 SQL、一个 Controller 方法解析参数、一个 Service 层做分页计算、一个 Mapper 接口、一个 VO 类专门承接查询结果------还要小心 ${} SQL 注入。

需求只说了四个筛选条件，代码已经快 100 行了。

然后小王说："对了，把部门筛选改成支持多选。还有，加一个性别筛选。"

你深吸一口气，继续写。

这个问题存在的唯一原因，就是你把"声明"和"执行"混在了一起。

如果换一种思想

我们换一个视角看这个问题。

数据库表，你已经定义好了。前端要查什么，用户说了算。

那为什么中间的翻译工作------把 HTTP 参数翻译成 SQL------需要你一行一行写 if-else？

有没有可能，让一个聪明的中间层来做这件事？它知道：

你的实体有哪些字段 → 这就是 检索边界
前端传了哪些参数 → 这就是 检索意图
两者一结合 → 生成 SQL

这个思路不是我的发明。在 API 领域，它有一个如雷贯耳的名字：

GraphQL --- 客户端指定要什么字段，服务端返回什么字段。一次请求，替代多次 REST 调用。

那在列表查询领域，能不能有同样的东西？

列表检索领域 Rest 版的 GraphQL

你只需要定义一个实体：

java 复制代码

@SearchBean(tables = "user u, dept d", where = "u.dept_id = d.id", autoMapTo = "u")
public class UserVO {
    private Long id;
    private String name;
    private Integer age;
    private String gender;
    @DbField("d.name")
    private String deptName;
    private LocalDate entryDate;
    // getters & setters...
}

然后，整个检索接口一行代码：

java 复制代码

@GetMapping("/user/search")
public SearchResult<UserVO> search() {
    return beanSearcher.search(UserVO.class, UserVO::getAge);
}

前端直接 GET 请求：

sql 复制代码

# 查询张姓用户，按年龄排序
GET /user/search? name=张 & name-op=sw & sort=age & order=desc

这一行代码返回的数据长这样：

json 复制代码

{
  "dataList": [
    { "id": 1, "name": "张三", "age": 25, "deptName": "技术部", "entryDate": "2023-03-01" },
    { "id": 2, "name": "张小明", "age": 28, "deptName": "产品部", "entryDate": "2022-11-15" }
  ],
  "totalCount": 47,
  "summaries": [ 1350 ]
}

分页、联表、多条件筛选、排序、统计------一个接口全搞定。 没有 XML。没有 if-else。没有 VO 转换代码。

这就是 Bean Searcher ------ 一个我用了三年、忍不住想安利给所有后端工程师的框架。

它到底做了什么

让我用一句话解释它的核心原理，因为理解了这一点，你就理解了它为什么能省掉 90% 的代码：

实体类声明检索边界，HTTP 参数驱动查询逻辑。

	传统方式（MyBatis / JPA）	Bean Searcher
筛选条件怎么定义	XML 里写 `<if>` / Java 里拼 `QueryWrapper`	参数名直接映射字段名
加一个新筛选条件	改 XML / 改 Java 代码 → 重新编译部署	前端直接传新参数，后端零改动
多表联查	手写 JOIN SQL	实体类声明关联关系
返回结果	需要 VO 转换层	SearchBean 就是 VO
安全性	自己写校验	防注入、防大页、防深度偏移，全部默认开启

打个比方：传统方式是"命令式"的 ------你告诉框架每一步怎么做。Bean Searcher 是"声明式"的------你声明"能查什么"（实体定义边界），然后前端通过参数表达"想查什么"（驱动查询逻辑）。

你不是在写查询。你是在声明检索边界。

一个会被问到的问题

"这难道不会让前端传太多参数吗？"

这个问题我被问了无数次。答案是：前端传多少参数，只和产品需求的复杂度有关，和后端用的什么框架毫无关系。

如果产品只需要一个模糊搜索框，前端就只传 ?name=张，不需要 name-op 和 name-ic。你甚至可以零注解使用------一个单纯的 POJO，字段名默认映射为数据库列名（驼峰转下划线）。

记住一件事：Annotation 是用来约束和精细化控制的，不是必须的。单表实体什么注解都不用加，天生可搜。

它和 MyBatis/JPA 是敌人吗？

绝对不是。

MyBatis 管增删改，Bean Searcher 管列表查。各司其职，和谐共存。

就像 GraphQL 不是为了取代 REST 而生的------它只是让 API 查询更灵活。Bean Searcher 也不是为了取代 MyBatis------它只是让列表检索不再痛苦。

	什么时候用
MyBatis / JPA	增删改、事务性操作、复杂业务逻辑
Bean Searcher	后台管理列表、数据导出、报表查询、任何"多条件动态筛选"场景
两者的关系	互补，不是替代。加一个依赖就够了。

真实项目里的体验

我在十几个项目里深度使用 Bean Searcher（分别是 Spring Boot 2/3/4 和 Solon 3/4），最大的感受不是"代码少了"------而是思维方式变了。

以前接到列表查询需求，脑子里想的是"这个 SQL 怎么写、参数怎么拼、排序怎么处理、分页传什么对象"。

现在接到列表查询需求，脑子里想的是"这个页面需要哪些字段，它们来自哪些表，哪些字段允许前端筛选"。

你不再是一个 SQL 拼接工。你是一个领域建模者。

而当你把这种体验告诉同事时，他们的第一反应通常是："这不就是......Java 后端版的 GraphQL？"

"对。"

试试看

如果你读到这里，发现上面说的痛点都是你每天在经历的------那你应该试一下。

不用重构项目，不用替换 ORM，不用改变任何架构。它是一个完全不侵入的框架，和 MyBatis/JPA/Spring Data JDBC 都能共存。

如果你觉得这玩意确实解决了你的痛点，点个 Star，让更多被列表查询折磨的 Java 工程师看到它。

毕竟------你把生命花在写 if-else 上，不如花在更有价值的事情上。