我这样写代码，比直接使用 MyBatis 效率提高了100倍！

| 首先数据库有两张表

| 接下来我们要实现一个用户查询的功能

• 可按用户名字段查询，要求：
• 可精确匹配（等于某个值）
• 可全模糊匹配（包含给定的值）
• 可后模糊查询（以...开头）
• 可前模糊查询（以.. 结尾）
• 可指定以上四种匹配是否可以忽略大小写
• 可按年龄字段查询，要求：
• 可精确匹配（等于某个年龄）
• 可大于匹配（大于某个值）
• 可小于匹配（小于某个值）
• 可区间匹配（某个区间范围）
• 可按角色ID查询，要求：精确匹配
• 可按用户ID查询，要求：同年龄字段
• 可指定只输出哪些列（例如，只查询 ID 与 用户名 列）
• 支持分页（每次查询后，页面都要显示满足条件的用户总数）
• 查询时可选择按  ID、用户名、年龄 等任意字段排序

| 后端接口该怎么写呢？

| 手把手：只一行代码实现以上需求

添加依赖

Maven ：

<dependency>
    <groupId>com.ejlchinagroupId>
    <artifactId>bean-searcher-boot-starterartifactId>
    <version>3.0.1version>
dependency>

Gradle ：

implementation 'com.ejlchina:bean-searcher-boot-starter:3.0.1'

然后写个实体类来承载查询的结果

@SearchBean(tables="user u, role r", joinCond="u.role_id = r.id", autoMapTo="u") 
public class User {

    private Long id;  // 用户ID（u.id）
    private String name; // 用户名（u.name）
    private int age;  // 年龄（u.age）
    private int roleId;  // 角色ID（u.role_id）
    @DbField("r.name")  // 指明这个属性来自 role 表的 name 字段
    private int role;  // 角色名（r.name）

    // Getter and Setter ...
}

接着就可以写用户查询接口了

@RestController
@RequestMapping("/user")
public class UserController {

    @Autowired
    private MapSearcher mapSearcher;  // 注入检索器（由 bean-searcher-boot-starter 提供）

    @GetMapping("/index")
    public SearchResult> index(HttpServletRequest request) {
     // 这里咱们只写一行代码
        return mapSearcher.search(User.class, MapUtils.flat(request.getParameterMap()));
    }

}

上述代码中的 MapUtils 是 Bean Searcher 提供的一个工具类，MapUtils.flat(request.getParameterMap()) 只是为了把前端传来的请求参数统一收集起来，然后剩下的，就全部交给 MapSearcher 检索器了。

| 这样就完了？那我们来测一下这个接口，看看效果吧

（1）无参请求

• GET /user/index

• 返回结果：

{
    "dataList": [           // 用户列表，默认返回第 0 页，默认分页大小为 15 （可配置）
        { "id": 1, "name": "Jack", "age": 25, "roleId": 1, "role": "普通用户" },
        { "id": 2, "name": "Tom", "age": 26, "roleId": 1, "role": "普通用户" },
        ...
    ],
    "totalCount": 100       // 用户总数
}

（2）分页请求（page | size）

• GET /user/index? page = 2 & size = 10

• 返回结果：结构同 （1）（只是每页 10 条，返回第 2 页）

参数名 size 和 page 可自定义， page 默认从 0 开始，同样可自定义，并且可与其它参数组合使用

（3）数据排序（sort | order）

• GET /user/index? sort = age & order = desc

• 返回结果：结构同 （1）（只是 dataList 数据列表以 age 字段降序输出）

参数名 sort 和 order 可自定义，可与其它参数组合使用

（4）指定（排除）字段（onlySelect | selectExclude）

• GET /user/index? onlySelect = id,name,role

• GET /user/index? selectExclude = age,roleId

• 返回结果：（ 列表只含 id,name 与 role 三个字段）

{
    "dataList": [           // 用户列表，默认返回第 0 页（只包含 id,name,role 字段）
        { "id": 1, "name": "Jack", "role": "普通用户" },
        { "id": 2, "name": "Tom", "role": "普通用户" },
        ...
    ],
    "totalCount": 100       // 用户总数
}

参数名 onlySelect 和 selectExclude 可自定义，可与其它参数组合使用

（5）字段过滤（op = eq）

• GET /user/index? age=20

• GET /user/index? age=20 & age-op=eq

• 返回结果：结构同 （1）（但只返回 age = 20 的数据）

参数 age-op = eq 表示 age 的 字段运算符 是 eq（Equal 的缩写），表示参数 age 与参数值 20 之间的关系是 Equal，由于 Equal 是一个默认的关系，所以 age-op = eq 也可以省略

