Humanizer 流畅日期 API 详解：In.Three 静态类实现 3 秒到 3 年的日期计算

开发工具【免费下载链接】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点击查看免费下载Humanizer 提供了一套以自然语言命名的流畅日期FluentDateAPI其中In.Three静态类专门用于表达从现在起 3 个时间单位之后以及从指定日期起 3 个时间单位之后的日期计算。本文以 Humanizer.In.Three.md 这一 API 参考文档为主体结合仓库源码与测试用例完整梳理In.Three的 7 个属性、7 个方法、底层实现原理及实际使用场景让你在 .NET 项目中能够直接用In.Three.Days、In.Three.MonthsFrom(date)这类可读性极强的表达式替代手写DateTime.Now.AddDays(3)。认识 In 与 In.Three把时间偏移写成自然语言In是 Humanizer 在 src/Humanizer/FluentDate 目录下定义的一个public partial class通过多个 partial 文件共同组装出一套完整的时间表达体系In.cs 提供TheYear(int year)等按年份取日期的方法In.Months.cs 提供January、JanuaryOf(int year)等按月取日期的方法In.SomeTimeFrom.cs 定义从One到Ten共 10 个静态嵌套类In.Three正是其中之一In.SomeTimeFrom.tt 是生成上述嵌套类的 T4 模板解释了为什么代码呈现高度对称的规律性。In.Three的完整声明为public static class In.Three它继承自System.Object内部不维护任何实例状态所有成员均为public static属于典型的纯工具型静态类。其职责非常单一围绕数字 3 提供 7 种时间单位秒、分钟、小时、天、周、月、年的相对当前时刻与相对指定时刻两类计算对应 7 个只读属性与 7 个同名From方法。In.Three 属性详解3 个时间单位之后的未来时刻In.Three的 7 个属性均返回System.DateTime语义统一为从现在起的 3 个对应时间单位。完整清单如下属性语义返回类型实际实现Seconds3 秒之后System.DateTimeDateTime.UtcNow.AddSeconds(3)Minutes3 分钟之后System.DateTimeDateTime.UtcNow.AddMinutes(3)Hours3 小时之后System.DateTimeDateTime.UtcNow.AddHours(3)Days3 天之后System.DateTimeDateTime.UtcNow.AddDays(3)Weeks3 周之后System.DateTimeDateTime.UtcNow.AddDays(21)Months3 个月之后System.DateTimeDateTime.UtcNow.AddMonths(3)Years3 年之后System.DateTimeDateTime.UtcNow.AddYears(3)属性声明示例其余属性模式完全一致public static System.DateTime Days { get; }使用示例using Humanizer; var deadline In.Three.Days; // 现在 3 天 var timeout In.Three.Seconds; // 现在 3 秒 var nextQuarter In.Three.Months; // 现在 3 个月 var anniversary In.Three.Years; // 现在 3 年需要特别留意两个实现细节依据 src/Humanizer/FluentDate/In.SomeTimeFrom.cs基准时刻是DateTime.UtcNow而非DateTime.Now所有从现在起的属性都以 UTC 时间为基准计算返回的DateTime的Kind为Utc。如果你的业务逻辑期望本地时间需要自行调用.ToLocalTime()转换或改用基于指定日期的方法。周的单位换算为天Weeks的底层实现是DateTime.UtcNow.AddDays(21)3 * 7而不是AddWeeksSystem.DateTime本就没有AddWeeks方法这一点与 In.SomeTimeFrom.tt 模板中的i * 7生成逻辑完全对应。In.Three 方法详解以指定日期为基准的偏移计算与 7 个属性一一对应In.Three提供 7 个以DateTime date为参数、返回System.DateTime的静态方法语义统一为从给定日期起 3 个对应时间单位之后。完整清单如下方法签名语义SecondsFrom(System.DateTime date)3 秒后MinutesFrom(System.DateTime date)3 分钟后HoursFrom(System.DateTime date)3 小时后DaysFrom(System.DateTime date)3 天后WeeksFrom(System.DateTime date)3 周后MonthsFrom(System.DateTime date)3 个月后YearsFrom(System.DateTime date)3 年后方法签名示例其余方法模式完全一致public static System.DateTime SecondsFrom(System.DateTime date);使用示例using Humanizer; var baseDate new DateTime(2025, 1, 20, 9, 0, 0); var d1 In.Three.SecondsFrom(baseDate); // 2025-01-20 09:00:03 var d2 In.Three.MinutesFrom(baseDate); // 2025-01-20 09:03:00 var d3 In.Three.HoursFrom(baseDate); // 2025-01-20 12:00:00 var d4 In.Three.DaysFrom(baseDate); // 2025-01-23 09:00:00 var d5 In.Three.WeeksFrom(baseDate); // 2025-02-10 09:00:0021 天 var d6 In.Three.MonthsFrom(baseDate); // 2025-04-20 09:00:00 var d7 In.Three.YearsFrom(baseDate); // 2028-01-20 09:00:00这些方法的底层实现同样见 src/Humanizer/FluentDate/In.SomeTimeFrom.cs直接调用date.AddSeconds(3)、date.AddMinutes(3)、date.AddHours(3)、date.AddDays(3)、date.AddDays(21)、date.AddMonths(3)、date.AddYears(3)完全依赖System.DateTime的内置Add*方法不涉及任何自定义时间算法因此可以放心地用于任意DateTime无论其Kind是Utc、Local还是Unspecified。关于月与年的边界语义这里有一个值得注意的事实AddMonths(3)与AddYears(3)遵循 .NET 标准规则——若基准日是月末结果会自动向该月月末取整。例如new DateTime(2025, 1, 31).AddMonths(3)得到2025-04-30而不是不存在的2025-04-31。这是 .NET 框架层行为In.Three并未做任何额外处理。源码视角In.Three 的 T4 生成机制In.Three乃至整个One~Ten系列静态类并非手工逐个编写而是由 T4 模板批量生成的。在 In.SomeTimeFrom.tt 中可以看到核心生成循环#for (var i 1; i 10; i){ var plural i 1 ? s : ; var second Second plural; // ... 依次构造 Second/Minute/Hour/Day/Week/Month/Year 的变量名 # public static class # i.ToWords().Dehumanize() # { public static DateTime # second # DateTime.UtcNow.AddSeconds(# i #); public static DateTime # second #From(DateTime date) date.AddSeconds(# i #); // ... 其余时间单位同理 } #}#这段模板揭示了三个设计事实数字 1~10 全覆盖In中实际存在One到Ten共 10 个嵌套类In.Three只是其中之一One类的属性采用单数命名Second、Minute……Two以上采用复数命名Seconds、Minutes……。类名由数字转单词生成模板通过i.ToWords().Dehumanize()生成类名即3.ToWords()→three→Dehumanize()→Three。这正体现了 Humanizer 自身 APINumberToWordsExtension 与 StringDehumanizeExtensions的复用——用 Humanizer 生成 Humanizer 的代码。周统一换算为 7 的倍数天数模板中Weeks为AddDays(i * 7)与前面分析的三天/三周实现完全吻合。因此如果未来想了解In.Five、In.Ten等兄弟类的行为只需看同一份 In.SomeTimeFrom.cs 中对应区段即可其模式与In.Three完全一致。测试与官方示例验证 In.Three 的实际调用方式虽然仓库中 InTests.cs 的用例集中在月份与In.Five.DaysFrom(baseDate)等场景但由此可以确认整套In系列的调用约定In.N.DaysFrom(baseDate)等价于baseDate.AddDays(N)。官方示例项目 website/docs/_examples/scenarios-fluent-dates/Program.cs 也展示了同类用法using Humanizer; var startingPoint new DateTime(2025, 1, 20, 9, 0, 0); var twoMonthsLater In.Two.MonthsFrom(startingPoint); Console.WriteLine($Two months later: {twoMonthsLater:yyyy-MM-dd HH:mm}); // 输出Two months later: 2025-03-20 09:00把In.Two.MonthsFrom换成In.Three.MonthsFrom即为In.Three的等价写法。由此可归纳出In.Three与原生DateTimeAPI 的对应关系表Humanizer 写法等价原生写法In.Three.Seconds/In.Three.SecondsFrom(d)DateTime.UtcNow.AddSeconds(3)/d.AddSeconds(3)In.Three.Minutes/In.Three.MinutesFrom(d)DateTime.UtcNow.AddMinutes(3)/d.AddMinutes(3)In.Three.Hours/In.Three.HoursFrom(d)DateTime.UtcNow.AddHours(3)/d.AddHours(3)In.Three.Days/In.Three.DaysFrom(d)DateTime.UtcNow.AddDays(3)/d.AddDays(3)In.Three.Weeks/In.Three.WeeksFrom(d)DateTime.UtcNow.AddDays(21)/d.AddDays(21)In.Three.Months/In.Three.MonthsFrom(d)DateTime.UtcNow.AddMonths(3)/d.AddMonths(3)In.Three.Years/In.Three.YearsFrom(d)DateTime.UtcNow.AddYears(3)/d.AddYears(3)实战要点与注意事项综合上文在实际项目中使用In.Three时有四个要点值得牢记属性返回基于 UTC 的 DateTimeIn.Three.Days等价于DateTime.UtcNow.AddDays(3)返回值的Kind为Utc。需要本地时间时请主动转换In.Three.Days.ToLocalTime()。From 方法不改变基准日期的 KindIn.Three.DaysFrom(localDate)返回的仍是Local类型的DateTimeFrom系列适合以业务上的具体日期为锚点做偏移不涉及 UTC 换算。周、月、年的边界行为周按 7 天计月、年遵循AddMonths/AddYears的月末取整规则做日历相关业务如账单周期、订阅到期日时需按此预期设计。仅覆盖 1~10 的整数偏移In只提供One~Ten十个数字类更复杂的偏移如 3.5 天、23 小时应回退使用DateTime.Add*原生方法或组合使用In.Three.Hours、In.Three.Minutes等成员自行叠加。若需要基于当天/当月而不是当前时刻的偏移可以参考同目录下的InDate系列如 InDate.SomeTimeFrom.cs仅 .NET 6 可用其返回类型为DateOnly与In.Three的DateTime语义互补。整体而言In.Three的价值不在于提供新算法而在于让时间偏移代码具备自解释性阅读In.Three.DaysFrom(contractDate)比阅读contractDate.AddDays(3)更能直接传达合同日期三天后的业务含义这正是 Humanizer FluentDate 设计的目标。赞分享开发工具【免费下载链接】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点击查看免费下载相关推荐Humanizer 流式日期 API 详解InDate.Ten 的 10 天 / 周 / 月 / 年日期计算Humanizer 流式日期 API 详解InDate.Ten 的 10 天 / 周 / 月 / 年日期计算 本篇技术指南聚焦 Humanizer 流式日期开发工具Humanizer 流畅日期 API 详解In.One 类 1 秒至 1 年时间推算的完整参考Humanizer 流畅日期 API 详解 In.One 类 1 秒至 1 年时间推算的完整参考 本篇技术指南聚焦 Humanizer 的 FluentDat开发工具Humanizer FluentDate API 解析In.Three——用一句3 个时间单位之后完成日期计算Humanizer FluentDate API 解析 In.Three ——用一句3 个时间单位之后完成日期计算 In.Three 是 Humanize开发工具上一篇Tmax-9B-MLX-4bit内存优化如何在256GB统一内存上高效运行下一篇Open Notebook 本地部署教程5 个步骤跑通你的私有 AI 笔记系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考