Humanizer 的 IDateOnlyHumanizeStrategy:深度定制 DateOnly.Humanize 日期人性化策略
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();
}
从这段代码可以提炼出完整的调用链:
- 未显式传入
dateToCompareAgainst时,以DateOnly.FromDateTime(DateTime.UtcNow)即"今天(UTC 视角)"作为比较基准; - 从
Configurator.DateOnlyHumanizeStrategy解析当前生效的策略实例; - 调用策略的
Humanize(input, comparisonBase, culture),策略内部计算时间距离并委托IFormatter生成本地化文案; - 可空重载
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 目录下存在一套同构的策略族:
- IDateTimeHumanizeStrategy.cs:
DateTime.Humanize的策略契约; - IDateTimeOffsetHumanizeStrategy.cs:
DateTimeOffset.Humanize的策略契约; - ITimeOnlyHumanizeStrategy.cs:
TimeOnly.Humanize的策略契约(同样受NET6_0_OR_GREATER保护)。
每个接口都对应 Configurator 上的一个可替换策略属性,且默认实现都委托给同一个 DateTimeHumanizeAlgorithms 静态类。这种"接口 + Configurator 属性 + 算法类"的组合,让使用者可以用最小的代价替换任意日期类型的人性化行为,而无需改动扩展方法与本地化管线。
总结:策略化设计的落地要点
围绕 IDateOnlyHumanizeStrategy,本文覆盖了从契约、调用链、内置实现到自定义扩展的完整路径。核心要点可归纳为:
- 契约极简:接口只有一个
Humanize(input, comparisonBase, culture)方法,返回本地化的日期距离文案; - 入口单一:
DateOnly.Humanize扩展方法通过Configurator.DateOnlyHumanizeStrategy解析策略,默认是DefaultDateOnlyHumanizeStrategy; - 两种内置策略:默认策略按固定阈值链(天 → 周 → 月 → 年)输出;精度策略通过
precision(默认 0.75)控制近似进位,适合对输出粒度有要求的场景; - 定制成本低:实现接口并在启动阶段挂载即可生效,但需遵循"启动时一次性设置"与线程安全约束;
- 本地化统一:文案最终由
Configurator.GetFormatter(culture)解析的区域短语表生成,策略本身不直接持有文案资源。
如需进一步深入,可继续阅读仓库中的对应实现与测试:DateTimeHumanizeAlgorithms.cs、DateOnlyHumanizeTests.cs,以及 API 文档 DefaultDateOnlyHumanizeStrategy 与 PrecisionDateOnlyHumanizeStrategy。