Humanizer 日期时间人性化策略体系详解:DateTimeHumanizeStrategy 命名空间与自定义策略开发指南

原创2026-09-25 23:37:581,631 阅读
文章标签:开发工具

Humanizer 日期时间人性化策略体系详解:DateTimeHumanizeStrategy 命名空间与自定义策略开发指南

导读

Humanizer.DateTimeHumanizeStrategy 是 Humanizer 库中负责把"两个时间点之间的距离"翻译成自然语言(如 "3 hours ago"、"yesterday"、"in 2 weeks")的核心命名空间。它面向 DateTime、DateTimeOffset、DateOnly、TimeOnly 四种时间类型,提供"默认精确匹配"与"精度近似"两套算法,并通过策略接口实现了完全可替换的扩展机制。阅读本文后,你将掌握:四类策略接口与八种内置策略的职责分工、默认算法与精度算法的内部判定逻辑、如何通过 Configurator 全局替换策略,以及如何实现自定义策略并在测试中验证行为。

一、命名空间全景:一个策略,四种时间类型

DateTimeHumanizeStrategy 命名空间的设计思路非常清晰:同一套"距离转文字"的语义,分别适配 .NET 中的四种时间类型。从 API 索引看,它对外暴露了 4 个接口和 8 个实现类,恰好形成 4 组一一对应的配对:

时间类型 策略接口 默认实现 精度实现
DateTime IDateTimeHumanizeStrategy DefaultDateTimeHumanizeStrategy PrecisionDateTimeHumanizeStrategy
DateTimeOffset IDateTimeOffsetHumanizeStrategy DefaultDateTimeOffsetHumanizeStrategy PrecisionDateTimeOffsetHumanizeStrategy
DateOnly(.NET 6+) IDateOnlyHumanizeStrategy DefaultDateOnlyHumanizeStrategy PrecisionDateOnlyHumanizeStrategy
TimeOnly(.NET 6+) ITimeOnlyHumanizeStrategy DefaultTimeOnlyHumanizeStrategy PrecisionTimeOnlyHumanizeStrategy

这种分组方式带来的直接好处是:上层 API(DateTime.Humanize()、DateTimeOffset.Humanize()、DateOnly.Humanize()、TimeOnly.Humanize())完全解耦于具体算法。每个接口都只定义一个方法:

// 以 IDateTimeHumanizeStrategy 为例(src/Humanizer/DateTimeHumanizeStrategy/IDateTimeHumanizeStrategy.cs)
public interface IDateTimeHumanizeStrategy
{
    string Humanize(DateTime input, DateTime comparisonBase, CultureInfo? culture);
}

三个参数的含义分别是:input(被描述的"目标时刻")、comparisonBase("基准时刻",通常为 DateTime.Now)、culture(可选文化,为 null 时使用当前线程文化)。返回值即本地化的自然语言描述,时态方向由 input 与 comparisonBase 的大小关系决定——未来时态(future)与过去时态(past)在算法内部以 Tense 枚举区分(定义见 src/Humanizer/Localisation/Tense.cs)。

需要特别说明的是,DateOnly 与 TimeOnly 的接口位于 #if NET6_0_OR_GREATER 条件编译块内(如 IDateOnlyHumanizeStrategy.cs),这是因为这两个类型是 .NET 6 才引入的 BCL 类型;面向 .NET Framework 4.8 等旧目标框架时,命名空间中只包含 DateTime / DateTimeOffset 相关的两个接口与四个实现类。

二、四类策略接口:约定与挂载点

接口的 XML 注释直接指明了每个接口的挂载位置——对应的 Configurator 静态属性。这个约定意味着:如果你想为某一种时间类型定制人性化文案,只需实现对应接口,并把实例赋给 Configurator 上对应的静态属性即可。

实际挂载点集中在 src/Humanizer/Configuration/Configurator.cs:

// Configurator.cs 中的关键默认值(第 107、138、148 行附近)
public static IDateTimeHumanizeStrategy DateTimeHumanizeStrategy { get; set; } = new DefaultDateTimeHumanizeStrategy();
public static IDateOnlyHumanizeStrategy   DateOnlyHumanizeStrategy   { get; set; } = new DefaultDateOnlyHumanizeStrategy();
public static ITimeOnlyHumanizeStrategy   TimeOnlyHumanizeStrategy   { get; set; } = new DefaultTimeOnlyHumanizeStrategy();

(DateTimeOffsetHumanizeStrategy 属性同样定义于该文件,默认值为 new DefaultDateTimeOffsetHumanizeStrategy()。)

而扩展方法层只是薄薄的转发层:src/Humanizer/DateHumanizeExtensions.cs 中 DateTime.Humanize() 的实现为 Configurator.DateTimeHumanizeStrategy.Humanize(input, comparisonBase, culture)(第 22 行),DateTimeOffset、DateOnly、TimeOnly 的扩展方法分别在 56、89、123 行以同样方式委托给各自的策略属性。也就是说,从扩展方法到策略实现的调用链是"纯委托"结构,策略内部算法完全由实现类自己决定。

