ASP.NET Core 2.1 Web API 对象绑定：空串映射可空Guid无需改模型返回400方案

开发ASP.NET Core 2.1 Web API应用时遇到JSON属性绑定异常：请求体中类型为Guid?（可空Guid）的属性收到空字符串值时，默认会被绑定为null，需求是该场景下直接返回400 BadRequest错误。

现有实现 #

API端点代码 #

public async Task<ActionResult<ExampleResponse>> ExamplePatch([FromBody] ExampleModel exampleModel,
        CancellationToken cancellationToken)
{
    /* 此时exampleModel.ExampleGuid已被初始化为null，需在业务逻辑执行前完成校验处理 */
    /* 部分业务处理逻辑 */
    return StatusCode(StatusCodes.Status201Created, ExampleResponse);
}

绑定的业务模型（NJsonSchema自动生成，不可修改） #

[System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "9.10.53.0 (Newtonsoft.Json v9.0.0.0)")]
public class ExampleModel 
{
    /* 此处省略其余大量属性定义 */
    [Newtonsoft.Json.JsonProperty("exampleGuid", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public System.Guid? ExampleGuid { get; set; }
}

触发问题的请求体示例 #

{
  /* ...其他参数... */
  "exampleGuid": ""
}

实现约束 #

• 模型为自动生成产物，无法修改类结构
• 无法为模型、属性新增任何标注特性

通过自定义Newtonsoft.Json的可空Guid反序列化器实现需求，无需修改自动生成的模型：

1. 自定义可空GuidJson转换器 #

using Newtonsoft.Json;
public class NullableGuidJsonConverter : JsonConverter<Guid?>
{
    public override Guid? ReadJson(JsonReader reader, Type objectType, Guid? existingValue, bool hasExistingValue, JsonSerializer serializer)
    {
        // 正常传null的情况，返回null，符合可空类型预期
        if (reader.TokenType == JsonToken.Null)
        {
            return null;
        }
        // 处理字符串类型的输入
        if (reader.TokenType == JsonToken.String)
        {
            string inputValue = reader.Value?.ToString();
            // 空字符串/全空白字符串直接抛出序列化异常，自动触发400响应
            if (string.IsNullOrWhiteSpace(inputValue))
            {
                throw new JsonSerializationException($"字段 {reader.Path} 不允许传入空字符串，请传入合法Guid或null");
            }
            // 正常解析合法Guid
            if (Guid.TryParse(inputValue, out var parsedGuid))
            {
                return parsedGuid;
            }
            // 非法Guid格式也直接报错
            throw new JsonSerializationException($"字段 {reader.Path} 的值 {inputValue} 不是合法的Guid格式");
        }
        // 其他不兼容的类型（比如对象、数字等）直接报错
        throw new JsonSerializationException($"字段 {reader.Path} 无法将类型 {reader.TokenType} 转换为可空Guid");
    }
    public override void WriteJson(JsonWriter writer, Guid? value, JsonSerializer serializer)
    {
        // 出站序列化逻辑保持默认行为，可根据需求调整
        if (value.HasValue)
        {
            writer.WriteValue(value.Value);
        }
        else
        {
            writer.WriteNull();
        }
    }
}

2. 全局注册转换器 #

在Startup.cs的ConfigureServices方法中配置Mvc的Json序列化选项，将自定义转换器加入全局配置：

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddJsonOptions(options =>
        {
            // 注册自定义可空Guid转换器，全局生效
            options.SerializerSettings.Converters.Add(new NullableGuidJsonConverter());
        })
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}

生效逻辑说明 #

• 传入合法Guid字符串时，正常绑定为对应Guid值
• 传入null时，正常绑定为null，符合可空类型的使用预期
• 传入空字符串/全空白字符串时，反序列化阶段直接抛出异常，ASP.NET Core会自动捕获该异常并返回400 BadRequest，无需在Action中手动校验
• 完全不改动自动生成的模型结构、无需添加任何特性，符合约束要求

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