Skip to content

Latest commit

 

History

History
330 lines (261 loc) · 9.84 KB

1.QuickStart.md

File metadata and controls

330 lines (261 loc) · 9.84 KB

快速入门

引入依赖

目前最新的版本号为：

Gradle

在项目的build.gradle中加入本项目的依赖:

dependencies {
    ...

    compile "org.cat73:mybatis-pager-spring-boot-starter:版本号"

    ...
}

Maven

在项目的pom.xml中加入本项目的依赖：

<dependencies>
    ...

    <dependency>
        <groupId>org.cat73</groupId>
        <artifactId>mybatis-pager-spring-boot-starter</artifactId>
        <version>版本号</version>
    </dependency>

    ...
</dependencies>

为接口增加分页支持

在注解了@RequestMapping的方法上增加注解@Pager，即可让这个接口中的查询支持分页

一般情况下，这个方法中应只有一次查询(也可允许多次，后面会讲)

默认只支持返回Map，且key为data的值应为Collection的子类，例：

/**
 * 用于测试分页的接口呢
 */
@RestController
@RequestMapping("/api/demo")
public class DemoController {
    @Autowired
    private IDemoService service;

    @Pager // 分页注解
    @GetMapping("/list")
    public Map<String, Object> list() {
        List<Demo> list = this.service.listAll(); // 只有一次查询，值应为`Collection`的子类

        Map<String, Object> result = new HashMap<>();
        result.put("data", list); // key 为 data
        return result;
    }
}

自定义的返回值类型

阿啦，这样好麻烦呀，我们的项目用的是实体类做返回值呢，你看就像下面这样的实体类：

public class Result<T> {
    /**
     * 响应码，负数为失败，其他为成功，具体含义见接口文档
     */
    private int c; // code
    /**
     * 响应数据，失败时为字符串的失败原因，成功时为返回值
     */
    private T d; // data

    // ... 省略 构造方法、getter、setter ...
}

嗯，看起来挺精简的，也挺节约传输流量的，这样的实体类因为我们无法预计会是什么样的，所以默认确实是不支持的

不过稍加配置就可以支持了哟，自己编辑一个返回值处理器，在应用启动时注册一下就好：

/**
 * 我自己的返回值处理器
 */
@Component // 注册为 Spring Bean 即可
public class MyResultHandler implements IPagerResultHandler<Result<Object>> {
    // 从这个返回值中读取分页的返回值
    @Override
    public Collection<?> getData(Result<Object> result) {
        return (Collection<?>) result.getD();
    }

    // 将分页结果写入返回值中
    @Override
    public void setData(Result<Object> result, PageBody<?> pageBody) {
        result.setD(pageBody);
    }
}

/**
 * 用于测试分页的接口呢
 */
@RestController
@RequestMapping("/api/demo")
public class DemoController {
    @Autowired
    private IDemoService service;

    @Pager // 分页注解
    @GetMapping("/list")
    public Result<List<Demo>> list() {
        List<Demo> list = this.service.listAll(); // 只有一次查询
        return new Result<>(0, list); // 按照之前写代码的习惯直接返回即可
    }
}

前端响应

经过分页注解处理的接口，和未经处理的接口的响应是不太一样的

比如上面那个例子，在转成JSON向前端输出后：

// 原来的返回值
{"c":0,"d":[... list 数据 ...]}
// 增加分页注解后的返回值
{"c":0,"d":{"page":1,"totalRow":20,"totalPage":2,"listData":[... list 数据 ...]}}

可以看到，增加注解之后，原来返回值的data部分发生了改变，那么我们展开来看看吧：

{
  "c": 0,
  "d": {
    "page": 1,        // 当前查的是第几页
    "totalRow": 20,   // 总共有多少条记录
    "totalPage": 2,   // 总共有多少页
    // 在增加分页注解之前，data 部分的值
    // 虽然格式跟之前一样，但现在只查了第一页的数据～
    "listData": [... list 数据 ...]
  }
}

参数

那么，前端要如何向后端传参呢？比如我希望查询第二页该怎么做呢？

很简单，只要提供查询参数即可，目前允许前端传四个参数：

  1. page 要查询第几页，从1开始，默认为1
  2. pageSize 每页有多少条记录，默认为10
  3. export 为true时会将数据导出为Excel，响应会转为文件下载，默认为false
  4. pager 在导出模式开启时，仍然进行分页，默认为false

导出模式我们之后再提，我们现在用前两个参数就可以满足需求了

那么，我们来看看如何传递这几个参数吧：

目前有两种参数传递方式

  1. 查询字符串，即URL问号后面的部分，如对于上面的测试接口

    http://localhost:8080/api/demo/list?page=1&pageSize=10

  2. 请求头的Header，即HTTP包中第二行开始直到双换行之前的内容，如对于上面这个接口

    GET /api/demo/list HTTP/1.1