（6）字段过滤（op = ne）

• GET /user/index? age=20 & age-op=ne

• 返回结果：结构同 （1）（但只返回 age != 20 的数据，ne 是 NotEqual 的缩写）

（7）字段过滤（op = ge）

• GET /user/index? age=20 & age-op=ge

• 返回结果：结构同 （1）（但只返回 age >= 20 的数据，ge 是 GreateEqual 的缩写）

（8）字段过滤（op = le）

• GET /user/index? age=20 & age-op=le

• 返回结果：结构同 （1）（但只返回 age <= 20 的数据，le 是 LessEqual 的缩写）

（9）字段过滤（op = gt）

• GET /user/index? age=20 & age-op=gt

• 返回结果：结构同 （1）（但只返回 age > 20 的数据，gt 是 GreateThan 的缩写）

（10）字段过滤（op = lt）

• GET /user/index? age=20 & age-op=lt

• 返回结果：结构同 （1）（但只返回 age < 20 的数据，lt 是 LessThan 的缩写）

（11）字段过滤（op = bt）

• GET /user/index? age-0=20 & age-1=30 & age-op=bt

• 返回结果：结构同 （1）（但只返回 20 <= age <= 30 的数据，bt 是 Between 的缩写）

参数 age-0 = 20 表示 age 的第 0 个参数值是 20。上述提到的 age = 20 实际上是 age-0 = 20 的简写形式。另：参数名 age-0 与 age-1 中的连字符 - 可自定义。

（12）字段过滤（op = mv）

• GET /user/index? age-0=20 & age-1=30 & age-2=40 & age-op=mv

• 返回结果：结构同 （1）（但只返回 age in (20, 30, 40) 的数据，mv 是 MultiValue 的缩写，表示有多个值的意思）

（13）字段过滤（op = in）

• GET /user/index? name=Jack & name-op=in

• 返回结果：结构同 （1）（但只返回 name 包含 Jack 的数据，in 是 Include 的缩写）

（14）字段过滤（op = sw）

• GET /user/index? name=Jack & name-op=sw

• 返回结果：结构同 （1）（但只返回 name 以 Jack 开头的数据，sw 是 StartWith 的缩写）

（15）字段过滤（op = ew）

• GET /user/index? name=Jack & name-op=ew

• 返回结果：结构同 （1）（但只返回 name 以 Jack 结尾的数据，ew 是 EndWith 的缩写）

（16）字段过滤（op = ey）

• GET /user/index? name-op=ey

• 返回结果：结构同 （1）（但只返回 name 为空 或为 null 的数据，ey 是 Empty 的缩写）

（17）字段过滤（op = ny）

• GET /user/index? name-op=ny

• 返回结果：结构同 （1）（但只返回 name 非空 的数据，ny 是 NotEmpty 的缩写）

（18）忽略大小写（ic = true）

• GET /user/index? name=Jack & name-ic=true

• 返回结果：结构同 （1）（但只返回 name 等于 Jack (忽略大小写) 的数据，ic 是 IgnoreCase 的缩写）

参数名 name-ic 中的后缀 -ic 可自定义，该参数可与其它的参数组合使用，比如这里检索的是 name 等于 Jack 时忽略大小写，但同样适用于检索 name 以 Jack 开头或结尾时忽略大小写。

当然，以上各种条件都可以组合，例如

• GET /user/index? name=Jack & name-op=sw & name-ic=true & roleId=1 & sort=id & size=10 & page=2
• 返回结果：结构同 （1）

| Bean Searcher

检索方法

• searchCount(Class beanClass, Map params) 查询指定条件下的数据 总条数

• searchSum(Class beanClass, Map params, String field) 查询指定条件下的 某字段 的 统计值

• searchSum(Class beanClass, Map params, String[] fields) 查询指定条件下的 多字段 的 统计值

• search(Class beanClass, Map params) 分页 查询指定条件下数据 列表 与 总条数

• search(Class beanClass, Map params, String[] summaryFields) 同上 + 多字段 统计

• searchFirst(Class beanClass, Map params) 查询指定条件下的 第一条 数据

• searchList(Class beanClass, Map params) 分页 查询指定条件下数据 列表

• searchAll(Class beanClass, Map params) 查询指定条件下 所有 数据 列表

MapSearcher 与 BeanSearcher

参数构建工具

另外，如果你是在 Service 里使用 Bean Searcher，那么直接使用 Map 类型的参数可能不太优雅，为此， Bean Searcher 特意提供了一个参数构建工具。

例如，同样查询 name 以 Jack (忽略大小写) 开头，且 roleId = 1，结果以 id 字段排序，每页加载 10 条，加载第 2 页，使用参数构建器，代码可以这么写：

