金宇澄我盯着那条报错看了整整三十秒：java.lang.NumberFormatException: For input string: "12.5kg"。接口文档上白纸黑字写着 weight 类型是 Integer，单位 kg，代码里我按 Integer 接，线上却传回来一个带单位、带小数、还是字符串的值。那一刻崩溃的不只是程序，还有我当时对“第三方接口”这个词的所有信任。
这种场景在后端开发里太常见了。文档只是理想世界的蓝图，线上接口返回的是现实世界的泥石流。今天想借这个崩溃瞬间，把第三方接口对接中最容易被低估的“类型信任”问题聊透：为什么文档写 Integer 并不等于接口真的返回 Integer，遇到这种情况怎么快速定位，以及如何用一套“防御性对接”的流程避免下次再踩。这篇文章主要写给做后端开发、接口对接、维护老系统、天天处理外部数据同步的同学，你应该能在里面看到自己踩过的坑。
1. 崩溃现场还原：文档只说 Integer，线上却返回 “12.5kg”
1.1 一个标准的重型翻车流程
先说具体业务。订单中心要同步第三方物流系统的包裹重量，对方给了接口文档，字段描述写得很简单：weight: Integer，单位 kg。联调阶段一切正常，对方返回 12、56、120，整整齐齐，代码按 Integer 接收，序列化正常，入库正常，怎么看都是个轻松活。
上线第二周，某个特殊包裹的重量变成了 "12.5kg"。同步任务开始批量报错，消息越积越多，重试了五次全部失败，队列堆积告警接着就来。我翻日志的时候，发现崩溃的位置有三个可能，取决于代码怎么写：
- 用 Jackson 直接反序列化到
Integer字段，收到字符串会抛MismatchedInputException或JsonMappingException，取决于你配置的宽松程度。 - 从
Map里拿到值后手动Integer.valueOf(...)，直接抛NumberFormatException，这就是我遇到的场景。 - 有人图省事用
(Integer) map.get("weight")强转，则会抛ClassCastException。
写个简化版本给大家看：
java复制// 方式一：Jackson 自动反序列化
public class ParcelDto {
private Integer weight; // 对方实际返回 "12.5kg"
}
// 报错：Cannot deserialize value of type java.lang.Integer from String "12.5kg"
// 方式二：手动解析
Object weight = rawMap.get("weight");
Integer w = Integer.valueOf(weight.toString());
// 报错：NumberFormatException: For input string: "12.5kg"
// 方式三：直接强转
Integer w = (Integer) rawMap.get("weight");
// 报错：ClassCastException: class java.lang.String cannot be cast to java.lang.Integer
同一个脏数据，在不同代码写法下，炸的方式完全不一样。这也是对接第三方时最烦的地方：不是你一个人写得有问题，而是整个链路的防御意识都没有建立。
1.2 别以为只有 Java 会这样，所有语言都有同款雷区
有人说“那是 Java 强类型太死板，换个语言就好了”。真不是。这种类型信任被打穿的问题，在哪个技术栈里都能遇到。
举个大家可能见过的例子。Redis 的 increment() 命令，如果你之前往键里存的是 "abc" 或者字符串形式的 "1.5"，再执行自增操作时，Redis 会直接返回 ERR value is not an integer or out of range。表面上看是命令用错了，实际是上一环节写入时类型认知就有问题。
再比如 Python 对接支付验签时，有个很经典的报错：argument should be integer or bytes-like object, not 'str'。本质上是文档说“传入整数/字节对象”，实际代码传了字符串。这就是文本约定和实际实现的偏差，跟语言无关。
最近接触一些新兴 AI 工具的 API 接入，也能看到类似现象。文档里写着某个参数必须是 positive integer，但调用方传了字符串或浮点数，报错往往是 api error: 400 the thinking_budget parameter must be a positive integer。平台很新，协议很新，但“类型、范围、格式