.NET Web API：API与文件上传的JSON反序列化策略一致性问题

要让两个端点的反序列化结果完全一致，不能只靠模型上的Json特性，核心是让ASP.NET自动反序列化和手动调用JsonSerializer.DeserializeAsync使用完全相同的配置规则，具体实现步骤如下：

1. 配置全局统一的JsonSerializerOptions #

ASP.NET自动处理请求体反序列化时，默认使用全局的JsonSerializerOptions配置。我们需要把所有自定义反序列化规则（比如字段非空约束、数字格式处理等）集中配置在这里，确保手动反序列化也复用这套配置。

在Program.cs中添加全局Json配置：

var builder = WebApplication.CreateBuilder(args);

// 添加控制器并配置Json选项
builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 示例：配置统一规则
        options.JsonSerializerOptions.PropertyNameCaseInsensitive = true; // 忽略属性大小写
        options.JsonSerializerOptions.NumberHandling = JsonNumberHandling.AllowReadingFromString; // 允许从字符串读取数字（全局生效，可替代模型上的特性）
        options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
        
        // 添加自定义转换器（如果有）
        // options.JsonSerializerOptions.Converters.Add(new CustomJsonConverter());
    });

// 其他服务配置...

var app = builder.Build();

// 中间件配置...

app.Run();

2. 模型上补充必要的Json特性 #

全局配置是基础，模型上的特性可以作为局部规则补充或覆盖全局配置。比如字段非空约束，可直接使用System.Text.Json提供的[JsonRequired]特性：

public class JsonItemModel {
    // 全局已配置NumberHandling，这里可以省略特性，也可以保留做局部声明
    // [JsonNumberHandling(JsonNumberHandling.AllowReadingFromString)]
    public int SomeField { get; init; } = 0;

    // 字段非空约束
    [JsonRequired]
    public string RequiredField { get; init; } = string.Empty;
    
    // 其他属性...
}

如果需要结合数据验证（比如ASP.NET自动返回400错误），可以同时添加[Required]数据注解特性，控制器默认已启用数据验证。

3. 调整手动反序列化的端点实现 #

手动调用JsonSerializer.DeserializeAsync时，默认会使用默认配置而非全局配置，所以需要注入全局配置并传入反序列化方法：

首先在控制器中注入IOptions<JsonOptions>：

private readonly IOptions<JsonOptions> _jsonOptions;

public YourController(IOptions<JsonOptions> jsonOptions)
{
    _jsonOptions = jsonOptions;
}

然后修改ImportWithFile方法，传入全局配置：

[HttpPost]
[Route("public/v1/myRouteWithFile/")]
public async Task<ActionResult<Guid>> ImportWithFile([FromForm] MyFormData formData) {
   using var stream = formData.File.OpenReadStream();
   // 使用全局配置进行反序列化
   var items = await JsonSerializer.DeserializeAsync<IEnumerable<JsonItemModel>>(
       stream, 
       _jsonOptions.Value.JsonSerializerOptions
   );

   if (items == null)
   {
       return BadRequest("上传的文件内容无效");
   }

   FooProcessItems(items);
   // 返回结果...
}

关键注意事项 #

• 避免混合序列化库：全程使用System.Text.Json，不要和Newtonsoft.Json混用，否则配置规则无法统一。
• 验证配置一致性：测试时用相同的输入数据分别调用两个端点，检查是否触发相同的约束（比如必填字段为空时是否都返回400错误，数字字符串是否都能正确反序列化为int）。
• 自定义转换器统一注册：如果有自定义的JsonConverter，必须添加到全局JsonSerializerOptions的Converters集合中，确保两种反序列化方式都能使用。

内容的提问来源于stack exchange，提问作者jeancallisti