若依分页只支持GET？从源码到实战教你正确使用POST分页

1. 为什么那么多人误以为若依分页“只支持GET”

我最早接触若依框架（RuoYi）的时候，也犯过同样的“思维定式”：分页查询嘛，无非就是把页码和每页条数拼到 URL 上，以 GET 请求的方式发给后端。这种习惯来自若依官方文档里大量以表格查询为主的示例，比如用户管理、角色管理、菜单管理这些页面，列表数据的加载几乎清一色是 GET 请求，参数直接暴露在地址栏上。

但是真实项目里需求是五花八门的。我这边的系统里有一个“订单流水查询”页面，查询条件特别多：时间范围、订单号、客户名称、商品编码、渠道来源、支付状态、物流单号……十几个筛选字段全部加在一起，URL 能拼出很长一串。更麻烦的是部分查询场景涉及敏感信息，比如客户手机号、身份证后四位，这些东西放到 URL 上的话，会留在浏览器历史记录、Nginx 访问日志、网关日志里，从安全角度来说非常不友好。后来我改成了 POST 提交，却发现若依的通用分页好像不起作用。一时间真的以为这个框架的 PageHelper 只认 GET。

不是若依不支持 POST，而是我们没有真正理解若依分页的底层机制。打个比方，若依的分页就像一把锁，很多人只见过用钥匙开锁（GET 请求中的 pageNum/pageSize 参数），就以为这把锁只能用钥匙打开，实际上只要参数配对，门禁卡、指纹都可以解锁。HTTP 方法只是传输方式的差别，分页参数的解析在框架内部其实是和请求方式解耦的。

要摆脱这个误区，必须从若依分页的完整链路看起。下面我拆解一下相关的核心代码和参数流转过程。

2. 源码视角：若依分页的“发动机”在参数解析而非请求方式

2.1 TableDataInfo 与分页参数的默认绑定过程

若依后端的分页入口，核心是一个 BaseController 类，里面有一个 startPage() 方法，几乎所有表格查询接口都会调用它。这个方法做的事情很纯粹，就是把前端传上来的 pageNum 和 pageSize 读取出来，交给 PageHelper 去处理。

java复制protected void startPage() {
    PageDomain pageDomain = TableSupport.buildPageRequest();
    Integer pageNum = pageDomain.getPageNum();
    Integer pageSize = pageDomain.getPageSize();
    String orderBy = SqlUtil.escapeOrderBySql(pageDomain.getOrderBy());
    Boolean reasonable = pageDomain.getReasonable();
    PageHelper.startPage(pageNum, pageSize, orderBy).setReasonable(reasonable);
}

关键就在 TableSupport.buildPageRequest() 这个静态方法。它内部用了 ServletUtils.getParameter() 从 request 里取参数。ServletUtils 对 HTTP 请求的读取是没有区分 GET 还是 POST 的，Tomcat 容器把请求参数统一封装成一个参数表，不管是 query string 里的键值对，还是请求体里以 application/x-www-form-urlencoded 格式提交的键值对，在 Servlet 层面都放进了同一个 parameter map。也就是说，只要 POST 请求的 body 里带了 pageNum=1&pageSize=10 这种 URL 编码的键值对，request.getParameter("pageNum") 就能取到值。

若依源码里对请求方式确实有判断，但那个判断是用来处理“排序字段”的，而不是判断分页是否被允许。在 TableSupport.buildPageRequest() 中，它会调用 SqlUtil.filterKeyword() 清理排序相关关键字，同时处理 isAsc 这个排序方向字段。这些参数同样是从 request 的 parameter 里读的，无论 GET 还是 POST，读取路径完全一样。

2.2 PageHelper 的分页上下文生命周期

当你调用 startPage() 之后，PageHelper 会把分页参数存储在 ThreadLocal 中。这里有个很重要的机制需要理解：PageHelper 不是通过方法签名、注解或者请求类型来感知分页的，它是靠“下一次执行的 MyBatis 查询语句”来触发拦截器。

java复制PageHelper.startPage(pageNum, pageSize);
// 下一个执行的查询会被自动分页
List<YourEntity> list = yourMapper.selectYourList(query);

