JSON字符串的完整實(shí)現(xiàn)與避坑指南)
1. 項(xiàng)目概述與核心需求拆解1.1 這個(gè)需求到底在解決什么問題USTRUCT 是 Unreal Engine 里進(jìn)行數(shù)據(jù)組織和網(wǎng)絡(luò)同步的基礎(chǔ)單元而 JSON 是跨語言、跨平臺交換數(shù)據(jù)時(shí)幾乎繞不開的文本格式。把 USTRUCT 實(shí)例對象轉(zhuǎn)成 JSON 字符串最典型的場景包括把服務(wù)端返回的數(shù)據(jù)持久化成配置文件、把玩家存檔以 JSON 明文形式導(dǎo)出以便調(diào)試、把藍(lán)圖/ C 里計(jì)算的復(fù)雜結(jié)構(gòu)體推送給 Web 前端、或者把一整套戰(zhàn)斗統(tǒng)計(jì)數(shù)據(jù)序列化后塞進(jìn) HTTP 請求體里。很多剛接觸 UE 序列化的開發(fā)者會下意識地去找一個(gè)“一鍵轉(zhuǎn)換”的內(nèi)置藍(lán)圖節(jié)點(diǎn)但實(shí)際動手之后就會發(fā)現(xiàn)UE 官方并沒有提供完整的 “UStruct To JSON String” 的傻瓜式全自動方案。自帶的FJsonObjectConverter::UStructToJsonObject能做結(jié)構(gòu)體到 JSON 對象的轉(zhuǎn)換但它輸出的是一棵FJsonObject對象樹而不是一個(gè)可以直接發(fā)給后端的字符串。你需要再調(diào)Serialize或者TJsonWriter做一步序列化。這個(gè)中間步驟的缺失恰恰是很多新手在論壇上反復(fù)提問的原因。除此之外USTRUCT 里能裝的類型很多嵌套結(jié)構(gòu)體、數(shù)組、TMap、TSet、bool、enum class、FVector、FRotator、FDateTime等等。每種類型的 JSON 表現(xiàn)形態(tài)都不一樣處理不當(dāng)就會出現(xiàn)字段丟失或者類型轉(zhuǎn)換異常。我見過有人用UKismetSystemLibrary::Conv_StringToObject這類節(jié)點(diǎn)試圖硬轉(zhuǎn)結(jié)果在編輯器里可能有效打包后因?yàn)榉瓷湫畔⒉蝗蛘邲]有正確的序列化標(biāo)記數(shù)據(jù)直接變空。所以這個(gè)項(xiàng)目標(biāo)題背后真正的核心需求是在 UE 的開發(fā)框架內(nèi)打通USTRUCT 反射系統(tǒng) → 通用 JSON 數(shù)據(jù)模型 → 純文本字符串這條鏈路而且要能裁剪出可配置、可擴(kuò)展、能解釋清楚每一步“為什么”的版本。1.2 適用人群與實(shí)際落地場景如果你是做 GamePlay 的需要把角色身上的裝備屬性面板導(dǎo)出一份“明文配置”給策劃校驗(yàn)這個(gè)方案很適用如果你是做客戶端網(wǎng)絡(luò)層的要把一條結(jié)構(gòu)化請求轉(zhuǎn)成 JSON 字符串進(jìn)行日志記錄或者加簽這個(gè)方案也很適用哪怕你只是想在編輯器工具腳本里批量把 DataTable 行數(shù)據(jù)轉(zhuǎn)成文件用于自動化測試用例生成同樣的思路可以復(fù)用。有一點(diǎn)要提前說明如果你只是有幾個(gè)固定字段、手寫拼接字符串就能解決的場景其實(shí)沒必要引入 FJsonObjectConverter。這個(gè)工具的本質(zhì)價(jià)值在于“反射驅(qū)動的泛型轉(zhuǎn)換”也就是任意 USTRUCT 丟進(jìn)去都能自動遍歷屬性。如果你面對的數(shù)據(jù)結(jié)構(gòu)是固定的那么手寫TSharedRefFJsonObject RootObj MakeSharedFJsonObject();然后一行行RootObj-SetStringField反而更直白也更好排錯(cuò)。但一旦結(jié)構(gòu)體多了、嵌套深了這種手寫方式就不可維護(hù)了。下面的方案權(quán)衡就是基于這兩種取舍來展開的。2. USTRUCT 與 JSON 之間的“翻譯”機(jī)制2.1 為什么不能直接調(diào)用 ToString做 UE 開發(fā)的人都知道每個(gè)USTRUCT在編譯期會被 UHTUnreal Header Tool掃描生成反射元數(shù)據(jù)包括屬性名、屬性類型、偏移量、標(biāo)記CPF_BlueprintVisible之類。這套反射系統(tǒng)是引擎所有序列化、網(wǎng)絡(luò)復(fù)制、編輯器細(xì)節(jié)面板的基石。JSON 序列化也建立在它之上遍歷屬性的反射信息讀取值再寫入FJsonObject。但這里有個(gè)關(guān)鍵點(diǎn)USTRUCT 本身沒有提供一個(gè)類似ToString的虛函數(shù)來約定“輸出我自己的 JSON”。它只是一個(gè)數(shù)據(jù)聚合體你說它是“待翻譯的原文”更合適。所以只能靠外部的轉(zhuǎn)換器來做翻譯。UE 內(nèi)置的FJsonObjectConverter就是這樣一個(gè)通用的外部翻譯機(jī)它掃描反射系統(tǒng)但多了一層“中間對象”FJsonValue的封裝。我可以打個(gè)比方USTRUCT像一份中英對照表的數(shù)據(jù)源里面有幾百行條目FJsonObjectConverter是翻譯官FJsonObject是翻譯后整理出的“中文版目錄”而最終的 JSON 字符串是把這份目錄用排版規(guī)則打印成文本文檔。你不能指望翻譯官直接把數(shù)據(jù)源變成打印好的文件中間總要有一步“整理成對象”的動作。2.2 FJsonObjectConverter 是“翻譯官”還是“排版工”深入看FJsonObjectConverter::UStructToJsonObject的源碼會發(fā)現(xiàn)它的職責(zé)非常單一根據(jù)反射信息把 USTRUCT 的每個(gè)屬性轉(zhuǎn)換成對應(yīng)的FJsonValue塞進(jìn)FJsonObject。它不管縮進(jìn)、不管換行、不管字符編碼那屬于TJsonWriter的活兒。FJsonObjectConverter底層的處理路徑大概是獲取 UStruct 的FStructProperty列表。遍歷每個(gè)屬性拿到屬性名和FProperty。根據(jù)FProperty的類型分派到不同的轉(zhuǎn)換函數(shù)比如FJsonObjectConverter::ConvertScalarFPropertyToJsonValue、ConvertArrayFPropertyToJsonValue、ConvertMapFPropertyToJsonValue等。調(diào)用FJsonObject::SetField寫入。所以要得到最終字符串還得再把FJsonObject交給FJsonSerializer::Serialize讓它識別 JSON 的標(biāo)準(zhǔn)語法輸出成字符串。分段來看整體功能鏈條是這樣FJsonObjectConverter::UStructToJsonObject - FJsonObject (對象樹) FJsonSerializer::Serialize(JsonObject, Writer) - FString (JSON 字符串)理解這個(gè)鏈條的最大好處是你可以隨時(shí)在中間插入“自定義字段”“過濾敏感字段”“統(tǒng)一加密”等步驟。后面講實(shí)操時(shí)我會重點(diǎn)利用這個(gè)中間層做可復(fù)用的封裝。2.3 字段名和 UPROPERTY 標(biāo)記的微妙關(guān)系FJsonObjectConverter默認(rèn)會使用 UPROPERTY 的名稱作為 JSON key。這意味著你原本的命名規(guī)范會直接暴露在 JSON 里。比如你在 C 里寫m_PlayerHealth或者PlayerHealth_JSON 里也會出現(xiàn)這種風(fēng)格的名字與前端團(tuán)隊(duì)約定俗成的player_health或者playerHealth不一致。要想改變這個(gè)名稱兩個(gè)常用方案在 UPROPERTY 上附加SerializeAs說明符這會在編輯器里提供一個(gè)字段名別名。在轉(zhuǎn)換前拷貝結(jié)構(gòu)體并重命名屬性不過這樣做會破壞反射的完整性更推薦用FJsonObjectConverter::CustomExportCallback來干預(yù)導(dǎo)出過程。實(shí)際項(xiàng)目里我傾向于這樣約定如果字段名需要對外不可變比如供外部存檔兼容那必須用SerializeAs如果只是內(nèi)部調(diào)試導(dǎo)出直接保持原有命名就好沒必要在工具鏈上過度設(shè)計(jì)。3. USTRUCT 與 JSON 字段映射的完整拆解3.1 基礎(chǔ)字段類型對照表這五個(gè)類型占掉了 90% 的工作量先列一張核心對照表這是我在實(shí)施這個(gè)功能時(shí)反復(fù)對源碼確認(rèn)過的結(jié)論USTRUCT/C 類型轉(zhuǎn)換后的 JSON 類型備注int32/int64/uint8NumberUE 內(nèi)部按JsonNumber處理如果你的值超出 JS 安全整數(shù)范圍2^53 – 1注意 Web 端解析精度丟失問題float/doubleNumber特別注意NaN、Infinity在標(biāo)準(zhǔn) JSON 里不合法序列化時(shí)可能會輸出怪異文本需要提前處理或過濾FString/FNameString一般情況下沒問題但如果你有特殊字符如引號、反斜杠TJsonWriter會自動轉(zhuǎn)義boolBool這里有個(gè)大坑USTRUCT 里的bool可能被 UHT 合并成 bitfield而bool bFlag : 1的轉(zhuǎn)換行為不同后面詳述枚舉UENUMNumber 或 String取決于你是否給枚舉設(shè)置了JsonEnumName或者在 UPROPERTY 上做了什么配置我自己實(shí)測下來int64和enum是問題最大的兩個(gè)。int64的原因不是 UE 轉(zhuǎn)不出來而是 JSON 標(biāo)準(zhǔn)本身沒有 64 位整數(shù)類型JS 里解析時(shí)容易丟失精度enum的原因則是很多人默認(rèn)轉(zhuǎn)成字符串名但實(shí)際上 UE 的默認(rèn)行為往往是把底層uint8值輸出形成了“我以為能讀結(jié)果看到一個(gè)數(shù)字”的困惑。3.2 嵌套結(jié)構(gòu)體和數(shù)組的“遞歸翻譯”邏輯FJsonObjectConverter對嵌套結(jié)構(gòu)體的處理方式其實(shí)是遞歸調(diào)用自身。這在閱讀源碼時(shí)很多人容易忽略它并不是“拍平”了映射到一個(gè)扁平的 JSON 對象里而是遇到一個(gè)內(nèi)部結(jié)構(gòu)體屬性時(shí)繼續(xù)為這個(gè)子結(jié)構(gòu)體創(chuàng)建子FJsonObject。舉個(gè)例子如果我有USTRUCT(BlueprintType) struct FInventoryItemData { GENERATED_BODY() UPROPERTY(EditAnywhere, BlueprintReadWrite) FString ItemName; UPROPERTY(EditAnywhere, BlueprintReadWrite) int32 StackCount; }; USTRUCT(BlueprintType) struct FPlayerSaveData { GENERATED_BODY() UPROPERTY(EditAnywhere, BlueprintReadWrite) int32 PlayerLevel; UPROPERTY(EditAnywhere, BlueprintReadWrite) TArrayFInventoryItemData InventoryItems; };那么轉(zhuǎn)換出的 JSON 大致長這樣{ PlayerLevel: 12, InventoryItems: [ { ItemName: 鐵劍, StackCount: 1 }, { ItemName: 治療藥水, StackCount: 3 } ] }這個(gè)遞歸邏輯的好處顯而易見只要你在 C 層把結(jié)構(gòu)體定義清楚嵌套層次再多轉(zhuǎn)換器都能自動展開。壞處也很直接如果結(jié)構(gòu)體內(nèi)部有循環(huán)引用比如結(jié)構(gòu)體里塞了一個(gè)指向自身的指針遞歸就會把棧擊穿。所以在設(shè)計(jì)數(shù)據(jù)結(jié)構(gòu)時(shí)指針型屬性盡量不要放在 USTRUCT 里用于序列化而是改為 ID 引用例如存ItemID而不是直接存UObject*。3.3 TMap 和 TSet 的 JSON 表現(xiàn)形態(tài)TMapFString, FString轉(zhuǎn)換后通常是一個(gè) JSON ObjectKey 作為屬性名Value 作為屬性值。這會帶來一個(gè)比較麻煩的問題如果 Key 不是字符串類型比如TMapint32, FStringFJsonObject無法直接表達(dá)整數(shù) Key最終會嘗試把它轉(zhuǎn)成字符串 Key。解析回來時(shí)你需要自己處理Atoi的轉(zhuǎn)換和可能的 Key 排序變化。TSet的情況更特殊它的 JSON 輸出往往是數(shù)組。這本身沒問題但要注意數(shù)組是有順序的而 TSet 的迭代順序在每次運(yùn)行之間可能不同。如果你拿這個(gè) JSON 當(dāng)緩存簽名或哈希依據(jù)就必須先給 TSet 排序否則簽名會因哈希順序抖動而頻繁失效。從工程經(jīng)驗(yàn)角度我的建議是序列化消息體時(shí)盡量避免直接用 TMap 和 TSet 作為頂級結(jié)構(gòu)它們適合被包在某個(gè)業(yè)務(wù)結(jié)構(gòu)里并且字段數(shù)量可控時(shí)使用。如果實(shí)在需要建議在序列化時(shí)統(tǒng)一排序或者干脆在 USTRUCT 里放TArrayFPairStruct代替雖然看起來不優(yōu)雅但兼容性和可預(yù)測性都更好。4. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 一個(gè)可直接落地的 UStructToJsonString 函數(shù)直接給結(jié)論這是我在項(xiàng)目里反復(fù)打磨過的一個(gè)通用函數(shù)兼顧了“單個(gè)結(jié)構(gòu)體”和“結(jié)構(gòu)體數(shù)組”兩種需求// Header #pragma once #include CoreMinimal.h #include Serialization/JsonSerializer.h #include JsonObjectConverter.h #include Kismet/BlueprintFunctionLibrary.h #include StructToJsonFunctionLibrary.generated.h UCLASS() class UStructToJsonFunctionLibrary : public UBlueprintFunctionLibrary { GENERATED_BODY() public: // 將單個(gè) USTRUCT 實(shí)例轉(zhuǎn)成 JSON 字符串 // 注意 TemplateType 必須是一個(gè) USTRUCT 類型 template typename StructType static FString ConvertStructToJsonString(const StructType InStruct, bool bPrettyPrint false, bool bIncludedDefaultValues false); }; template typename StructType FString UStructToJsonFunctionLibrary::ConvertStructToJsonString(const StructType InStruct, bool bPrettyPrint, bool bIncludedDefaultValues) { static_assert(TIsDerivedFromStructType, FStructBase::IsDerived, ConvertStructToJsonString 只支持 USTRUCT 類型); FString OutputString; // 第一步把 USTRUCT 翻譯成 FJsonObject // 注意第三參數(shù) bIncludedDefaultValues默認(rèn) false 表示跳過與默認(rèn)值完全相同的字段 TSharedRefFJsonObject JsonObject FJsonObjectConverter::UStructToJsonObject( StructType::StaticStruct(), InStruct, 0, 0, bIncludedDefaultValues ); // 第二步把 FJsonObject 序列化成字符串 TSharedRefTJsonWriterTCHAR, TPrettyJsonPrintPolicyTCHAR JsonWriter ...; // 根據(jù) bPrettyPrint 決定使用緊湊輸出還是美化輸出 if (bPrettyPrint) { TSharedRefTJsonWriterTCHAR, TPrettyJsonPrintPolicyTCHAR PrettyWriter TJsonWriterFactoryTCHAR, TPrettyJsonPrintPolicyTCHAR::Create(OutputString); if (!FJsonSerializer::Serialize(JsonObject, PrettyWriter)) { UE_LOG(LogTemp, Error, TEXT(結(jié)構(gòu)體轉(zhuǎn) JSON 字符串序列化失敗)); return TEXT({}); } } else { TSharedRefTJsonWriterTCHAR, TCondensedJsonPrintPolicyTCHAR CondensedWriter TJsonWriterFactoryTCHAR, TCondensedJsonPrintPolicyTCHAR::Create(OutputString); if (!FJsonSerializer::Serialize(JsonObject, CondensedWriter)) { UE_LOG(LogTemp, Error, TEXT(結(jié)構(gòu)體轉(zhuǎn) JSON 字符串序列化失敗)); return TEXT({}); } } return OutputString; }4.2 參數(shù)選擇的細(xì)節(jié)0 和 0 是什么意思很多人第一次看到UStructToJsonObject的四參版本時(shí)會暈?zāi)莾蓚€(gè)0分別是CheckFlags和SkipFlags。它們決定了哪些屬性標(biāo)記會影響序列化CheckFlags第一個(gè)0指定必須包含的屬性標(biāo)記一般傳0表示“不過濾”。SkipFlags第二個(gè)0指定必須跳過的屬性標(biāo)記傳0表示“全部都轉(zhuǎn)”。如果你想跳過所有EditInstanceOnly的屬性可以這樣寫EPropertyFlags SkipFlags CPF_Edit | CPF_BlueprintVisible; TSharedRefFJsonObject JsonObject FJsonObjectConverter::UStructToJsonObject( StructType::StaticStruct(), InStruct, 0, SkipFlags, false );這個(gè)標(biāo)志位機(jī)制非常有用但在普通業(yè)務(wù)代碼里很容易被忽略。我建議在封裝函數(shù)時(shí)增加一個(gè)TSetEPropertyFlags參數(shù)把需求變化的可能留出來而不是寫死0, 0。4.3 Blueprint 側(cè)如何調(diào)用由于模板函數(shù)沒法直接暴露給藍(lán)圖常見的做法是提供一個(gè)普通參數(shù)版本比如傳const FGenericStructWrapper或者直接把常用結(jié)構(gòu)體打包成幾個(gè)重載函數(shù)。不過 UE 的藍(lán)圖函數(shù)庫支持自定義結(jié)構(gòu)體作為參數(shù)琥珀色地“動態(tài)”轉(zhuǎn)換的函數(shù)還是比較麻煩。最實(shí)用的是這樣如果你只需要導(dǎo)出幾個(gè)固定結(jié)構(gòu)體就寫幾個(gè)顯式包裝函數(shù)UFUNCTION(BlueprintPure, Category Json|Struct) static FString ConvertInventoryDataToJson(const FInventoryItemData Data, bool bPrettyPrint false);每個(gè)函數(shù)內(nèi)部調(diào)用模板函數(shù)。這樣做的好處藍(lán)圖節(jié)點(diǎn)有明顯的輸入輸出參數(shù)類型是強(qiáng)類型不容易接錯(cuò)同時(shí)在 C 層保持了泛型轉(zhuǎn)換的靈活性。要是你想做一個(gè)“傳任何結(jié)構(gòu)體都行”的泛型藍(lán)圖節(jié)點(diǎn)需要引入U(xiǎn)K2Node自定義節(jié)點(diǎn)工作量大不少不建議一開始就投入除非項(xiàng)目里這種需求非常多。4.4 實(shí)際項(xiàng)目中的輸出示例簡單與嵌套結(jié)構(gòu)用上面的FInventoryItemData跑一遍緊湊輸出大概是{ItemName:鐵劍,StackCount:1}用FPlayerSaveData跑一遍緊湊輸出大概是{PlayerLevel:12,InventoryItems:[{ItemName:鐵劍,StackCount:1},{ItemName:治療藥水,StackCount:3}]}美化了之后{ PlayerLevel: 12, InventoryItems: [ { ItemName: 鐵劍, StackCount: 1 }, { ItemName: 治療藥水, StackCount: 3 } ] }有一個(gè)細(xì)節(jié)值得注意緊湊輸出更適合用來做日志、做緩存 key因?yàn)槲谋倔w積小、不會引入多余的空白符美化輸出更適合給測試人員或策劃人員閱讀用來排查配置錯(cuò)誤。5. 類型收斂與特殊場景處理5.1 bool 字段的“隱藏陷阱”如果 USTRUCT 里的bool屬性沒有單獨(dú)加uint8或: 1位域聲明UHT 在某些編譯設(shè)置下會把它視作普通屬性。一旦你攃雜了 bitfield比如UPROPERTY(EditAnywhere, BlueprintReadWrite) bool bIsAlive : 1;在某些引擎版本里反射系統(tǒng)會把它當(dāng)成一個(gè)獨(dú)立的布爾屬性處理但底層存儲是和旁邊的其他 bitfield 布爾擠在一起的。此時(shí)如果項(xiàng)目里混用老代碼轉(zhuǎn) JSON 時(shí)可能會出現(xiàn)“值不對”的情況但排查起來異常困難因?yàn)槟阍谡{(diào)試器里看結(jié)構(gòu)體里的值是正常的。我的建議是能不用 bitfield 就不用 bitfield。特別是涉及存檔/網(wǎng)絡(luò)同步的數(shù)據(jù)結(jié)構(gòu)一個(gè) bool 占 4 字節(jié)和占 1 bit在絕大多數(shù)業(yè)務(wù)場景里根本不值得省那點(diǎn)內(nèi)存。改成普通 bool 后序列化的確定性大幅提升也讓 FJsonObjectConverter 少一層意外。5.2 枚舉到底該轉(zhuǎn)數(shù)字還是字符串默認(rèn)行為下枚舉會被轉(zhuǎn)成底層數(shù)值。這在 UE 里沒什么問題因?yàn)樽x取回來時(shí)可以static_castEYourEnum(JsonValue-AsNumber())。但 JSON 的接收方一旦換了語言、換了框架他看到的只是一個(gè)數(shù)字可讀性極差尤其當(dāng)枚舉項(xiàng)有幾十個(gè)的時(shí)候必須維護(hù)一份“數(shù)字?含義”的對照表。想讓枚舉變成字符串可以在枚舉聲明上做文章UENUM(BlueprintType, JsonSerializeAsString) enum class EEquipmentSlot : uint8 { Head, Chest, Legs };加了JsonSerializeAsString后FJsonObjectConverter在序列化時(shí)會把枚舉名作為字符串輸出。這個(gè)標(biāo)記在新版引擎里是支持的如果你用的引擎沒有就需要自己重寫導(dǎo)出回調(diào)把枚舉值映射到約定字符串。開發(fā)時(shí)我一般優(yōu)先用字符串除非和外部系統(tǒng)有明確的二進(jìn)制壓縮要求因?yàn)樽址耪咸奖懔恕?.3 FVector、FRotator、FLinearColor 怎么處理這些引擎內(nèi)置結(jié)構(gòu)體很特殊它們既有USTRUCT的反射元數(shù)據(jù)但業(yè)務(wù)上又經(jīng)常被當(dāng)成“基礎(chǔ)標(biāo)量”處理。FJsonObjectConverter默認(rèn)會把它們轉(zhuǎn)成嵌套對象例如FVector會變成{ X: 1.0, Y: 2.0, Z: 3.0 }這本身沒有錯(cuò)但很多外部接口更希望收到一個(gè)數(shù)組比如[1.0, 2.0, 3.0]或者一個(gè)帶精度控制的定制格式。這種情況我建議你不要去改轉(zhuǎn)換器全局行為而是讓業(yè)務(wù)結(jié)構(gòu)體自己承載序列化格式USTRUCT(BlueprintType) struct FPositionPayload { GENERATED_BODY() UPROPERTY() TArrayfloat Coords; };然后從FVector轉(zhuǎn)成Coords。這樣做的代價(jià)是要寫幾個(gè)轉(zhuǎn)換函數(shù)但收益是 JSON 契約完全可控不再依賴引擎的默認(rèn)表達(dá)。5.4 FDateTime 與 FGuidFDateTime在 JSON 里默認(rèn)輸出的是Ticks或毫秒時(shí)間戳外部系統(tǒng)看到一串長數(shù)字非常不友好。我更習(xí)慣把日期時(shí)間字段在 USTRUCT 里聲明為FString業(yè)務(wù)層負(fù)責(zé)格式化這樣前端不用再做時(shí)間戳解析。FGuid默認(rèn)會轉(zhuǎn)成字符串這個(gè)基本沒有坑但要注意字符串里的大小寫風(fēng)格ToString(EGuidFormats::DigitsWithHyphens)和默認(rèn)輸出不完全一樣。為了契約統(tǒng)一建議統(tǒng)一走一次規(guī)范化再入庫。6. 常見問題與排查技巧實(shí)錄6.1 轉(zhuǎn)出來是空對象 “{}”最經(jīng)典的原因結(jié)構(gòu)體類型沒有加USTRUCT標(biāo)記或者屬性沒有加UPROPERTY。反射系統(tǒng)遍歷的就是這些元數(shù)據(jù)只要標(biāo)記缺失屬性就會被跳過。檢查時(shí)不要只看代碼里有沒有USTRUCT還要確認(rèn)整個(gè)類在頭文件里被 UHT 正確處理過。一個(gè)有效的確認(rèn)方法在編輯器里隨便拖一個(gè)該結(jié)構(gòu)體變量到藍(lán)圖節(jié)點(diǎn)上如果能正常選擇其成員反射就沒問題如果不能就是 UHT 沒有識別。還有一個(gè)容易忽略的情況USTRUCT 定義在.cpp文件里。UHT 默認(rèn)只掃描.h中的聲明放在.cpp里的結(jié)構(gòu)體在某些版本里能編譯但反射不完整序列化出來就是空對象。所以USTRUCT 必須放在頭文件里這一條務(wù)必寫進(jìn)團(tuán)隊(duì)規(guī)范。6.2 int64 數(shù)值末尾的精度丟失如果你把int64轉(zhuǎn)成 JSON Number然后用 Javascript 的JSON.parse解析數(shù)字超過Number.MAX_SAFE_INTEGER時(shí)精度會丟。這已經(jīng)不是 UE 的問題而是 JSON 格式本身沒有“bigint”概念。如果業(yè)務(wù)里確實(shí)有大數(shù)據(jù) ID建議用FString存儲或者序列化時(shí)專門寫成帶后綴的大數(shù)字字符串比如999999999999999999讓接收方自行決定解析策略。6.3 特殊字符和編譯器的“UTF-8 BOM”問題輸出中文或特殊字符到 JSON 時(shí)TJsonWriter默認(rèn)支持FString內(nèi)碼到 UTF-8 的轉(zhuǎn)換但如果你把字符串直接打印到控制臺或者 Windows 下的命令行會出現(xiàn)亂碼。這通常是控制臺代碼頁問題不是 JSON 序列化的問題。用文本文件保存 JSON 時(shí)優(yōu)先選用帶 BOM 的 UTF-8否則某些低版本的工具特別是記事本老版本會視為 ANSI。6.4 嵌套數(shù)組很大時(shí)為何性能掉得厲害FJsonObjectConverter需要遍歷反射元數(shù)據(jù)并為每個(gè)字段創(chuàng)建智能指針對象字段多了之后裝箱開銷不小。如果你一個(gè)結(jié)構(gòu)體里嵌套了成千上萬個(gè)元素每幀都轉(zhuǎn)換性能會非常難看。排查時(shí)可以用Stats或者簡單的FPlatformTime::Cycles前后差值統(tǒng)計(jì)。結(jié)論通常不是“轉(zhuǎn)換器太慢”而是“調(diào)用頻率太高”或者“單次數(shù)據(jù)量太大”。優(yōu)化手段也簡單適合分批轉(zhuǎn)換、延遲轉(zhuǎn)換、或者緩存轉(zhuǎn)換結(jié)果而不是換一個(gè)更快的 JSON 庫。6.5 常見問題速查表現(xiàn)象可能原因處理辦法轉(zhuǎn)出來是{}USTRUCT 或 UPROPERTY 缺失/UHT 未識別確認(rèn)結(jié)構(gòu)體在頭文件屬性全部加 UPROPERTYEnum 輸出數(shù)字而非字符串未加JsonSerializeAsString或版本不支持改用 CustomExport或在結(jié)構(gòu)體上做字符串映射TArray 順序錯(cuò)亂使用了 TSet 或?qū)?TArray 做了并發(fā)寫確認(rèn)容器類型TSet 需排序?qū)С鋈掌谧兂梢淮當(dāng)?shù)字FDateTime 默認(rèn)走時(shí)間戳業(yè)務(wù)上用 FString 保存格式化日期嵌套太深導(dǎo)致棧溢出結(jié)構(gòu)體循環(huán)引用改為 ID 引用禁止 USTRUCT 里存指針7. 從“單次轉(zhuǎn)換”到“統(tǒng)一序列化層”的工程化思考寫到這里這個(gè)工具函數(shù)單看已經(jīng)能用了但它會在項(xiàng)目里到處被調(diào)用日志里用、存檔里用、網(wǎng)絡(luò)包里也用。一旦出現(xiàn)了“存檔用 A 版本網(wǎng)絡(luò)用 B 版本”的偏差排查起來就非常痛苦。所以我最后想分享的是工程層面的體會。我一般會在項(xiàng)目里再抽象一層IFJsonSerializable或者一個(gè)專門負(fù)責(zé)序列化的USubsystem它的職責(zé)不是“怎么轉(zhuǎn)”而是“哪些類該用什么規(guī)則轉(zhuǎn)”。比如某一類存檔結(jié)構(gòu)體在導(dǎo)出前要加版本號和 CRC某一類網(wǎng)絡(luò)請求體在導(dǎo)出前要把 DateTime 格式統(tǒng)一成 ISO8601。這些規(guī)則如果散落在各個(gè)調(diào)用點(diǎn)后期維護(hù)就是災(zāi)難。集中到一個(gè)統(tǒng)一模塊后規(guī)則可以測試、可以配置、也可以在切換后端協(xié)議時(shí)做一次性重寫。從我在幾個(gè)項(xiàng)目里的實(shí)測結(jié)果來看花一下午把這個(gè)小工具打磨成可配置的序列化層后續(xù)省下來的排障時(shí)間遠(yuǎn)超投入。它不像戰(zhàn)斗系統(tǒng)、渲染管線那么引人注目卻是存檔兼容、前后端聯(lián)調(diào)、數(shù)據(jù)排查這些環(huán)節(jié)的地基工程。所以如果你現(xiàn)在正在做 USTRUCT 轉(zhuǎn) JSON 的功能別止步于“能轉(zhuǎn)出字符串”多想想你的數(shù)據(jù)結(jié)構(gòu)有多少種變體、誰來提供契約、字段變更時(shí)怎么灰度那才是這個(gè)功能的真正價(jià)值所在。 UE中USTRUCT轉(zhuǎn)JSON字符串的完整實(shí)現(xiàn)與避坑指南
1. 項(xiàng)目概述與核心需求拆解1.1 這個(gè)需求到底在解決什么問題USTRUCT 是 Unreal Engine 里進(jìn)行數(shù)據(jù)組織和網(wǎng)絡(luò)同步的基礎(chǔ)單元而 JSON 是跨語言、跨平臺交換數(shù)據(jù)時(shí)幾乎繞不開的文本格式。把 USTRUCT 實(shí)例對象轉(zhuǎn)成 JSON 字符串最典型的場景包括把服務(wù)端返回的數(shù)據(jù)持久化成配置文件、把玩家存檔以 JSON 明文形式導(dǎo)出以便調(diào)試、把藍(lán)圖/ C 里計(jì)算的復(fù)雜結(jié)構(gòu)體推送給 Web 前端、或者把一整套戰(zhàn)斗統(tǒng)計(jì)數(shù)據(jù)序列化后塞進(jìn) HTTP 請求體里。很多剛接觸 UE 序列化的開發(fā)者會下意識地去找一個(gè)“一鍵轉(zhuǎn)換”的內(nèi)置藍(lán)圖節(jié)點(diǎn)但實(shí)際動手之后就會發(fā)現(xiàn)UE 官方并沒有提供完整的 “UStruct To JSON String” 的傻瓜式全自動方案。自帶的FJsonObjectConverter::UStructToJsonObject能做結(jié)構(gòu)體到 JSON 對象的轉(zhuǎn)換但它輸出的是一棵FJsonObject對象樹而不是一個(gè)可以直接發(fā)給后端的字符串。你需要再調(diào)Serialize或者TJsonWriter做一步序列化。這個(gè)中間步驟的缺失恰恰是很多新手在論壇上反復(fù)提問的原因。除此之外USTRUCT 里能裝的類型很多嵌套結(jié)構(gòu)體、數(shù)組、TMap、TSet、bool、enum class、FVector、FRotator、FDateTime等等。每種類型的 JSON 表現(xiàn)形態(tài)都不一樣處理不當(dāng)就會出現(xiàn)字段丟失或者類型轉(zhuǎn)換異常。我見過有人用UKismetSystemLibrary::Conv_StringToObject這類節(jié)點(diǎn)試圖硬轉(zhuǎn)結(jié)果在編輯器里可能有效打包后因?yàn)榉瓷湫畔⒉蝗蛘邲]有正確的序列化標(biāo)記數(shù)據(jù)直接變空。所以這個(gè)項(xiàng)目標(biāo)題背后真正的核心需求是在 UE 的開發(fā)框架內(nèi)打通USTRUCT 反射系統(tǒng) → 通用 JSON 數(shù)據(jù)模型 → 純文本字符串這條鏈路而且要能裁剪出可配置、可擴(kuò)展、能解釋清楚每一步“為什么”的版本。1.2 適用人群與實(shí)際落地場景如果你是做 GamePlay 的需要把角色身上的裝備屬性面板導(dǎo)出一份“明文配置”給策劃校驗(yàn)這個(gè)方案很適用如果你是做客戶端網(wǎng)絡(luò)層的要把一條結(jié)構(gòu)化請求轉(zhuǎn)成 JSON 字符串進(jìn)行日志記錄或者加簽這個(gè)方案也很適用哪怕你只是想在編輯器工具腳本里批量把 DataTable 行數(shù)據(jù)轉(zhuǎn)成文件用于自動化測試用例生成同樣的思路可以復(fù)用。有一點(diǎn)要提前說明如果你只是有幾個(gè)固定字段、手寫拼接字符串就能解決的場景其實(shí)沒必要引入 FJsonObjectConverter。這個(gè)工具的本質(zhì)價(jià)值在于“反射驅(qū)動的泛型轉(zhuǎn)換”也就是任意 USTRUCT 丟進(jìn)去都能自動遍歷屬性。如果你面對的數(shù)據(jù)結(jié)構(gòu)是固定的那么手寫TSharedRefFJsonObject RootObj MakeSharedFJsonObject();然后一行行RootObj-SetStringField反而更直白也更好排錯(cuò)。但一旦結(jié)構(gòu)體多了、嵌套深了這種手寫方式就不可維護(hù)了。下面的方案權(quán)衡就是基于這兩種取舍來展開的。2. USTRUCT 與 JSON 之間的“翻譯”機(jī)制2.1 為什么不能直接調(diào)用 ToString做 UE 開發(fā)的人都知道每個(gè)USTRUCT在編譯期會被 UHTUnreal Header Tool掃描生成反射元數(shù)據(jù)包括屬性名、屬性類型、偏移量、標(biāo)記CPF_BlueprintVisible之類。這套反射系統(tǒng)是引擎所有序列化、網(wǎng)絡(luò)復(fù)制、編輯器細(xì)節(jié)面板的基石。JSON 序列化也建立在它之上遍歷屬性的反射信息讀取值再寫入FJsonObject。但這里有個(gè)關(guān)鍵點(diǎn)USTRUCT 本身沒有提供一個(gè)類似ToString的虛函數(shù)來約定“輸出我自己的 JSON”。它只是一個(gè)數(shù)據(jù)聚合體你說它是“待翻譯的原文”更合適。所以只能靠外部的轉(zhuǎn)換器來做翻譯。UE 內(nèi)置的FJsonObjectConverter就是這樣一個(gè)通用的外部翻譯機(jī)它掃描反射系統(tǒng)但多了一層“中間對象”FJsonValue的封裝。我可以打個(gè)比方USTRUCT像一份中英對照表的數(shù)據(jù)源里面有幾百行條目FJsonObjectConverter是翻譯官FJsonObject是翻譯后整理出的“中文版目錄”而最終的 JSON 字符串是把這份目錄用排版規(guī)則打印成文本文檔。你不能指望翻譯官直接把數(shù)據(jù)源變成打印好的文件中間總要有一步“整理成對象”的動作。2.2 FJsonObjectConverter 是“翻譯官”還是“排版工”深入看FJsonObjectConverter::UStructToJsonObject的源碼會發(fā)現(xiàn)它的職責(zé)非常單一根據(jù)反射信息把 USTRUCT 的每個(gè)屬性轉(zhuǎn)換成對應(yīng)的FJsonValue塞進(jìn)FJsonObject。它不管縮進(jìn)、不管換行、不管字符編碼那屬于TJsonWriter的活兒。FJsonObjectConverter底層的處理路徑大概是獲取 UStruct 的FStructProperty列表。遍歷每個(gè)屬性拿到屬性名和FProperty。根據(jù)FProperty的類型分派到不同的轉(zhuǎn)換函數(shù)比如FJsonObjectConverter::ConvertScalarFPropertyToJsonValue、ConvertArrayFPropertyToJsonValue、ConvertMapFPropertyToJsonValue等。調(diào)用FJsonObject::SetField寫入。所以要得到最終字符串還得再把FJsonObject交給FJsonSerializer::Serialize讓它識別 JSON 的標(biāo)準(zhǔn)語法輸出成字符串。分段來看整體功能鏈條是這樣FJsonObjectConverter::UStructToJsonObject - FJsonObject (對象樹) FJsonSerializer::Serialize(JsonObject, Writer) - FString (JSON 字符串)理解這個(gè)鏈條的最大好處是你可以隨時(shí)在中間插入“自定義字段”“過濾敏感字段”“統(tǒng)一加密”等步驟。后面講實(shí)操時(shí)我會重點(diǎn)利用這個(gè)中間層做可復(fù)用的封裝。2.3 字段名和 UPROPERTY 標(biāo)記的微妙關(guān)系FJsonObjectConverter默認(rèn)會使用 UPROPERTY 的名稱作為 JSON key。這意味著你原本的命名規(guī)范會直接暴露在 JSON 里。比如你在 C 里寫m_PlayerHealth或者PlayerHealth_JSON 里也會出現(xiàn)這種風(fēng)格的名字與前端團(tuán)隊(duì)約定俗成的player_health或者playerHealth不一致。要想改變這個(gè)名稱兩個(gè)常用方案在 UPROPERTY 上附加SerializeAs說明符這會在編輯器里提供一個(gè)字段名別名。在轉(zhuǎn)換前拷貝結(jié)構(gòu)體并重命名屬性不過這樣做會破壞反射的完整性更推薦用FJsonObjectConverter::CustomExportCallback來干預(yù)導(dǎo)出過程。實(shí)際項(xiàng)目里我傾向于這樣約定如果字段名需要對外不可變比如供外部存檔兼容那必須用SerializeAs如果只是內(nèi)部調(diào)試導(dǎo)出直接保持原有命名就好沒必要在工具鏈上過度設(shè)計(jì)。3. USTRUCT 與 JSON 字段映射的完整拆解3.1 基礎(chǔ)字段類型對照表這五個(gè)類型占掉了 90% 的工作量先列一張核心對照表這是我在實(shí)施這個(gè)功能時(shí)反復(fù)對源碼確認(rèn)過的結(jié)論USTRUCT/C 類型轉(zhuǎn)換后的 JSON 類型備注int32/int64/uint8NumberUE 內(nèi)部按JsonNumber處理如果你的值超出 JS 安全整數(shù)范圍2^53 – 1注意 Web 端解析精度丟失問題float/doubleNumber特別注意NaN、Infinity在標(biāo)準(zhǔn) JSON 里不合法序列化時(shí)可能會輸出怪異文本需要提前處理或過濾FString/FNameString一般情況下沒問題但如果你有特殊字符如引號、反斜杠TJsonWriter會自動轉(zhuǎn)義boolBool這里有個(gè)大坑USTRUCT 里的bool可能被 UHT 合并成 bitfield而bool bFlag : 1的轉(zhuǎn)換行為不同后面詳述枚舉UENUMNumber 或 String取決于你是否給枚舉設(shè)置了JsonEnumName或者在 UPROPERTY 上做了什么配置我自己實(shí)測下來int64和enum是問題最大的兩個(gè)。int64的原因不是 UE 轉(zhuǎn)不出來而是 JSON 標(biāo)準(zhǔn)本身沒有 64 位整數(shù)類型JS 里解析時(shí)容易丟失精度enum的原因則是很多人默認(rèn)轉(zhuǎn)成字符串名但實(shí)際上 UE 的默認(rèn)行為往往是把底層uint8值輸出形成了“我以為能讀結(jié)果看到一個(gè)數(shù)字”的困惑。3.2 嵌套結(jié)構(gòu)體和數(shù)組的“遞歸翻譯”邏輯FJsonObjectConverter對嵌套結(jié)構(gòu)體的處理方式其實(shí)是遞歸調(diào)用自身。這在閱讀源碼時(shí)很多人容易忽略它并不是“拍平”了映射到一個(gè)扁平的 JSON 對象里而是遇到一個(gè)內(nèi)部結(jié)構(gòu)體屬性時(shí)繼續(xù)為這個(gè)子結(jié)構(gòu)體創(chuàng)建子FJsonObject。舉個(gè)例子如果我有USTRUCT(BlueprintType) struct FInventoryItemData { GENERATED_BODY() UPROPERTY(EditAnywhere, BlueprintReadWrite) FString ItemName; UPROPERTY(EditAnywhere, BlueprintReadWrite) int32 StackCount; }; USTRUCT(BlueprintType) struct FPlayerSaveData { GENERATED_BODY() UPROPERTY(EditAnywhere, BlueprintReadWrite) int32 PlayerLevel; UPROPERTY(EditAnywhere, BlueprintReadWrite) TArrayFInventoryItemData InventoryItems; };那么轉(zhuǎn)換出的 JSON 大致長這樣{ PlayerLevel: 12, InventoryItems: [ { ItemName: 鐵劍, StackCount: 1 }, { ItemName: 治療藥水, StackCount: 3 } ] }這個(gè)遞歸邏輯的好處顯而易見只要你在 C 層把結(jié)構(gòu)體定義清楚嵌套層次再多轉(zhuǎn)換器都能自動展開。壞處也很直接如果結(jié)構(gòu)體內(nèi)部有循環(huán)引用比如結(jié)構(gòu)體里塞了一個(gè)指向自身的指針遞歸就會把棧擊穿。所以在設(shè)計(jì)數(shù)據(jù)結(jié)構(gòu)時(shí)指針型屬性盡量不要放在 USTRUCT 里用于序列化而是改為 ID 引用例如存ItemID而不是直接存UObject*。3.3 TMap 和 TSet 的 JSON 表現(xiàn)形態(tài)TMapFString, FString轉(zhuǎn)換后通常是一個(gè) JSON ObjectKey 作為屬性名Value 作為屬性值。這會帶來一個(gè)比較麻煩的問題如果 Key 不是字符串類型比如TMapint32, FStringFJsonObject無法直接表達(dá)整數(shù) Key最終會嘗試把它轉(zhuǎn)成字符串 Key。解析回來時(shí)你需要自己處理Atoi的轉(zhuǎn)換和可能的 Key 排序變化。TSet的情況更特殊它的 JSON 輸出往往是數(shù)組。這本身沒問題但要注意數(shù)組是有順序的而 TSet 的迭代順序在每次運(yùn)行之間可能不同。如果你拿這個(gè) JSON 當(dāng)緩存簽名或哈希依據(jù)就必須先給 TSet 排序否則簽名會因哈希順序抖動而頻繁失效。從工程經(jīng)驗(yàn)角度我的建議是序列化消息體時(shí)盡量避免直接用 TMap 和 TSet 作為頂級結(jié)構(gòu)它們適合被包在某個(gè)業(yè)務(wù)結(jié)構(gòu)里并且字段數(shù)量可控時(shí)使用。如果實(shí)在需要建議在序列化時(shí)統(tǒng)一排序或者干脆在 USTRUCT 里放TArrayFPairStruct代替雖然看起來不優(yōu)雅但兼容性和可預(yù)測性都更好。4. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 一個(gè)可直接落地的 UStructToJsonString 函數(shù)直接給結(jié)論這是我在項(xiàng)目里反復(fù)打磨過的一個(gè)通用函數(shù)兼顧了“單個(gè)結(jié)構(gòu)體”和“結(jié)構(gòu)體數(shù)組”兩種需求// Header #pragma once #include CoreMinimal.h #include Serialization/JsonSerializer.h #include JsonObjectConverter.h #include Kismet/BlueprintFunctionLibrary.h #include StructToJsonFunctionLibrary.generated.h UCLASS() class UStructToJsonFunctionLibrary : public UBlueprintFunctionLibrary { GENERATED_BODY() public: // 將單個(gè) USTRUCT 實(shí)例轉(zhuǎn)成 JSON 字符串 // 注意 TemplateType 必須是一個(gè) USTRUCT 類型 template typename StructType static FString ConvertStructToJsonString(const StructType InStruct, bool bPrettyPrint false, bool bIncludedDefaultValues false); }; template typename StructType FString UStructToJsonFunctionLibrary::ConvertStructToJsonString(const StructType InStruct, bool bPrettyPrint, bool bIncludedDefaultValues) { static_assert(TIsDerivedFromStructType, FStructBase::IsDerived, ConvertStructToJsonString 只支持 USTRUCT 類型); FString OutputString; // 第一步把 USTRUCT 翻譯成 FJsonObject // 注意第三參數(shù) bIncludedDefaultValues默認(rèn) false 表示跳過與默認(rèn)值完全相同的字段 TSharedRefFJsonObject JsonObject FJsonObjectConverter::UStructToJsonObject( StructType::StaticStruct(), InStruct, 0, 0, bIncludedDefaultValues ); // 第二步把 FJsonObject 序列化成字符串 TSharedRefTJsonWriterTCHAR, TPrettyJsonPrintPolicyTCHAR JsonWriter ...; // 根據(jù) bPrettyPrint 決定使用緊湊輸出還是美化輸出 if (bPrettyPrint) { TSharedRefTJsonWriterTCHAR, TPrettyJsonPrintPolicyTCHAR PrettyWriter TJsonWriterFactoryTCHAR, TPrettyJsonPrintPolicyTCHAR::Create(OutputString); if (!FJsonSerializer::Serialize(JsonObject, PrettyWriter)) { UE_LOG(LogTemp, Error, TEXT(結(jié)構(gòu)體轉(zhuǎn) JSON 字符串序列化失敗)); return TEXT({}); } } else { TSharedRefTJsonWriterTCHAR, TCondensedJsonPrintPolicyTCHAR CondensedWriter TJsonWriterFactoryTCHAR, TCondensedJsonPrintPolicyTCHAR::Create(OutputString); if (!FJsonSerializer::Serialize(JsonObject, CondensedWriter)) { UE_LOG(LogTemp, Error, TEXT(結(jié)構(gòu)體轉(zhuǎn) JSON 字符串序列化失敗)); return TEXT({}); } } return OutputString; }4.2 參數(shù)選擇的細(xì)節(jié)0 和 0 是什么意思很多人第一次看到UStructToJsonObject的四參版本時(shí)會暈?zāi)莾蓚€(gè)0分別是CheckFlags和SkipFlags。它們決定了哪些屬性標(biāo)記會影響序列化CheckFlags第一個(gè)0指定必須包含的屬性標(biāo)記一般傳0表示“不過濾”。SkipFlags第二個(gè)0指定必須跳過的屬性標(biāo)記傳0表示“全部都轉(zhuǎn)”。如果你想跳過所有EditInstanceOnly的屬性可以這樣寫EPropertyFlags SkipFlags CPF_Edit | CPF_BlueprintVisible; TSharedRefFJsonObject JsonObject FJsonObjectConverter::UStructToJsonObject( StructType::StaticStruct(), InStruct, 0, SkipFlags, false );這個(gè)標(biāo)志位機(jī)制非常有用但在普通業(yè)務(wù)代碼里很容易被忽略。我建議在封裝函數(shù)時(shí)增加一個(gè)TSetEPropertyFlags參數(shù)把需求變化的可能留出來而不是寫死0, 0。4.3 Blueprint 側(cè)如何調(diào)用由于模板函數(shù)沒法直接暴露給藍(lán)圖常見的做法是提供一個(gè)普通參數(shù)版本比如傳const FGenericStructWrapper或者直接把常用結(jié)構(gòu)體打包成幾個(gè)重載函數(shù)。不過 UE 的藍(lán)圖函數(shù)庫支持自定義結(jié)構(gòu)體作為參數(shù)琥珀色地“動態(tài)”轉(zhuǎn)換的函數(shù)還是比較麻煩。最實(shí)用的是這樣如果你只需要導(dǎo)出幾個(gè)固定結(jié)構(gòu)體就寫幾個(gè)顯式包裝函數(shù)UFUNCTION(BlueprintPure, Category Json|Struct) static FString ConvertInventoryDataToJson(const FInventoryItemData Data, bool bPrettyPrint false);每個(gè)函數(shù)內(nèi)部調(diào)用模板函數(shù)。這樣做的好處藍(lán)圖節(jié)點(diǎn)有明顯的輸入輸出參數(shù)類型是強(qiáng)類型不容易接錯(cuò)同時(shí)在 C 層保持了泛型轉(zhuǎn)換的靈活性。要是你想做一個(gè)“傳任何結(jié)構(gòu)體都行”的泛型藍(lán)圖節(jié)點(diǎn)需要引入U(xiǎn)K2Node自定義節(jié)點(diǎn)工作量大不少不建議一開始就投入除非項(xiàng)目里這種需求非常多。4.4 實(shí)際項(xiàng)目中的輸出示例簡單與嵌套結(jié)構(gòu)用上面的FInventoryItemData跑一遍緊湊輸出大概是{ItemName:鐵劍,StackCount:1}用FPlayerSaveData跑一遍緊湊輸出大概是{PlayerLevel:12,InventoryItems:[{ItemName:鐵劍,StackCount:1},{ItemName:治療藥水,StackCount:3}]}美化了之后{ PlayerLevel: 12, InventoryItems: [ { ItemName: 鐵劍, StackCount: 1 }, { ItemName: 治療藥水, StackCount: 3 } ] }有一個(gè)細(xì)節(jié)值得注意緊湊輸出更適合用來做日志、做緩存 key因?yàn)槲谋倔w積小、不會引入多余的空白符美化輸出更適合給測試人員或策劃人員閱讀用來排查配置錯(cuò)誤。5. 類型收斂與特殊場景處理5.1 bool 字段的“隱藏陷阱”如果 USTRUCT 里的bool屬性沒有單獨(dú)加uint8或: 1位域聲明UHT 在某些編譯設(shè)置下會把它視作普通屬性。一旦你攃雜了 bitfield比如UPROPERTY(EditAnywhere, BlueprintReadWrite) bool bIsAlive : 1;在某些引擎版本里反射系統(tǒng)會把它當(dāng)成一個(gè)獨(dú)立的布爾屬性處理但底層存儲是和旁邊的其他 bitfield 布爾擠在一起的。此時(shí)如果項(xiàng)目里混用老代碼轉(zhuǎn) JSON 時(shí)可能會出現(xiàn)“值不對”的情況但排查起來異常困難因?yàn)槟阍谡{(diào)試器里看結(jié)構(gòu)體里的值是正常的。我的建議是能不用 bitfield 就不用 bitfield。特別是涉及存檔/網(wǎng)絡(luò)同步的數(shù)據(jù)結(jié)構(gòu)一個(gè) bool 占 4 字節(jié)和占 1 bit在絕大多數(shù)業(yè)務(wù)場景里根本不值得省那點(diǎn)內(nèi)存。改成普通 bool 后序列化的確定性大幅提升也讓 FJsonObjectConverter 少一層意外。5.2 枚舉到底該轉(zhuǎn)數(shù)字還是字符串默認(rèn)行為下枚舉會被轉(zhuǎn)成底層數(shù)值。這在 UE 里沒什么問題因?yàn)樽x取回來時(shí)可以static_castEYourEnum(JsonValue-AsNumber())。但 JSON 的接收方一旦換了語言、換了框架他看到的只是一個(gè)數(shù)字可讀性極差尤其當(dāng)枚舉項(xiàng)有幾十個(gè)的時(shí)候必須維護(hù)一份“數(shù)字?含義”的對照表。想讓枚舉變成字符串可以在枚舉聲明上做文章UENUM(BlueprintType, JsonSerializeAsString) enum class EEquipmentSlot : uint8 { Head, Chest, Legs };加了JsonSerializeAsString后FJsonObjectConverter在序列化時(shí)會把枚舉名作為字符串輸出。這個(gè)標(biāo)記在新版引擎里是支持的如果你用的引擎沒有就需要自己重寫導(dǎo)出回調(diào)把枚舉值映射到約定字符串。開發(fā)時(shí)我一般優(yōu)先用字符串除非和外部系統(tǒng)有明確的二進(jìn)制壓縮要求因?yàn)樽址耪咸奖懔恕?.3 FVector、FRotator、FLinearColor 怎么處理這些引擎內(nèi)置結(jié)構(gòu)體很特殊它們既有USTRUCT的反射元數(shù)據(jù)但業(yè)務(wù)上又經(jīng)常被當(dāng)成“基礎(chǔ)標(biāo)量”處理。FJsonObjectConverter默認(rèn)會把它們轉(zhuǎn)成嵌套對象例如FVector會變成{ X: 1.0, Y: 2.0, Z: 3.0 }這本身沒有錯(cuò)但很多外部接口更希望收到一個(gè)數(shù)組比如[1.0, 2.0, 3.0]或者一個(gè)帶精度控制的定制格式。這種情況我建議你不要去改轉(zhuǎn)換器全局行為而是讓業(yè)務(wù)結(jié)構(gòu)體自己承載序列化格式USTRUCT(BlueprintType) struct FPositionPayload { GENERATED_BODY() UPROPERTY() TArrayfloat Coords; };然后從FVector轉(zhuǎn)成Coords。這樣做的代價(jià)是要寫幾個(gè)轉(zhuǎn)換函數(shù)但收益是 JSON 契約完全可控不再依賴引擎的默認(rèn)表達(dá)。5.4 FDateTime 與 FGuidFDateTime在 JSON 里默認(rèn)輸出的是Ticks或毫秒時(shí)間戳外部系統(tǒng)看到一串長數(shù)字非常不友好。我更習(xí)慣把日期時(shí)間字段在 USTRUCT 里聲明為FString業(yè)務(wù)層負(fù)責(zé)格式化這樣前端不用再做時(shí)間戳解析。FGuid默認(rèn)會轉(zhuǎn)成字符串這個(gè)基本沒有坑但要注意字符串里的大小寫風(fēng)格ToString(EGuidFormats::DigitsWithHyphens)和默認(rèn)輸出不完全一樣。為了契約統(tǒng)一建議統(tǒng)一走一次規(guī)范化再入庫。6. 常見問題與排查技巧實(shí)錄6.1 轉(zhuǎn)出來是空對象 “{}”最經(jīng)典的原因結(jié)構(gòu)體類型沒有加USTRUCT標(biāo)記或者屬性沒有加UPROPERTY。反射系統(tǒng)遍歷的就是這些元數(shù)據(jù)只要標(biāo)記缺失屬性就會被跳過。檢查時(shí)不要只看代碼里有沒有USTRUCT還要確認(rèn)整個(gè)類在頭文件里被 UHT 正確處理過。一個(gè)有效的確認(rèn)方法在編輯器里隨便拖一個(gè)該結(jié)構(gòu)體變量到藍(lán)圖節(jié)點(diǎn)上如果能正常選擇其成員反射就沒問題如果不能就是 UHT 沒有識別。還有一個(gè)容易忽略的情況USTRUCT 定義在.cpp文件里。UHT 默認(rèn)只掃描.h中的聲明放在.cpp里的結(jié)構(gòu)體在某些版本里能編譯但反射不完整序列化出來就是空對象。所以USTRUCT 必須放在頭文件里這一條務(wù)必寫進(jìn)團(tuán)隊(duì)規(guī)范。6.2 int64 數(shù)值末尾的精度丟失如果你把int64轉(zhuǎn)成 JSON Number然后用 Javascript 的JSON.parse解析數(shù)字超過Number.MAX_SAFE_INTEGER時(shí)精度會丟。這已經(jīng)不是 UE 的問題而是 JSON 格式本身沒有“bigint”概念。如果業(yè)務(wù)里確實(shí)有大數(shù)據(jù) ID建議用FString存儲或者序列化時(shí)專門寫成帶后綴的大數(shù)字字符串比如999999999999999999讓接收方自行決定解析策略。6.3 特殊字符和編譯器的“UTF-8 BOM”問題輸出中文或特殊字符到 JSON 時(shí)TJsonWriter默認(rèn)支持FString內(nèi)碼到 UTF-8 的轉(zhuǎn)換但如果你把字符串直接打印到控制臺或者 Windows 下的命令行會出現(xiàn)亂碼。這通常是控制臺代碼頁問題不是 JSON 序列化的問題。用文本文件保存 JSON 時(shí)優(yōu)先選用帶 BOM 的 UTF-8否則某些低版本的工具特別是記事本老版本會視為 ANSI。6.4 嵌套數(shù)組很大時(shí)為何性能掉得厲害FJsonObjectConverter需要遍歷反射元數(shù)據(jù)并為每個(gè)字段創(chuàng)建智能指針對象字段多了之后裝箱開銷不小。如果你一個(gè)結(jié)構(gòu)體里嵌套了成千上萬個(gè)元素每幀都轉(zhuǎn)換性能會非常難看。排查時(shí)可以用Stats或者簡單的FPlatformTime::Cycles前后差值統(tǒng)計(jì)。結(jié)論通常不是“轉(zhuǎn)換器太慢”而是“調(diào)用頻率太高”或者“單次數(shù)據(jù)量太大”。優(yōu)化手段也簡單適合分批轉(zhuǎn)換、延遲轉(zhuǎn)換、或者緩存轉(zhuǎn)換結(jié)果而不是換一個(gè)更快的 JSON 庫。6.5 常見問題速查表現(xiàn)象可能原因處理辦法轉(zhuǎn)出來是{}USTRUCT 或 UPROPERTY 缺失/UHT 未識別確認(rèn)結(jié)構(gòu)體在頭文件屬性全部加 UPROPERTYEnum 輸出數(shù)字而非字符串未加JsonSerializeAsString或版本不支持改用 CustomExport或在結(jié)構(gòu)體上做字符串映射TArray 順序錯(cuò)亂使用了 TSet 或?qū)?TArray 做了并發(fā)寫確認(rèn)容器類型TSet 需排序?qū)С鋈掌谧兂梢淮當(dāng)?shù)字FDateTime 默認(rèn)走時(shí)間戳業(yè)務(wù)上用 FString 保存格式化日期嵌套太深導(dǎo)致棧溢出結(jié)構(gòu)體循環(huán)引用改為 ID 引用禁止 USTRUCT 里存指針7. 從“單次轉(zhuǎn)換”到“統(tǒng)一序列化層”的工程化思考寫到這里這個(gè)工具函數(shù)單看已經(jīng)能用了但它會在項(xiàng)目里到處被調(diào)用日志里用、存檔里用、網(wǎng)絡(luò)包里也用。一旦出現(xiàn)了“存檔用 A 版本網(wǎng)絡(luò)用 B 版本”的偏差排查起來就非常痛苦。所以我最后想分享的是工程層面的體會。我一般會在項(xiàng)目里再抽象一層IFJsonSerializable或者一個(gè)專門負(fù)責(zé)序列化的USubsystem它的職責(zé)不是“怎么轉(zhuǎn)”而是“哪些類該用什么規(guī)則轉(zhuǎn)”。比如某一類存檔結(jié)構(gòu)體在導(dǎo)出前要加版本號和 CRC某一類網(wǎng)絡(luò)請求體在導(dǎo)出前要把 DateTime 格式統(tǒng)一成 ISO8601。這些規(guī)則如果散落在各個(gè)調(diào)用點(diǎn)后期維護(hù)就是災(zāi)難。集中到一個(gè)統(tǒng)一模塊后規(guī)則可以測試、可以配置、也可以在切換后端協(xié)議時(shí)做一次性重寫。從我在幾個(gè)項(xiàng)目里的實(shí)測結(jié)果來看花一下午把這個(gè)小工具打磨成可配置的序列化層后續(xù)省下來的排障時(shí)間遠(yuǎn)超投入。它不像戰(zhàn)斗系統(tǒng)、渲染管線那么引人注目卻是存檔兼容、前后端聯(lián)調(diào)、數(shù)據(jù)排查這些環(huán)節(jié)的地基工程。所以如果你現(xiàn)在正在做 USTRUCT 轉(zhuǎn) JSON 的功能別止步于“能轉(zhuǎn)出字符串”多想想你的數(shù)據(jù)結(jié)構(gòu)有多少種變體、誰來提供契約、字段變更時(shí)怎么灰度那才是這個(gè)功能的真正價(jià)值所在。