項目標題將 USTRUCT 類型的實例對象轉換成對應的 JSON 字符串格式服務端要做一份配置下發(fā)接口要求客戶端把玩家當前狀態(tài)打包成 JSON 字符串 POST 上去。我第一次圖省事用FString::Printf一段一段手工拼 JSON十幾個字段拼到一半就分不清誰是誰了該轉義的引號、換行也鬧出過幾次解析失敗。換成 USTRUCT 加FJsonObjectConverter之后幾十行手拼代碼縮成了兩三行字段誰有誰沒有、什么類型什么名字全部由反射系統(tǒng)統(tǒng)一處理問題一次性清干凈。這篇內容講的就是這件事在 Unreal Engine 里把一個聲明了 USTRUCT 的結構體實例按照字段定義轉換成 JSON 字符串順帶也講清楚反向的 JSON 字符串還原結構體。文章會覆蓋原理、模塊依賴、基礎寫法、字段映射、復雜類型處理、性能邊界和常見坑。適合正在做網(wǎng)絡對接、存檔讀寫、調試工具或者單純想把結構體快速導出去給別的程序用的開發(fā)者。不管你是剛接觸 JSON 轉換還是已經(jīng)踩過不少坑都能在里面找到能直接拿去用的方案。1. 項目拆解USTRUCT轉JSON到底在解決什么問題1.1 標題背后的核心需求標題里的兩個關鍵詞非常明確一個是 USTRUCT一個是 JSON。USTRUCT 是 Unreal Engine 中用于聲明“帶反射信息結構體”的宏。所謂反射就是這個結構體運行時能告訴引擎自己有哪些字段、字段是什么類型、字段名是什么。JSON 這端則是一種跨語言、跨平臺、純文本的數(shù)據(jù)交換格式廣泛用于 Web API、配置文件、日志上報、編輯器導出等場景。把兩者結合起來本質就是讓 UE 的 C 結構體能以 JSON 文本形式“走出引擎”被服務端、網(wǎng)頁端、Python 腳本或者其他任何支持 JSON 的系統(tǒng)讀取。這個需求的背后通常不是“想用 JSON”而是“要和外界交換數(shù)據(jù)”。自己項目內部用結構體傳參很舒服可一旦數(shù)據(jù)要發(fā)到 HTTP 接口、寫進人類可讀的配置文件、或者導出給策劃看就必須轉成文本。JSON 只是最通用、最不容易出錯的文本載體。1.2 典型應用場景實際項目里這個轉換能力最常見的使用場景有四類。第一類是網(wǎng)絡消息體?？蛻舳撕头斩酥g用 HTTP 或者 WebSocket 通信消息體按 JSON 組織。客戶端把 USTRUCT 代表的玩家信息、戰(zhàn)績、背包數(shù)據(jù)一次性轉成 JSON 發(fā)送服務端解析后入庫。第二類是本地配置和存檔。把結構體實例保存為 JSON 文件下次啟動讀回來。比起自己定義二進制格式JSON 文件可以直接打開檢查出問題一眼就能看出來。第三類是調試輸出。結構體里字段多用UE_LOG一個個打印太啰嗦。直接轉換成 JSON 字符串打一條日志字段名和值都看得清清楚楚。第四類是編輯器工具和外部程序交換。比如寫編輯器插件批量導資源信息導出的就可以是 JSON 數(shù)組文件。1.3 能做什么、不能做什么這套做法能覆蓋絕大多數(shù)普通結構體整數(shù)、浮點數(shù)、布爾、字符串、枚舉、數(shù)組、嵌套結構體以及一部分容器類型。但它不是萬能的。TMap、TSet這類容器的支持在不同引擎版本里差異很大FText導出后是一個嵌套對象而不僅僅是文本沒有UPROPERTY修飾的字段不參與轉換反射系統(tǒng)看不到它。這些邊界不是一個“轉換函數(shù)”能包辦的需要寫的人在代碼里做好約定。還有個容易搞混的點USTRUCT 和 UObject 是兩回事。USTRUCT 是輕量的值類型可以用StaticStruct()拿到反射定義UObject 是引擎對象序列化走的是另一套UObjectToJsonObjectString之類的路徑。標題里明確說“USTRUCT 類型的實例對象”所以本文聚焦在結構體上。2. 前置準備與序列化原理2.1 反射系統(tǒng)為什么 USTRUCT 是前提先理解一個關鍵點UE 里的 JSON 轉換器不是靠猜字段來做序列化的它靠的是反射元數(shù)據(jù)。當你寫下USTRUCT(BlueprintType)并給字段加上UPROPERTY后UHTUnreal Header Tool會在編譯期生成這個結構體的反射描述。運行時FJsonObjectConverter會通過TFieldIteratorFProperty遍歷結構體的所有反射屬性逐個讀取當前實例里對應字段的值再根據(jù)字段類型決定寫入 JSON 對象的方式。所以有三條硬性規(guī)則結構體必須用USTRUCT聲明并包含GENERATED_BODY()。想導出到 JSON 的字段必須用UPROPERTY修飾。字段類型必須在轉換器的支持范圍內。我見過不少新人把USTRUCT當普通 C 結構體用字段全裸奔結果轉換函數(shù)返回空對象原因就是反射系統(tǒng)根本看不到這些裸字段。2.2 FJsonObjectConverter 與 FJsonSerializer 的分工UE 的 JSON 體系里有兩個核心工具很多人會混淆。FJsonObjectConverter負責統(tǒng)一“內存對象”和“FJsonObject”之間的轉換。它做的事情是把 USTRUCT 實例里的每個字段映射成FJsonValue節(jié)點再塞進一個TSharedPtrFJsonObject。FJsonSerializer負責“FJsonObject”和“文本 JSON”之間的互相轉換。它把一個樹形的 JSON 對象序列化成字符串或者從字符串解析出樹形對象。這里有個非常好的中間層思路當你只需要“USTRUCT 轉字符串”時可以一步到位調用現(xiàn)成接口但當你想在序列化前后修改字段、加字段、刪字段時就應該先轉成FJsonObject改完再序列化。這個中間層也是后面做字段映射、自定義格式的入口。2.3 工程模塊依賴設置寫代碼之前先確認工程模塊引用了 JSON 相關模塊。在項目的.Build.cs文件里需要添加依賴PublicDependencyModuleNames.AddRange(new string[] { Core, CoreUObject, Engine, Json, JsonUtilities });Json是核心模塊JsonUtilities提供了一些封裝工具舊版本工程尤其常見。如果只用到FJsonObjectConverter和FJsonSerializer一般Json模塊就夠但為了保險我通常兩個都加。編寫代碼時需要包含頭文件#include JsonObjectConverter.h #include Dom/JsonObject.h #include Serialization/JsonSerializer.h如果編譯報找不到JsonObjectConverter.h先別查頭文件路徑回去檢查.Build.cs是否真的加了模塊。3. 基礎實操一行代碼完成USTRUCT轉JSON字符串3.1 定義一個可轉換的USTRUCT以一個游戲玩家檔案為例USTRUCT(BlueprintType) struct FPlayerProfile { GENERATED_BODY() UPROPERTY(BlueprintReadOnly) FString PlayerName; UPROPERTY(BlueprintReadOnly) int32 Level 1; UPROPERTY(BlueprintReadOnly) float Score 0.0f; UPROPERTY(BlueprintReadOnly) bool bIsVIP false; UPROPERTY(BlueprintReadOnly) TArrayFString Achievements; };必須注意字段上的UPROPERTY不是可有可無。如果一個字段想不出現(xiàn)在 JSON 里要么不寫UPROPERTY要么在結構體上用UPROPERTY(Transient)標記成瞬態(tài)字段然后在轉換時配合SkipFlags排除。3.2 標準轉換寫法聲明一個實例并填充數(shù)據(jù)然后調用轉換接口FPlayerProfile Profile; Profile.PlayerName TEXT(Ada); Profile.Level 42; Profile.Score 99.5f; Profile.bIsVIP true; Profile.Achievements { TEXT(FirstBlood), TEXT(TankKiller) }; FString OutJson; const bool bSuccess FJsonObjectConverter::UStructToJsonObjectString( FPlayerProfile::StaticStruct(), Profile, OutJson ); if (bSuccess) { UE_LOG(LogTemp, Log, TEXT(%s), *OutJson); }輸出結果是{PlayerName:Ada,Level:42,Score:99.5,bIsVIP:true,Achievements:[FirstBlood,TankKiller]}這一步就是標題說的核心需求。FPlayerProfile::StaticStruct()拿到結構體的反射定義Profile是實例內存地址OutJson接收結果。有一點要提前打預防針不同引擎版本里UStructToJsonObjectString的參數(shù)表不完全一樣。比如 UE4.27 和 UE5.3 在“是否支持縮進參數(shù)”“是否支持自定義序列化器”上就有差異。最穩(wěn)妥的辦法是在編輯器里對著JsonObjectConverter.h的聲明確認參數(shù)順序。本文示例方案是最常用的一組參數(shù)核心用法在所有支持FJsonObjectConverter的版本里都成立。3.3 反序列化從JSON字符串還原USTRUCT轉換是雙向的光會導出不夠還要能讀回來。FPlayerProfile Restored; const bool bParseSuccess FJsonObjectConverter::JsonObjectStringToUStruct( OutJson, FPlayerProfile::StaticStruct(), Restored ); if (bParseSuccess) { // Restored.PlayerName TEXT(Ada) }JsonObjectStringToUStruct是字符串入口內部會先調用FJsonSerializer::Deserialize解析成FJsonObject再通過JsonObjectToUStruct寫回結構體。這里有一個很常見的需求服務端返回的 JSON 里可能有額外字段而結構體里并沒有對應屬性。此時新版引擎的JsonObjectToUStruct提供了不允許“部分字段缺失”的嚴格模式參數(shù)。常規(guī)場景不啟用嚴格模式解析器會自動跳過結構體里沒有的字段這樣前后端字段擴展時不會因為多一個字段就把整段解析搞掛。3.4 CheckFlags 與 SkipFlags 這兩個參數(shù)UStructToJsonObjectString參數(shù)里有一對很容易被忽略的int64標記位CheckFlags和SkipFlags。CheckFlags表示只導出“包含這些標記”的屬性。比如傳入CPF_Edit就只導出標了Edit的屬性平時基本用不上。SkipFlags表示跳過“包含這些標記”的屬性。這個才是真正常用的。舉例來說如果一個字段加了Transient表示它不需要持久化UPROPERTY(Transient) FString SessionToken;轉換時不想帶上它就可以這樣FJsonObjectConverter::UStructToJsonObjectString( FPlayerProfile::StaticStruct(), Profile, OutJson, 0, CPF_Transient );我還會把CPF_Deprecated也放進SkipFlags把標記了廢棄的字段一起過濾掉。這個參數(shù)在處理老結構體、兼容歷史字段時非常有用比改結構體定義要溫柔得多。4. 實用細節(jié)字段名映射與復雜類型處理4.1 字段名默認規(guī)則與坑UE 的 JSON 轉換器默認輸出的是UPROPERTY原本的名字。也就是說C 里叫PlayerNameJSON 里就是PlayerName不會自動轉成playerName或player_name。這在實際對接外部系統(tǒng)時經(jīng)常出問題。服務端接口可能是player_name可能是playerName甚至可能是全小寫。如果為每個字段改名最簡單的做法是先轉成FJsonObject再在對象層做改名映射TSharedPtrFJsonObject RootObject MakeSharedFJsonObject(); FJsonObjectConverter::UStructToJsonObject( FPlayerProfile::StaticStruct(), Profile, RootObject.ToSharedRef(), 0, 0 ); // 把 PlayerName 改成 player_name FString Value RootObject-GetStringField(TEXT(PlayerName)); RootObject-RemoveField(TEXT(PlayerName)); RootObject-SetStringField(TEXT(player_name), Value);改完之后再序列化FString OutJson; TSharedRefTJsonWriterTCHAR Writer TJsonWriterFactoryTCHAR::Create(OutJson); FJsonSerializer::Serialize(RootObject.ToSharedRef(), Writer);這個做法的好處是把“協(xié)議字段名”和“C字段名”徹底解耦。我自己的項目里會把映射關系集中放一張TMapFString, FString配置表后端改協(xié)議名時只改配置不動結構體代碼。4.2 布爾字段的 b 前綴引發(fā)的麻煩UE 的命名規(guī)范是布爾字段加b前綴例如bIsVIP。轉換器導出時也原樣帶出去JSON 里就出現(xiàn)了bIsVIP:true。外部接口通常不喜歡這個b。處理方式和字段改名一樣在FJsonObject中間層把bIsVIP改成is_vip或者isVip。也可以從結構體設計層面規(guī)避。如果這個結構體只是內部邏輯使用的那就保留b前綴如果是專門為網(wǎng)絡協(xié)議建的傳輸 DTO可以故意給字段起名時不帶b比如就叫IsVIP不過這樣會犧牲一點 UE 命名風格的一致性。在這個問題上沒有絕對正確答案團隊約定一致最重要。4.3 嵌套結構體、數(shù)組、TArray 與枚舉嵌套的 USTRUCT 會被自動展開成 JSON 對象不需要額外處理USTRUCT(BlueprintType) struct FPlayerProfile { GENERATED_BODY() UPROPERTY(BlueprintReadOnly) FEquipment Equip; };轉換結果里的Equip會是一個完整的 JSON 對象等價于內嵌結構體的字段集合。TArray序列化成 JSON 數(shù)組里面的元素可以是基礎類型也可以是嵌套結構體轉換器都會遞歸處理。枚舉是很多團隊栽過跟頭的地方。不同引擎版本對枚舉的序列化方式不一樣有的導成數(shù)字有的導成字符串名稱。如果對接的服務端對枚舉類型有嚴格要求我建議不要依賴轉換器的默認行為要么在結構體里單獨用一個int32存枚舉整數(shù)值要么在FJsonObject中間層手動讀取枚舉名并寫入字符串字段。容器類型里TMap是最需要小心的。舊版引擎對TMap的支持不穩(wěn)定部分版本直接不支持新版本對TMapFString, T這類“字符串鍵”的支持相對好但整數(shù)鍵、結構體鍵會出各種怪問題。常規(guī)建議是網(wǎng)絡對接用的結構體盡量避免TMap改成TArray加“Key、Value”成對字段。這樣無論引擎版本怎么變序列化結果都是穩(wěn)定的。4.4 FText、軟引用等特殊類型注意FText在 UE 里是本地化文本內部結構遠比FString復雜。JSON 轉換時它會被導成一個帶culture、text、key等字段的嵌套對象而不是一個簡單的字符串。如果服務端不關心本地化只是想要一個字符串請直接用FString類型。FSoftObjectPath、TSoftClassPtr、TSubclassOf這些資源引用類型轉換器導出的通常是對象路徑字符串。反序列化時能否真正加載出對象取決于項目資源和引擎行為不要指望 JSON 一解析完就有可用的對象指針。5. 性能邊界與更成熟的設計5.1 別在 Tick 里高頻轉換FJsonObjectConverter 用的是反射遍歷雖然有不錯的優(yōu)化但每次轉換都會創(chuàng)建FJsonObject樹、動態(tài)分配節(jié)點、生成字符串。在開發(fā)構建下這個成本會明顯放大如果放在Tick里對幾百個對象每幀轉換一次很快就能看到主線程卡頓。我的經(jīng)驗法則是低頻任務每秒一次、手動觸發(fā)、存檔、發(fā)送消息隨便用。高頻任務每幀、每幾百毫秒輪詢先考慮做快照避免直接持有游戲線程上的大結構體。萬級以上對象的批量轉換優(yōu)先丟到異步線程轉換完再回到游戲線程處理結果。還有一個實用技巧如果同一份結構體在短時間內需要多次轉 JSON可以在字段不變時緩存上一次的結果字符串減少重復反射遍歷。5.2 用 FJsonObject 中間層做高級操作前面提到過UStructToJsonObjectString是為了方便的一次性封裝真正靈活的是先轉FJsonObject再操作。一個典型的例子是在導出前給根對象追加一個公共字段TSharedPtrFJsonObject RootObject MakeSharedFJsonObject(); FJsonObjectConverter::UStructToJsonObject( FPlayerProfile::StaticStruct(), Profile, RootObject.ToSharedRef(), 0, 0 ); RootObject-SetStringField(TEXT(client_version), TEXT(1.8.5)); RootObject-SetNumberField(TEXT(timestamp), FDateTime::UtcNow().ToUnixTimestamp());還可以把一個結構體塞進另一個結構體作為子對象或者把整個對象丟進數(shù)組。這些操作在純字符串層面幾乎沒法做但在FJsonObject樹形結構上就是幾個方法調用的事。5.3 不要依賴字段順序很多人的直覺是結構體字段按定義順序導出JSON 里也是按這個順序顯示。實際上FJsonObject內部用的是映射結構存儲字段序列化輸出的字段順序并不保證和結構體定義順序一致在不同引擎版本、不同編譯配置下都可能變化。這個排序的不確定性在對接時千萬不要設為前提。JSON 格式本身就不該依賴字段順序服務端、腳本、測試工具都應該按鍵名取字段。如果某個場景真的必須固定順序比如要做文件簽名校驗就需要完全繞開FJsonObject直接用手寫TJsonWriter的方式生成字符串TSharedRefTJsonWriterTCHAR Writer TJsonWriterFactoryTCHAR::Create(OutJson); Writer-WriteObjectStart(); Writer-WriteValue(TEXT(PlayerName), Profile.PlayerName); Writer-WriteValue(TEXT(Level), Profile.Level); Writer-WriteObjectEnd(); Writer-Close();這樣輸出順序完全由代碼控制不會受映射結構干擾。代價是每個字段都要手寫適合少量、穩(wěn)定的場景。6. 問題排查與實操速查6.1 常見問題速查表我把實際開發(fā)中遇到最多的問題整理成一張表覆蓋率和命中率都非常高?，F(xiàn)象可能原因解決方案輸出{}或缺失字段字段沒加UPROPERTY給字段補上UPROPERTY輸出{}且完全不報錯結構體沒有GENERATED_BODY()或宏寫錯檢查USTRUCT定義重新生成頭文件編譯找不到JsonObjectConverter.h模塊依賴沒加Json在.Build.cs添加Json和JsonUtilities布爾導出帶b前綴UE 字段命名規(guī)范導致在FJsonObject中間層改名或定義傳輸 DTO 時不用b前綴JSON 字段順序亂FJsonObject內部是映射結構后端按鍵名取值固定順序請手寫 Writer反序列化返回 false但 JSON 看起來正常字段類型不匹配或啟用了嚴格模式打印 JSON 核對類型關閉嚴格模式使用寬容解析枚舉導出成數(shù)字/字符串不符合預期不同版本默認行為不同用int32手動存枚舉或中間層手動改字段TMap轉換報錯或結果不對舊引擎對容器支持有限改用TArrayFKeyValuePair或自定義序列化FText導成一大串嵌套對象FText內部結構特殊傳輸層改用FString6.2 版本差異自查方法Unreal 的 JSON 轉換接口在 4.x 和 5.x 之間經(jīng)歷過不少調整。與其記我寫的某一版參數(shù)不如掌握一個自查方法打開引擎源碼目錄找到JsonObjectConverter.h直接看當前版本里UStructToJsonObjectString和JsonObjectStringToUStruct的完整聲明。版本差異集中在幾個地方FieldToPropertyMap參數(shù)改名或刪除。是否支持縮進參數(shù)Indent。是否支持自定義序列化器TCustomJsonSerializationMap。反序列化時是否允許部分字段缺失。遇到參數(shù)不匹配的編譯錯誤不要硬套老代碼優(yōu)先去看當前引擎的頭文件注釋那里才是最新、最準確的行為說明。這篇內容看起來是講一個轉換函數(shù)實際上是把 UE 反射序列化這條鏈路完整走了一遍。我個人在實際項目維護中最深的一個體會是與其讓結構體字段直接暴露給外部協(xié)議不如在FJsonObject層面做一層命名映射和字段過濾把協(xié)議變化隔離在轉換模塊內部。這樣后端改一次字段名、加一次字段類型改動范圍都只限于那個轉換模塊而不會波及整個游戲邏輯。如果你也在長期對接外部系統(tǒng)這個思路值得盡早落地。