Host: localhost:8080
Page: 1
PageSize: 10

参数名冲突

你可能会说，我们的项目已经给某个参数以特殊的用途了，比如有个全局Filter会需要page这个参数

emmm 讲真这很少见，不过还是有解决方法的，只要在application.yml或application.properties增加配置即可：

pager:
  # 参数的前缀，如设置为`pager_`，则页数的参数名应为`pager_page`，默认为空字符串
  prefix: myprefix_

现在问题就解决了，前端传参时都增加这个前缀即可，比如对于page这个参数，传myprefix_page即可

跳过分页

开始我们说过，一次请求中应该只有一次查询才对，但很多时候就是需要多次查询

比如需要先查出登陆的用户的实体，读出他的手机号，然后根据手机号查询数据

这里我们可以通过跳过分页的查询来解决：

/**
 * 用于测试分页的接口呢
 */
@RestController
@RequestMapping("/api/demo")
public class DemoController {
    @Autowired
    private IDemoService service;

    @Pager // 分页注解
    @GetMapping("/list")
    public Result<List<Demo>> list() {
        // 查询当前登陆的用户，这次查询是跳过分页的
        User user = Pagers.skipPager({ this.service.queryCurrentLoginUser() });
        // 仍然只有一次查询(未跳过分页)
        List<Demo> list = this.service.listByMobile(user.getMobile());
        // 如果还有其他查询，也需要跳过分页哟～
        List<Demo2> list2 = Pagers.skipPager({ this.service.queryByDemos(list) });
        // 返回结果
        return new Result<>(0, list2);
    }
}

导出模式

有时候，我们可能需要把分页查询的结果导出成Excel给客户下载

每次都写一堆POI操作甚是繁琐，因此@Pager还增加了导出模式的支持

可以通过给@Pager注解设置export参数来开启导出模式的支持

默认提供了SimplePagerExport，可作为你的导出实现的父类，基本可以完成大部分需求场景

对了，导出类必须保证拥有公共的、无参的构造方法才可以哟～

/**
 * 用于测试分页的接口呢
 */
@RestController
@RequestMapping("/api/demo")
public class DemoController {
    @Autowired
    private IDemoService service;

    // 设置导出配置
    // filenamePrefix 为下载时文件名的前缀
    // exportColumns 为导出的 Excel 的列标题
    @Pager(export=DemoListExport.class, filenamePrefix="DemoList", exportColumns = { "字段1", "字段2" })
    @GetMapping("/list")
    public Result<List<Demo>> list() {
        List<Demo> list = this.service.listAll();
        return new Result<>(0, list);
    }

    /**
     * Demo 的导出实现
     */
    public static class DemoListExport extends SimplePagerExport<Demo> {
        @Override
        public List<?> row(Demo obj, int idx) {
            return Arrays.asList(demo.getField1(), demo.getField2());
        }
    }
}

这样，后端的工作就算完成了，而前端只需要在正常的查询时将之前提到的分页参数export设置为true即可

为了方便，通常可以在前端渲染成这样：

<a href="/api/demo/list?export=true">导出</a>

默认情况下，导出模式会将全量数据导出，不会再进行分页

如果需要继续进行分页，则可设置pager为true，并照常传分页的参数即可

注解参数

如果我们不加以限制，可能会有恶意的攻击者故意传一个很大的pageSize，服务器可能会因此当机甚至挂掉

这时我们可以用@Pager的参数来防止这种情况：

/**
 * 用于测试分页的接口呢
 */
@RestController
@RequestMapping("/api/demo")
public class DemoController {
    @Autowired
    private IDemoService service;

    // 设置 pageSize 在 1 ～ 100 之间，超出范围的会使用最接近的值
    @Pager(min = 1, max = 100)
    @GetMapping("/list")
    public Result<List<Demo>> list() {
        List<Demo> list = this.service.listAll(); // 只有一次查询
        return new Result<>(0, list); // 按照之前写代码的习惯直接返回即可
    }
}

默认情况下(未主动设置时)，min会使用1，而max会使用100

有时，前端可能会觉得每个接口都要传pageSize有些麻烦，这时可以设置df参数：

/**
 * 用于测试分页的接口呢
 */
@RestController
@RequestMapping("/api/demo")
public class DemoController {
    @Autowired
    private IDemoService service;

    // 设置如果没传 pageSize 时默认使用的 pageSize
    @Pager(df = 10)
    @GetMapping("/list")
    public Result<List<Demo>> list() {
        List<Demo> list = this.service.listAll(); // 只有一次查询
        return new Result<>(0, list); // 按照之前写代码的习惯直接返回即可
    }
}

结语

好啦，本项目目前大概就提供了这些功能呢，祝您使用愉快哟～