startPage() 和紧接着的 Mapper 查询方法之间，不需要有任何代码层面的绑定关系。只要这两步在同一个线程内执行，PageHelper 就认为你要对下一次查询做分页。所以理论上讲，无论 GET 还是 POST，只要请求进入了后端同一个线程，并在调用 Mapper 方法之前执行了 startPage()，分页一定生效。

很多人遇到的“POST 分页失效”问题，其实根本原因在自己的业务代码层面。最常见的有两种情况：第一，Controller 方法里压根没有调用 startPage()，而是自己在 Service 里直接 new 了一个分页对象来处理，绕过了若依的封装；第二，startPage() 被调用之后，在 Mapper 查询执行之前，又发生了跨方法调用、新开线程，导致 ThreadLocal 里的分页参数丢失。

2.3 为什么前端切换成 POST 后就拿不到分页数据了

再从前端角度看一眼就清楚了。若依前端的 request.js 工具类封装了 axios 实例，它的响应拦截器会判断后端返回的数据结构。若依后端的表格接口统一返回 TableDataInfo 对象，结构大致是：

json复制{
  "code": 200,
  "msg": "查询成功",
  "rows": [...],
  "total": 100
}

问题往往出现在请求头的 Content-Type 上。axios 的 GET 请求不会主动设置请求体，参数自动拼在 URL 上；POST 请求如果用默认配置，Content-Type 是 application/json;charset=UTF-8，body 里是一段 JSON 字符串。若依后端的 startPage() 依赖的是 Servlet 的 getParameter() 方法，而 getParameter() 默认只会解析两种格式：URL 里的 query string 和 content type 为 application/x-www-form-urlencoded 的请求体。请求体如果是 JSON 格式，它不会自动解析到 parameter map 中，pageNum 自然就是 null。

所以真正的误区在于：不是 POST 不被支持，而是你那一次的 POST 请求格式没有被 Servlet 容器解析。搞清楚这一点之后，解决思路就很清晰了：要么把 POST 请求的 Content-Type 改成表单格式，要么在若依框架里加一个 JSON 解析的过滤器，把 JSON body 里的分页参数解放出来。

3. 实操改造一：用表单格式的 POST 请求直接触发若依分页

3.1 最简单的方案：改造前端请求封装

如果项目里的查询条件不是特别多，或者你希望改动最小，直接把请求头格式调整一下就行。前端代码中，调用列表接口的地方原本可能是这样：

javascript复制export function listOrder(query) {
  return request({
    url: '/system/order/list',
    method: 'get',
    params: query
  })
}

改成 POST 的时候，如果只是把 method 换成 post，axios 会把数据放到请求体，并且默认使用 JSON 格式。这种写法后端读不到分页参数。正确的做法是显式指定请求头：

javascript复制export function listOrder(query) {
  return request({
    url: '/system/order/list',
    method: 'post',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    data: qs.stringify(query)
  })
}

注意 qs 工具，若依前端项目自带了 qs 依赖，在 package.json 里就能看到。qs.stringify() 会把对象转成 key1=value1&key2=value2 的字符串，这样后端 request.getParameter() 就能正常解析 pageNum、pageSize、orderByColumn、isAsc 这些分页参数。

如果你不想在每个接口函数里单独写 headers，也可以直接在 request.js 的 axios 默认配置里做调整，把 POST 请求的 Content-Type 统一改成表单格式。但要注意，这会影响所有 POST 接口，包括那些需要传 JSON 给后端的业务接口。建议在具体接口上单独配置，或者在 request.js 里写一个判断逻辑：

javascript复制// 当data是普通对象时，统一转成form-data格式
if (config.method === 'post' && typeof config.data === 'object' && !(config.data instanceof FormData)) {
  config.data = qs.stringify(config.data)
  config.headers['Content-Type'] = 'application/x-www-form-urlencoded'
}

3.2 后端无需任何修改，但要注意参数命名

