如何从带时区的ISO8601 JSON DateTime反序列化DateOnly？

一、为什么DateOnly.Parse对带时区的ISO8601字符串抛出异常？ #

DateOnly的设计定位是仅处理无时区的日期信息：它允许带时间部分的ISO字符串（如2024-09-13T12:00:00.000），是因为时间部分不会改变日期的确定性——无论时间点是几点，日期都是明确的2024-09-13。

但带时区偏移（+02:00）或UTC标记（Z）的字符串存在歧义：时区会改变时间对应的绝对日期。例如2024-09-13T01:00:00.000+02:00对应的UTC时间是2024-09-12T23:00:00，实际日期是12号而非13号。DateOnly没有时区处理能力，无法确定应该基于哪个时区解析日期，因此直接抛出异常避免逻辑错误。

二、JSON反序列化的最优解决办法 #

自定义JSON转换器是最理想的方案——既不需要修改前端逻辑，也能保留DateOnly类型的语义正确性，完美适配浏览器提交的带时区ISO字符串。

方案1：System.Text.Json 自定义转换器 #

实现JsonConverter<DateOnly>，在反序列化时自动处理带时区的字符串：

public class DateOnlyJsonConverter : JsonConverter<DateOnly>
{
    public override DateOnly Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        var dateString = reader.GetString();
        // 优先解析为DateTimeOffset，处理时区后提取日期
        if (DateTimeOffset.TryParse(dateString, out var dateTimeOffset))
        {
            // 可根据业务需求选择UTC日期或本地日期
            return DateOnly.FromDateTime(dateTimeOffset.UtcDateTime.Date);
            // return DateOnly.FromDateTime(dateTimeOffset.LocalDateTime.Date);
        }
        // 兼容不带时区的日期字符串
        return DateOnly.Parse(dateString);
    }

    public override void Write(Utf8JsonWriter writer, DateOnly value, JsonSerializerOptions options)
    {
        // 序列化时输出标准无时区日期格式
        writer.WriteStringValue(value.ToString("yyyy-MM-dd"));
    }
}

使用方式：

• 局部注册：在模型属性上标记转换器

public class YourPocoModel
{
    [JsonConverter(typeof(DateOnlyJsonConverter))]
    public DateOnly SubmitDate { get; set; }
}

• 全局注册：在JsonSerializerOptions中添加转换器，全局生效

var jsonOptions = new JsonSerializerOptions();
jsonOptions.Converters.Add(new DateOnlyJsonConverter());
var model = JsonSerializer.Deserialize<YourPocoModel>(requestJson, jsonOptions);

方案2：Newtonsoft.Json 自定义转换器 #

如果项目使用Newtonsoft.Json，可实现对应的转换器：

public class DateOnlyNewtonsoftConverter : JsonConverter<DateOnly>
{
    public override DateOnly ReadJson(JsonReader reader, Type objectType, DateOnly existingValue, bool hasExistingValue, JsonSerializer serializer)
    {
        var dateString = reader.Value.ToString();
        if (DateTimeOffset.TryParse(dateString, out var dateTimeOffset))
        {
            return DateOnly.FromDateTime(dateTimeOffset.UtcDateTime.Date);
        }
        return DateOnly.Parse(dateString);
    }

    public override void WriteJson(JsonWriter writer, DateOnly value, JsonSerializer serializer)
    {
        writer.WriteValue(value.ToString("yyyy-MM-dd"));
    }
}

使用方式：

• 局部注册

public class YourPocoModel
{
    [JsonConverter(typeof(DateOnlyNewtonsoftConverter))]
    public DateOnly SubmitDate { get; set; }
}

• 全局注册

var jsonSettings = new JsonSerializerSettings();
jsonSettings.Converters.Add(new DateOnlyNewtonsoftConverter());
var model = JsonConvert.DeserializeObject<YourPocoModel>(requestJson, jsonSettings);

补充：精准格式匹配（可选） #

如果需要严格匹配ISO8601格式，可在转换器中使用TryParseExact指定支持的格式集合，避免解析非预期的字符串：

var supportedFormats = new[] 
{ 
    "yyyy-MM-dd'T'HH:mm:ss.fff", 
    "yyyy-MM-dd'T'HH:mm:ss.fffzzz", 
    "yyyy-MM-dd'T'HH:mm:ss.fffZ" 
};

if (DateOnly.TryParseExact(dateString, supportedFormats, CultureInfo.InvariantCulture, DateTimeStyles.None, out var date))
{
    return date;
}
// fallback到DateTimeOffset解析

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