Humanizer OnDate 流式日期访问器详解：用 DateOnly 优雅表达“某月某日“

开发工具【免费下载链接】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 的 FluentDate 子模块为 .NET 开发者提供了一套自然语言式的日期构建 API。本文聚焦其中的OnDate类它通过嵌套的月份类型与The(int)、The1stThe31st等一系列静态成员让你在 .NET 6 项目中以近乎口语的方式直接构造DateOnly实例。读完本文你将掌握OnDate的完整成员构成、它与On/In/InDate的关系、底层代码生成原理以及如何在测试与业务代码中正确使用这套流式 API。OnDate 类概述OnDate是 Humanizer 中负责用流式语法表达某个日期的公开类定义如下public class OnDate它继承自System.Object位于Humanizer命名空间下因此只要项目引用了 Humanizer 包即可直接使用OnDate.January.The23rd这样的写法。该类的全部实现位于 src/Humanizer/FluentDate/OnDate.Days.cs并且整个文件被#if NET6_0_OR_GREATER条件编译指令包裹——这意味着它依赖 .NET 6 引入的System.DateOnly类型仅在 .NET 6 及以上目标框架TFM中可用。从类结构看OnDate本身是一个纯静态外观facade容器其真正的访问能力来自嵌套其中的 12 个月份类型January、February、March、April、May、June、July、August、September、October、November、December。每个月份类型都对应当前年份中该月的某一天这一语义。月份嵌套类型与两种访问方式以 OnDate.Days.cs 中的January为例可以看到每个月份类型都提供两类静态成员public class January { /// summary /// The nth day of January of the current year /// /summary public static DateOnly The(int dayNumber) new(DateTime.Now.Year, 1, dayNumber); /// summary /// The 1st day of January of the current year /// /summary public static DateOnly The1st new(DateTime.Now.Year, 1, 1); // The2nd ... The31st 依此类推 }1. 动态方法The(int dayNumber)签名public static DateOnly The(int dayNumber)语义返回当前年份中该月的第dayNumber天取值范围1 到该月实际天数。传入超出范围的值会由new DateTime(...)的构造逻辑抛出ArgumentOutOfRangeException如 2 月传入 31典型用途当日期数字来自变量、循环或用户输入时使用例如OnDate.February.The(11)。2. 静态属性The1stThe31st语义为每月的每一天生成一个命名属性如The1st、The2nd……The31st覆盖范围按月实际天数生成。1 月、3 月等大月生成到The31st2 月仅生成到The28th模板基于闰年 2012 计算DateTime.DaysInMonth平年 2 月 29 日通过The(int)才能表达命名风格采用英文序数词格式1st、2nd、3rd、4th…与Humanizer.Ordinalize()扩展的输出一致典型用途表达固定不变的纪念日式日期如OnDate.December.The25th表示今年圣诞节。源码级实现T4 模板生成与 DateOnly 语义OnDate.Days.cs并非手写维护的 2300 多行代码而是由 T4 文本模板 src/Humanizer/FluentDate/OnDate.Days.tt 自动生成的。模板的核心逻辑清晰可循const int leapYear 2012; for (var month 1; month 12; month) { var firstDayOfMonth new DateTime(leapYear, month, 1); var monthName firstDayOfMonth.ToString(MMMM); // 生成月份嵌套类型 for (var day 1; day DateTime.DaysInMonth(leapYear, month); day) { var ordinalDay day.Ordinalize(); // 生成 TheNth 属性 } }这段模板说明了三件事月份命名借助DateTime.ToString(MMMM)输出英文月份名January…December因此月份类型名与当前区域性设置相关天数上限以 2012 这个闰年为基准调用DateTime.DaysInMonth保证 2 月 29 日The29th能被生成出来而平年 2 月只有 28 天序数词生成day.Ordinalize()复用了 Humanizer 自身的序数词扩展与The1st/The2nd的命名保持一致。每个访问器最终都收敛到一行构造代码 new(DateTime.Now.Year, month, day);注意这里显式使用了DateTime.Now.Year即当前年份这是OnDate与下面将要对比的On系列共同的核心语义它们永远指向今年的某一天而不是任意年份。与 On、In、InDate 的关系一套 API 的四种形态FluentDate 模块围绕用英文介词表达时间这一设计提供了四个相互对照的入口类全部位于 src/Humanizer/FluentDate 目录类返回类型语义源码文件OnDateTime今年某月某日可变日期时间On.Days.csOnDateDateOnly今年某月某日仅日期OnDate.Days.csInDateTime今年某月第一天等In.Months.cs、In.SomeTimeFrom.csInDateDateOnly今年某月第一天等InDate.Months.cs、InDate.csOnvsOnDate两者成员结构完全一致On也有January.The(int)、January.The1st等唯一差别是返回类型——On返回DateTime带时间部分时间默认为零点OnDate返回DateOnly。On的实现位于 On.Days.cs同样由 On.Days.tt 生成但不限定 .NET 6InvsInDateIn/InDate语义为某月的第一天例如In.April表示今年 4 月 1 日InDate同样仅在NET6_0_OR_GREATER下编译见 InDate.Months.cs。OnDate与InDate的区别可概括为OnDate精确到日InDate只到月的第一天。由此可以总结选型建议目标框架为 .NET 6、且只需要日期概念时优先用OnDate/InDate需要与DateTimeAPI 混用、或目标框架为 .NET Framework/.NET Core 3.1 时使用On/In。实战示例从构造到断言基础用法using Humanizer; // 今年 1 月 23 日DateOnly DateOnly jan23 OnDate.January.The23rd; // 今年 2 月 11 日动态天数 DateOnly feb11 OnDate.February.The(11); // 今年 12 月 25 日 DateOnly christmas OnDate.December.The25th; // 与 InDate 对照今年 4 月 1 日 DateOnly aprilFirst InDate.April;与现有日期逻辑衔接DateOnly可以直接参与比较、作为数据库如 EF Core 8 的date列映射类型if (OnDate.January.The1st DateOnly.FromDateTime(DateTime.Now)) { // 今天是今年元旦 }测试侧验证Humanizer 官方测试在 tests/Humanizer.Tests/FluentDate/OnDateTests.cs 中对该 API 做了直接断言例如[Fact] public void OnJanuaryThe23rd() Assert.Equal(new(DateTime.Now.Year, 1, 23), OnDate.January.The23rd); [Fact] public void OnFebruaryThe() Assert.Equal(new(DateTime.Now.Year, 2, 11), OnDate.February.The(11));更全面的覆盖见 GeneratedFluentDateTests.cs该文件同样由生成逻辑产出逐月逐日验证TheNth属性。由于实现依赖DateTime.Now.Year测试只断言年份与当前一致这也提示了一个使用注意点测试中不要硬编码具体年份除非先 mock 掉时钟。使用注意事项与边界年份语义OnDate所有成员都基于DateTime.Now.Year无法直接表达明年/去年某日。跨年份的日期需要自行组合例如new DateOnly(DateTime.Now.Year 1, 12, 25)或借助InDate.TheYear(int)见 InDate.cs表达某年 1 月 1 日框架限制OnDate仅对NET6_0_OR_GREATER目标框架编译老框架请使用返回DateTime的 On.Days.cs月份类型与属性数量12 个月份类型中属性生成数量按 2012 闰年计算因此 2 月含The29th但平年调用它会在运行时构造失败大月与小月属性个数不同31 天 vs 30 天可读性收益OnDate.January.The1st比new DateOnly(DateTime.Now.Year, 1, 1)更具自描述性尤其适合在领域规则、报表默认值、配置默认日期等位置使用使代码贴近业务语言。小结OnDate是 Humanizer FluentDate 家族中专为 .NET 6DateOnly场景设计的流式日期构造器通过 12 个嵌套月份类型 The(int)方法 The1stThe31st命名属性把今年某月某日的构造过程变成了可读性极强的链式表达式。其源码由 OnDate.Days.tt 模板生成、由 OnDate.Days.cs 承载实现、并由 OnDateTests.cs 与 GeneratedFluentDateTests.cs 双重验证。当你需要把特定日期写进代码且希望它读起来像一句英文时OnDate就是 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点击查看免费下载相关推荐Humanizer InDate 完整指南用 DateOnly 流式构造某年某月的日期Humanizer InDate 完整指南用 DateOnly 流式构造某年某月的日期 Humanizer 的 InDate 类提供了一套面向 Syste开发工具Humanizer InDate.Four API 详解用 DateOnly 构建从某日起 4 天/周/月/年的流式日期计算Humanizer InDate.Four API 详解用 DateOnly 构建从某日起 4 天/周/月/年的流式日期计算 本文基于 Humanizer开发工具Humanizer OnDate 类详解用流式语法构建 DateOnly 日期Humanizer OnDate 类详解用流式语法构建 DateOnly 日期 导读 Humanizer.OnDate 是 Humanizer 日期流式 AP开发工具上一篇百度ERNIE-4.5-VL-28B-A3B-Base-PT深度解析多模态路由优化技术架构与实现下一篇如何免费使用AI视频放大神器Video2X3步让老旧视频重获新生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考