使用表单 POST 请求，后端代码可以原封不动。startPage() 能拿到 pageNum 和 pageSize，TableDataInfo 的封装也正常。唯一要提醒的是，表单方式传参的时候参数名必须严格对齐：pageNum、pageSize、orderByColumn、isAsc。如果你在前端用了别的别名，比如 page、limit，那后端照样拿不到。

若依的 PageDomain 类源码里定义了这些字段名，前端封装的 TableQuery 对象在拼参数时也是用的这些名字，所以一般情况下不会出错。但有的团队会封装二次分页组件，统一把页码字段名改成 pageNumber、pageSize 之类的，这时表单 POST 请求就会失效，必须自己去继承 BaseController 并重写 startPage()，或者定义一个自定义的分页参数解析器。

3.3 实测结果参考

我在本地用若依前后端分离版 3.8.5 做过测试，写了一个订单流水查询接口，查询条件有八个字段。用表单格式 POST 提交，后端打印日志能看到分页 SQL 正常拦截：

text复制==>  Preparing: SELECT * FROM order_info WHERE order_no LIKE ? AND customer_name LIKE ? LIMIT ?
==> Parameters: %SO20231128%(String), %张三%(String), 10(Long)

total 数量也正确返回了。事实证明，只要请求体可被 Servlet 解析，GET 和 POST 在使用层面没有差别。这个方案改动量最小，适合大部分中小型项目。

4. 实操改造二：让若依支持 JSON 格式的 POST 分页请求

4.1 需求场景：为什么表单格式在某些场合不够用

如果查询条件很多，比如超过十个字段，并且前端统一使用了 application/json 格式提交，那表单方案的兼容性就不够了。另外有人可能用了若依微服务版本，各服务之间的调用有时候需要直接传 JSON 体，这时候也没法保证 Content-Type 是表单。

这种情况下，我的做法是在若依的后端加一个参数解析过滤器，专门处理 JSON 请求体里的分页参数。思路并不复杂：拦截进入 Controller 的请求，提前读取 body 中的 JSON 字符串，把 pageNum、pageSize 等参数取出来，重新塞回 request 的 parameter map 中。这样前端就可以直接以 JSON 格式 POST，后端 startPage() 依然能通过 TableSupport.buildPageRequest() 拿到分页参数。

4.2 实现一个可复用的请求包装过滤器

以若依前后端分离版为例，我新增了一个过滤器类 JsonServletRequestWrapper，它继承了 HttpServletRequestWrapper，核心逻辑是重写 getParameter() 方法。实现的关键点在于：

• 过滤器读取 body 时，要注意 body 只能读一次。因为 Controller 层还要再读 body 里的业务参数，所以必须用 ContentCachingRequestWrapper 或者自定义的包装类把 body 缓存下来。
• 读取 JSON 时只提取参数层级的字段，不要递归解析所有嵌套对象。分页参数都是顶级字段。
• 把解析出来的参数放入一个合并的 Map 中，优先保留原 request 里的 URL 参数，再塞入 body 中的 JSON 字段，避免覆盖。

下面是一个参考实现：

java复制public class JsonPageParamRequestWrapper extends HttpServletRequestWrapper {

    private final Map<String, String[]> params = new HashMap<>();

    public JsonPageParamRequestWrapper(HttpServletRequest request) throws IOException {
        super(request);
        // 保留原始参数（URL上的query string）
        this.params.putAll(request.getParameterMap());

        // 读取body中的JSON
        String body = StreamUtils.copyToString(request.getInputStream(), StandardCharsets.UTF_8);
        if (StringUtils.isNotBlank(body)) {
            JSONObject jsonObject = JSON.parseObject(body);
            if (jsonObject != null) {
                for (String key : jsonObject.keySet()) {
                    Object value = jsonObject.get(key);
                    if (value == null) continue;
                    if (value instanceof JSONArray) {
                        JSONArray array = (JSONArray) value;
                        String[] values = array.toArray(new String[0]);
                        params.put(key, values);
                    } else {
                        params.put(key, new String[]{String.valueOf(value)});
                    }
                }
            }
        }
    }

    @Override
    public String getParameter(String name) {
        String[] values = params.get(name);
        if (values != null && values.length > 0) {
            return values[0];
        }
        return null;
    }

    @Override
    public Map<String, String[]> getParameterMap() {
        return params;
    }
}

