GFramework/docs/zh-CN/game/serialization.md

title, description

title	description
序列化系统	序列化系统提供了统一的对象序列化和反序列化接口，支持 JSON 格式和运行时类型处理。

序列化系统

概述

序列化系统是 GFramework.Game 中用于对象序列化和反序列化的核心组件。它提供了统一的序列化接口，支持将对象转换为字符串格式（如 JSON）进行存储或传输，并能够将字符串数据还原为对象。

序列化系统与数据存储、配置管理、存档系统等模块深度集成，为游戏数据的持久化提供了基础支持。

主要特性：

• 统一的序列化接口
• JSON 格式支持
• 运行时类型序列化
• 泛型和非泛型 API
• 与存储系统无缝集成
• 类型安全的反序列化

核心概念

序列化器接口

ISerializer 定义了基本的序列化操作：

public interface ISerializer : IUtility
{
    // 将对象序列化为字符串
    string Serialize<T>(T value);

    // 将字符串反序列化为对象
    T Deserialize<T>(string data);
}

运行时类型序列化器

IRuntimeTypeSerializer 扩展了基本接口，支持运行时类型处理：

public interface IRuntimeTypeSerializer : ISerializer
{
    // 使用运行时类型序列化对象
    string Serialize(object obj, Type type);

    // 使用运行时类型反序列化对象
    object Deserialize(string data, Type type);
}

JSON 序列化器

JsonSerializer 是基于 Newtonsoft.Json 的实现：

public sealed class JsonSerializer : IRuntimeTypeSerializer
{
    string Serialize<T>(T value);
    T Deserialize<T>(string data);
    string Serialize(object obj, Type type);
    object Deserialize(string data, Type type);
}

基本用法

注册序列化器

在架构中注册序列化器：

using GFramework.Core.Abstractions.Serializer;
using GFramework.Game.Serializer;

public class GameArchitecture : Architecture
{
    protected override void Init()
    {
        // 注册 JSON 序列化器
        var jsonSerializer = new JsonSerializer();
        RegisterUtility<ISerializer>(jsonSerializer);
        RegisterUtility<IRuntimeTypeSerializer>(jsonSerializer);
    }
}

序列化对象

使用泛型 API 序列化对象：

using GFramework.SourceGenerators.Abstractions.Rule;

public class PlayerData
{
    public string Name { get; set; }
    public int Level { get; set; }
    public int Experience { get; set; }
}

[ContextAware]
public partial class SaveController : IController
{
    public void SavePlayer()
    {
        var serializer = this.GetUtility<ISerializer>();

        var player = new PlayerData
        {
            Name = "Player1",
            Level = 10,
            Experience = 1000
        };

        // 序列化为 JSON 字符串
        string json = serializer.Serialize(player);
        Console.WriteLine(json);
        // 输出: {"Name":"Player1","Level":10,"Experience":1000}
    }
}

反序列化对象

从字符串还原对象：

public void LoadPlayer()
{
    var serializer = this.GetUtility<ISerializer>();

    string json = "{\"Name\":\"Player1\",\"Level\":10,\"Experience\":1000}";

    // 反序列化为对象
    var player = serializer.Deserialize<PlayerData>(json);

    Console.WriteLine($"玩家: {player.Name}, 等级: {player.Level}");
}

运行时类型序列化

处理不确定类型的对象：

public void SerializeRuntimeType()
{
    var serializer = this.GetUtility<IRuntimeTypeSerializer>();

    object data = new PlayerData { Name = "Player1", Level = 10 };
    Type dataType = data.GetType();

    // 使用运行时类型序列化
    string json = serializer.Serialize(data, dataType);

    // 使用运行时类型反序列化
    object restored = serializer.Deserialize(json, dataType);

    var player = restored as PlayerData;
    Console.WriteLine($"玩家: {player?.Name}");
}

高级用法

与存储系统集成

序列化器与存储系统配合使用：

using GFramework.Core.Abstractions.Storage;
using GFramework.Game.Storage;
using GFramework.SourceGenerators.Abstractions.Rule;

[ContextAware]
public partial class DataManager : IController
{
    public async Task SaveData()
    {
        var serializer = this.GetUtility<ISerializer>();
        var storage = this.GetUtility<IStorage>();

        var gameData = new GameData
        {
            Score = 1000,
            Coins = 500
        };

        // 序列化数据
        string json = serializer.Serialize(gameData);

        // 写入存储
        await storage.WriteAsync("game_data", json);
    }

