很長(zhǎng)一段時(shí)間里我前后端分離的項(xiàng)目一多就發(fā)現(xiàn)一個(gè)特別有意思的現(xiàn)象兩邊同事明明都覺(jué)得自己沒(méi)寫(xiě)錯(cuò)接口一聯(lián)調(diào)就開(kāi)始扯皮。前端說(shuō)后端接口返回的JSON字段對(duì)不上后端說(shuō)前端傳的JSON格式我解析不了。這類(lèi)問(wèn)題聽(tīng)上去是小事可一旦進(jìn)入線(xiàn)上輕則功能白屏重則數(shù)據(jù)錯(cuò)亂。所以后來(lái)我專(zhuān)門(mén)把JSON交互處理這套東西整理成了一套筆記這次干脆把筆記改寫(xiě)成一篇可以直接拿去參考的實(shí)操文章。這篇文章圍繞的就是一件事前后端之間、服務(wù)與服務(wù)之間的JSON數(shù)據(jù)到底怎么做到“發(fā)得出去、收得回來(lái)、兩邊都看得懂”。我會(huì)從JSON的本質(zhì)、Java里的JSON處理庫(kù)選型、Spring Boot中JSON交互的落地配置一直聊到自定義序列化器和線(xiàn)上排查手段。內(nèi)容不算難但信息量不小適合剛接觸接口開(kāi)發(fā)的初學(xué)者也適合被JSON解析問(wèn)題折磨過(guò)、想系統(tǒng)梳理一遍的后端開(kāi)發(fā)。1. 從一次前后端聯(lián)調(diào)事故說(shuō)起JSON交互到底卡在哪1.1 前后端各說(shuō)各話(huà)的典型現(xiàn)場(chǎng)我印象很深的一次事故發(fā)生在某電商促銷(xiāo)項(xiàng)目聯(lián)調(diào)階段。后端寫(xiě)了一個(gè)商品詳情的接口返回的是這樣的結(jié)構(gòu){ code: 200, data: { goodsId: 12345, goodsName: 某品牌保溫杯, createTime: 1719820800000 }, msg: success }結(jié)果前端拿著這個(gè)JSON直接懵了我要的商品名是goodsName你給我的字段倒是這個(gè)可createTime為什么是一串?dāng)?shù)字我們頁(yè)面上要顯示“2024-07-01 12:00:00”這串毫秒時(shí)間戳我怎么展示后端同事也很委屈數(shù)據(jù)庫(kù)存的本來(lái)就是datetime我用接口工具測(cè)的時(shí)候看到的也是正常時(shí)間啊怎么一傳到前端就變成數(shù)字了這個(gè)場(chǎng)景各位寫(xiě)過(guò)前后端分離項(xiàng)目的朋友應(yīng)該都不陌生。問(wèn)題根本不在“誰(shuí)對(duì)誰(shuí)錯(cuò)”而是兩邊的數(shù)據(jù)契約沒(méi)有對(duì)齊。后端返回的是Java對(duì)象序列化之后的JSON前端看到的是JSON解析之后的對(duì)象中間經(jīng)過(guò)序列化和反序列化這兩道工序只要有一道工序的配置不一致看到的東西就不一樣。1.2 JSON交互的本質(zhì)一份兩端共同遵守的協(xié)議我把JSON交互拆成三個(gè)關(guān)鍵詞結(jié)構(gòu)約定、序列化規(guī)則、解析規(guī)則。結(jié)構(gòu)約定是雙方對(duì)字段名、嵌套層級(jí)、數(shù)據(jù)類(lèi)型達(dá)成的一致意見(jiàn)序列化規(guī)則是后端把Java對(duì)象變成JSON字符串時(shí)如何轉(zhuǎn)換類(lèi)型和格式解析規(guī)則是前端或下游服務(wù)拿到JSON字符串后如何還原成自己需要的對(duì)象。三者缺一個(gè)交互就會(huì)出現(xiàn)偏差。舉個(gè)最直觀的說(shuō)法JSON交互就像兩個(gè)人約定用同一種語(yǔ)言寫(xiě)信。約定用中文是結(jié)構(gòu)約定按語(yǔ)法把想法寫(xiě)成句子是序列化對(duì)方讀到句子后理解意思是解析。如果寫(xiě)信的人用中文但收信的人以為信里全是英文或者寫(xiě)信人把日期寫(xiě)成“7月1日”收信人卻當(dāng)成“1月7日”信息就悄悄變了。所以我在項(xiàng)目里定了一個(gè)規(guī)矩任何接口在動(dòng)工前先寫(xiě)一份字段對(duì)照表。字段叫什么名、什么類(lèi)型、空值怎么處理、時(shí)間用什么格式、嵌套多深全部寫(xiě)清楚。這個(gè)習(xí)慣看起來(lái)麻煩卻能省掉后面大量“我這邊對(duì)你那邊錯(cuò)”的爭(zhēng)論。1.3 交互處理的最小鏈路拆解一次完整的JSON交互鏈路大概是這樣的后端收到HTTP請(qǐng)求取出請(qǐng)求體里的JSON字符串交給反序列化器轉(zhuǎn)成Java對(duì)象然后業(yè)務(wù)邏輯處理再把返回結(jié)果交給序列化器轉(zhuǎn)成JSON字符串最后寫(xiě)進(jìn)HTTP響應(yīng)。前端拿到響應(yīng)后再做一次JSON解析。用代碼表達(dá)就是// 請(qǐng)求側(cè)字符串 - Java對(duì)象 String requestJson ...; ObjectMapper mapper new ObjectMapper(); GoodsQuery query mapper.readValue(requestJson, GoodsQuery.class); // 響應(yīng)側(cè)Java對(duì)象 - 字符串 GoodsDetail detail goodsService.queryDetail(query); String responseJson mapper.writeValueAsString(detail);看起來(lái)只有兩行核心代碼但里面藏著大量細(xì)節(jié)日期類(lèi)型轉(zhuǎn)成什么格式、枚舉轉(zhuǎn)成字符串還是序號(hào)、數(shù)組空的時(shí)候是輸出[]還是null、下劃線(xiàn)命名的字段和駝峰命名的字段怎么映射、對(duì)象里有循環(huán)引用怎么辦……每一個(gè)細(xì)節(jié)都可能成為線(xiàn)上事故的導(dǎo)火索。2. 別說(shuō)“不就轉(zhuǎn)一下JSON嘛”數(shù)據(jù)形態(tài)轉(zhuǎn)換里的隱性細(xì)節(jié)2.1 三種數(shù)據(jù)形態(tài)閱讀態(tài)、內(nèi)存態(tài)、傳輸態(tài)我經(jīng)常跟新人強(qiáng)調(diào)一個(gè)概念JSON在整套交互流程里并不是同一個(gè)東西。它可以分成三種形態(tài)來(lái)看。第一種是閱讀態(tài)也就是你在接口文檔、網(wǎng)頁(yè)格式化工具里看到的那個(gè)文本帶縮進(jìn)、帶引號(hào)人能直接看懂。第二種是內(nèi)存態(tài)比如Java里那個(gè)帶著屬性、類(lèi)型、嵌套關(guān)系的對(duì)象它活在JVM堆里。第三種是傳輸態(tài)就是HTTP請(qǐng)求體或響應(yīng)體里實(shí)際的字節(jié)流可能是被壓縮過(guò)的、被轉(zhuǎn)義過(guò)的、按某種編碼傳輸?shù)摹：芏嘟馕鰡?wèn)題本質(zhì)上就是這三種狀態(tài)之間轉(zhuǎn)換時(shí)出了問(wèn)題。比如后端把對(duì)象轉(zhuǎn)成字符串時(shí)沒(méi)配置日期格式內(nèi)存態(tài)里好好的LocalDateTime到傳輸態(tài)就變成了時(shí)間戳再比如前端給后端傳JSON中間經(jīng)過(guò)網(wǎng)關(guān)時(shí)被重新編碼中文字符出現(xiàn)亂碼那就是傳輸態(tài)這里出了問(wèn)題。認(rèn)清這三種形態(tài)之后排查問(wèn)題會(huì)有一個(gè)很清晰的方向先看問(wèn)題是出在序列化、傳輸還是反序列化。不要一上來(lái)就懷疑代碼邏輯寫(xiě)錯(cuò)了。2.2 String轉(zhuǎn)對(duì)象和對(duì)象轉(zhuǎn)String遠(yuǎn)不是new一個(gè)ObjectMapper很多新手覺(jué)得JSON轉(zhuǎn)換不就是new ObjectMapper()然后調(diào)用兩個(gè)方法嗎表面上沒(méi)錯(cuò)但一旦牽扯到復(fù)雜類(lèi)型事情就沒(méi)那么簡(jiǎn)單。舉個(gè)例子前端傳過(guò)來(lái)一個(gè)JSON數(shù)組[ {userId: 1, userName: A同學(xué)}, {userId: 2, userName: B同學(xué)} ]后端如果直接寫(xiě)ListUser userList mapper.readValue(json, List.class);這段代碼能跑但運(yùn)行到userList.get(0).getUserName()的時(shí)候大概率會(huì)報(bào)ClassCastException。原因很簡(jiǎn)單List.class只能告訴反序列化器“目標(biāo)是List”卻沒(méi)法告訴它“List里裝的是User”。泛型信息在運(yùn)行時(shí)被擦除了Jackson拿到的只是一個(gè)泛型List它只能按LinkedHashMap來(lái)解析。正確寫(xiě)法是用TypeReference把泛型帶進(jìn)去ListUser userList mapper.readValue(json, new TypeReferenceListUser() {});這個(gè)坑幾乎所有寫(xiě)過(guò)Java接口的人都踩過(guò)。我當(dāng)時(shí)給新人講的時(shí)候打了個(gè)比方你要快遞員送一箱蘋(píng)果光說(shuō)“送一箱”是不夠的得說(shuō)清楚箱子里是什么。List.class就是那個(gè)沒(méi)說(shuō)清楚的“一箱”而new TypeReferenceListUser() {}就是“一箱蘋(píng)果”。2.3 為什么空值、特殊字符在轉(zhuǎn)換中最容易出問(wèn)題序列化和反序列化里最容易出問(wèn)題的不是常規(guī)數(shù)據(jù)而是邊界數(shù)據(jù)?？罩稻褪堑湫?。后端有一個(gè)對(duì)象某個(gè)字段是null默認(rèn)序列化之后這個(gè)字段可能直接消失也可能輸出null取決于全局配置。前端如果寫(xiě)死了要取這個(gè)字段拿到的卻是undefined頁(yè)面上可能就渲染異常。特殊字符是另一個(gè)重災(zāi)區(qū)。JSON字符串里如果包含換行符、引號(hào)、反斜杠序列化時(shí)必須正確轉(zhuǎn)義否則生成的JSON就是非法JSON前端一解析就報(bào)錯(cuò)。更隱蔽的是那些不可見(jiàn)字符比如某些業(yè)務(wù)系統(tǒng)從別的地方復(fù)制過(guò)來(lái)的文本里帶了特殊空白符肉眼完全看不出來(lái)但JSON解析器對(duì)某些字符的處理邏輯并不一致同一個(gè)字符串在A庫(kù)解析成功在B庫(kù)解析失敗。我對(duì)這個(gè)問(wèn)題的處理思路很樸素在所有對(duì)外接口的序列化配置里把空值處理策略顯式地定好要么統(tǒng)一輸出null要么統(tǒng)一忽略同時(shí)在接口測(cè)試階段就覆蓋“字符串帶引號(hào)、帶換行、帶emoji”這類(lèi)用例別等上線(xiàn)了再由用戶(hù)幫我們發(fā)現(xiàn)。3. 三個(gè)主流JSON庫(kù)的取舍選型不該只看百度搜到哪篇3.1 三庫(kù)差異對(duì)照我實(shí)際用下來(lái)的感受Java生態(tài)里處理JSON的庫(kù)翻來(lái)覆去就那么幾個(gè)Spring Boot默認(rèn)自帶的Jackson、國(guó)內(nèi)用得多的Fastjson、老牌的Gson。網(wǎng)上關(guān)于它們誰(shuí)快的文章一抓一大把但真正到項(xiàng)目選型時(shí)我更看重的是穩(wěn)定性和可控性。先說(shuō)我自己的使用感受。Jackson是Spring Boot的默認(rèn)選擇這意味著在Spring項(xiàng)目里引入它幾乎零成本而且Spring Boot的自動(dòng)配置已經(jīng)幫你把序列化器接好了注解支持也最豐富。Gson是Google出品的API設(shè)計(jì)很簡(jiǎn)潔new Gson().toJson(obj)和fromJson兩個(gè)方法搞定大部分場(chǎng)景但功能深度不如Jackson。Fastjson最大的特點(diǎn)是序列化性能在某些場(chǎng)景下確實(shí)快API寫(xiě)起來(lái)也很順手但歷史上暴露過(guò)的安全漏洞讓我在核心鏈路上不太敢用它。我做過(guò)的幾個(gè)老項(xiàng)目里這三種庫(kù)都出現(xiàn)過(guò)。有些項(xiàng)目因?yàn)闅v史原因從Fastjson切到過(guò)Jackson單純是因?yàn)橥ㄓ眯愿谩⑸鐓^(qū)維護(hù)頻率更高。Gson我一般只用在一些自己寫(xiě)的小工具里圖它輕便。3.2 性能不是唯一標(biāo)準(zhǔn)安全性和可控性更關(guān)鍵如果你去搜“Fastjson為什么快”會(huì)看到一堆壓測(cè)數(shù)據(jù)確實(shí)在某些場(chǎng)景下它的表現(xiàn)不錯(cuò)。但我選JSON庫(kù)從來(lái)不把性能當(dāng)成第一指標(biāo)因?yàn)閷?duì)于絕大多數(shù)業(yè)務(wù)系統(tǒng)來(lái)說(shuō)JSON序列化根本不在性能瓶頸上真正耗時(shí)的是數(shù)據(jù)庫(kù)查詢(xún)和遠(yuǎn)程調(diào)用。我更在意的是三點(diǎn)。第一是否支持自定義序列化器和反序列化器因?yàn)闃I(yè)務(wù)里總有一些特殊字段需要特殊處理比如脫敏。第二對(duì)未知字段、循環(huán)引用、深層嵌套這類(lèi)極端情況的默認(rèn)行為是否可控能不能通過(guò)配置兜住。第三框架自動(dòng)配置的深度換句話(huà)說(shuō)就是我是不是只寫(xiě)一個(gè)注解就能讓整個(gè)項(xiàng)目的JSON交互行為發(fā)生改變。拿Jackson舉例它支持JsonIgnore、JsonProperty、JsonFormat、JsonSerialize、JsonDeserialize幾乎覆蓋了我遇到過(guò)的所有需求。Gson也可以用TypeAdapter做到類(lèi)似效果但寫(xiě)起來(lái)會(huì)繁瑣不少。3.3 一個(gè)項(xiàng)目究竟該怎么選我的選型建議是這樣的如果是Spring Boot新項(xiàng)目直接用Jackson沒(méi)必要額外引庫(kù)因?yàn)镴ackson已經(jīng)深度集成在Spring Boot的MVC里日期格式化、空值處理、字段命名策略都能通過(guò)配置文件統(tǒng)一管理如果是一個(gè)老項(xiàng)目想重構(gòu)且現(xiàn)有代碼大量使用了Fastjson的API也不要急著全換一步一步把高危鏈路先切到Jackson測(cè)試穩(wěn)定后再推進(jìn)如果只是寫(xiě)個(gè)腳本或者做本地小工具Gson完全夠用。這里有個(gè)特別容易踩的雷一個(gè)項(xiàng)目里同時(shí)引了多個(gè)JSON庫(kù)平時(shí)各用各的看起來(lái)相安無(wú)事等某一天工具類(lèi)里混用了這兩個(gè)庫(kù)的注解和API序列化結(jié)果就會(huì)出現(xiàn)莫名其妙的差異。項(xiàng)目里最好統(tǒng)一一個(gè)主JSON庫(kù)工具類(lèi)只封裝這一個(gè)庫(kù)的API別給自己留混用的機(jī)會(huì)。4. Spring Boot里JSON交互的落地姿勢(shì)與全局配置4.1 RequestBody和ResponseBody到底做了什么在Spring Boot的Web層JSON交互最核心的就是兩個(gè)注解RequestBody和ResponseBody。很多新手只是會(huì)用但并不完全清楚它們背后的機(jī)制。RequestBody作用在方法參數(shù)上告訴Spring把HTTP請(qǐng)求體里的JSON字符串反序列化成后面的Java對(duì)象。這個(gè)過(guò)程中Spring用的就是當(dāng)前容器里注冊(cè)的MappingJackson2HttpMessageConverter消息轉(zhuǎn)換器負(fù)責(zé)把請(qǐng)求體字符串轉(zhuǎn)成對(duì)象。ResponseBody作用在返回值上或者直接加在類(lèi)上讓所有方法生效告訴Spring把Java對(duì)象序列化成JSON字符串寫(xiě)進(jìn)響應(yīng)體。用RestController就相當(dāng)于在類(lèi)上同時(shí)加上了Controller和ResponseBody這也是現(xiàn)在最主流的寫(xiě)法。如果你遇到一個(gè)問(wèn)題后端寫(xiě)好的RequestBody User user前端傳了JSON過(guò)來(lái)但user對(duì)象里某些字段為null。不要急著懷疑前端先想想是不是前后端字段名沒(méi)對(duì)上。默認(rèn)情況下Jackson是把JSON字段名和Java屬性名做一一映射的前端傳的userName后端對(duì)象里屬性也是userName才能正確對(duì)應(yīng)。如果前端習(xí)慣傳下劃線(xiàn)風(fēng)格user_name后端就得加全局配置或者用JsonProperty(user_name)做映射。4.2 全局Jackson配置日期、空值、命名策略一網(wǎng)打盡全局配置的意義在于你不必在每個(gè)字段上都寫(xiě)注解只需要在配置文件里聲明一套默認(rèn)策略就能讓所有接口的JSON行為統(tǒng)一。我用Spring Boot時(shí)最常配置的幾項(xiàng)如下spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8 default-property-inclusion: non_null serialization: write-dates-as-timestamps: false deserialization: fail-on-unknown-properties: false第一行指定日期格式為yyyy-MM-dd HH:mm:ss第二行指定時(shí)區(qū)為東八區(qū)這一點(diǎn)特別重要因?yàn)槿绻愕姆?wù)器在別的時(shí)區(qū)不指定時(shí)區(qū)會(huì)導(dǎo)致日期序列化出來(lái)差8個(gè)小時(shí)第三行表示序列化時(shí)忽略值為null的字段第四行讓日期序列化時(shí)不輸出時(shí)間戳而是輸出格式化字符串第五行是反序列化時(shí)遇到未知字段不報(bào)錯(cuò)這對(duì)于前端多傳冗余字段的情況很友好。日期格式在這個(gè)配置里是全局生效的但業(yè)務(wù)里總有幾個(gè)接口需要用不同的日期格式這時(shí)候可以用JsonFormat在字段上覆蓋全局配置。記住一個(gè)原則全局定默認(rèn)局部做覆蓋注釋里說(shuō)清楚為什么覆蓋。4.3 統(tǒng)一響應(yīng)包裝把“成功/失敗”的反饋規(guī)則先定下來(lái)JSON交互里另一個(gè)被忽略但很重要的問(wèn)題就是響應(yīng)結(jié)構(gòu)不統(tǒng)一。有的接口成功時(shí)返回的是一個(gè)對(duì)象失敗時(shí)返回的是一個(gè)字符串或者成功和失敗字段的嵌套層級(jí)完全不同。前端對(duì)接起來(lái)就非常痛苦每個(gè)接口都要單獨(dú)寫(xiě)解析邏輯。我習(xí)慣在項(xiàng)目里做一個(gè)統(tǒng)一的響應(yīng)包裝類(lèi)類(lèi)似下面這樣public class ApiResultT { private Integer code; private String message; private T data; public static T ApiResultT success(T data) { ... } public static T ApiResultT error(Integer code, String message) { ... } }所有接口的返回值都包裝成ApiResultTcode表示業(yè)務(wù)狀態(tài)碼message是給前端展示的提示信息data是真正的業(yè)務(wù)數(shù)據(jù)。這樣前端只需要判斷code再?zèng)Q定取message還是data規(guī)則就固定下來(lái)了。統(tǒng)一包裝看起來(lái)是件小事但它在整個(gè)團(tuán)隊(duì)里建立的是一套交互契約。每次開(kāi)會(huì)討論接口時(shí)大家只需要關(guān)心data里是什么而不需要擔(dān)心外面那層殼今天會(huì)不會(huì)變。5. 實(shí)戰(zhàn)踩坑清單日期、循環(huán)引用、泛型丟失、中文亂碼5.1 日期格式不一致典型的“兩邊都對(duì)合不上”接著開(kāi)頭那個(gè)案例繼續(xù)說(shuō)。日期格式不一致是JSON交互里出現(xiàn)頻率最高的坑而且它的結(jié)構(gòu)非常一致后端認(rèn)為自己在序列化時(shí)輸出了格式化字符串前端看到的是時(shí)間戳或者前端給后端傳了一個(gè)2024-07-01 12:00:00后端反序列化時(shí)也按這個(gè)格式解析但由于時(shí)區(qū)不對(duì)入庫(kù)時(shí)間成了2024-06-30 04:00:00。排查日期問(wèn)題的順序我一般是先看序列化配置里有沒(méi)有指定格式和時(shí)區(qū)再看字段上有沒(méi)有被JsonFormat單獨(dú)覆蓋最后看傳輸過(guò)程中是否有中間層重新處理了日期字段。有一次我們排查了很久最后發(fā)現(xiàn)是網(wǎng)關(guān)層對(duì)響應(yīng)體做了字符串替換把時(shí)間格式里的斜杠替換成了橫杠結(jié)果后端看到的是橫杠格式的字符串再次序列化時(shí)格式全亂了。所以排查要覆蓋鏈路中的每一個(gè)節(jié)點(diǎn)不能只看服務(wù)端。5.2 循環(huán)引用和懶加載一序列化就整頁(yè)報(bào)錯(cuò)循環(huán)引用是后端對(duì)象序列化中最讓人頭疼的問(wèn)題。舉個(gè)常見(jiàn)的場(chǎng)景一個(gè)訂單對(duì)象里有用戶(hù)對(duì)象用戶(hù)對(duì)象里又有一個(gè)訂單列表序列化訂單時(shí)Jackson發(fā)現(xiàn)訂單里有用戶(hù)用戶(hù)又有訂單訂單里又有用戶(hù)……如果不做任何限制它就會(huì)無(wú)限嵌套下去最后棧溢出。解決循環(huán)引用有三個(gè)方向。第一個(gè)是業(yè)務(wù)上明確不需要閉環(huán)直接在某一端用JsonIgnore把不需要的字段忽略掉第二個(gè)是用JsonIdentityInfo讓相同對(duì)象在序列化時(shí)以ID引用而不是展開(kāi)完整對(duì)象第三個(gè)是從設(shè)計(jì)上避免雙向?qū)ο笾苯颖┞督o前端改用DTO數(shù)據(jù)傳輸對(duì)象只返回前端需要的那幾個(gè)字段。還有一個(gè)讓很多人踩過(guò)的坑是Hibernate的懶加載。一個(gè)實(shí)體類(lèi)里有OneToMany的關(guān)系屬性沒(méi)被訪(fǎng)問(wèn)時(shí)它是一個(gè)代理對(duì)象直接序列化時(shí)會(huì)觸發(fā)LazyInitializationException。這種情況我一般也用DTO解決顯式地把需要的數(shù)據(jù)查出來(lái)再組裝成返回對(duì)象而不是試圖把JPA實(shí)體直接丟給序列化器。5.3 泛型與類(lèi)型擦除List 接口返回前端拿不到全字段前面提到了TypeReference這里展開(kāi)講一個(gè)實(shí)際案例。有個(gè)接口返回ListUser實(shí)現(xiàn)時(shí)直接用了List.class作為反序列化目標(biāo)。結(jié)果前端拿到數(shù)據(jù)后發(fā)現(xiàn)user對(duì)象里混著一堆LinkedHashMap的結(jié)構(gòu)所有的字段都變成了map.get(xxx)的取值方式。前端說(shuō)接口文檔寫(xiě)得不對(duì)后端說(shuō)我返回的就是數(shù)組。兩邊都很委屈但根源只有一個(gè)反序列化時(shí)泛型信息丟失。Jackson在反序列化時(shí)如果無(wú)法得知目標(biāo)元素類(lèi)型只會(huì)按照最通用的Map結(jié)構(gòu)處理。這個(gè)問(wèn)題不光影響List任何帶泛型的類(lèi)型都會(huì)遇到比如MapString, User、PageResultUser處理方式都一樣要么用TypeReference要么在繼承類(lèi)時(shí)把泛型固定下來(lái)比如定義一個(gè)UserList extends ArrayListUser這是個(gè)很偏門(mén)但有效的技巧。5.4 中文亂碼與特殊字符Tomcat配置和轉(zhuǎn)義策略中文亂碼在JSON交互里雖然不像以前那么常見(jiàn)但一旦出現(xiàn)就特別難排查因?yàn)樗皇呛蠖舜a的問(wèn)題而是整個(gè)鏈路的編碼不統(tǒng)一。HTTP請(qǐng)求和響應(yīng)都有各自的字符集如果服務(wù)端返回Content-Type: application/json;charsetUTF-8而中間某層把它改成了別的編碼中文就會(huì)變成亂碼。Spring Boot里可以這樣顯式地設(shè)置響應(yīng)編碼server: servlet: encoding: charset: UTF-8 enabled: true force: trueforce: true表示強(qiáng)制所有請(qǐng)求和響應(yīng)都使用UTF-8避免因?yàn)榭蛻?hù)端沒(méi)帶編碼參數(shù)導(dǎo)致的亂碼。另外還要注意JSON字符串本身對(duì)控制字符是有限制的比如\u0000這類(lèi)字符不能被直接放進(jìn)JSON字符串。如果業(yè)務(wù)數(shù)據(jù)里可能包含這類(lèi)字符序列化時(shí)往往會(huì)被丟棄或轉(zhuǎn)義兩端看到的文本就不同。對(duì)于包含接口日志的數(shù)據(jù)我建議在寫(xiě)日志時(shí)把請(qǐng)求體和響應(yīng)體做一次JSON美化輸出同時(shí)打印轉(zhuǎn)義后的可見(jiàn)字符串這樣定位問(wèn)題才不會(huì)被特殊字符干擾。6. 自定義序列化器把敏感字段的“對(duì)外長(zhǎng)相”攥在自己手里6.1 什么場(chǎng)景值得寫(xiě)一個(gè)自定義序列化器全局配置解決的是通用問(wèn)題但業(yè)務(wù)里總有那么幾個(gè)字段不按常理出牌。最常見(jiàn)的場(chǎng)景就是數(shù)據(jù)脫敏。比如用戶(hù)手機(jī)號(hào)數(shù)據(jù)庫(kù)里存的是13812345678接口返回給前端時(shí)頁(yè)面可能只需要展示138****5678。這個(gè)需求如果用JsonIgnore把字段整個(gè)忽略掉前端就拿不到數(shù)據(jù)了如果讓前端自己截?cái)嗄堑扔诎衙撁暨壿媮G給了用戶(hù)也不合理。更合理的做法是數(shù)據(jù)庫(kù)存原始數(shù)據(jù)接口按場(chǎng)景決定“對(duì)外長(zhǎng)相”。后端默認(rèn)配置下敏感字段可以統(tǒng)一掛一個(gè)自定義序列化器序列化時(shí)自動(dòng)脫敏。這樣業(yè)務(wù)代碼里不需要寫(xiě)任何脫敏邏輯前端拿到手的就是已經(jīng)處理好的數(shù)據(jù)。6.2 手機(jī)號(hào)脫敏字段一個(gè)10行的自定義序列化器在Jackson里實(shí)現(xiàn)自定義序列化器很簡(jiǎn)單繼承JsonSerializerT重寫(xiě)serialize方法再用JsonSerialize注解掛到字段上。public class PhoneDesensitizeSerializer extends JsonSerializerString { Override public void serialize(String phone, JsonGenerator gen, SerializerProvider serializers) throws IOException { if (phone null || phone.length() 7) { gen.writeString(phone); return; } gen.writeString(phone.substring(0, 3) **** phone.substring(7)); } } public class UserVO { JsonSerialize(using PhoneDesensitizeSerializer.class) private String phone; }這段代碼的核心是serialize方法判斷手機(jī)號(hào)夠不夠7位不夠就直接輸出夠就把中間四位替換成星號(hào)。字段類(lèi)上掛注解后Jackson在序列化這個(gè)字段時(shí)就會(huì)走進(jìn)這個(gè)邏輯。這個(gè)思路還能延伸到很多地方身份證號(hào)脫敏、郵箱地址脫敏、銀行卡號(hào)脫敏。規(guī)則不同但寫(xiě)法大同小異。我用這個(gè)方式在項(xiàng)目里統(tǒng)一處理過(guò)一批敏感字段效果很好最大的好處是脫敏規(guī)則收斂在序列化器里而不是散落在各個(gè)業(yè)務(wù)方法的if/else里。6.3 自定義反序列化處理前端多態(tài)字段的實(shí)踐自定義反序列化的場(chǎng)景相對(duì)少一些但一遇到就是硬需求。舉個(gè)真實(shí)例子前端有一個(gè)值可能是字符串也可能是字符串?dāng)?shù)組也可能是單個(gè)對(duì)象也可能是對(duì)象數(shù)組。這種不確定的入?yún)⒑蠖巳绻欢x一種類(lèi)型必有一半的請(qǐng)求解析失敗。我的處理方式是在反序列化器里做兼容。繼承JsonDeserializerT重寫(xiě)deserialize先看當(dāng)前JsonToken是什么類(lèi)型如果是VALUE_STRING就按字符串解析如果是START_ARRAY就遍歷數(shù)組把元素收集起來(lái)然后統(tǒng)一返回一個(gè)List結(jié)構(gòu)。public class FlexibleStringListDeserializer extends JsonDeserializerListString { Override public ListString deserialize(JsonParser p, DeserializationContext ctxt) throws IOException { ListString result new ArrayList(); if (p.currentToken() JsonToken.START_ARRAY) { while (p.nextToken() ! JsonToken.END_ARRAY) { result.add(p.getValueAsString()); } } else { result.add(p.getValueAsString()); } return result; } }這種靈活反序列化器能解決接口兼容問(wèn)題但我建議只用在做舊接口兼容、第三方回調(diào)適配這類(lèi)場(chǎng)景。新寫(xiě)的內(nèi)部接口能定死類(lèi)型就定死類(lèi)型別為了省事什么都兼容不然代碼越寫(xiě)越復(fù)雜最后自己都搞不清一個(gè)字段到底有多少種可能性。7. 聯(lián)調(diào)與線(xiàn)上排查我慣用的三板斧7.1 聯(lián)調(diào)期用哪些手段快速驗(yàn)證JSON交互聯(lián)調(diào)階段最容易發(fā)現(xiàn)JSON交互問(wèn)題這時(shí)候我很少直接打開(kāi)瀏覽器看頁(yè)面而是先用接口測(cè)試工具把請(qǐng)求和響應(yīng)分開(kāi)驗(yàn)證。我常用的驗(yàn)證步驟是第一步新建請(qǐng)求寫(xiě)入JSON請(qǐng)求體確認(rèn)HTTP狀態(tài)碼和響應(yīng)結(jié)構(gòu)第二步檢查響應(yīng)JSON里每個(gè)字段的類(lèi)型重點(diǎn)關(guān)注時(shí)間、金額、數(shù)組空值第三步把響應(yīng)JSON復(fù)制到格式化工具里看一眼整體嵌套對(duì)不對(duì)。如果是一個(gè)比較復(fù)雜的JSON結(jié)構(gòu)前端同學(xué)經(jīng)常會(huì)問(wèn)“這個(gè)字段到底是字符串還是數(shù)字”。為了避免這個(gè)溝通成本我習(xí)慣在接口文檔里直接標(biāo)注示例值示例值能寫(xiě)123的字符串還是123的字符串都要寫(xiě)清楚。很多字段歧義本質(zhì)上就是示例值不明確造成的。7.2 線(xiàn)上JSON解析異常日志的定位思路線(xiàn)上環(huán)境沒(méi)有接口測(cè)試工具那么方便所以日志是排查的主通道。JSON解析異常常見(jiàn)報(bào)錯(cuò)有幾種JsonParseException表示請(qǐng)求體根本不是合法JSON多半是前端拼錯(cuò)了字符或者被中間層截?cái)郙ismatchedInputException表示JSON結(jié)構(gòu)合法但類(lèi)型對(duì)不上比如前端傳了字符串后端定義的是數(shù)字InvalidDefinitionException表示序列化目標(biāo)本身有問(wèn)題比如循環(huán)引用、找不到getter方法。我的定位思路是先看異常信息里指向的字段名再拿原始請(qǐng)求體做一次本機(jī)復(fù)現(xiàn)。很多線(xiàn)上解析問(wèn)題本地一復(fù)現(xiàn)就能定位因?yàn)閳?bào)錯(cuò)信息已經(jīng)告訴你字段名了。真正難的是那種“偶發(fā)解析失敗”這種情況多半和特定輸入值有關(guān)比如某個(gè)字符串里帶了換行符某個(gè)字符串特別長(zhǎng)超過(guò)了中間件限制。解決偶發(fā)問(wèn)題的辦法是把請(qǐng)求體完整打到日志里一次復(fù)現(xiàn)就什么都能看出來(lái)。7.3 一次排查經(jīng)歷請(qǐng)求體過(guò)大與嵌套JSON邊界問(wèn)題最后分享一個(gè)印象比較深的排查經(jīng)歷。當(dāng)時(shí)線(xiàn)上有個(gè)接口偶爾報(bào)錯(cuò)錯(cuò)誤信息是“Unexpected character...”但同樣的請(qǐng)求參數(shù)重新提交一次又能成功。從表現(xiàn)看像是數(shù)據(jù)傳輸過(guò)程中內(nèi)容被截?cái)嗔?。查了一圈最后定位到是網(wǎng)關(guān)層對(duì)請(qǐng)求體大小做了限制超過(guò)限制的請(qǐng)求體被攔下一部分后端收到的是半截JSON自然解析失敗。解決方法是調(diào)大請(qǐng)求體限制并在網(wǎng)關(guān)層增加對(duì)Content-Length的校驗(yàn)超長(zhǎng)的請(qǐng)求提前返回明確提示而不是讓它進(jìn)入后端變成一條看不懂的解析異常。這個(gè)案例給我的啟發(fā)是JSON交互問(wèn)題不能只盯著JSON本身還要看承載它的整個(gè)管道。HTTP頭部、網(wǎng)關(guān)配置、代理層、編碼設(shè)置每一層都有可能改動(dòng)JSON的實(shí)際內(nèi)容。排查看鏈路這六個(gè)字是我處理這類(lèi)問(wèn)題最核心的心得。再補(bǔ)充一個(gè)實(shí)際經(jīng)驗(yàn)JSON交互想要少出問(wèn)題接口文檔和前后端契約是最前線(xiàn)的防線(xiàn)。數(shù)據(jù)格式再簡(jiǎn)單也要把示例寫(xiě)清楚字段再多也要統(tǒng)一空值處理。這些東西看起來(lái)算不上核心技術(shù)但真到了線(xiàn)上報(bào)錯(cuò)搶救的時(shí)候每一份清晰的約定都能幫你少點(diǎn)一次應(yīng)急工單。希望這篇文章里梳理的思路能讓你在下次遇到JSON交互問(wèn)題時(shí)手里有一張完整的排查地圖。