Humanizer 中 IDateOnlyHumanizeStrategy 接口详解:自定义 DateOnly 人性化日期策略

原创2026-09-24 10:15:371,344 阅读
文章标签:开发工具

Humanizer 中 IDateOnlyHumanizeStrategy 接口详解:自定义 DateOnly 人性化日期策略

Humanizer 提供了 DateOnly.Humanize 扩展方法,可将两个 System.DateOnly 之间的时间差转换为"3 days ago"、"one month from now"这类自然语言表述。IDateOnlyHumanizeStrategy 是控制这一行为的策略接口:本文基于仓库中的 API 参考文档与源码实现,讲解该接口的契约定义、两个内置实现(DefaultDateOnlyHumanizeStrategy 与 PrecisionDateOnlyHumanizeStrategy)的底层算法差异,以及如何通过 Configurator.DateOnlyHumanizeStrategy 将自定义策略挂接进 Humanizer。读完本文,你将能够独立实现并注册一个符合仓库契约的日期人性化策略,并理解默认与精度两种内置算法在日期边界处理上的具体差别。

接口契约:IDateOnlyHumanizeStrategy

IDateOnlyHumanizeStrategy 是 DateOnly.Humanize 的策略入口。按照 API 参考文档(见 IDateOnlyHumanizeStrategy 文档)的定义,实现该接口即可为 DateOnly.Humanize 创建新策略,并将其挂接到 Configurator.DateOnlyHumanizeStrategy:

public interface IDateOnlyHumanizeStrategy
{
    string Humanize(DateOnly input, DateOnly comparisonBase, CultureInfo? culture);
}

接口只有一个方法 Humanize(DateOnly, DateOnly, CultureInfo),用于计算两个日期之间以词表示的时间距离(distance of time in words)。参数语义如下:

参数 类型 说明
input System.DateOnly 要被人性化的目标日期
comparisonBase System.DateOnly 比较基准日期;input 大于它时结果为将来时(from now),小于它时为过去时(ago)
culture System.Globalization.CultureInfo 用于本地化输出的文化;传 null 时使用当前线程文化

返回值类型为 System.String,即本地化后的时间距离表述。

从源码结构看(IDateOnlyHumanizeStrategy.cs),该接口整体被 #if NET6_0_OR_GREATER 条件编译包裹——因为 System.DateOnly 自 .NET 6 才引入,所以这个策略体系仅在 .NET 6+ 目标框架上可用。接口的 XML 注释与 API 文档完全一致:"Implement this interface to create a new strategy for DateOnly.Humanize and hook it in the Configurator.DateOnlyHumanizeStrategy"。

调用链:从 Humanize 扩展方法到策略

策略并不是孤立存在的,它的上游调用点在 DateHumanizeExtensions.cs 中。DateOnly.Humanize 扩展方法(约 L86-L90)的调用链为:

public static string Humanize(this DateOnly input, DateOnly? dateToCompareAgainst = null, CultureInfo? culture = null)
{
    var comparisonBase = dateToCompareAgainst ?? DateOnly.FromDateTime(DateTime.UtcNow);
    return Configurator.DateOnlyHumanizeStrategy.Humanize(input, comparisonBase, culture);
}

关键行为有两点,均有源码可证:

  • 基准日期默认取当前 UTC 日期:当 dateToCompareAgainst 为 null 时,使用 DateOnly.FromDateTime(DateTime.UtcNow) 作为 comparisonBase。
  • 空值返回"never":DateOnly? 的可空重载(L99-L109)在 input 为 null 时不调用策略,而是走 Configurator.GetFormatter(culture).DateHumanize_Never(),输出本地化的"never"。测试 DateOnlyHumanizeTests.cs 中的 Never 用例验证了 ((DateOnly?)null).Humanize() 返回 "never"。

也就是说,策略只负责"两个非空日期之间的词化",基准日期的选取和空值兜底由扩展方法层完成——这也是自定义策略实现者可以依赖的契约边界。