    public async Task<GameData> LoadData()
    {
        var serializer = this.GetUtility<ISerializer>();
        var storage = this.GetUtility<IStorage>();

        // 从存储读取
        string json = await storage.ReadAsync<string>("game_data");

        // 反序列化数据
        return serializer.Deserialize<GameData>(json);
    }
}

序列化复杂对象

处理嵌套和集合类型：

public class InventoryData
{
    public List<ItemData> Items { get; set; }
    public Dictionary<string, int> Resources { get; set; }
}

public class ItemData
{
    public string Id { get; set; }
    public string Name { get; set; }
    public int Quantity { get; set; }
}

public void SerializeComplexData()
{
    var serializer = this.GetUtility<ISerializer>();

    var inventory = new InventoryData
    {
        Items = new List<ItemData>
        {
            new ItemData { Id = "sword_01", Name = "铁剑", Quantity = 1 },
            new ItemData { Id = "potion_hp", Name = "生命药水", Quantity = 5 }
        },
        Resources = new Dictionary<string, int>
        {
            { "gold", 1000 },
            { "wood", 500 }
        }
    };

    // 序列化复杂对象
    string json = serializer.Serialize(inventory);

    // 反序列化
    var restored = serializer.Deserialize<InventoryData>(json);

    Console.WriteLine($"物品数量: {restored.Items.Count}");
    Console.WriteLine($"金币: {restored.Resources["gold"]}");
}

处理多态类型

序列化继承层次结构：

public abstract class EntityData
{
    public string Id { get; set; }
    public string Type { get; set; }
}

public class PlayerEntityData : EntityData
{
    public int Level { get; set; }
    public int Experience { get; set; }
}

public class EnemyEntityData : EntityData
{
    public int Health { get; set; }
    public int Damage { get; set; }
}

public void SerializePolymorphic()
{
    var serializer = this.GetUtility<IRuntimeTypeSerializer>();

    // 创建不同类型的实体
    EntityData player = new PlayerEntityData
    {
        Id = "player_1",
        Type = "Player",
        Level = 10,
        Experience = 1000
    };

    EntityData enemy = new EnemyEntityData
    {
        Id = "enemy_1",
        Type = "Enemy",
        Health = 100,
        Damage = 20
    };

    // 使用运行时类型序列化
    string playerJson = serializer.Serialize(player, player.GetType());
    string enemyJson = serializer.Serialize(enemy, enemy.GetType());

    // 根据类型反序列化
    var restoredPlayer = serializer.Deserialize(playerJson, typeof(PlayerEntityData));
    var restoredEnemy = serializer.Deserialize(enemyJson, typeof(EnemyEntityData));
}

自定义序列化逻辑

虽然 GFramework 使用 Newtonsoft.Json，但你可以通过特性控制序列化行为：

using Newtonsoft.Json;

public class CustomData
{
    // 忽略此属性
    [JsonIgnore]
    public string InternalId { get; set; }

    // 使用不同的属性名
    [JsonProperty("player_name")]
    public string Name { get; set; }

    // 仅在值不为 null 时序列化
    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public string? OptionalField { get; set; }

    // 格式化日期
    [JsonProperty("created_at")]
    [JsonConverter(typeof(IsoDateTimeConverter))]
    public DateTime CreatedAt { get; set; }
}

批量序列化

处理多个对象的序列化：

public async Task SaveMultipleData()
{
    var serializer = this.GetUtility<ISerializer>();
    var storage = this.GetUtility<IStorage>();

    var dataList = new Dictionary<string, object>
    {
        { "player", new PlayerData { Name = "Player1", Level = 10 } },
        { "inventory", new InventoryData { Items = new List<ItemData>() } },
        { "settings", new SettingsData { Volume = 0.8f } }
    };

    // 批量序列化和保存
    foreach (var (key, data) in dataList)
    {
        string json = serializer.Serialize(data);
        await storage.WriteAsync(key, json);
    }

    Console.WriteLine($"已保存 {dataList.Count} 个数据文件");
}

错误处理

处理序列化和反序列化错误：