Map params = MapUtils.builder()
        .field(User::getName, "Jack").op(Operator.StartWith).ic()
        .field(User::getRoleId, 1)
        .orderBy(User::getId, "asc")
        .page(2, 10)
        .build()
List users = beanSearcher.searchList(User.class, params);

这里使用的是 BeanSearcher 检索器，以及它的 searchList(Class beanClass, Map params) 方法。

运算符约束

@SearchBean(tables="user u, role r", joinCond="u.role_id = r.id", autoMapTo="u") 
public class User {

    @DbField(onlyOn = {Operator.Equal, Operator.StartWith})
    private String name;

    // 为减少篇幅，省略其它字段...
}

（1）还是使用运算符约束：

@SearchBean(tables="user u, role r", joinCond="u.role_id = r.id", autoMapTo="u") 
public class User {

    @DbField(onlyOn = Operator.Equal)
    private String name;

    // 为减少篇幅，省略其它字段...
}

（2）在 Controller 的接口方法里把运算符参数覆盖：

@GetMapping("/index")
public SearchResult> index(HttpServletRequest request) {
    Map params = MapUtils.flatBuilder(request) // 收集前端传来的参数 
        .field(User::getName).op(Operator.Equal)   // 把 name 字段的运算符直接覆盖为 Equal
        .build()
    return mapSearcher.search(User.class, params);
}

条件约束

@SearchBean(tables="user u, role r", joinCond="u.role_id = r.id", autoMapTo="u") 
public class User {

    @DbField(conditional = false)
    private int age;

    // 为减少篇幅，省略其它字段...
}

参数过滤器

@Bean
public ParamFilter myParamFilter() {
    return new ParamFilter() {
        @Override
        public  Map doFilter(BeanMeta beanMeta, Map paraMap) {
            // beanMeta 是正在检索的实体类的元信息, paraMap 是当前的检索参数
            // TODO: 这里可以添加一下自定义的参数过滤规则
            return paraMap;      // 返回过滤后的检索参数
        }
    };
}

| 某同学问

参数咋这么怪，这么多呢，和前端有仇呀

• 参数名是否奇怪，这其实看个人喜好，如果你不喜欢中划线 -，不喜欢 op

  、ic 后缀，完全可以自定义，参考这篇文档：https://searcher.ejlchina.com/guide/latest/params.html#字段参数

• 参数个数的多少，其实是和需求的复杂程度相关，如果需求很简单，其实很多参数没必要让前端传，后端直接塞进去就好，比如：name 只要求后模糊匹配，age 只要求区间匹配，那可以这样：

@GetMapping("/index")
public SearchResult> index(HttpServletRequest request) {
    Map params = MapUtils.flatBuilder(request)
        .field(User::getName).op(Operator.StartWith)
        .field(User::getAge).op(Operator.Between)
        .build()
    return mapSearcher.search(User.class, params);
}

@SearchBean(tables="user u, role r", joinCond="u.role_id = r.id", autoMapTo="u") 
public class User {

    @DbField(onlyOn = Operator.StartWith)
    private String name;
    @DbField(onlyOn = Operator.Between)
    private String age;

    // 为减少篇幅，省略其它字段...
}

入参是 request，我 swagger 文档不好渲染了呀

@GetMapping("/index")
public SearchResult> index(Integer page, Integer size, 
            String sort, String order, String name, Integer roleId,
            @RequestParam(value = "name-op", required = false) String name_op,
            @RequestParam(value = "name-ic", required = false) Boolean name_ic,
            @RequestParam(value = "age-0", required = false) Integer age_0,
            @RequestParam(value = "age-1", required = false) Integer age_1,
            @RequestParam(value = "age-op", required = false) String age_op) {
    Map params = MapUtils.builder()
        .field(Employee::getName, name).op(name_op).ic(name_ic)
        .field(Employee::getAge, age_0, age_1).op(age_op)
        .field(Employee::getRoleId, roleId)
        .orderBy(sort, order)
        .page(page, size)
        .build();
    return mapSearcher.search(User.class, params);
}

字段参数之间的关系都是 “且” 呀，那 “或” 呢？“且” “或” 任意组合呢？

上文所述的字段参数之间确是都是 "且" 的关系，至于 “或”，虽然这种使用场景不太多，但 Bean Searcher 也是支持的，详细可以参考这篇文章：

https://github.com/ejlchina/bean-searcher/issues/8

| 结语

• 支持 嵌入参数
• 支持 字段转换器
• 支持 Sql 拦截器
• 支持 多数据源
• 支持 自定义注解
• 等等

| 项目 GitHub 地址