挂接点:Configurator.DateOnlyHumanizeStrategy

策略的注册入口在 Configurator.cs:

#if NET6_0_OR_GREATER
    /// <summary>
    /// The strategy to be used for DateOnly.Humanize
    /// </summary>
    /// <remarks>
    /// This property should be set only once during application startup before any humanization operations occur.
    /// For thread-safety, use volatile reads or appropriate synchronization when accessing this property in multi-threaded scenarios.
    /// In production applications, avoid changing this value after the application has started serving requests.
    /// </remarks>
    public static IDateOnlyHumanizeStrategy DateOnlyHumanizeStrategy { get; set; } = new DefaultDateOnlyHumanizeStrategy();
#endif

这是一个可静态设置的属性,默认实例为 DefaultDateOnlyHumanizeStrategy。源码 <remarks> 明确给出了使用约束:

  • 该属性应在应用启动阶段、任何人性化操作发生之前只设置一次;
  • 多线程场景下读取该属性时,建议使用 volatile 读取或适当同步;
  • 生产环境中,避免在开始处理请求之后修改该值。

因此自定义策略的挂接方式就是在启动阶段(例如 Program.cs 或 ModuleInitializer)执行:

Configurator.DateOnlyHumanizeStrategy = new MyCustomDateOnlyHumanizeStrategy();

这与同文件中 DateTimeHumanizeStrategy、DateTimeOffsetHumanizeStrategy、TimeSpanHumanizeStrategy、TimeOnlyHumanizeStrategy 等兄弟属性的约定完全一致,Humanizer 的整套日期人性化能力都通过 Configurator 上的静态策略属性统一暴露。

内置实现一:DefaultDateOnlyHumanizeStrategy

仓库中该接口的两个内置实现都位于 src/Humanizer/DateTimeHumanizeStrategy/ 目录(与 API 文档中 "Derived" 一节列出的两个派生类对应):

DefaultDateOnlyHumanizeStrategy 本身是一层极薄的委托,把实际计算交给 DateTimeHumanizeAlgorithms.cs 的静态算法:

public class DefaultDateOnlyHumanizeStrategy : IDateOnlyHumanizeStrategy
{
    public string Humanize(DateOnly input, DateOnly comparisonBase, CultureInfo? culture) =>
        DateTimeHumanizeAlgorithms.DefaultHumanize(input, comparisonBase, culture);
}

DefaultHumanize(DateOnly, DateOnly, CultureInfo) 的算法逻辑(DateTimeHumanizeAlgorithms.cs L153-L169 及其调用的私有 DefaultHumanize(TimeSpan, ...) L192-L264)可以归纳为以下几步:

  1. 同日短路:input == comparisonBase 时直接返回"today"。该路径走 DateOnlyHumanizeToday(L171-L178):先取 formatter.DateHumanize(TimeUnit.Millisecond, Tense.Past, 0),再若 formatter 是 DefaultFormatter 则进一步调用 DateHumanize_Today,从而允许派生 formatter 单独重写"today"措辞。
  2. 确定时态与天数差:tense = input > comparisonBase ? Tense.Future : Tense.Past;天数差用 Math.Abs(comparisonBase.DayNumber - input.DayNumber) 计算,并构造为整天的 TimeSpan。
  3. sameMonth 判断:comparisonBase.AddMonths(tense == Tense.Future ? 1 : -1) == input,用于 28~29 天区间的措辞选择(跨月显示 "X days ago",同月内显示 "one month ago/from now")。
  4. 阶梯式区间映射:由小到大依次判断 TotalMilliseconds < 500(now)、TotalSeconds < 60/120、TotalMinutes < 60/90、TotalHours < 24/48、TotalDays < 7(按天)、< 28(按周,ts.Days / 7)、28~30(受 sameMonth 影响)、< 345(按 TotalDays / 29.5 折算月)、否则按 TotalDays / 365 折算年(最小为 1 年)。