public void SafeDeserialize()
{
    var serializer = this.GetUtility<ISerializer>();

    string json = "{\"Name\":\"Player1\",\"Level\":\"invalid\"}"; // 错误的数据

    try
    {
        var player = serializer.Deserialize<PlayerData>(json);
    }
    catch (ArgumentException ex)
    {
        Console.WriteLine($"反序列化失败: {ex.Message}");
        // 返回默认值或重新尝试
    }
    catch (JsonException ex)
    {
        Console.WriteLine($"JSON 格式错误: {ex.Message}");
    }
}

public PlayerData DeserializeWithFallback(string json)
{
    var serializer = this.GetUtility<ISerializer>();

    try
    {
        return serializer.Deserialize<PlayerData>(json);
    }
    catch
    {
        // 返回默认数据
        return new PlayerData
        {
            Name = "DefaultPlayer",
            Level = 1,
            Experience = 0
        };
    }
}

版本兼容性

处理数据结构变化：

// 旧版本数据
public class PlayerDataV1
{
    public string Name { get; set; }
    public int Level { get; set; }
}

// 新版本数据（添加了新字段）
public class PlayerDataV2
{
    public string Name { get; set; }
    public int Level { get; set; }
    public int Experience { get; set; } = 0;  // 新增字段，提供默认值
    public DateTime LastLogin { get; set; } = DateTime.Now;  // 新增字段
}

public PlayerDataV2 LoadWithMigration(string json)
{
    var serializer = this.GetUtility<ISerializer>();

    try
    {
        // 尝试加载新版本
        return serializer.Deserialize<PlayerDataV2>(json);
    }
    catch
    {
        // 如果失败，尝试加载旧版本并迁移
        var oldData = serializer.Deserialize<PlayerDataV1>(json);
        return new PlayerDataV2
        {
            Name = oldData.Name,
            Level = oldData.Level,
            Experience = oldData.Level * 100,  // 根据等级计算经验
            LastLogin = DateTime.Now
        };
    }
}

最佳实践

1. 使用接口而非具体类型：依赖 ISerializer 接口

   ✓ var serializer = this.GetUtility<ISerializer>();
   ✗ var serializer = new JsonSerializer(); // 避免直接实例化
   

2. 为数据类提供默认值：确保反序列化的健壮性

   public class GameData
   {
       public string Name { get; set; } = "Default";
       public int Score { get; set; } = 0;
       public List<string> Items { get; set; } = new();
   }
   

3. 处理反序列化异常：避免程序崩溃

   try
   {
       var data = serializer.Deserialize<GameData>(json);
   }
   catch (Exception ex)
   {
       Logger.Error($"反序列化失败: {ex.Message}");
       return GetDefaultData();
   }
   

4. 避免序列化敏感数据：使用 [JsonIgnore] 标记

   public class UserData
   {
       public string Username { get; set; }
   
       [JsonIgnore]
       public string Password { get; set; }  // 不序列化密码
   }
   

5. 使用运行时类型处理多态：保持类型信息

   var serializer = this.GetUtility<IRuntimeTypeSerializer>();
   string json = serializer.Serialize(obj, obj.GetType());
   

6. 验证反序列化的数据：确保数据完整性

   var data = serializer.Deserialize<GameData>(json);
   if (string.IsNullOrEmpty(data.Name) || data.Score < 0)
   {
       throw new InvalidDataException("数据验证失败");
   }
   

性能优化

减少序列化开销

// 避免频繁序列化大对象
public class CachedSerializer
{
    private string? _cachedJson;
    private GameData? _cachedData;

    public string GetJson(GameData data)
    {
        if (_cachedData == data && _cachedJson != null)
        {
            return _cachedJson;
        }

        var serializer = GetSerializer();
        _cachedJson = serializer.Serialize(data);
        _cachedData = data;
        return _cachedJson;
    }
}

异步序列化

public async Task SaveDataAsync()
{
    var serializer = this.GetUtility<ISerializer>();
    var storage = this.GetUtility<IStorage>();

    var data = GetLargeData();

    // 在后台线程序列化
    string json = await Task.Run(() => serializer.Serialize(data));

    // 异步写入存储
    await storage.WriteAsync("large_data", json);
}

分块序列化

