调若依（RuoYi）接口时，你大概率碰过这种怪事：浏览器里页面一切正常，一改用 Postman 或 Apifox 调试，URL 明明是对的，Params 标签里也老老实实填了一堆键值对，点发送后后端 Controller 里的变量要么是 null，要么查出来的数据怎么都不对。上周我在若依微服务版本的接口联调中又遇到一次，排查下来发现“params 传不上去”这个说法其实是个大箩筐，里面装了至少四种完全不同的故障，处理方式也截然不同。这篇文章不绕弯子，直接把我踩过的坑和排查思路完整捋一遍，给正在拿若依做二次开发、或者刚从前端转手调试接口的同学做个参考。
这里先统一口径：我所说的 params，既包括 Postman/Apifox 工具栏里的 Params 标签（也就是 URL Query 参数），也包括若依前端 axios 请求里 config.params 那个对象。两者本质是一回事，最终都会变成 URL 问号后面的键值对。
1. 问题发生的四个现场：先搞清“传不上去”死在哪一环
我见过太多人一上来就改后端代码，改来改去发现根本不是代码的事。所以别急着动手，先判断你属于下面哪一类现场。不同现场，根因和解决方案完全不在一个层面。
1.1 现场一：请求发出去了，但后端直接 401/403
这是最容易被误会成“params 没传上去”的情况。事实上参数传没传，后端压根没机会看到，因为请求在进入 Controller 之前就被若依的安全拦截器拦住了。
如果你用的是若依单体版（RuoYi-Vue / RuoYi单体），默认走的是 Spring Security。未登录状态下，除了登录接口、验证码接口等白名单路径外，其他接口全部会被拦截并返回 JSON：{code: 401, msg: "认证失败，无法访问系统资源"}。如果你在浏览器里调试正常，换到 Postman 就报这个错，不用怀疑，就是没带登录凭证。
若依前端请求时会把 Token 放在请求头里：
// 若依前后端分离版 request.js 中的核心逻辑 const service = axios.create({ baseURL: process.env.VUE_APP_BASE_API, timeout: 10000 }) service.interceptors.request.use(config => { if (getToken()) { config.headers['Authorization'] = 'Bearer ' + getToken() } return config })浏览器里能调通，是因为前端页面早就通过登录接口拿到了 token，并且保存在 localStorage 中，axios 拦截器自动带上。而 Postman/Apifox 是全新环境，token 不存在，自然被拦。解决办法不是研究 params，而是先登录拿 token，并在请求头里加上Authorization: Bearer <token>。
如果你用的是若依微服务 Plus 或其他基于 Sa-Token 的版本，情况类似，只是 Token 名称和认证头写法可能略有不同，具体以你手上的项目代码为准，全局搜一下获取请求头的工具类就能找到。
1.2 现场二：请求正常通过，但 Controller 里参数全是 null
这个现场最常见，也最迷惑人。接口返回 200，页面有响应体，但查出来的数据是空的，或者分页数据显示的不是你想查的那一页。打开后端日志一看，Controller 方法里的实体对象字段全是默认值。
这种情况说明请求已经杀进 Controller 了，问题出在 Spring MVC 把 URL 上的参数绑定到方法参数时，名字没对上。注意：Spring MVC 的查询参数绑定是对大小写敏感的，不像 MySQL 字段那样默认不区分大小写。你传username，后端实体字段是userName，绑定就失败，属性保持 null。
我在接手一个若依 MES 项目时就遇到过：接口文档里写的是username，但若依的SysUser实体字段叫userName，前端开发照着文档传参，后端收不到，查出来永远是一张空表。这个坑不踩一次，真的很难想到是大小写问题。
1.3 现场三：GET 请求把参数塞进了 Body
还有一类经典错误是把 GET 请求的查询参数写在 Body 里，尤其是从 POST 请求改过来的时候容易犯。Postman 和 Apifox 都支持 GET 请求带 Body，但 Spring MVC 默认不解析 GET 请求的 Body 内容，你写一堆 JSON 或者 form-data 进去，后端根本不会读。
如果你在 Apifox 里看到参数填在了 Body 标签下，而接口是 GET 方法，请把这些参数剪切到 Params 标签下。这是操作层面的问题，不是代码问题。
1.4 现场四：状态码 404，路径压根不对
这种情况通常和若依前端的代理前缀有关。若依前端默认 baseURL 是/prod-api，开发环境通过 vite/webpack 代理转发到后端 8080 端口。你在后端地址上直接访问http://localhost:8080/prod-api/system/user/list，但若依后端的 Controller 实际路径是/system/user/list，没有/prod-api前缀，自然 404。
在 Postman 或 Apifox 中调试若依后端接口时，建议直接使用后端真实地址，例如http://localhost:8080/system/user/list，而不是前端拼接后的地址。如果你必须测试带代理前缀的地址，请确认代理转发规则，别让 404 耽误半小时。
2. 若依后端到底靠什么接收 params 参数：从 URL 到实体对象
搞清楚故障现场之后，必须回到本质：若依后端接参的机制到底是什么。只有理解了这条路，你才能判断 params 到底该长什么样。
2.1 Spring MVC 的 GET 查询参数绑定规则
Spring MVC 处理 GET 请求查询参数时，可以根据 Controller 方法签名做多种绑定。最基础的是@RequestParam，它明确规定 URL 上的某个 key 对应某个变量。但若依的大多数查询接口并不这么写，而是直接传实体对象。举个例子，若依用户管理列表接口的典型写法：
@GetMapping("/list") public TableDataInfo list(SysUser user) { startPage(); List<SysUser> list = userService.selectUserList(user); return getDataTable(list); }注意，这个方法没有@RequestParam("userName") String userName这种写法，而是直接声明一个SysUser user实体对象。Spring MVC 拿到 URL 查询参数后，会自动把所有 key 按名字映射到SysUser的字段上。换句话说，你在 params 里写的 key，必须和SysUser实体类的字段名完全一致，才能被塞进对象的属性里。
我在第二节里会放一张对照表，但先强调一个核心结论：若依后端实体接参不关心你传了几个参数，只关心你传的 key 叫不叫得出实体属性的名字。传对了，一个字段都不会漏；传错了，后端也无能为力，不会报错，只是静默地保持 null。
2.2 完整链路：params → URL → Server → Controller
为了让你把整条链路刻进脑子，我把它拆成四步：
- Postman/Apifox 里的 Params 标签维护键值对，点击发送后拼接成 URL 的 query string，例如
?pageNum=1&pageSize=10&userName=admin。 - 后端应用服务器（Tomcat/Jetty）收到 HTTP 请求，解析 URL，把 query string 存入请求对象。
- Spring MVC 的前端控制器（DispatcherServlet）根据请求路径找到对应 Controller 方法。
- Spring MVC 的
DataBinder尝试把 query string 中的键值对映射到方法参数对象上。
这四步中，最容易出问题的是第 4 步，因为它涉及反射和属性名的匹配规则。如果中间有任何一步心态不稳，你看到的表象都是“params 没传上去”，但实际原因千差万别。所以我强烈建议，遇到这类问题别直接改代码，先把链路拆开逐段排查。
2.3 分页参数为什么“消失了”：被 PageQuery 夹层吃掉
还有一个高频困惑：params 里明明传了pageNum=2&pageSize=20，为什么返回结果一直是第一页？或者为什么第二页的数据和第一页一样？
若依的分页逻辑并没有写在 Controller 方法参数里，而是通过startPage()这个方法从当前请求中直接读取分页参数。startPage()内部会从请求对象中取出pageNum、pageSize、orderByColumn、isAsc这四个参数，存入线程变量，随后 PageHelper 拦截器会接管 SQL 分页。
也就是说，即便你的 Controller 方法没有显示声明分页参数，只要 URL 上有pageNum和pageSize，它们也会被startPage()捡走。这时候有两个容易踩的坑：
- 参数名写错。比如写成
page、size、pagesize，startPage()读不到，就用了默认值，导致分页不生效。 - 排序参数写错。若依默认读取
orderByColumn和isAsc，如果你传的是sort、order，排序不会生效，数据看起来乱序。
所以排查 params 问题时，别只盯业务字段，分页字段同样需要验证。最快捷的办法，就是把pageNum和pageSize单独测一次，不带任何业务参数，看看返回的数据量和页码是否按预期变化。
3. Postman 与 Apifox 中 params 参数的正确打开方式
工具层面也有不少门道。很多人以为 Params 标签就是无脑填 key-value，其实里面藏着几个容易出问题的动作。
3.1 Params 标签、Query String、URL 三者的关系
本质上，Postman/Apifox 的 Params 标签是帮你维护 query string 的可视化工具。你点一下发送，它会把 Params 里的键值对拼接到 URL 问号后面。所以你既可以手工在地址栏里写?userName=admin，也可以在 Params 里填userName: admin，效果完全一样。
但要注意，如果你既在地址栏手写了参数，又在 Params 里填了同名参数，工具通常会把两个都带上，最终 URL 里会出现重复的 key。后端拿到这种请求时，取决于服务器解析规则，可能取第一个值，也可能取最后一个值，行为不可预测。我建议只选一种方式，尽量统一用 Params 标签维护，不要让地址栏和 Params 混着写。
Apifox 中还有一个细节：它会把参数自动分组成 query、path、header、cookie 等类型。如果你在 Apifox 里创建接口时，不小心把参数类型设成了 path，那么发送时参数不会出现在 URL query 部分，而是试图替换 URL 里的{}占位符。若依后端接口的路径参数一般用@PathVariable接收，比如/system/user/{userId}，如果你把参数类型搞混，后端同样收不到。
3.2 参数名对齐：字段名、驼峰和下划线的一次无声教训
这一节我要给出一份基于若依常见实体字段的对照表，你可以直接照抄检查。这是我踩过坑后的经验总结：
| 若依实体字段 | 正确传参 key | 容易写错的样子 |
|---|---|---|
| userName | userName | username、name、user_name |
| nickName | nickName | nickname、昵称 |
| phonenumber | phonenumber | phone、phoneNumber |
| status | status | state、isStatus |
| deptId | deptId | dept_id、departmentId |
| params[beginTime] | params[beginTime] | beginTime |
最后一行特别说下：若依的时间范围查询，通常用的是params[beginTime]和params[endTime]。这是一种嵌套参数写法，Spring MVC 会把params[beginTime]映射到SysUser对象中名为params的 Map 属性的beginTime键上。如果你在 Postman 里直接填beginTime=2023-01-01，后端也不会报错，但查询条件不会带上。
遇到这种带中括号的 key，在 Apifox / Postman 里直接原样填就行，工具会做 URL 编码，不会把中括号弄丢。
3.3 Content-Type 与编码：中文和特殊字符怎么处理
GET 请求的参数都经过 URL 编码。你填了一个中文参数“张三”，工具会自动编码成%E5%BC%A0%E4%B8%89。这本来不是问题，但如果你习惯在地址栏手工粘贴 URL，很容易粘到未编码的中文，后端可能收到乱码，导致查询结果为空。
另外，若依后端可能配置了 XSS 过滤器，会在参数进入 Controller 之前做过滤。虽然这不会导致参数消失，但如果参数值里带了特殊字符（比如<script>片段），就会被过滤掉。调试带特殊字符的查询条件时，可以先换个普通词验证，确认基础链路没问题，再去排查过滤规则。
Content-Type 方面，GET 请求一般不需要手动设置。如果你之前测试 POST 接口时切换到了application/json，改回 GET 请求时注意 Body 要选none。很多工具会在切换方法时保留 Body 配置，导致参数重复出现在不同位置，结果后端一个都吃不到。
4. 若依框架暗处的三道拦截：token、XSS 和请求头
你以为 params 只要填对了，后端就一定能收到吗？未必。在进入 Controller 之前，若依框架还藏着几道拦截，它们不关心你的参数叫什么名字，但会直接决定你的请求能不能活着走到参数绑定那一步。
4.1 Authorization 头缺失引发的全盘拒绝
这个问题我在前面提到了，这里再展开一下操作细节。在 Postman 或 Apifox 中调试若依接口，建议先调用登录接口：
POST http://localhost:8080/login Content-Type: application/json { "username": "admin", "password": "admin123" }登录成功后，响应体里会返回 token 字段。把它复制出来，在 Apifox 中设置一个环境变量token，然后在具体请求的 Authorization 标签页选择 Bearer Token，值为{{token}}。这样你后续测试的每个接口都会自动带上认证头，不会出现“参数传了但接口报 401”的错觉。
如果你用的是若依微服务版本，网关层还会做 token 解析与用户信息透传，有时候 params 里需要额外带上租户信息或客户端标识。这种情况建议先看网关的过滤器代码，确认最终转发到后端服务上的请求头需要哪些字段。别照着单体版的习惯盲目调试。
4.2 XSS 过滤器对参数值的清剿
若依框架自带一个 XSS 过滤器，默认会拦截常见脚本关键字。它处理的是参数值，不是参数名，所以通常不会让你“收不到参数”，但可能让参数值发生变化。比如你传一个<script>标签，过滤器会将其替换为空字符。
这个坑主要在调试富文本搜索、或者输入包含特殊符号的内容时暴露出来。遇到查询结果不对，而你已经确认参数名无误时，可以留意一下过滤器的配置。若依的 XSS 过滤器支持通过注解@Xss跳过校验，但生产环境不建议轻易关闭。调试阶段如果非要验证，可以在 Control方法上临时加个白名单路由，测完再恢复。
4.3 若依 Plus 的签名校验：params 数组是如何被规整的
如果你用的是若依 Plus（RuoYi-Vue-Plus）这类功能增强版，可能还会多一道签名拦截。部分版本在网关或独立服务上配置了请求签名校验，要求请求头携带时间戳、随机数、签名值。签名规则一般会按参数名排序再拼接字符串做哈希。这种情况下，你手动在 params 里填的参数，会先被签名工具重新排序，如果签名不匹配，请求直接失败，你根本看不到“参数到底进没进去”。
判断项目是否开启了签名校验的办法很简单：登录后随便调一个查询接口，看响应体是不是提示签名错误或非法请求。如果是，优先去项目里搜sign、requestSign、overall之类的配置项，要么在开发环境关闭，要么写个脚本动态生成签名。我在实际项目中更推荐先关掉签名，把接口业务调通，再单独做签名组的自动化测试。
5. 完整排错链路：从 Apifox 传参失败到定位代码的真实过程
前面都是知识点罗列，这一节我拿出一个真实排查过程，帮你把这些知识点串成一条可复用的症状排查链路。这个方法我用了很多年，至今没有失手过。
5.1 Step1：确认请求真的到达了后端
场景复现：我用 Apifox 请求若依用户列表接口，URL 是http://localhost:8080/system/user/list，Params 里填了pageNum=1、pageSize=10、userName=admin，发送后接口返回 200，但 data 是空数组。
第一步不是看参数，而是确认请求到达后端。最快的方式是看后端控制台是否有请求日志。若依的后端一般配置了 access log 或者全局日志拦截器，如果控制台里能看到请求 URL 和参数打印，说明请求进入了应用；如果什么都没打印，先解决路由问题。
这里有一个实用技巧：在浏览器里直接访问同一个 URL，如果浏览器能返回数据，Apifox 不行，大概率是请求头或身份认证差异；如果浏览器也返回空数组，那就是查询条件本身的问题，和工具无关。
5.2 Step2：用日志验证 Controller 方法的入参
确认请求到达后端后，在对应 Controller 方法入口临时加一行日志打印，把收到的实体对象打出来：
@GetMapping("/list") public TableDataInfo list(SysUser user) { System.out.println("收到的查询条件：" + user); startPage(); List<SysUser> list = userService.selectUserList(user); return getDataTable(list); }如果你不想改动业务代码，也可以加一个临时专用的调试接口，一次性打印所有请求参数：
@GetMapping("/test/params") public Map<String, String> testParams(@RequestParam Map<String, String> params) { return params; }然后用 Apifox 把原来的参数原样发到这个/test/params接口上。这个接口会原样返回后端实际收到的 key-value 集合。如果返回里没有userName，说明 URL 拼接或参数名有问题；如果有userName，说明后端接收没问题，问题在实体绑定或业务查询逻辑。
5.3 Step3：判断是参数名问题还是业务问题
我在实际排错中，90% 的情况都卡在参数名不匹配。那次 MES 项目的经历就是一个标准案例：Apifox 里传了username=admin，后端/test/params返回了username: admin，说明后端收到了；但 Controller 里的SysUser user.name是空的。我检查了实体字段，发现字段是userName，于是把 Params 里的username改成userName，问题瞬间解决。
如果你排除了参数名问题，下一步检查业务层。若依的selectUserList会构建动态 SQL，可能因为空对象导致查询条件压根没拼进 WHERE 子句。比如你传了status=0，但实体里 status 是 Integer，若依的 MyBatis 映射可能在类型转换时把 0 当成了默认值处理。这种情况需要看 XML 里的 SQL 判断条件是否用了<if test="status != null">，以及传入值的类型是否和字段匹配。
5.4 Step4：完整的状态码-原因对照表
最后给你一张速查表，以后遇到类似问题可以先按这个思路对号入座：
| 现象 | 大概率原因 | 第一排查动作 |
|---|---|---|
| 401 / 认证失败 | 未携带 token 或 token 过期 | 登录获取 token，加 Authorization 头 |
| 403 / 无权限 | 当前用户角色无权访问该接口 | 检查用户权限、字典配置 |
| 404 | 访问路径错误或缺少代理前缀 | 确认后端真实路径，去除 /prod-api 前缀 |
| 200 但 data 为空 | 参数绑定失败或查询条件无结果 | 用/test/params接口验证参数名 |
| 200 但数据一直是第一页 | pageNum/pageSize 名字不对或未读取 | 检查分页参数名，确认 startPage() 逻辑 |
| 参数值乱码 | 中文未编码或编码不一致 | 使用工具 Params 标签自动编码 |
6. 我调试若依接口的一个小习惯：先打底、再加料、最后找拦截器
最后分享一个我自己的调试顺序习惯，它帮我节省的时间远比想象中多。
我现在调试任何若依接口，都不急着一次性把所有参数填满，而是先发一个最小请求：只带pageNum=1&pageSize=10，不带任何业务条件。这一步是验证基础链路——路由、认证、分页、SQL 是否都正常。如果最小请求都通不过，那就不是 params 的问题，而是系统部署、配置或者权限的问题，得先去解决这些底层问题。
最小请求跑通之后，我会逐个添加业务参数。每加一个参数就发送一次，看到哪一次开始返回结果不对，问题就锁定在刚添加的那个参数上。这样把“是否传参失败”的定位范围缩得极小，不至于混淆多个因素的叠加影响。
如果参数名确认无误，但结果仍然异常，我才会去翻拦截器、过滤器、签名校验这些暗处的逻辑。排查顺序永远是从外到内：工具操作 -> 网络路径 -> 后端接收 -> 参数绑定 -> 业务处理。颠倒顺序，只会自己给自己挖坑。
这套流程不仅适用于若依，也适用于绝大多数 Spring Boot 后端的接口调试。希望这些经验能帮你少走几步弯路，下次再有人在群里问“Postman 上 params 传不上去”，你也能拿出这篇文章的思路替他快速定位问题。
