Humanizer 的 IDateOnlyHumanizeStrategy:深度定制 DateOnly.Humanize 日期人性化策略

原创2026-09-25 14:08:222,165 阅读
文章标签:开发工具

Humanizer 的 IDateOnlyHumanizeStrategy:深度定制 DateOnly.Humanize 日期人性化策略

本指南以 Humanizer 2.14.1 版本文档中的 IDateOnlyHumanizeStrategy 接口为主线,系统讲解 DateOnly.Humanize 的策略化设计:如何理解该接口的契约、两个内置策略的行为差异、如何编写自定义策略并挂载到 Configurator.DateOnlyHumanizeStrategy。读完本文,你将掌握 DateOnly 日期距离转自然语言的完整调用链,并能按业务规则替换默认的人性化策略。

接口定位:DateOnly 日期人性化的可插拔契约

IDateOnlyHumanizeStrategy 是 Humanizer 为 DateOnly.Humanize 扩展方法设计的策略接口。其官方说明非常明确:实现该接口即可为 DateOnly.Humanize 创建新的策略,并通过 Configurator.DateOnlyHumanizeStrategy 挂载启用。

接口定义位于 src/Humanizer/DateTimeHumanizeStrategy/IDateOnlyHumanizeStrategy.cs:

#if NET6_0_OR_GREATER

namespace Humanizer;

/// <summary>
/// Implement this interface to create a new strategy for DateOnly.Humanize and hook it in the Configurator.DateOnlyHumanizeStrategy
/// </summary>
public interface IDateOnlyHumanizeStrategy
{
    /// <summary>
    /// Calculates the distance of time in words between two provided dates used for DateOnly.Humanize
    /// </summary>
    string Humanize(DateOnly input, DateOnly comparisonBase, CultureInfo? culture);
}

#endif

需要注意的第一点:整个接口(以及 DateOnly、TimeOnly 相关的全部人性化 API)都被 #if NET6_0_OR_GREATER 编译指令包裹。因为 System.DateOnly 类型本身是 .NET 6 才引入的,所以该接口只在 .NET 6 及更高版本的目标框架下可见。这一点也体现在公共 API 审批测试中:tests/Humanizer.Tests/ApiApprover/PublicApiApprovalTest.Approve_Public_Api.DotNet8_0.verified.txt 中包含该接口与两个派生类,而面向 .NET Framework 4.8 的审批文件(Approve_Public_Api.Net4_8.verified.txt)中不会出现它们。

接口只有一个方法,契约极简,但它背后连接着一条完整的"策略解析 → 算法计算 → 本地化格式化"调用链。

Humanize 方法签名与参数语义

IDateOnlyHumanizeStrategy 定义了一个三参数方法,是"计算两个日期之间以文字表达的时间距离"的统一入口:

string Humanize(System.DateOnly input, System.DateOnly comparisonBase, System.Globalization.CultureInfo culture);
参数 类型 语义
input System.DateOnly 需要被人性化表述的目标日期(如"3 天前"中的那个日期)
comparisonBase System.DateOnly 比较基准日期,用于计算与 input 的时间距离
culture System.Globalization.CultureInfo 输出文案所用的文化;传 null 时使用当前线程文化

返回值是 System.String,即本地化的人性化日期表述。参考实现(DefaultDateOnlyHumanizeStrategy、PrecisionDateOnlyHumanizeStrategy)在内部都把它透传给核心算法类 DateTimeHumanizeAlgorithms。

关于 culture 参数的细节:它被声明为可空。从 Configuration/LocaliserRegistry.cs 的 ResolveForCulture 可以看到,null 会被替换为 CultureInfo.CurrentCulture,然后按"子文化逐级向上查找父文化"的方式解析最合适的本地化组件;找不到时回退到英文(en)默认实现。这意味着策略实现中即使 culture 为 null,最终也能得到确定的文化上下文。

调用链:Humanize 扩展方法如何驱动策略

DateOnly.Humanize 的扩展方法位于 src/Humanizer/DateHumanizeExtensions.cs:

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);
}

public static string Humanize(this DateOnly? input, DateOnly? dateToCompareAgainst = null, CultureInfo? culture = null)
{
    if (input.HasValue)
    {
        return Humanize(input.Value, dateToCompareAgainst, culture);
    }

    return Configurator
        .GetFormatter(culture)
        .DateHumanize_Never();
}

从这段代码可以提炼出完整的调用链:

  1. 未显式传入 dateToCompareAgainst 时,以 DateOnly.FromDateTime(DateTime.UtcNow) 即"今天(UTC 视角)"作为比较基准;
  2. 从 Configurator.DateOnlyHumanizeStrategy 解析当前生效的策略实例;
  3. 调用策略的 Humanize(input, comparisonBase, culture),策略内部计算时间距离并委托 IFormatter 生成本地化文案;
  4. 可空重载 DateOnly? 在值为 null 时不会走策略,而是直接返回本地化的 "never"(由 DefaultFormatter.DateHumanize_Never 输出)。