public async Task SaveLargeDataset()
{
    var serializer = this.GetUtility<ISerializer>();
    var storage = this.GetUtility<IStorage>();

    var largeDataset = GetLargeDataset();

    // 分块保存
    const int chunkSize = 100;
    for (int i = 0; i < largeDataset.Count; i += chunkSize)
    {
        var chunk = largeDataset.Skip(i).Take(chunkSize).ToList();
        string json = serializer.Serialize(chunk);
        await storage.WriteAsync($"data_chunk_{i / chunkSize}", json);
    }
}

常见问题

问题：如何序列化循环引用的对象？

解答： Newtonsoft.Json 默认不支持循环引用，需要配置：

// 注意：GFramework 的 JsonSerializer 使用默认设置
// 如需处理循环引用，避免创建循环引用的数据结构
// 或使用 [JsonIgnore] 打破循环

public class Node
{
    public string Name { get; set; }
    public List<Node> Children { get; set; }

    [JsonIgnore]  // 忽略父节点引用，避免循环
    public Node? Parent { get; set; }
}

问题：序列化后的 JSON 太大怎么办？

解答： 使用压缩或分块存储：

public async Task SaveCompressed()
{
    var serializer = this.GetUtility<ISerializer>();
    var storage = this.GetUtility<IStorage>();

    var data = GetLargeData();
    string json = serializer.Serialize(data);

    // 压缩 JSON
    byte[] compressed = Compress(json);

    // 保存压缩数据
    await storage.WriteAsync("data_compressed", compressed);
}

private byte[] Compress(string text)
{
    using var output = new MemoryStream();
    using (var gzip = new GZipStream(output, CompressionMode.Compress))
    using (var writer = new StreamWriter(gzip))
    {
        writer.Write(text);
    }
    return output.ToArray();
}

问题：如何处理不同平台的序列化差异？

解答： 使用平台无关的数据类型：

public class CrossPlatformData
{
    // 使用 string 而非 DateTime（避免时区问题）
    public string CreatedAt { get; set; } = DateTime.UtcNow.ToString("O");

    // 使用 double 而非 float（精度一致）
    public double Score { get; set; }

    // 明确指定编码
    public string Text { get; set; }
}

问题：反序列化失败时如何恢复？

解答： 实现备份和恢复机制：

public async Task<GameData> LoadWithBackup(string key)
{
    var serializer = this.GetUtility<ISerializer>();
    var storage = this.GetUtility<IStorage>();

    try
    {
        // 尝试加载主数据
        string json = await storage.ReadAsync<string>(key);
        return serializer.Deserialize<GameData>(json);
    }
    catch
    {
        // 尝试加载备份
        try
        {
            string backupJson = await storage.ReadAsync<string>($"{key}_backup");
            return serializer.Deserialize<GameData>(backupJson);
        }
        catch
        {
            // 返回默认数据
            return new GameData();
        }
    }
}

问题：如何加密序列化的数据？

解答： 在序列化后加密：

public async Task SaveEncrypted(string key, GameData data)
{
    var serializer = this.GetUtility<ISerializer>();
    var storage = this.GetUtility<IStorage>();

    // 序列化
    string json = serializer.Serialize(data);

    // 加密
    byte[] encrypted = EncryptString(json);

    // 保存
    await storage.WriteAsync(key, encrypted);
}

public async Task<GameData> LoadEncrypted(string key)
{
    var serializer = this.GetUtility<ISerializer>();
    var storage = this.GetUtility<IStorage>();

    // 读取
    byte[] encrypted = await storage.ReadAsync<byte[]>(key);

    // 解密
    string json = DecryptToString(encrypted);

    // 反序列化
    return serializer.Deserialize<GameData>(json);
}

问题：序列化器是线程安全的吗？

解答： JsonSerializer 本身是线程安全的，但建议通过架构的 Utility 系统访问：

// 线程安全的访问方式
public async Task ParallelSave()
{
    var tasks = Enumerable.Range(0, 10).Select(async i =>
    {
        var serializer = this.GetUtility<ISerializer>();
        var data = new GameData { Score = i };
        string json = serializer.Serialize(data);
        await SaveToStorage($"data_{i}", json);
    });

    await Task.WhenAll(tasks);
}

相关文档

• 数据与存档系统 - 数据持久化
• 存储系统 - 文件存储
• 设置系统 - 设置数据序列化
• Utility 系统 - 工具类注册