Humanizer 中 IDateOnlyHumanizeStrategy 接口详解:自定义 DateOnly 人性化日期策略
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 —— 默认的"距离->词"计算器
- PrecisionDateOnlyHumanizeStrategy —— 基于精度系数的近似计算器
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)可以归纳为以下几步:
- 同日短路:
input == comparisonBase时直接返回"today"。该路径走DateOnlyHumanizeToday(L171-L178):先取formatter.DateHumanize(TimeUnit.Millisecond, Tense.Past, 0),再若 formatter 是DefaultFormatter则进一步调用DateHumanize_Today,从而允许派生 formatter 单独重写"today"措辞。 - 确定时态与天数差:
tense = input > comparisonBase ? Tense.Future : Tense.Past;天数差用Math.Abs(comparisonBase.DayNumber - input.DayNumber)计算,并构造为整天的TimeSpan。 - sameMonth 判断:
comparisonBase.AddMonths(tense == Tense.Future ? 1 : -1) == input,用于 28~29 天区间的措辞选择(跨月显示 "X days ago",同月内显示 "one month ago/from now")。 - 阶梯式区间映射:由小到大依次判断
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 版本文档中还有配套页面,可结合阅读:
- IDateTimeHumanizeStrategy
- IDateTimeOffsetHumanizeStrategy
- ITimeOnlyHumanizeStrategy
- DefaultDateOnlyHumanizeStrategy
- PrecisionDateOnlyHumanizeStrategy
- Configurator
小结
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 中的用例可作为行为回归的参考基线。