前后端接口联调工具箱：五个常被一起用的工具
上周三下午，组里的前端跑过来找我。他调一个新上线的订单接口，浏览器里看到响应是 401，但他「明明已经登录了」。更怪的是，同样请求在 Postman 里能拿到数据，换到浏览器就挂。
打开 Network 面板，问题一堆：响应体是一坨没换行的 JSON，看不出结构；Authorization 里带的是 Bearer Token，不知道有没有过期；payload 里的下单时间是 13 位数字，跟数据库对不上；返回码一会儿 401 一会儿 200；请求参数里还塞了中文，URL 里一堆 %E4。
联调最常见的局面就是这样：一堆症状混在一起，分不清哪个是因哪个是果。这时候硬盯 Network 没用，得顺着一条动线把它们拆开。下面是那天我陪他走下来用到的五个工具，每个解决一个具体的小问题。
先把响应体展开，看清楚结构
第一个动作永远是格式化响应体。订单接口返回的是压缩过的一行 JSON，肉眼根本看不出嵌套。data.items[0].coupon 这种路径，不格式化你都不知道 coupon 在 items 数组里还是 data 同级。
最快的办法是把响应体整段复制，丢进 JSON 格式化工具。点一下美化，缩进、层级全亮出来。那天格式化完才发现，响应体里压根没有 coupon 字段，前端在代码里取了一个不存在的 key，界面那个「优惠券」位置当然一直空白。
顺带一个技巧：工具报错就说明响应体不是合法 JSON，多半是后端在 JSON 外面包了 HTML 错误页，或者中间件塞了调试日志。比如 Unexpected token < at position 0，position 0 是 <，说明返回的是 HTML 不是 JSON，先去看响应头的 Content-Type。
鉴权字段有问题，去解析 Token
401 是最先暴露的症状。前端坚持自己登录了，我让他把请求头里 Authorization: Bearer 后面那串 token 复制出来，粘到 JWT 解析工具 里。
一眼看出问题：Payload 里 exp 对应的时间是当天上午 10 点 12 分，而当时已经下午 3 点。token 早过期了。
为什么 Postman 能通？因为他 Postman 里贴的是一小时前手动复制的新 token，浏览器里用的是 localStorage 缓存的旧 token，axios 拦截器没走 refresh 分支。这么个小问题，被「我明明登录了」遮了一个小时。
JWT 的 Header 和 Payload 是 Base64URL 编码，不是加密，粘进工具就能看到 sub、exp、iat 这些字段。联调鉴权时先看两件事：exp 有没有过期；Payload 里有没有后端期望的字段（角色、租户 ID）。改完刷新逻辑，401 消失。
时间字段对不上，把时间戳还原成可读时间
接下来前端指着 createTime 说数据不对。数据库里这条订单 2023 年 11 月下单，响应里却显示 2024 年。
后端返回的 createTime 是 1700000000000，13 位毫秒级。前端代码里有个地方写成了 new Date(createTime / 1000)，把已经是毫秒的值又除了一次 1000，时间往前推了 27 年多。我把这串数字丢进 时间戳转换工具，它同时给出秒级和毫秒级两种结果，以及本地时间和 UTC，对齐基准一看就清楚。
13 位和 10 位的坑比想象中常见：后端 Java 默认出毫秒，前端 JS 也默认毫秒，但凡中间串了任何 Python、Go、C 的服务，就可能在某一处丢三位 0。遇到时间字段对不上，别在脑子里反复算，直接丢进工具换算。
状态码看不懂，查一下含义
真正让人头大的是返回码。同一个接口，第一次请求 401（token 过期那个），换 token 后 200，但有个管理后台子接口返回 403。前端一脸懵：我都是登录的同一个账号，为什么这个能调那个不能调？
具体场景里没人记得全 401 和 403 的区别。我把 403 输进 HTTP 状态码查询，工具给出含义、分类和排查建议：403 是「已认证但无权限」，问题在角色策略而不是凭证。顺着这个方向查，果然是后端给这个账号配的角色里少了「订单管理」这一项。如果当时按 401 的思路去查 token，能查一下午。
顺带提一句 5xx。联调时偶尔遇到 502、504，前端第一反应经常是「我代码错了」。其实 5xx 全是服务端的锅：502 是网关收到了上游的无效响应（上游进程挂了），504 是网关等上游超时了（慢查询卡住）。看到这两个码，直接找后端看日志。
参数里带中文，确认百分号编码
最后一个小问题。订单搜索接口接一个 keyword 参数，前端传「优惠券」，后端死活查不到。打开请求 URL，看到 keyword=%E4%BC%98%E6%83%A0%E5%88%B8。
把这段编码粘进 URL 编码解码工具，点解码出来「优惠券」，再点编码得回原样，跟请求里的一致。说明编码没问题，问题在后端的搜索逻辑。
但排查过程中发现另一个坑：前端代码里有个地方用了 encodeURI 编码 keyword，而不是 encodeURIComponent。如果 keyword 里带了 & 或 =（比如搜「a&b」），encodeURI 不会编码这两个字符，服务端就会把参数切成两段。这是 URL 编码最常见的坑：参数值用 encodeURIComponent，整条 URL 才用 encodeURI，两者不能混。
一条动线，五个工具
回头看这次联调，五个工具按排查顺序登场：JSON 格式化看清结构，解析 JWT 看 exp 过没过期，时间戳工具换算秒级毫秒级，查状态码含义确认方向，URL 编解码核对百分号编码。五个工具本地运算，不传数据，放在书签里随用随开。
联调的本质是把一团乱麻按一条动线拆成小问题，每一步用对工具，症状自然就分清楚了。下次再遇到接口「返回 401 但数据对不上」，按这条链路走一遍，多半比硬盯 Network 面板快。
相关文章