4.3 过滤器配置和注意事项

过滤器注册位置很重要。它必须在若依原有的 XssFilter 之前或者提前读取 body，因为若依 XSS 过滤器也会对 body 做包装，如果配置顺序不对，body 流被提前消费掉，后续 Controller 的 @RequestBody 会拿到空值。

我在若依的 FilterConfig 配置类里注册了这个过滤器，设置 urlPatterns 为 /*，并指定 order 为最高优先级。这样 JSON body 里的分页参数能被提前提取，同时业务参数也能正常流转到 @RequestBody 里。

还要注意一个问题：如果不想让所有 JSON 请求都被解析一遍，可以提高过滤器效率，也可以只在特定路径下生效。我的建议是做一个可配置的路径匹配，比如只对 /*/list 或以 *.list 结尾的接口启用，这样减少无谓的 body 读取。

4.4 前端使用 JSON 格式 POST 的效果

过滤器一旦生效，前端代码就回到了最自然的写法：

javascript复制export function listOrder(query) {
  return request({
    url: '/system/order/list',
    method: 'post',
    data: query
  })
}

axios 默认的 Content-Type 就是 JSON，直接传对象就行，无需 qs.stringify()。后端 Controller 里照常使用 startPage()，数据直接返回，不需要任何改动。

我在实际项目中采用的就是这个思路。前端页面里所有表格查询接口全部改成 JSON POST，查询条件再多再长都没问题，URL 不再被拉成长线，Nginx 日志里也不会出现客户手机号了。分页依然正常。唯一要留意的是性能损耗，每次请求多了一步 body 读取和 JSON 解析，但这个开销对于内部管理系统的请求量来说完全可以忽略。

5. 若依分页 POST 化之后容易踩的隐藏坑

5.1 排序参数丢失导致表格默认排序失效

很多项目里表格有默认排序逻辑，比如按创建时间倒序。若依前端封装的 table 组件在加载数据时会自动带上 orderByColumn 和 isAsc 这两个参数。POST 化之后，如果前端调整了请求封装但漏掉这两个参数，后端排序就会失效，数据顺序变得诡异。

排查方法：在浏览器 Network 面板看请求体里有没有 orderByColumn 和 isAsc 字段。如果没有，要去 table 初始化配置里检查 defaultSort 或者 queryParams 是否被覆盖。我之前踩过这个坑，前端同事封装请求时图省事，只留了 pageNum 和 pageSize，结果列表数据一直是乱的，查了半天才发现是 orderByColumn 丢失。

5.2 参数名大小写与 Spring 绑定问题

POST 请求如果是表单格式，getParameter() 是不区分大小写的，但 Spring MVC 在绑定 PageDomain 时，属性名是驼峰命名法，比如 orderByColumn 对应成员变量 orderByColumn。如果你传的 JSON 里写的是 orderbycolumn 或 order_by_column，要么映射不上，要么被当成 null。

有一种情况很容易被忽略：若依的前端表格组件在某些版本里生成的排序参数是 orderByColumn，但是查询条件对象里如果写了 orderBy 这种自定义字段，就不会被 PageDomain 接收。你需要检查后端 TableSupport.buildPageRequest() 到底从 getParameter("orderByColumn") 还是 getParameter("orderBy") 里取值，不同若依版本可能略有差异。

5.3 自定义 Controller 没有走 BaseController.startPage()

若依的代码生成器生成的 Controller 默认继承 BaseController，但很多开发者会自己手写 Controller，可能继承的是别的基类，或者干脆直接 implements 接口。在这样的类里如果调用 PageHelper.startPage() 的姿势不对，POST 分页同样不生效。

一个经常出问题的写法是：

java复制@PostMapping("/list")
public TableDataInfo list(@RequestBody YourQuery query) {
    YourQuery target = new YourQuery();
    BeanUtils.copyProperties(query, target);
    // 这里忘了调用 startPage()
    startPage();
    List<YourEntity> list = yourService.selectList(target);
    return getDataTable(list);
}

