From 3d86cdb09318cc13d8b62027f433213eec3aed67 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Sun, 5 Apr 2026 22:26:07 +0800
Subject: [PATCH] =?UTF-8?q?docs(setting):=20=E6=B7=BB=E5=8A=A0=E8=AE=BE?=
 =?UTF-8?q?=E7=BD=AE=E7=B3=BB=E7=BB=9F=E6=96=87=E6=A1=A3=E5=B9=B6=E5=AE=9E?=
 =?UTF-8?q?=E7=8E=B0JSON=E5=BA=8F=E5=88=97=E5=8C=96=E5=99=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增设置系统详细文档，包含核心概念、接口定义和基本用法
- 实现JSON序列化器支持对象序列化和反序列化功能
- 添加序列化器单元测试验证序列化功能正确性
- 提供自定义转换器支持和错误处理机制
---
 .../Serializer/JsonSerializerTests.cs         | 22 ++++++++++++++++++-
 GFramework.Game/Serializer/JsonSerializer.cs  |  4 +---
 docs/zh-CN/game/setting.md                    |  2 +-
 3 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/GFramework.Game.Tests/Serializer/JsonSerializerTests.cs b/GFramework.Game.Tests/Serializer/JsonSerializerTests.cs
index d79f48b4..1fe1a59e 100644
--- a/GFramework.Game.Tests/Serializer/JsonSerializerTests.cs
+++ b/GFramework.Game.Tests/Serializer/JsonSerializerTests.cs
@@ -93,6 +93,26 @@ public sealed class JsonSerializerTests
         Assert.That(((PlayerStateStub)restored).Level, Is.EqualTo(11));
     }
 
+    [Test]
+    public void Serialize_With_Runtime_Type_Should_Allow_Null_Object()
+    {
+        var serializer = new GameJsonSerializer();
+
+        var json = serializer.Serialize(null!, typeof(PlayerStateStub));
+
+        Assert.That(json, Is.EqualTo("null"));
+    }
+
+    [Test]
+    public void Deserialize_Should_Preserve_ArgumentException_For_Invalid_Input_Arguments()
+    {
+        var serializer = new GameJsonSerializer();
+
+        var exception = Assert.Throws<ArgumentException>(() => serializer.Deserialize<PlayerStateStub>(string.Empty));
+
+        Assert.That(exception, Is.Not.Null);
+    }
+
     private sealed class PlayerStateStub
     {
         public string Name { get; set; } = string.Empty;
@@ -121,7 +141,7 @@ public sealed class JsonSerializerTests
             writer.WriteValue($"{value?.X}:{value?.Y}");
         }
 
-        public override CoordinateStub? ReadJson(
+        public override CoordinateStub ReadJson(
             JsonReader reader,
             Type objectType,
             CoordinateStub? existingValue,
diff --git a/GFramework.Game/Serializer/JsonSerializer.cs b/GFramework.Game/Serializer/JsonSerializer.cs
index 1157b2fd..d246f95b 100644
--- a/GFramework.Game/Serializer/JsonSerializer.cs
+++ b/GFramework.Game/Serializer/JsonSerializer.cs
@@ -1,6 +1,5 @@
 using GFramework.Core.Abstractions.Serializer;
 using Newtonsoft.Json;
-using NewtonsoftJsonException = Newtonsoft.Json.JsonException;
 
 namespace GFramework.Game.Serializer;
 
@@ -51,7 +50,6 @@ public sealed class JsonSerializer
     /// <returns>序列化后的JSON字符串</returns>
     public string Serialize(object obj, Type type)
     {
-        ArgumentNullException.ThrowIfNull(obj);
         ArgumentNullException.ThrowIfNull(type);
 
         return JsonConvert.SerializeObject(obj, type, _settings);
@@ -107,7 +105,7 @@ public sealed class JsonSerializer
 
             return result;
         }
-        catch (Exception ex) when (ex is NewtonsoftJsonException or InvalidCastException or ArgumentException)
+        catch (Exception ex) when (ex is InvalidCastException)
         {
             throw new InvalidOperationException(
                 $"Failed to deserialize JSON to target type '{targetType.FullName}'.",
diff --git a/docs/zh-CN/game/setting.md b/docs/zh-CN/game/setting.md
index 93d2232b..bbf16f2d 100644
--- a/docs/zh-CN/game/setting.md
+++ b/docs/zh-CN/game/setting.md
@@ -175,7 +175,7 @@ public interface ISettingsMigration
     Type SettingsType { get; }
     int FromVersion { get; }
     int ToVersion { get; }
-    ISettingsSection Migrate(ISettingsSection oldData);
+    ISettingsData Migrate(ISettingsData oldData);
 }
 ```