注意:对 DateOnly 输入,时间差只含整天,小时/分钟/秒分支实际上只有"0 天→now/today"这一种情形会命中,其余都落在天/周/月/年分支——这是 DateOnly 版本相对于 DateTime 版本的自然简化。

测试文件 DateOnlyHumanizeTests.cs 对该策略的行为给出了可验证的锚点:

测试用例 输入(input, base) 期望输出
DefaultStrategy_SameDate 2015-07-05, 2015-07-05 today
DefaultStrategy_MonthApart 2015-08-05, 2015-07-05 one month from now
DefaultStrategy_DaysAgo 2015-07-02, 2015-07-05 3 days ago
DefaultStrategy_YearsAgo 当前日期 -24 个月 2 years ago

内置实现二:PrecisionDateOnlyHumanizeStrategy

PrecisionDateOnlyHumanizeStrategy 引入了一个 precision(近似精度)构造参数(见 PrecisionDateOnlyHumanizeStrategy.cs):

public class PrecisionDateOnlyHumanizeStrategy(double precision = .75) : IDateOnlyHumanizeStrategy
{
    readonly double precision = precision;

    public string Humanize(DateOnly input, DateOnly comparisonBase, CultureInfo? culture) =>
        DateTimeHumanizeAlgorithms.PrecisionHumanize(input, comparisonBase, precision, culture);
}

默认精度为 0.75。与 Default 策略的"硬区间"不同,Precision 策略(DateTimeHumanizeAlgorithms.cs 的 PrecisionHumanize(DateOnly, ...))先用 DayNumber 绝对差得到整天数,然后按"阈值 × precision"逐级向上进位:

  • seconds >= 59 * precision 进 1 分钟,minutes >= 59 * precision 进 1 小时,hours >= 23 * precision 进 1 天;
  • 月:days >= 30 * precision && days <= 31 记 1 个月;days > 31 且 days < 365 * precision 时以 30 天为基准折算 factor,再按 days >= 30 * (factor + precision) 决定是否进位;
  • 年:days >= 365 * precision && days <= 366 记 1 年;days > 365 时以 365 天为基准折算并做同样的进位判断;
  • 最终从大到小(年→月→日→时→分→秒)取第一个非零单位,交给 Configurator.GetFormatter(culture).DateHumanize(...) 输出。

同样的"同日返回 today"短路也存在于 Precision 路径(L25-L28)。测试锚点(均在 DateOnlyHumanizeTests.cs):

测试用例 输入(input, base, precision=0.75) 期望输出
PrecisionStrategy_NextDay 2015-07-05, 2015-07-04 tomorrow
PrecisionStrategy_UsesAbsoluteDayDistance 第 1 组 2016-01-01, 2015-12-31 tomorrow
PrecisionStrategy_UsesAbsoluteDayDistance 第 2 组 2016-01-01, 2015-01-01 one year from now

另外 SameDate_UsesDateOnlyWordingWithoutChangingCultureFallback 用例验证了无论使用哪个策略、传入 en-GB 还是 fr-FR 文化,同日都分别输出 today / maintenant,证明本地化措辞由 formatter 层承担,策略层只负责选单位与时态。

两种策略的行为差异

从源码结构看,两类内置策略的差异集中在"日期→单位"的折算方式上,而时态判定(input > comparisonBase)和 formatter 调用是共享的:

  • Default 策略:区间边界是固定的经验值(<120s、<60min、<90min、<48h、<7d、<28d、28~30d、<345d、≥345d),月按 29.5 天、年按 365 天折算,适合"今天/昨天/下周"这类贴近自然语言的展示。
  • Precision 策略:所有进位阈值都乘以 precision(默认 0.75),精度越高(越接近 1)进位越保守,越低(如 0.5)则越早进位到更大单位;对 DateOnly 这种整天粒度输入,实际体现为"接近整月/整年时四舍五入到哪一档"。

如果你需要的是介于两者之间的自定义行为(例如统一按 365.25 天折算年、或在特定天数区间强制输出周),实现该接口是最直接的扩展点,而无需修改 Humanizer 本身。

自定义策略示例

