Humanizer 默认日期人性化策略解析DefaultDateTimeHumanizeStrategy 的算法、调用链与本地化原理【免费下载链接】HumanizerHumanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities项目地址: https://gitcode.com/gh_mirrors/hu/Humanizer导读DefaultDateTimeHumanizeStrategy是 .NET 开源库 Humanizer 中负责把两个DateTime之间的时间距离转化为自然语言短语如 yesterday、2 hours ago、in 3 months的默认实现类。它是DateTime.Humanize()扩展方法在未做任何自定义配置时实际执行的底层策略本文基于仓库中的 API 参考文档与源码完整讲解该类的公开 API、内部判定算法、与扩展方法及本地化 Formatter 的协作关系并给出可直接运行的调用示例与自定义策略的接入方式。类概述一个实现了策略接口的时间距离转文字计算器DefaultDateTimeHumanizeStrategy位于 Humanizer 的日期人性化DateTimeHumanize策略族中其职责在源码注释里定义得非常明确The default distance of time - words calculator即时间距离转文字的默认计算器。public class DefaultDateTimeHumanizeStrategy : Humanizer.IDateTimeHumanizeStrategy继承关系System.Object→DefaultDateTimeHumanizeStrategy实现接口IDateTimeHumanizeStrategy接口本身定义在 IDateTimeHumanizeStrategy.cspublic interface IDateTimeHumanizeStrategy { /// summary /// Calculates the distance of time in words between two provided dates used for DateTime.Humanize /// /summary string Humanize(DateTime input, DateTime comparisonBase, CultureInfo? culture); }从源码结构看该接口是整个策略模式的入口约定Humanizer 允许通过替换实现此接口的类来改变DateTime.Humanize()的输出粒度与措辞风格DefaultDateTimeHumanizeStrategy只是其中的默认实现同族的还有PrecisionDateTimeHumanizeStrategy支持自定义近似精度。构造函数与公开方法签名DefaultDateTimeHumanizeStrategy() 构造函数public DefaultDateTimeHumanizeStrategy();无参构造函数用于初始化该类的一个新实例。由于策略对象本身是无状态的状态全部通过方法参数传入它在 Configurator.cs 中被直接作为默认值实例化public static IDateTimeHumanizeStrategy DateTimeHumanizeStrategy { get; set; } new DefaultDateTimeHumanizeStrategy();Humanize(DateTime, DateTime, CultureInfo) 方法public string Humanize(System.DateTime input, System.DateTime comparisonBase, System.Globalization.CultureInfo? culture);功能计算两个给定日期之间的时间距离并以文字形式返回。参数说明参数类型含义inputDateTime要被人性化的目标日期comparisonBaseDateTime比较基准日期input相对它计算距离cultureCultureInfo?输出短语使用的区域文化传null时使用当前线程的文化返回string即人性化的时间距离短语如 5 minutes ago。从调用链上看DefaultDateTimeHumanizeStrategy自身非常轻量其 完整实现 只有一个表达式体方法把真正的计算委托给了内部静态算法类public class DefaultDateTimeHumanizeStrategy : IDateTimeHumanizeStrategy { public string Humanize(DateTime input, DateTime comparisonBase, CultureInfo? culture) DateTimeHumanizeAlgorithms.DefaultHumanize(input, comparisonBase, culture); }调用链从 DateTime.Humanize() 到策略再到算法策略类并非被直接调用的起点。日常开发中使用的是 DateHumanizeExtensions.cs 中定义的DateTime.Humanize()扩展方法public static string Humanize(this DateTime input, bool? utcDate null, DateTime? dateToCompareAgainst null, CultureInfo? culture null) { var comparisonBase dateToCompareAgainst ?? DateTime.UtcNow; utcDate ?? input.Kind ! DateTimeKind.Local; comparisonBase utcDate.Value ? comparisonBase.ToUniversalTime() : comparisonBase.ToLocalTime(); return Configurator.DateTimeHumanizeStrategy.Humanize(input, comparisonBase, culture); }完整调用链如下扩展方法层DateHumanizeExtensions.Humanize处理可选参数——dateToCompareAgainst缺省时以DateTime.UtcNow为基准utcDate缺省时按input.Kind推断input.Kind ! DateTimeKind.Local则按 UTC 处理随后将基准时间统一换算为 UTC 或本地时间。策略分发层Configurator.DateTimeHumanizeStrategy读取当前配置的策略实例默认即DefaultDateTimeHumanizeStrategy调用其Humanize。算法层DateTimeHumanizeAlgorithms.DefaultHumanize执行具体的时间粒度判定与短语组装。格式化层Configurator.GetFormatter(culture)按文化解析出IFormatter最终产出本地化短语。此外扩展方法还提供了DateTime?可空重载DateHumanizeExtensions.cs当值为null时直接返回DateHumanize_Never()即 never不会进入策略层。默认算法剖析粒度分档与短语选择真正的核心逻辑位于 DateTimeHumanizeAlgorithms.csDefaultHumanize先做前置计算再调用私有重载完成粒度判定。第一步确定时态与时间差public static string DefaultHumanize(DateTime input, DateTime comparisonBase, CultureInfo? culture) { var tense input comparisonBase ? Tense.Future : Tense.Past; var ts new TimeSpan(Math.Abs(comparisonBase.Ticks - input.Ticks)); var sameMonth comparisonBase.Date.AddMonths(tense Tense.Future ? 1 : -1) input.Date; var days Math.Abs((input.Date - comparisonBase.Date).Days); return DefaultHumanize(ts, sameMonth, days, tense, culture); }时态判定input comparisonBase即未来Future否则为过去Past对应Tense枚举。时间差以TimeSpan形式取两个时刻的绝对差值。sameMonth 预判用于 28~30 天这一特殊区间——当差值接近下个月同一天时输出1 month而非30 days。days按日期部分忽略时刻计算相差的天数。第二步按时间跨度逐级分档私有重载 DefaultHumanize(TimeSpan ts, bool sameMonth, int days, Tense tense, CultureInfo? culture) 是一串自小而大的 if 分档每一档选择TimeUnit与数量交给 Formatter 渲染时间跨度条件输出的时间单位数量TotalMilliseconds 500Millisecond0即 nowTotalSeconds 60Secondts.SecondsTotalSeconds 120Minute1TotalMinutes 60Minutets.MinutesTotalMinutes 90Hour1TotalHours 24Hourts.HoursTotalHours 48DaydaysTotalDays 7Dayts.DaysTotalDays 28Weekts.Days / 728 TotalDays 30Month同月或 Day1 或ts.DaysTotalDays 345MonthFloor(TotalDays / 29.5)其余YearFloor(TotalDays / 365)若为 0 则取 1几个值得注意的工程细节约化rounding策略 60s但 120s这一档不存在——当差值超过 60 秒但不足 120 秒时会向上约化为1 minute同理 60~90 分钟向上约化为1 hour、24~48 小时向上约化为1 day。这是典型的取最接近的自然表达单位策略。月份换算345天以下按29.5天/月估算345天及以上按365天/年估算并兜底years 1避免出现0 years。28~30 天特例若两个日期落在相邻月份的同一日sameMonth true输出1 month否则仍按天数输出保证月边界场景的语义正确。第三步交给 Formatter 产出本地化短语算法层不做任何硬编码文案而是通过Configurator.GetFormatter(culture)获取 IFormatter调用formatter.DateHumanize(TimeUnit timeUnit, Tense timeUnitTense, int unit);本地化原理从 YAML 短语表到 DefaultFormatter短语的实际文本来源于各语言的 YAML 资源文件。以英语为例en.yml 的relativeDate段落定义了完整的过去/未来短语表例如phrases: relativeDate: now: now today: today never: never past: day: single: yesterday multiple: afterCount: ago forms: singular: day default: days future: day: single: tomorrow multiple: afterCount: from now forms: singular: day default: daysDefaultFormatterDefaultFormatter.cs的DateHumanize方法从该短语表解析出结果public virtual string DateHumanize(TimeUnit timeUnit, Tense timeUnitTense, int unit) TryFormatDateFromPhraseTable(timeUnit, timeUnitTense, unit, out var result) ? result : throw new InvalidOperationException($Missing generated relative-date phrase for {Culture.Name} and unit {timeUnit}.);短语表由源码生成器从 YAML 编译而来支持single单数特例如 yesterday/tomorrow、multiple的复数形式以及{count}占位符。这就是为什么同一种时间距离在不同culture下会输出完全不同的自然表达而策略算法本身与文化无关。与 PrecisionDateTimeHumanizeStrategy 的对比同族策略 PrecisionDateTimeHumanizeStrategy.cs 允许通过构造函数传入精度参数默认0.75public 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); }两者的核心差异Default按固定阈值分档60s、120s、90min等追求最常见的自然表达例如 61 秒输出 a minute ago。Precision用precision参与进位判断如seconds 59 * precision、minutes 59 * precision可以近似出更精确的整数单位结果适合需要更严格数值语义如TimeSpan场景的场合。如何替换与自定义策略由于Configurator.DateTimeHumanizeStrategy是公开可写属性Configurator.cs你可以在应用启动时整体替换日期人性化策略// 使用默认策略显式声明 Configurator.DateTimeHumanizeStrategy new DefaultDateTimeHumanizeStrategy(); // 或切换为高精度策略 Configurator.DateTimeHumanizeStrategy new PrecisionDateTimeHumanizeStrategy(0.9);也可以实现IDateTimeHumanizeStrategy接口编写完全自定义的策略类再赋给该属性。仓库源码注释Configurator.cs给出了明确的线程安全约束该属性只应在应用启动阶段、任何人性化操作发生之前设置一次在多线程场景下访问该属性时应使用 volatile 读取或适当的同步机制生产环境应避免在服务已经开始处理请求后再修改此值。测试验证如何用注入基准时间保证可断言策略的正确性由测试体系覆盖。仓库的 DateHumanize.cs 提供了一个Verify辅助方法根据TimeUnit与Tense构造TimeSpan增量并在测试中把Configurator.DateTimeHumanizeStrategy显式设为DefaultDateTimeHumanizeStrategy或带精度的策略再通过dateToCompareAgainst注入固定的基准时间如2013-06-20 09:58:22 UTC从而消除CPU 滴答导致断言竞态的问题。这种做法同样值得在实际业务测试中借鉴调用Humanize时显式传入dateToCompareAgainst与culture即可让时间表达的输出完全确定、可单测。实战示例与注意事项using Humanizer; using System.Globalization; var now new DateTime(2026, 9, 23, 12, 0, 0, DateTimeKind.Utc); // 过去 5 分钟 now.AddMinutes(-5).Humanize(utcDate: true, dateToCompareAgainst: now); // 5 minutes ago // 未来 1 天英文短语表中有单数特例 now.AddDays(1).Humanize(utcDate: true, dateToCompareAgainst: now); // tomorrow // 过去 1 天 now.AddDays(-1).Humanize(utcDate: true, dateToCompareAgainst: now); // yesterday // 指定中文文化输出 now.AddDays(2).Humanize(utcDate: true, dateToCompareAgainst: now, culture: new CultureInfo(zh-CN)); // 输出中文相对时间短语 // 空值返回 never DateTime? never null; never.Humanize(); // never使用要点归纳DefaultDateTimeHumanizeStrategy是Configurator.DateTimeHumanizeStrategy的默认值覆盖了绝大多数相对时间展示需求无需任何配置即可工作若需要更精确的整数单位表达可切换到PrecisionDateTimeHumanizeStrategy并调整精度参数传入culture可获得完整的多语言本地化输出短语来自 src/Humanizer/Locales 下的各语言 YAML 资源在测试与时间敏感的业务逻辑中始终通过dateToCompareAgainst显式传入基准时间保证结果确定性替换策略务必在应用启动阶段完成并遵守仓库文档给出的线程安全建议。总结DefaultDateTimeHumanizeStrategy虽是一个仅有十几个有效代码行的类却处于 Humanizer 日期人性化能力的关键位置它向上承接DateTime.Humanize()扩展方法向下委托给DateTimeHumanizeAlgorithms完成时间粒度分档最终由DefaultFormatter依据各语言的 YAML 短语表输出本地化文字。理解它的算法分档、时态判定、与PrecisionDateTimeHumanizeStrategy的差异以及Configurator的替换机制就掌握了 Humanizer 相对时间表达功能的完整脉络。【免费下载链接】HumanizerHumanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities项目地址: https://gitcode.com/gh_mirrors/hu/Humanizer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