看起来没什么问题，但 startPage() 必须在 Mapper 查询之前调用，而且和查询必须发生在同一个线程。如果你在 Service 里用了异步线程池、或者用 @Async 注解，分页就会失效。这个和请求方式无关，但 POST 化之后更容易暴露，因为改造成本低，很多人开始重构查询接口，一重构就把原有链路搞复杂了。

5.4 使用了 MyBatis-Plus 时的分页插件冲突

若依本身用的是 PageHelper，但有些项目在集成 MyBatis-Plus 后会同时引入分页插件 PaginationInnerInterceptor。两个分页插件同时存在，会发生拦截器顺序竞争，导致分页结果混乱。和 POST 请求没有直接关系，但在排查 POST 分页失效时容易误判。

我的建议是：若依项目里如果要用 MyBatis-Plus 的 selectPage，就不要再额外调用若依的 startPage() 了。两者选其一，不要混用。如果非要用 MyBatis-Plus 的内置分页，可以直接自己写分页查询，不用走 BaseController 的通用方法。

6. 几个容易忽略的参数传递细节

6.1 表单 POST 与 JSON POST 在 Servlet 层面的本质差异

表格对比一下更直观：

补参数加载请求为 GET 请求时，如果 URL 里携带中文参数，浏览器会自动进行百分号编码，后端 Tomcat 默认使用 UTF-8 解码，一般不会乱码。表单 POST 和 JSON POST 也是同理，只要项目里配置了 CharacterEncodingFilter，基本不存在乱码问题。若依自带了这个配置，不用担心。

6.2 关于 axios 的 params 和 data 混用问题

如果你在前端把 GET 改成 POST，但保留了 params: query 的写法，并且同时写了一个空的 data: {}，后果是分页参数全在 URL 上，请求体为空。后端 getParameter() 能取到参数吗？能。这其实也算一种可用的方式，但多此一举不是重点，重点是如果查询条件较多，URL 会变得很长，最终可能超过服务器默认的最大 URL 长度限制，返回 414 错误。这种情况不是若依的问题，是 Nginx 和 Tomcat 的限制。所以从工程角度出发，查询条件多的时候直接用 POST，并且把所有参数放在 body 里最稳妥。

6.3 其他后端语言的若依版本注意点

若依除了 Java 前后端分离版，还有若依 Spring Boot 单体版、若依微服务版、Python 版本。Python 版若依底层用的是 Flask/Django 类框架，分页参数解析逻辑和 Java 版不同，POST 请求天然支持 JSON。如果你用的是微服务版本，里面网关层的参数透传、Token 校验可能会影响请求体的读取，排查分页失效时需要同时关注网关层是否有 body 缓存。

7. 从我项目里总结的分页 POST 改造建议

首先建议团队统一规范：查询条件超过五个字段的接口，统一使用 POST；普通下拉框、单选默认为 GET，保持和若依默认逻辑一致。这样可以避免所有查询接口都 POST 化带来的不必要改动，也能降低排查成本。

其次是前端封装层面，建议在 request.js 里增加一个自定义配置项，比如 isPageQuery 或者 method: 'postForm'，根据这个配置自动决定使用表单格式还是 JSON 格式。若依封装良好的话，页面组件不用改，只需要在列表接口函数里多加一个参数，可维护性会好很多。

我个人的实践结论是：若依分页本身完全没有绑定 GET，它只关心 pageNum、pageSize、orderByColumn、isAsc 这四个参数能否在 startPage() 执行时被正确读取。把这个底层逻辑想通了，POST 分页就只是一个参数传递形式问题。

最后分享一个排错技巧：遇到 POST 分页失效，先在浏览器 Network 面板里查看请求的 Content-Type 和请求体格式。如果 Content-Type 是 JSON，你要么改表单格式，要么用上面的自定义包装类方案。如果 Content-Type 是表单格式但分页仍失效，后端打一个断点，看 TableSupport.buildPageRequest() 取到的 pageNum 是不是 null。只要这一行判断对了，90% 的问题都能定位。