结合上面的契约与挂接点,一个最小可用的自定义策略骨架如下(示例代码,非仓库内文件):

using System.Globalization;
using Humanizer;

sealed class MyDateOnlyHumanizeStrategy : IDateOnlyHumanizeStrategy
{
    public string Humanize(DateOnly input, DateOnly comparisonBase, CultureInfo? culture)
    {
        // 同日短路,与内置策略保持一致的契约
        if (input == comparisonBase)
        {
            return Configurator.GetFormatter(culture) is DefaultFormatter defaultFormatter
                ? defaultFormatter.DateHumanize_Today(
                      Configurator.GetFormatter(culture).DateHumanize(TimeUnit.Millisecond, Tense.Past, 0))
                : Configurator.GetFormatter(culture).DateHumanize(TimeUnit.Millisecond, Tense.Past, 0);
        }

        var tense = input > comparisonBase ? Tense.Future : Tense.Past;
        var days = Math.Abs(comparisonBase.DayNumber - input.DayNumber);

        // 自定义折算逻辑,例如:>= 14 天一律按周输出
        if (days >= 14)
        {
            return Configurator.GetFormatter(culture).DateHumanize(TimeUnit.Week, tense, days / 7);
        }

        return Configurator.GetFormatter(culture).DateHumanize(TimeUnit.Day, tense, days);
    }
}

挂接(在应用启动阶段执行一次):

Configurator.DateOnlyHumanizeStrategy = new MyDateOnlyHumanizeStrategy();

实现时需要注意的几点,均可在源码中找到依据:

  • 文化解析不要自己做:内置策略统一通过 Configurator.GetFormatter(culture) 取 formatter,culture 为 null 时回退到当前线程文化,自定义实现沿用同一入口即可保持本地化行为一致;
  • 同日措辞:若希望"today"支持 formatter 级重写,参照 DateTimeHumanizeAlgorithms.cs 中 DateOnlyHumanizeToday 的写法(仅当 formatter 为 DefaultFormatter 时才调用 DateHumanize_Today);测试 TodayWording_PreservesCustomDateHumanizeOverride 验证了派生 formatter 重写 DateHumanize_Today 的生效路径;
  • 时态方向:input > comparisonBase 是 Future(from now / tomorrow),否则 Past(ago / yesterday),测试 PrecisionStrategy_UsesAbsoluteDayDistance 中"基准日 2015-12-31、输入日 2016-01-01 输出 tomorrow"即印证了这一约定;
  • 线程安全:按 Configurator.cs 的 remarks,策略实例应在启动时一次性设置,运行时不再更换。

相关 API 文档

该接口所在的 Humanizer.DateTimeHumanizeStrategy 命名空间在 v2.13.14 版本文档中还有配套页面,可结合阅读:

小结

  • IDateOnlyHumanizeStrategy 只定义一个方法 string Humanize(DateOnly input, DateOnly comparisonBase, CultureInfo? culture),是 DateOnly.Humanize 的策略抽象,仅在 .NET 6+(#if NET6_0_OR_GREATER)下编译。
  • 扩展方法 DateHumanizeExtensions.cs 负责选取基准日期(默认 DateOnly.FromDateTime(DateTime.UtcNow))、处理可空输入(返回本地化 "never"),然后把非空两日期的词化交给策略。
  • 策略通过 Configurator.cs 的 DateOnlyHumanizeStrategy 静态属性挂接,默认值为 DefaultDateOnlyHumanizeStrategy,且约定启动时设置一次。
  • 两个内置实现(DefaultDateOnlyHumanizeStrategy 与 PrecisionDateOnlyHumanizeStrategy)分别对应固定区间算法与带 precision(默认 0.75)进位系数的近似算法,二者均委托给 DateTimeHumanizeAlgorithms.cs 中的静态方法,最终措辞统一由 IFormatter.DateHumanize 按 culture 本地化输出;DateOnlyHumanizeTests.cs 中的用例可作为行为回归的参考基线。
登录后查看全文
Humanizer