先说个真实经历。前阵子线上监控突然冒出一个高频崩溃报错内容是 “failed to deserialize the json body into the target type: input: missing field ...”。排查了一会儿才发现既不是后端接口挂掉也不是网络问题而是某个接口在上一个版本悄悄改了一个字段名客户端没跟上。类似这种 JSON 解析异常在安卓项目里几乎是“月经问题”隔三差五出现一次每次都能让开发者在深夜挠头。今天这篇就把我在安卓开发中遇到的 JSON 解析异常做一次完整梳理从异常分类、发生原理、排查流程到防御方案一次性讲透。1. 先把 JSON 解析异常分成三类别再眉毛胡子一把抓每次有同事跑过来跟我说“JSON 又解析失败了”我第一句话都是反问一句具体报的什么错是格式不对、结构不对还是类型不对这三种情况虽然听着都叫“解析异常”但产生原因、排查方向、解决办法完全不同混在一起处理只会浪费时间。1.1 格式非法JSON 文本本身就不是一个合法 JSON这一类最直白也最好判断后端返回的内容无法被解析器识别为 JSON 格式。典型场景包括服务端异常时没有统一错误处理直接把一个 HTML 错误页或 Java 堆栈信息返回来。网关超时返回了纯文本内容比如一串 “Bad Gateway”。接口发生了重定向拿到了一个带标签的 HTML 页面。最经典的后端返回了一个以逗号结尾的数组或者键名没有加双引号。这类问题在 Gson、Moshi、kotlinx.serialization 中通常表现为JsonSyntaxException、MalformedJsonException或SerializationException报错信息里常常带着行号和列号比如 “End of input at line 1 column 5”。判断方法很简单把返回内容原样拷贝到 JSON 校验工具里如果校验工具都报错说明问题在网络层和响应层压根没到模型层。1.2 结构不匹配JSON 合法但长相比模型预期差太远这一类才是项目中最常见的解析异常。JSON 本身完全合法只是它的组织架构和客户端定义的数据模型对不上。举几个实际场景模型定义的是一个对象后端返回的是一个数组。后端把data字段改成了content客户端还在找data。原本应该直接返回用户对象结果后端多加了一层{ result: { user_info: {...} } }。数组里嵌套对象的层级比模型多了一层或者少了一层。Gson 遇到这种情况经常抛JsonSyntaxException: java.lang.IllegalStateException: Expected BEGIN_OBJECT but was BEGIN_ARRAY这句话当时把我折磨惨了后来看到类似的直接就能猜到八成是根节点结构对不上。1.3 类型不匹配字段名一样类型却不是一回事这种异常藏在更深的地方字段名能和模型对上但从 JSON 里拿到的值和模型字段声明的类型不匹配。经典例子{ user_name: 张三, user_age: 18, is_vip: 1 }如果模型定义是data class UserModel( val user_name: String, val user_age: Int, val is_vip: Boolean )那解析时大概率会挂或者得到一个让后续业务崩溃的值。服务端把user_age的18当字符串返回is_vip用1表示布尔值客户端模型却按Int和Boolean定义解析器在类型转换时就直接抛出异常了。1.4 三类问题一张表看清楚类型典型报错关键字出错环节排查方向格式非法Unexpected character / End of input网络响应层抓原始返回内容先过一遍校验工具结构不匹配Expected BEGIN_OBJECT but was BEGIN_ARRAY序列化映射层对比JSON结构和模型类的层级关系类型不匹配Expected a string but was NUMBER序列化映射层逐一核对每个字段的JSON值与模型类型理清这三张脸之后再碰上任何解析异常我会先花三十秒确认属于哪一类而不是直接 breakpoint 进去逐行 debug。2. 解析链路上“missing field”是怎么一步步发生的“missing field”这一类报错值得单独拿出来聊因为它特别迷惑人。字面意思明明是“字段缺失”但很多时候你打开后端接口一看字段就在那里甚至数据都没问题。那问题到底出在哪儿2.1 missing field 的一般出现位置先说出现场景。如果你的项目是 Kotlin Retrofit kotlinx.serialization或者用了 Moshi 作为 converter这类报错很常见。报错通常长这样failed to deserialize the json body into the target type: input: missing field order_id at path: $.order_id注意关键词missing field。这是序列化器在告诉你我解析 JSON 时找不到模型里某个必填字段对应的键。很多人的第一反应是“后端没返回这个字段”。但这只是可能性之一而且往往不是最真实的原因。2.2 字段缺失的四种隐藏原因第一种后端字段名不一致。后端返回的是orderNo模型里却用的是order_id中间又没有SerializedName做映射序列化器自然找不到。第二种后端确实没返回这个字段。这种情况反而最常见原因是后端把某个字段设计成了“条件返回”。比如订单接口中只有已支付的订单才会返回pay_time未支付订单直接省略这个键。如果模型里把pay_time定义成必填的Long那未支付订单请求一到客户端解析层立刻报 missing field。第三种接口经过网关或 BFF 层时被改了结构。尤其在一些中大型项目里客户端请求的接口并非后端原始接口中间还有一层聚合服务。聚合服务可能因为缓存策略、字段过滤规则或者版本号判断把某些字段给丢掉了。第四种模型字段本身是 Kotlin 非空类型没有默认值。这一点在 Kotlin kotlinx.serialization 环境里特别明显。即使后端返回了null只要字段类型声明为非空且无默认值序列化器也会判为异常。2.3 一个让我印象深刻的排查案例有一个版本App 内订单列表页突然出现一大批解析崩溃崩溃信息都是 “missing field order_status”。我先把线上报错的完整原文找出来然后调出对应接口的访问日志发现返回的 JSON 里根本没有order_status这个键只有status。后来找后端同事一聊才知道他们做了一次内部字段重构把order_status统一改成了status但接口文档没同步更新。客户端按照文档开发自然就崩了。这个案例说明一个道理大部分 missing field 的根因不是“少了一个键”而是“前后端的字段契约没有对齐”。排查的时候不要只盯着模型要把服务端实际返回内容拉出来对比。2.4 修这个问题的标准姿势我的做法有两步第一把模型里非必要的字段规范为可空类型或者给默认值从根上避免“一缺就崩”。Serializable data class OrderModel( SerialName(order_id) val orderId: Long 0L, SerialName(status) val orderStatus: Int -1, val goodsList: ListGoodsModel emptyList() )第二和服务端确认字段命名冲突的解决方案。能恢复兼容就恢复不能恢复就同步更新SerialName映射关系并且让后端接口文档、请求日志、客户端模型三处保持一致。注意Kotlin 的SerialName和 Gson 的SerializedName是两个库里不同的注解千万别在 kotlinx.serialization 中误用成 Gson 的注解否则等于没写。3. 一个真实订单接口的完整排查过程从崩溃到根因排查 JSON 解析异常最忌讳的就是凭感觉改代码。我总结的一套流程基本能覆盖九成以上的场景下面用一次真实排查串起来讲。3.1 拿到崩溃信息后先做三件事看到异常的第一时间我不会打开代码找模型而是先收集三样东西完整异常堆栈注意看异常类型和行号列号。对应用户的操作路径大概知道是哪个页面触发的请求。接口的原始返回内容这个最核心。抓原始内容的方式有很多如果本地能复现用 Charles 或者 Wireshark 抓包如果本地复现不了就去日志平台找接口响应日志如果项目集成了 OkHttp 拦截器那更好直接看日志里的 response body。3.2 把原始 JSON 和模型对比着看假设拿到这么一段原始 JSON{ order_id: 20260115001, pay_status: 2, items: [ { goods_name: 手机, price: 1999.00 } ] }而客户端模型长这样data class OrderModel( SerializedName(order_id) val orderId: Long, SerializedName(pay_status) val payStatus: Int, SerializedName(items) val items: ListGoodsModel ) data class GoodsModel( SerializedName(goods_name) val goodsName: String, SerializedName(price) val price: Double )这一对比就发现两个问题order_id的值是字符串20260115001但模型定义的是Longprice的值是字符串1999.00但模型定义的是Double。3.3 定位根因并选择修复方案第一个问题如果发生在 Gson 中String自动转Long有时候能成功但如果内容包含非数字字符就直接崩在 kotlinx.serialization 中则基本是类型不匹配异常。第二个问题同样如此。修复方案有三个层次最省事把模型改成后端实际返回的类型。最稳妥模型字段全部改成String在业务层再做转换。最灵活自定义JsonAdapter/KSerializer统一处理字符串和数字的兼容转换。我一般优先选择第一种因为后端类型就是事实标准强行让客户端适配只会埋下更多坑。只有当接口被多个端复用、没法轻易变更时才选择第三种。3.4 不是所有问题都靠改模型解决有些时候你会发现 JSON 和模型完全对得上就一个字段对不上。这时候别急着改代码先去沟通。我一个同事就吃过这个亏看到某个字段总是解析失败自己把模型字段类型改成了String能跑了也不报错了。结果过了两周后端把这个字段从100改成了100又崩了。后来一查才发现后端接口在测试环境和生产环境的序列化策略不一样导致同一个字段在不同环境返回的类型不同。所以遇到“字段名一样但类型总变”的情况一定要把服务端不同环境、不同版本的返回都拉出来对比找到规律后再决定方案。4. 常见解析报错对照表看到报错就能直接定位方向前面讲的是思路这一节给一个可以直接对照的速查表。项目里遇到解析异常打开这张表基本能少走一半弯路。4.1 不同解析库的报错风格不一样安卓生态里的 JSON 解析库五花八门但每个库的报错风格差异很大Gson 的报错通常包含JsonSyntaxException和IllegalStateException并且经常出现 “Expected BEGIN_OBJECT but was BEGIN_ARRAY” 这种句式。Moshi 的报错则类似 “Expected a string but was NUMBER at path $.price”直接把错误路径$.price标出来排查难度低很多。kotlinx.serialization 的报错偏向 “MissingFieldException” 和 “JsonDecodingException”语义非常明确。4.2 我整理的高频报错速查表报错关键信息大概率原因排查方向推荐解法Expected BEGIN_OBJECT but was BEGIN_ARRAY根节点是数组模型却定义成对象检查接口响应最外层结构模型改为ListX或增加统一包装类Expected BEGIN_ARRAY but was BEGIN_OBJECT模型期待数组实际拿到对象检查嵌套层级和字段名调整模型字段类型或 JSON 路径Expected a string but was NUMBER字符串类型字段收到数字核对具体字段在服务端的类型定义字段类型改 String或自定义适配器missing field xxx / Required field xxx is missingJSON 里缺少必填键拉原始返回内容确认键是否存在给字段默认值或改为可空类型java.lang.NumberFormatException: For input string: abc字符串转数字失败检查该字段是否有脏数据改用字符串接收或校验后转换Unexpected character (t) at position...返回了非 JSON 内容查看完整响应体从网络层排查处理错误响应End of input at line X column YJSON 文本被截断检查完整响应是否读完查看 Content-Length 和 Gzip 配置这张表没法覆盖所有情况但高频的解析异常基本都在这儿了。4.3 一个容易翻车的隐藏场景混淆影响除了上面这些报错还有一个你必须要警惕的隐藏雷区R8 / ProGuard 混淆导致模型字段被改名。项目开启混淆后如果没配置 keep 规则模型类里的orderId字段可能被混淆成a、b这种短名字。Gson 反射解析时按字段名去找orderId自然找不到。Moshi 和 kotlinx.serialization 在编译期生成代码受混淆影响相对小但也不是完全没有。解决方法是给所有用于 JSON 映射的模型类加上混淆保留规则或者在包名层面统一 keep-keep class com.example.data.model.** { *; }这个坑我踩过不止一次凡是线上出现“解析异常但本地怎么跑都正常”的情况先怀疑混淆。5. 防御性解析设计让异常在发生之前就被消化排查异常只是治标真正想让项目稳定必须做防御性设计。说白了就是即使后端数据达不到模型预期App 也不能直接崩溃。这块是我最想分享的干货。5.1 模型字段尽量用安全默认值不要把“非空”写成信仰很多刚入门的朋友喜欢把所有字段都定义成非空类型觉得这样访问起来方便不用到处判空。但在 JSON 解析场景里这恰恰是崩溃的源头。后端接口的字段缺失、字段为 null、类型变化都可能在某个意想不到的版本出现。所以我的建议是和网络层打交道的数据模型尽量做到“关键字段可空普通字段给默认值”。data class UserModel( val userId: String , val userName: String? null, val age: Int 0, val avatar: String? null, val tags: ListString emptyList() )这样设计的用意很明显不管 JSON 里缺了什么解析层都能给出一个合理的“最低可用状态”业务层再做兜底判断。5.2 统一响应包装类屏蔽“成功却解析失败”的问题很多团队都会定义一个统一的响应外壳比如data class ApiResponseT( val code: Int, val message: String, val data: T? )但我想强调的一点是data字段建议声明为T?并配合泛型解析。理由很简单服务端返回成功时data一定有值但返回失败时data可能直接缺失。如果你把data定义成非空T一旦后端某个接口在成功状态下没返回data解析层直接崩溃。统一包装类的另一个作用是失败时也能给出结构化的错误信息方便客户端展示友好提示而不是抛一个解析异常。5.3 解析失败要有兜底策略而不是只会弹 Toast解析异常出现时用户已经在 APP 里ta 关心的不是“Data parsing error”而是“这个页面还能不能用”。所以我在实际项目里给解析加了三层兜底第一层解析失败后重试一次。排除偶发网络问题或瞬时丢包。第二层如果重试仍失败查看本地缓存是否有历史数据能用旧数据就用旧数据并在页面显示“数据更新失败”的轻提示。第三层如果连缓存都没有再显示完整的失败页面或重试按钮。这个思路在电商、资讯类 App 里尤其重要。一次解析失败就白屏用户的忍耐度是很低的。5.4 前后端契约管理比代码本身更重要防御性解析只是客户端堵漏真正减少解析异常的根本是管好前后端之间的接口契约。我自己经过几次大踩坑后推动团队做了三件事前后端约定统一的字段命名规范能统一用下划线就全部用下划线不要混用。接口文档从手写维护迁移到 OpenAPI 规范每次字段变更要同步更新。后端删字段或者改类型前必须发公告通知客户端保留一个版本周期的兼容期。这些措施看起来和写代码没关系但带来的收益非常大。接手维护老项目时尤其能体会到很多解析异常根本不是技术问题是协作流程出了问题。6. 大 JSON 解析的内存与性能隐患另一个“异常”现场最后说一个很多人会忽略的点JSON 解析异常不只是“解析失败”那一种还有一种异常是“解析成功但把内存吃爆了”。6.1 全量解析在大数据量场景下的问题如果你的接口返回的是一个包含几千条记录的 JSON 数组直接交给解析库全量解析成对象列表内存开销会大得吓人。每条记录再嵌套几张图片地址、几个标签数组整体内存可能在瞬间上涨几十 MB在主线程解析的话还会伴随明显的卡顿。更严重的是 OOM。我见过一个日志上传模块本地日志先拼成一个大 JSON 再一次性上传结果某个用户本地日志特别大拼接出来的 JSON 文本本身就有几十 MB客户端一解析直接崩溃。6.2 用流式解析处理大体量 JSON这时候就该请出流式解析方案。Gson 提供了JsonReaderkotlinx.serialization 也支持Json.decodeToSequence它们的特点是不一次性加载整个对象树而是边读边处理。下面是 GsonJsonReader处理大数组的一个简化示例val reader JsonReader(FileReader(file)) reader.beginArray() while (reader.hasNext()) { reader.beginObject() var id: String? null var name: String? null while (reader.hasNext()) { when (reader.nextName()) { id - id reader.nextString() name - name reader.nextString() else - reader.skipValue() } } reader.endObject() // 在这里逐条处理数据比如写入数据库 } reader.endArray()注意代码里的else - reader.skipValue()这个技巧在处理未知字段时特别重要可以跳过不关心的字段减少无谓解析。6.3 什么时候必须用流式解析我总结的经验是如果单次解析的 JSON 文本超过 5 MB或者单列表超过 1000 条记录并且这些数据全量加载对业务没有意义就优先考虑流式解析。流式解析的缺点是代码量明显增加灵活性也差一些。所以并不是所有场景都推荐常规的接口数据全量解析完全够用。但如果你在做本地大文件导入、日志上报、数据仓库同步类功能流式解析就是你绕不开的必修课。6.4 别忽略线程调度另一个容易被忽略的点是JSON 解析尽量别放主线程。Gson、Moshi 这类库在解析数据量较大的 JSON 时耗时可能达到几十毫秒甚至几百毫秒。在低端机上这会直接导致界面卡顿、掉帧、ANR 前兆。Retrofit 默认不会把你的 converter 切到 IO 线程所以如果用了自定义 converter一定要确保解析过程发生在后台线程或者至少用Dispatchers.IO包裹一下。排查卡顿问题的时候可以用 Android Profiler 记录 CPU 和内存曲线如果发现某段时间JsonReader或Gson相关方法占用明显优先通过线程调度和流式解析去优化。最后再补一点个人的体会处理 JSON 解析异常最重要的不是背下所有报错含义而是建立一套“从异常信息定位到根因”的思维链路。每次都问自己三个问题这个 JSON 合法吗结构和我模型对应吗类型匹配吗问完这三个问题九成的解析异常都能找到方向。剩下的那一成往往藏在接口版本、后端环境、数据脏值这些看似不相关的问题里学会抓包、看原始返回、核对日志你就已经赢过了大多数只会在代码里打日志的开发者。