Humanizer 流式日期 API 详解：On.December 类源码级解析

开发工具【免费下载链接】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 的On类族为 .NET 开发者提供了一组日历般自然的流式日期访问器。本篇文章以On.December为核心完整讲解其 31 个具名日期属性The1stThe31st、通用The(int)方法、构造函数与继承结构并对照仓库源码On.Days.cs与测试用例OnTests.cs剖析其实现原理与适用边界。读完本文你将能在自己的 .NET 项目中熟练使用On.December.The25th这类零魔法数字的日期表达并理解它背后的 T4 代码生成机制。一、On.December是什么On.December是 HumanizerOn静态类内嵌的嵌套类专门为 12 月提供流式日期访问器。它在源码中位于 On.Days.csOnDate.Days.cs中还有对应的DateOnly版本类摘要如下public class On { /// summary /// Provides fluent date accessors for December /// /summary public class December { // ... } }成员说明完整类型名Humanizer.On.December基类System.ObjectHumanizer 文档标注的继承链为 Object → December命名空间Humanizer定位所有成员均为static无需实例化即可调用1.1 构造函数public December();构造函数是编译器生成的默认构造函数用于初始化 December 类的新实例。实际使用中On.December只承载静态成员直接以On.December.TheXxx形式访问即可无需也无法在常规用法中手动构造实例。1.2 全部 31 个具名属性12 月共有 31 天On.December为此提供了从The1st到The31st共 31 个静态只读属性每个属性都返回当前年份的指定日。例如public static DateTime The1st { get; } // 当前年 12 月 1 日 public static DateTime The10th { get; } // 当前年 12 月 10 日 public static DateTime The24th { get; } // 当前年 12 月 24 日平安夜 public static DateTime The25th { get; } // 当前年 12 月 25 日圣诞节 public static DateTime The31st { get; } // 当前年 12 月 31 日跨年夜完整成员清单源码逐一实现The1st、The2nd、The3rd、The4th、The5th、The6th、The7th、The8th、The9th、The10th、The11th、The12th、The13th、The14th、The15th、The16th、The17th、The18th、The19th、The20th、The21st、The22nd、The23rd、The24th、The25th、The26th、The27th、The28th、The29th、The30th、The31st1.3 通用方法The(int dayNumber)当 31 个具名属性无法满足需求例如需要动态计算日期时可调用通用方法public static DateTime The(int dayNumber);参数dayNumber为System.Int32表示当前年份 12 月的第 n 天返回System.DateTime。二、源码实现一行代码背后的机制2.1 属性与方法的真实实现从 On.Days.cs 可以看到所有成员都是一行表达式public class December { public static DateTime The(int dayNumber) new(DateTime.Now.Year, 12, dayNumber); public static DateTime The1st new(DateTime.Now.Year, 12, 1); // The2nd ~ The31st 依此类推 public static DateTime The25th new(DateTime.Now.Year, 12, 25); // ... }核心规律年份始终取DateTime.Now.Year即当前年。月份固定为 12。日具名属性为硬编码数字The(int)方法则透传调用方传入的dayNumber。也就是说On.December.The4th等价于new DateTime(DateTime.Now.Year, 12, 4)。2.2 T4 模板生成12 个月份的同一套代码On.December并非手写代码而是由 T4 模板 On.Days.tt 自动生成。模板的核心逻辑是for (var month 1; month 12; month) { // 用闰年 2012 计算每月天数2 月 29 天 var daysInMonth DateTime.DaysInMonth(2012, month); // 生成月份类 The(int dayNumber) // 再对每一天调用 day.Ordinalize() 生成 The1st/The2nd/The3rd... }因此仓库中同时存在On.January、On.February……On.December共 12 个结构完全对称的嵌套类On.December只是这套模板在 12 月上的产物。属性命名中的1st/2nd/3rd/4th...正是调用了 Humanizer 自身的Ordinalize()扩展方法见 InflectorExtensions.cs 体系生成的序数词后缀。三、典型用法与代码示例using Humanizer; // 具名属性圣诞节当前年份 DateTime christmas On.December.The25th; // 通用方法动态指定日期 DateTime deadline On.December.The(20); // 组合使用先拿到 12 月某日再基于它做运算 var newYearEve On.December.The31st; var firstDayOfNextYear newYearEve.AddDays(1); // 输出示例以 2026 年为例 Console.WriteLine(christmas); // 2026/12/25 0:00:00 Console.WriteLine(deadline); // 2026/12/20 0:00:00需要注意返回的DateTime时间部分为00:00:00午夜。当前年是惰性求值的属性在每次访问时都读取DateTime.Now.Year因此同一属性在同一天内读取结果相同跨年如跨年夜的午夜前后读取则可能不同。具名属性的命名完全遵循英文序数词习惯1/2/3/21/22/23/31 分别对应1st/2nd/3rd/21st/22nd/23rd/31st。四、配套的DateOnly变体OnDate.December从 .NET 6 起仓库还在 OnDate.Days.cs 中提供了返回DateOnly的平行版本public class OnDate { public class December { public static DateOnly The(int dayNumber) new(DateTime.Now.Year, 12, dayNumber); public static DateOnly The1st new(DateTime.Now.Year, 12, 1); // The2nd ~ The31st 依此类推 } }若你的项目面向 .NET 6 且无需时间部分优先使用OnDate.December以避免多余的午夜时间戳语义。对应测试位于 OnDateTests.cs该文件整体以#if NET6_0_OR_GREATER包裹。五、测试验证行为与预期完全一致仓库用 xUnit 事实测试锁定了On.December的行为OnTests.cs[Fact] public void OnDecemberThe4th() Assert.Equal(new(DateTime.Now.Year, 12, 4), On.December.The4th); [Fact] public void OnFebruaryThe() Assert.Equal(new(DateTime.Now.Year, 2, 11), On.February.The(11));测试要点On.December.The4th必须恒等于new DateTime(当前年份, 12, 4)通用方法On.February.The(11)同样走DateTime.Now.Year年份逻辑GeneratedFluentDateTests.cs 中维护了January1 … December12的月份对照表用于系统性校验 12 个月份生成的代码。六、适用场景与注意事项适用场景业务代码中需要表达今年 12 月的某个固定日期如年度结算日、圣诞节促销、年终报告截止日用On.December.The25th比new DateTime(DateTime.Now.Year, 12, 25)更直观、更少魔法数字配合 Humanizer 其他日期扩展如Humanize()、In/InDate系列构建可读的日期业务逻辑。注意事项始终基于当前年无法直接指定其他年份。若要表达2009 年 12 月应改用In系列如In.DecemberOf(2009)见 InTests.cs 中的InDecemberOf2009测试。参数边界The(int dayNumber)若传入超出 1–31 的范围如 0 或 32会触发ArgumentOutOfRangeException由DateTime构造函数抛出调用方需自行校验。时区与并发值来自本地系统时钟的DateTime.Now跨时区部署时以运行机器本地时间为准。七、小结On.December是 Humanizer 流式日期 体系的一个缩影通过 T4 模板为每个月生成 31 个具名静态属性与一个通用The(int)方法让当前年份某月某日的表达从new DateTime(DateTime.Now.Year, 12, 25)进化为On.December.The25th。结合OnDate.DecemberDateOnly 版与In.DecemberOf(2009)指定年份版你可以在不同场景下都获得自然、可读、零歧义的日期代码。若要继续探索可查看同类 API 文档 Humanizer.On.md、Humanizer.OnDate.md以及全部 12 个月的生成代码 On.Days.cs。赞分享开发工具【免费下载链接】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 详解In.Nine 类完整参考与源码级解析Humanizer 流式日期 API 详解 In.Nine 类完整参考与源码级解析 本篇文章聚焦 Humanizer 流式日期FluentDateAPI开发工具Seerr 源码构建与部署完整指南从克隆到开机自启的五步实操Seerr 源码构建与部署完整指南从克隆到开机自启的五步实操 从源码构建 SeerrJellyseerr 社区延续项目的媒体请求管理服务你拿到的不只是最开发工具Humanizer 流式日期 API 详解In 类使用指南与源码剖析Humanizer 流式日期 API 详解In 类使用指南与源码剖析 In 类是 Humanizer 流式日期Fluent Date体系中最常用的静态入口开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考