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