Fast.Serialization.Newtonsoft.Json

逐成员 API、参数与返回参考

版本 3.5.25；目标 net8.0、net9.0、net10.0。依赖 Newtonsoft.Json 与对应目标框架的 MVC NewtonsoftJson 集成包；源中央版本 Newtonsoft.Json 为 13.0.4。命名空间 Fast.Serialization。

bash

dotnet add package Fast.Serialization.Newtonsoft.Json

两个注册入口

入口	行为
`IServiceCollection.AddSerialization(Action<MvcNewtonsoftJsonOptions> configureOptions = null)`	配置默认转换器，保存工具使用的 `JsonContext.SerializerOptions`，向 MVC 选项注册默认设置
`IMvcBuilder.AddSerialization()`	调用 MVC `AddNewtonsoftJson()`，选择 NewtonsoftJson 作为 MVC 格式器

以下为消费端 Program.cs，使用 Microsoft.NET.Sdk.Web，目标选择本页列出的 .NET 8、9 或 10，并安装上方指定包。app.Run() 表示正常宿主启动；本次文档维护不会执行它。

csharp

using Fast.Serialization;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSerialization();
builder.Services.AddControllers().AddSerialization();

var app = builder.Build();
app.MapControllers();
app.Run();

两个调用各有职责。只调用服务集合扩展不等于已切换 MVC JSON 格式器。自定义 configureOptions 目前只应用于静态上下文的选项；MVC 自定义行为需要另行通过 Configure<MvcNewtonsoftJsonOptions> 等 MVC 选项入口设置。该注册不自动配置 Minimal API 的 System.Text.Json 管道。

默认值与公开 API

项目	语义
日期格式	`yyyy-MM-dd HH:mm:ss`；注册 DateTime/DateTimeOffset 及可空转换器，不承诺保留时区偏移文本
long / long?	注册长整数转换器，按框架约定输出字符串
数值、枚举、Exception	注册 int/decimal/double/枚举/异常转换器
循环引用	`ReferenceLoopHandling.Ignore`
字符串转义	`StringEscapeHandling.Default`
`JsonContext.SerializerOptions`	公开读取 `JsonSerializerSettings`，不是 System.Text.Json 的 JsonSerializerOptions
`ToObject<T>()` / `ToObject(Type)`	JSON 字符串或字典转换为对象；解析/转换异常由 Newtonsoft.Json 传播
`ToJsonString()`	使用该包设置序列化
`DeepCopy<T>()`	JSON 往返副本，只覆盖可序列化数据
`DateJsonConverter`、`NullableDateJsonConverter`	日期格式转换，默认 `yyyy-MM-dd`
`TimeJsonConverter`、`NullableTimeJsonConverter`	时间格式转换
`DataMaskingConverter`、`DataMaskingTypeEnum`	属性数据脱敏；模式包括姓名、账号、手机号、证件、邮箱、银行卡、地址、车牌、IP

与 System.Text.Json 包具有相同的公开类型名称，但底层选项、转换器基类与扩展合同属于不同 JSON 库。消费项目选择一种实现；选择实现时需验证日期、long、枚举、空值、循环对象与属性标注，不以名称相同推断序列化结果完全一致。

序列化与反序列化调用

在上面的 MVC 注册之后，业务代码使用同一命名空间的公开扩展。此示例所在项目只选择 Newtonsoft.Json 版本的 Fast.Serialization，避免与另一实现的同名扩展产生冲突。

csharp

using Fast.Serialization;

public sealed class ItemSnapshot
{
    public long Id { get; set; }
    public string Name { get; set; } = "";
}

public sealed class SnapshotCodec
{
    public string Encode(ItemSnapshot item) => item.ToJsonString();
    public ItemSnapshot Decode(string json) => json.ToObject<ItemSnapshot>();
    public ItemSnapshot Copy(ItemSnapshot item) => item.DeepCopy();
}

工具选项取自 JsonContext.SerializerOptions。字段忽略、命名和转换器会影响副本，不能把 DeepCopy 当成完整 CLR 对象克隆。空输入与非法 JSON 按本扩展及 Newtonsoft.Json 的异常合同处理；不提供“解析失败自动返回新对象”的保证。实际 MVC 返回行为要用控制器响应验证，不能仅靠工具序列化结果证明格式器已启用。

来源与验证

依据注册、MVC 入口、选项。本轮为静态核对，新增示例未编译、未执行协议兼容测试。

Decimal 数值精度

默认 decimal / decimal? 输出直接保留 decimal 值，不再经过 double 中转。只有显式指定小数位数时才执行现有 Math.Round 规则；可空值仍保持 null。JSON 数值在 JavaScript number 中是否能精确表达是另一层合同，高精度消费者应使用合适的数值表示。

Fast.Serialization.Newtonsoft.Json ​

两个注册入口 ​

默认值与公开 API ​

序列化与反序列化调用 ​

来源与验证 ​