三、默认策略:面向日常口语的分段判定

四个 Default*HumanizeStrategy 实现类本身没有任何业务逻辑,只是把参数原样转交给 DateTimeHumanizeAlgorithms 这个内部静态类:

// DefaultDateTimeHumanizeStrategy.cs
public string Humanize(DateTime input, DateTime comparisonBase, CultureInfo? culture) =>
    DateTimeHumanizeAlgorithms.DefaultHumanize(input, comparisonBase, culture);

真正体现"人性化"直觉的,是 DateTimeHumanizeAlgorithms.cs 中 DefaultHumanize 的分段判定逻辑——它按时间跨度从小到大逐级挑选最贴近口语的表述,而不是机械地取最大单位:

< 500 ms        → 刚刚(毫秒级,用 0 值)
< 60 秒         → N 秒前/后
< 120 秒        → 1 分钟前/后(口语习惯)
< 60 分钟       → N 分钟前/后
< 90 分钟       → 1 小时前/后(口语习惯)
< 24 小时       → N 小时前/后
< 48 小时       → 昨天/明天(基于日历日差)
< 7 天          → N 天前/后
< 28 天         → N 周前/后
28~30 天        → 同月则为 1 个月,否则按天
< 345 天        → N 个月(按 29.5 天/月折算)
其余             → N 年前/后(按 365 天/年折算,至少 1)

几个值得玩味的实现细节:

  • 120 秒与 90 分钟的"口语化边界":跨度在 60~120 秒时输出"1 分钟",60~90 分钟时输出"1 小时",这是为了符合英语等语言中 "a minute ago"、"an hour ago" 的自然表达习惯,避免出现 "2 minutes" 这种反直觉表述;
  • 48 小时内的"昨天/明天"判定:DefaultHumanize 在 ts.TotalHours < 48 时使用日历日差 days(由 (input.Date - comparisonBase.Date).Days 计算),而非单纯的小时数,从而正确处理跨日边界;
  • 28~30 天的"月份歧义":此区间会额外检查 sameMonth——即 comparisonBase 加/减一个月后是否恰好等于 input 所在日期(未来用 AddMonths(1)、过去用 AddMonths(-1),见第 142 行)。若同月则报"1 个月",否则报具体的 N 天,避免把 29 天误报成不存在的"第 2 个月";
  • 最终兜底:超过 345 天按 365 天/年折算年数,且当年数折算为 0 时强制为 1(第 257-261 行),保证 1 年内偏大的跨度也能输出 "1 year"。