Configurator.DateOnlyHumanizeStrategy 属性定义在 src/Humanizer/Configuration/Configurator.cs,默认值为 new DefaultDateOnlyHumanizeStrategy():

public static IDateOnlyHumanizeStrategy DateOnlyHumanizeStrategy { get; set; } = new DefaultDateOnlyHumanizeStrategy();

该属性的 XML 注释给出了重要的使用约束:应只在应用启动阶段、任何人性化操作发生之前设置一次;多线程场景下访问该属性时需要注意 volatile 读或合适的同步手段;生产应用启动服务后应避免再修改该值。这与 Humanizer 中 DateTimeHumanizeStrategy、DateTimeOffsetHumanizeStrategy、TimeOnlyHumanizeStrategy 等策略属性的约束一致。

内置实现一:DefaultDateOnlyHumanizeStrategy

DefaultDateOnlyHumanizeStrategy 是默认策略,实现位于 src/Humanizer/DateTimeHumanizeStrategy/DefaultDateOnlyHumanizeStrategy.cs:

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

它把工作完全委托给 src/Humanizer/DateTimeHumanizeStrategy/DateTimeHumanizeAlgorithms.cs 中的 DefaultHumanize(DateOnly, DateOnly, CultureInfo)。该算法的关键逻辑:

  • 同日判定:input == comparisonBase 时直接返回"今天"的本地化文案(DateOnlyHumanizeToday 会通过 DefaultFormatter.DateHumanize_Today 输出 DateToday 短语,见 DefaultFormatter.cs,从而兼容自定义 formatter 对 DateHumanize 的覆写);
  • 时态判定:input > comparisonBase 为将来时(Tense.Future),否则为过去时(Tense.Past);
  • 距离计算:用 DayNumber 相减得到纯天数差,构造 TimeSpan(diffDays, 0, 0, 0);
  • 跨月判定:comparisonBase.AddMonths(±1) == input 用于处理"恰隔一月"的输出;
  • 分级阈值:按"毫秒 → 秒 → 分钟 → 小时 → 天 → 周 → 月 → 年"的链条逐级判断。

由于 DateOnly 不含时间部分,实际生效的分支是从"天"开始的。完整阈值链如下(DefaultHumanize(TimeSpan, ...),同一文件的 L192-L264):

距离区间 输出单位 说明
TotalDays < 7 Day 输出具体天数
TotalDays < 28 Week ts.Days / 7 取整周数
TotalDays 在 28~30 之间 Month / Day 若 sameMonth 为真输出 "1 month",否则输出具体天数
TotalDays < 345 Month floor(TotalDays / 29.5) 折算月数
其余(≥345 天) Year floor(TotalDays / 365),至少为 1 年

对应测试见 tests/Humanizer.Tests/DateOnlyHumanizeTests.cs:

var inputTime = new DateOnly(2015, 07, 05);
var baseTime  = new DateOnly(2015, 07, 05);
Assert.Equal("today", inputTime.Humanize(baseTime));           // 同日 → today

var inputTime2 = new DateOnly(2015, 08, 05);
var baseTime2  = new DateOnly(2015, 07, 05);
Assert.Equal("one month from now", inputTime2.Humanize(baseTime2)); // 恰隔一月

var inputTime3 = new DateOnly(2015, 07, 02);
var baseTime3  = new DateOnly(2015, 07, 05);
Assert.Equal("3 days ago", inputTime3.Humanize(baseTime3));   // 过去 3 天

内置实现二:PrecisionDateOnlyHumanizeStrategy

PrecisionDateOnlyHumanizeStrategy 是精度敏感的策略,实现位于 src/Humanizer/DateTimeHumanizeStrategy/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);
}

它通过主构造函数接收一个 precision 参数(近似精度,默认 0.75),并把计算委托给 DateTimeHumanizeAlgorithms.PrecisionHumanize(DateOnly, DateOnly, double, CultureInfo)(DateTimeHumanizeAlgorithms.cs)。与默认策略相比,其核心差异在于先按精度对各单位做四舍五入式逼近,再从大到小选择输出单位:

  • 同日仍返回"今天"文案;
  • 距离仍以 DayNumber 差值为准(纯天数),跨年、跨月场景也基于绝对天数距离计算;
  • 逼近规则(同一文件 L48-L96):如 days >= 23 * precision 则天数进位;days 落在 30 * precision~31 之间记为 1 个月;days > 31 且 < 365 * precision 时按月近似(floor(days/30) 结合精度进位);days 落在 365 * precision~366 之间记为 1 年;days > 365 时按年近似(floor(days/365) 结合精度进位);
  • 输出时按"年 → 月 → 日 → 时 → 分 → 秒 → 毫秒"的优先级,选取第一个非零单位交给 Configurator.GetFormatter(culture).DateHumanize(TimeUnit, tense, unit) 生成本地化文案。

precision 参数直观地控制了近似程度:precision 越大,小单位越容易进位成大单位。测试用例(DateOnlyHumanizeTests.cs)给出了两个可直接验证的行为:

// 相距 1 天,默认精度 0.75 → "tomorrow"
var inputTime = new DateOnly(2015, 07, 05);
var baseTime  = new DateOnly(2015, 07, 04);
Assert.Equal("tomorrow",
    new PrecisionDateOnlyHumanizeStrategy(0.75).Humanize(inputTime, baseTime, CultureInfo.CurrentUICulture));

// 跨年场景按绝对天数计算:1 月 1 日对 1 月 1 日 → "one year from now"
Assert.Equal("one year from now",
    new PrecisionDateOnlyHumanizeStrategy(0.75).Humanize(new DateOnly(2016,1,1), new DateOnly(2015,1,1), CultureInfo.CurrentUICulture));

两个内置策略的公共 API 形态(含 PrecisionDateOnlyHumanizeStrategy(double precision = 0.75) 的默认参数)均由 tests/Humanizer.Tests/ApiApprover/PublicApiApprovalTest.Approve_Public_Api.DotNet8_0.verified.txt 审批锁定。

编写并挂载自定义策略

理解了接口契约与调用链后,自定义策略只需两步:实现接口、在启动时挂载到 Configurator.DateOnlyHumanizeStrategy。下面是一个按业务需求定制的示例(示意实现,展示接口用法):

using System.Globalization;
using Humanizer;

// 1. 实现接口:用日历日差值直接生成文案
public sealed class CalendarDayDateOnlyHumanizeStrategy : IDateOnlyHumanizeStrategy
{
    public string Humanize(DateOnly input, DateOnly comparisonBase, CultureInfo? culture)
    {
        var diffDays = comparisonBase.DayNumber - input.DayNumber;

        if (diffDays == 0)
            return "today";
        if (diffDays == 1)
            return "yesterday";
        if (diffDays == -1)
            return "tomorrow";

        return diffDays > 0
            ? $"{diffDays} days ago"
            : $"{Math.Abs(diffDays)} days from now";
    }
}

// 2. 应用启动阶段(Main / ModuleInitializer / Program.cs)挂载
Configurator.DateOnlyHumanizeStrategy = new CalendarDayDateOnlyHumanizeStrategy();

挂载后,所有 DateOnly.Humanize() 调用都会走新策略。需要注意几点约束:

  • 挂载时机:务必在应用启动阶段、任何 Humanize 调用发生之前完成赋值(Configurator.DateOnlyHumanizeStrategy 的 XML 注释明确要求这一点);
  • 线程安全:该属性是可读写静态属性,多线程读写场景需要自行保证可见性(volatile 或同步);
  • 文案本地化:如果自定义策略需要输出本地化文案,应通过 Configurator.GetFormatter(culture)(见 Configurator.cs)获取当前文化的 IFormatter,并调用 DateHumanize(TimeUnit, Tense, unit) 系列方法;该 formatter 基于生成的区域短语表(LocalePhraseTable)工作,找不到对应短语时会抛出 InvalidOperationException(见 DefaultFormatter.cs);
  • 同一日期的特判:参照内置算法,建议在策略中对 input == comparisonBase 单独处理"今天"文案,以兼容 DefaultFormatter.DateHumanize_Today 的覆写语义(测试 TodayWording_PreservesCustomDateHumanizeOverride 验证了这一点,见 DateOnlyHumanizeTests.cs)。

与相关策略接口的横向对照

IDateOnlyHumanizeStrategy 并非孤立设计,Humanizer 的 DateTimeHumanizeStrategy 目录下存在一套同构的策略族:

每个接口都对应 Configurator 上的一个可替换策略属性,且默认实现都委托给同一个 DateTimeHumanizeAlgorithms 静态类。这种"接口 + Configurator 属性 + 算法类"的组合,让使用者可以用最小的代价替换任意日期类型的人性化行为,而无需改动扩展方法与本地化管线。

总结:策略化设计的落地要点

围绕 IDateOnlyHumanizeStrategy,本文覆盖了从契约、调用链、内置实现到自定义扩展的完整路径。核心要点可归纳为:

  1. 契约极简:接口只有一个 Humanize(input, comparisonBase, culture) 方法,返回本地化的日期距离文案;
  2. 入口单一:DateOnly.Humanize 扩展方法通过 Configurator.DateOnlyHumanizeStrategy 解析策略,默认是 DefaultDateOnlyHumanizeStrategy;
  3. 两种内置策略:默认策略按固定阈值链(天 → 周 → 月 → 年)输出;精度策略通过 precision(默认 0.75)控制近似进位,适合对输出粒度有要求的场景;
  4. 定制成本低:实现接口并在启动阶段挂载即可生效,但需遵循"启动时一次性设置"与线程安全约束;
  5. 本地化统一:文案最终由 Configurator.GetFormatter(culture) 解析的区域短语表生成,策略本身不直接持有文案资源。

如需进一步深入,可继续阅读仓库中的对应实现与测试:DateTimeHumanizeAlgorithms.cs、DateOnlyHumanizeTests.cs,以及 API 文档 DefaultDateOnlyHumanizeStrategy 与 PrecisionDateOnlyHumanizeStrategy。

登录后查看全文
Humanizer