🤝 理想中的联调：插头与插座的完美契合
在项目经理的甘特图里，联调是这样的：
| 动作 | 时间 | 描述 |
|---|---|---|
| 后端开发 | 3 天 | 写好逻辑，暴露接口，提供文档（Swagger/YApi）。 |
| 前端开发 | 3 天 | 画好页面，根据文档写好调用逻辑。 |
| 联调 | 0.5 天 | 前端连上后端，数据完美展示，收工。 |
现实是：
这 0.5 天最后变成了5 天。
而且这 5 天里，空气中弥漫着：“是你代码写错了”、“不，是你参数传错了”、“文档明明不是这么写的”的怒吼。
🕵️♂️ 第一关：文档是“仅供参考”的诈骗
联调的第一分钟，通常是从400 Bad Request（参数错误）开始的。
场景：
前端盯着屏幕：“我完全按照文档传的参数，为什么报错？”
后端盯着屏幕：“我后台收到的参数是空的，你怎么传的？”
抓包破案：
- 大小写陷阱：
- 文档：
userId - 后端代码：
user_id（后端习惯蛇形命名） - 前端代码：
userid（前端手滑了） - 结果：三方都不一致，谁也别想通。
- 类型诈骗：
- 文档：
status(Number, 0或1) - 后端接收：
Integer - 前端传参：
status: "1"(String) - 后端框架：SpringMVC 默认还能帮你转一下，但如果是复杂的 JSON 嵌套，直接报错
JsonParseException。 - 争吵：后端：“你为什么传字符串？” 前端：“URL 参数默认就是字符串啊！你不会转一下吗？”
- 布尔值的罗生门：
- 前端传：
isVip: true - 后端想要：
isVip: 1(因为数据库里存的是 tinyint) - 争吵：前端：“是/否不就是 true/false 吗？” 后端：“我数据库里没有 boolean 类型！”
结论：接口文档在写完的那一刻就已经过期了。只有代码才是诚实的，但它们语言不通。
🔢 第二关：精度丢失——消失的后三位
这是联调中最隐蔽、最坑爹的 Bug，没有之一。
场景：
后端使用雪花算法 (Snowflake)生成了一个订单 ID：1765392849582710452(这是一个 19 位的 JavaLong类型整数)。
后端把这个 ID 通过 JSON 发给了前端。
前端接收，打印在控制台：1765392849582710500。
注意看：最后三位变了！452 变成了 500！
原因：
- Java 的
Long是64 位整数。 - JavaScript 的
Number是双精度浮点数(IEEE 754)。它的安全整数范围只能到53 位(约 9007 万亿)。 - 超过这个范围，JS 就会丢失精度，自动把末尾变成 0。
后果：
前端拿着这个错误的 ID...500去调用“查询订单详情”接口。
后端：“查无此单”。
前端：“这就是你刚才给我的 ID 啊！”
后端：“放屁，我给你的是...452！”
两人对着屏幕上的日志陷入了对自己视力的怀疑，直到有人想起 JS 的这个万年巨坑。
防御代码：
后端必须把所有Long类型的 ID，转成String(字符串) 再发给前端。
🚧 第三关：CORS——浏览器的“看门狗”
代码没问题，参数没问题，但请求就是发不出去。
浏览器控制台飘红：Access to XMLHttpRequest at '...' has been blocked by CORS policy.
前端：“后端，你没配跨域！给我加个 Header！”
后端：“我配了啊！Access-Control-Allow-Origin: *我都加了！”
前端：“还是不行！”
排查真相：
- 带 Cookie 的跨域：如果请求要带 Cookie，后端就不能设为
*，必须设为具体的域名。 - 预检请求 (OPTIONS)：浏览器正式发 POST 之前，会先发一个 OPTIONS 请求探路。后端拦截器一看：“这是啥请求？没 Token？拦截！”
- OPTIONS 请求被后端拦截了，前端就死活发不出 POST。
代价：为了搞定这个红色的报错，两人得花一下午时间去研究 HTTP 协议和 Nginx 配置。
🎭 第四关：Mock 数据的温柔陷阱
在后端接口没写好之前，前端通常会用Mock(模拟) 数据来开发。
Mock 数据是完美的：
- 所有字段都有值。
- 列表永远不为空。
- 图片地址永远有效。
- 没有任何异常情况。
联调那一刻，美梦破碎：
前端连上真实的后端，页面瞬间崩成了一坨。
- Null 指针炸弹：
- Mock：
user: { name: "Tom", age: 18 } - 真实：
user: null(因为这人没填资料) - 前端代码：
user.name->Uncaught TypeError: Cannot read property ‘name’ of null。白屏。
- 空列表的尴尬：
- Mock：列表里总有数据。
- 真实：新用户注册，列表是空的。
- 前端忘了写“暂无数据”的占位图，页面显示一片尴尬的空白，或者布局塌陷。
- 图片加载失败：
- 真实数据里，图片 URL 可能是坏的，或者是 HTTP (在 HTTPS 网页里被拦截)。
- 页面上出现了一排排丑陋的“裂开的图片”图标。
🕵️ 第五关：网络环境的“鬼打墙”
场景：
前端在公司内网，后端在云服务器。
前端：“调不通，超时。”
后端：“我本地 curl 是通的啊。”
原因排查：
- VPN：后端服务器只允许公司 VPN IP 访问。前端忘开 VPN 了，或者 VPN 掉线了。
- hosts：前端电脑的 host 绑定的域名指向了测试环境，但后端发版发到了预发环境。
- HTTPs 证书：测试环境的证书是自签名的（不安全）。
- 安卓/iOS APP 默认拦截不安全的证书，请求直接发不出去。前端得求着客户端开发去把“忽略证书校验”的开关打开。
💡 总结：联调是人际关系的试金石
为什么接口联调这么痛苦？
因为这是**“理想逻辑”（我的代码）和“残酷现实”**（别人的代码 + 复杂的网络）发生物理碰撞的时刻。
一场顺利的联调，需要：
- 后端：不仅写代码，还要写靠谱的文档，还要把
Long转String，还要配好CORS。 - 前端：不仅画页面，还要防御
null值，还要处理401/500错误，还要对齐字段名。 - 心态：即使对方传回来的 JSON 是一坨垃圾，也要心平气和地问：“亲，这里是不是字段名拼错了？”而不是直接吼：“你写的什么破玩意！”