DefaultHumanize 的四个 DateOnly/TimeOnly 重载(#if NET6_0_OR_GREATER 块内)遵循同样的规则,差异在于:DateOnly 重载直接用 DayNumber 差值构造天级 TimeSpan,相等时走 DateOnlyHumanizeToday 输出"今天"(借助 DefaultFormatter.DateHumanize_Today,见第 171-178 行);TimeOnly 重载则把 sameMonth 固定为 true、days 固定为 0,因为纯时间比较天然不会跨月。

四、精度策略:可调近似度的数学逼近

Precision*HumanizeStrategy 系列(如 PrecisionDateTimeHumanizeStrategy.cs)是 C# 12 主构造函数风格的实现,构造参数 precision 默认值为 0.75:

public class PrecisionDateTimeHumanizeStrategy(double precision = .75) : IDateTimeHumanizeStrategy
{
    readonly double precision = precision;

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

precision 的语义是近似阈值:值越接近 1,越倾向于向上进位;值越小,越保守。它通过 PrecisionHumanize 中一组"分数阈值"参与判定:

// 从较小单位向较大单位逐步近似
if (ts.Milliseconds >= 999 * precision) seconds += 1;
if (seconds >= 59 * precision)           minutes += 1;
if (minutes >= 59 * precision)           hours += 1;
if (hours >= 23 * precision)             days += 1;

// 月与年的折算
if (days >= 30 * precision && days <= 31) months = 1;
if (days > 31 && days < 365 * precision)  // 按 30 天/月折算并据 precision 决定是否 +1
if (days >= 365 * precision && days <= 366) years = 1;
if (days > 365)                            // 按 365 天/年折算并据 precision 决定是否 +1

由于 precision = 0.75,默认行为是"59.25 秒即进位为 1 分钟""23.25 小时即进位为 1 天",属于比较激进的近似;当你需要更保守的结果(例如严格的 59.9 秒才算 1 分钟),可以构造 new PrecisionDateTimeHumanizeStrategy(0.9) 并替换默认策略。输出时从年、月、日、时、分、秒逐级取最大非零单位(第 98-130 行),因此精度策略更适合需要"单一醒目单位"的业务场景,比如倒计时展示。

与默认策略类似,DateTimeOffset 变体会先把输入统一为 UTC 再计算(input.UtcDateTime),避免时区偏移干扰时长差;DateOnly 变体相等时同样输出"今天"。

五、配置与替换:三种注入方式

1. 全局静态替换(默认机制)

Configurator 上的属性是可写的静态属性,直接赋值即可全库生效:

// 用精度策略替换 DateTime 的默认策略
Configurator.DateTimeHumanizeStrategy = new PrecisionDateTimeHumanizeStrategy(precision: 0.9);

// 之后所有 DateTime.Humanize() 调用都会走精度算法
var text = DateTime.UtcNow.AddMinutes(65).Humanize(); // "in an hour"

2. 传入 comparisonBase 与 culture 的单次调用

扩展方法层面,Humanize() 本身支持显式传基准时间与文化,用于单元测试或国际化场景:

// 指定基准时间(典型测试写法)
var baseTime = new DateTime(2020, 1, 1, 0, 0, 0);
var result = baseTime.AddDays(2).Humanize(comparisonBase: baseTime); // "2 days from now"

// 指定文化,输出随语言环境本地化
var zh = new CultureInfo("zh-CN");
var resultZh = DateTime.UtcNow.AddHours(-3).Humanize(culture: zh);

3. 自定义策略(接口注入)

实现一个接口并挂载到对应属性,即可完全接管某类型的人性化文案。例如一个把所有跨度都输出为小时的自定义策略:

public class HoursOnlyDateTimeStrategy : IDateTimeHumanizeStrategy
{
    public string Humanize(DateTime input, DateTime comparisonBase, CultureInfo? culture)
    {
        var hours = Math.Abs((comparisonBase - input).TotalHours);
        var tense = input > comparisonBase ? "in" : "ago";
        return $"{hours:F0} hours {tense}";
    }
}

// 挂载
Configurator.DateTimeHumanizeStrategy = new HoursOnlyDateTimeStrategy();

由于 Configurator 是静态可写属性,替换会在进程内立即对所有后续 Humanize() 调用生效;在测试中更换策略后,建议在测试收尾时恢复为默认实现,避免影响其他测试用例(仓库测试中 DateTimeHumanizeDefaultStrategyTests 等即按此思路组织,见 tests/Humanizer.Tests/DateTimeHumanizeDefaultStrategyTests.cs)。

六、策略的时态与本地化输出

无论默认还是精度算法,最终输出都委托给 Configurator.GetFormatter(culture) 获取的 IFormatter(默认实现见 src/Humanizer/Localisation/Formatters/DefaultFormatter.cs),并以 TimeUnit(Year/Month/Week/Day/Hour/Minute/Second/Millisecond,定义见 src/Humanizer/Localisation/TimeUnit.cs)配合 Tense 生成本地化短语。这意味着:

  • 策略只负责"算单位",不负责"造句子"——所有语言的字面量都由 Formatter 从本地化资源(Locales/*.yml,如 src/Humanizer/Locales/en.yml)读取,因此策略天然支持多语言;
  • 传入 culture 为 null 时使用 CultureInfo.CurrentCulture,传入指定文化时则输出对应语言的 "yesterday / tomorrow / 3 weeks ago" 等表达。

七、源码级验证:测试如何锁定策略行为

仓库测试覆盖了策略的典型行为,可作为自定义策略的对拍参考:

  • DateTimeHumanizeDefaultStrategyTests.cs 验证默认策略下秒、分、时、天、周、月、年各分段的输出,例如 1 天报 "yesterday"、30 天报 "one month";
  • DateTimeHumanizePrecisionStrategyTests.cs 验证精度策略的近似行为,包括自定义 precision 参数的效果;
  • DateTimeOffsetHumanizeTests.cs 与 DateOnlyHumanizeTests.cs、TimeOnlyHumanizeTests.cs 分别锁定三种其他时间类型的策略输出,且大量测试通过 <a href="https://link.gitcode.com/i/570505fcec1c898661503681240716c7" target="_blank">UseCulture] 特性([tests/Humanizer.Tests/UseCultureAttribute.cs)验证多语言下的文案。

这些测试文件同时印证了一个设计事实:Humanize 的语义是"以当前时刻或指定基准为参照的相对时间",策略层把"参照系选择 + 单位折算"封装成可替换单元,这正是 DateTimeHumanizeStrategy 命名空间的价值所在。

总结

Humanizer.DateTimeHumanizeStrategy 是 Humanizer 相对时间能力的策略中枢:四个接口对应四种时间类型,默认策略提供贴合口语的分段文案,精度策略提供可调近似度的单一单位输出,两者共享 DateTimeHumanizeAlgorithms 的折算逻辑,并通过 Configurator 的静态属性实现即插即用。开发者在日常业务中可直接使用 DateTime.Humanize() 获得本地化相对时间;在需要定制文案或近似规则时,实现对应接口并挂载到 Configurator 即可,无需改动 Humanizer 任何内部代码。

登录后查看全文
Humanizer