Humanizer 的 OnDate.February:用 DateOnly 流式访问 2 月每一天的完整指南
Humanizer 的 OnDate.February:用 DateOnly 流式访问 2 月每一天的完整指南
OnDate.February 是 Humanizer 流式日期(Fluent Date)API 家族中面向 2 月的专用访问器,它以嵌套类的形式为 2 月的每一天提供一个静态属性(The1st 到 The29th),并提供一个按天数取值的 The(int dayNumber) 方法,返回值均为 System.DateOnly。本文基于当前仓库中 version-3.0.10 的 API 文档 展开,并结合源码与测试用例,完整覆盖该类全部 29 个属性、动态取值方法、生成原理、闰年处理与测试验证,读完即可在自己的 .NET 6+ 项目中直接使用。
OnDate.February 的定位:DateOnly 版的流式 2 月访问器
在 Humanizer 的 Humanizer 命名空间下,OnDate 是一个容器类,内部按月份嵌套了 12 个类(January~December),每个类都遵循相同的模式:为当月每一天提供一个"第 N 天"的静态属性,以及一个 The(int dayNumber) 方法。OnDate.February 正是其中负责 2 月的那个嵌套类。
public class OnDate.February
类的继承链为 System.Object → February,这一点与仓库中 OnDate.Days.cs 源码 的声明一致(public class February 嵌套于 public class OnDate 内部)。
关键设计点在于:OnDate 系列返回的是 System.DateOnly,而不是 System.DateTime。DateOnly 是 .NET 6 引入的、专门表示"年-月-日"且不含时间部分的日期类型,因此整套 OnDate API 被编译指令 #if NET6_0_OR_GREATER 包裹,仅在 .NET 6 及以上框架中可用。与之相对的,仓库中还提供了返回 DateTime 的 On.Days.cs 系列(On.February.The11th 等),供需要完整时间组件的场景使用。
快速上手:三行代码拿到 2 月日期
引用 Humanizer 包后,直接通过静态属性即可获得 2 月某一天(年份取当前年份):
using Humanizer;
DateOnly valentinesDay = OnDate.February.The14th; // 今年 2 月 14 日
DateOnly arbitraryDay = OnDate.February.The(23); // 今年 2 月 23 日
与手写 new DateOnly(DateTime.Now.Year, 2, 14) 相比,OnDate.February.The14th 以自然语言般的表达消除了魔法数字,代码自文档化程度更高。仓库测试 OnDateTests.cs 中给出了等价性的验证方式:
[Fact]
public void OnFebruaryThe() =>
Assert.Equal(new(DateTime.Now.Year, 2, 11), OnDate.February.The(11));
完整 API 清单:29 个属性加 1 个动态方法
根据 Humanizer.OnDate.February.md 的 API 文档,OnDate.February 共暴露 29 个静态属性(对应 2 月的 1~29 天)和 1 个静态方法。所有属性均声明为:
public static System.DateOnly The{第N天} { get; }
下表列出全部属性及其语义:
| 属性 | 语义 | 属性 | 语义 |
|---|---|---|---|
The1st |
2 月 1 日 | The16th |
2 月 16 日 |
The2nd |
2 月 2 日 | The17th |
2 月 17 日 |
The3rd |
2 月 3 日 | The18th |
2 月 18 日 |
The4th |
2 月 4 日 | The19th |
2 月 19 日 |
The5th |
2 月 5 日 | The20th |
2 月 20 日 |
The6th |
2 月 6 日 | The21st |
2 月 21 日 |
The7th |
2 月 7 日 | The22nd |
2 月 22 日 |
The8th |
2 月 8 日 | The23rd |
2 月 23 日 |
The9th |
2 月 9 日 | The24th |
2 月 24 日 |
The10th |
2 月 10 日 | The25th |
2 月 25 日 |
The11th |
2 月 11 日 | The26th |
2 月 26 日 |
The12th |
2 月 12 日 | The27th |
2 月 27 日 |
The13th |
2 月 13 日 | The28th |
2 月 28 日 |
The14th |
2 月 14 日 | The29th |
2 月 29 日 |
The15th |
2 月 15 日 |
属性命名使用英文序数词后缀(1st、2nd、3rd、21st、22nd、23rd 等),与日常英语表达一致。
动态取值方法 The(int dayNumber)
除固定属性外,还提供按参数取任意一天的方法:
public static System.DateOnly The(int dayNumber);
- 参数:
dayNumber,类型System.Int32,表示 2 月中的第几天; - 返回值:
System.DateOnly。
该方法适合天数在运行时才确定的场景(如由业务规则计算出的日期),例如 OnDate.February.The(userInput)。
源码实现解析:一行表达式与 T4 代码生成
OnDate.February 的实现非常精简。在 OnDate.Days.cs 中,February 类的核心代码如下:
public class February
{
/// <summary>
/// The nth day of February of the current year
/// </summary>
public static DateOnly The(int dayNumber)
=> new(DateTime.Now.Year, 2, dayNumber);
/// <summary>
/// The 1st day of February of the current year
/// </summary>
public static DateOnly The1st
=> new(DateTime.Now.Year, 2, 1);
// ……The2nd 到 The28th 依此类推……
/// <summary>
/// The 29th day of February of the current year
/// </summary>
public static DateOnly The29th
=> new(DateTime.Now.Year, 2, 29);
}
从源码结构可以确认几个实现事实:
- 年份始终取
DateTime.Now.Year:所有属性与方法都以"当前年份 + 固定月份 2 + 目标日"构造DateOnly,因此每年 2 月调用都会自动得到当年的日期,无需手动传入年份; - 属性均为表达式体 getter:每个属性内部就是一个
DateOnly构造表达式,无额外逻辑,开销可忽略; - 2 月最多提供到
The29th:The29th的存在使闰年场景(2 月 29 日)天然可用;非闰年时该日期不存在,构造DateOnly会抛出ArgumentOutOfRangeException,这属于DateOnly类型的正常边界行为,使用前需按业务判断年份。
值得说明的是,这份看似"重复"的代码并非手写,而是由 T4 文本模板 OnDate.Days.tt 自动生成的。模板的核心逻辑如下:
const int leapYear = 2012;
for (var month = 1; month <= 12; month++)
{
var monthName = new DateTime(leapYear, month, 1).ToString("MMMM");
// ……生成 public class 月份名 嵌套类……
for (var day = 1; day <= DateTime.DaysInMonth(leapYear, month); day++)
{
var ordinalDay = day.Ordinalize();
// ……生成 public static DateOnly The{序数} => new(DateTime.Now.Year, 月份, 天);
}
}
这段模板揭示了两个设计细节:
- 模板以 2012 年(闰年)为基准计算每月天数:
DateTime.DaysInMonth(2012, 2)返回 29,因此 2 月恰好生成The1st~The29th共 29 个属性;其他月份如 4 月则只生成到The30th。也就是说,"每个属性对应合法的一天"这一正确性由生成逻辑保证; - 属性名中的序数词由 Humanizer 自身的
Ordinalize()扩展方法生成:1.Ordinalize()得到"1st",这正是属性The1st命名中st/nd/rd/th后缀的来源,体现了 Humanizer 用自身能力生成自身 API 的巧思(Ordinalize定义于 OrdinalizeExtensions.cs)。
测试验证:仓库如何证明 API 行为
OnDate.February 的行为在 OnDateTests.cs 中有直接测试覆盖:
#if NET6_0_OR_GREATER
public class OnDateTests
{
[Fact]
public void OnJanuaryThe23rd() =>
Assert.Equal(new(DateTime.Now.Year, 1, 23), OnDate.January.The23rd);
[Fact]
public void OnDecemberThe4th() =>
Assert.Equal(new(DateTime.Now.Year, 12, 4), OnDate.December.The4th);
[Fact]
public void OnFebruaryThe() =>
Assert.Equal(new(DateTime.Now.Year, 2, 11), OnDate.February.The(11));
}
#endif
测试文件的 #if NET6_0_OR_GREATER 预编译指令与源码保持一致,再次确认 OnDate 系列仅面向 .NET 6+。其中 OnFebruaryThe 用例验证了 The(int dayNumber) 方法:当参数为 11 时,结果应等于 new DateOnly(当前年, 2, 11)——与源码 new(DateTime.Now.Year, 2, dayNumber) 的实现完全对应。如果你对某一天的固定属性有疑问,也可以仿照该模式用 Assert.Equal(new(DateTime.Now.Year, 2, N), OnDate.February.TheNth) 自行验证。
流式日期家族的横向对比
OnDate.February 不是孤立的 API,理解它与同族 API 的关系能帮你选对工具:
| API | 返回类型 | 框架要求 | 源码文件 | 用途 |
|---|---|---|---|---|
OnDate.February.The11th |
DateOnly |
.NET 6+ | OnDate.Days.cs | 只需日期、不要时间部分时 |
On.February.The11th |
DateTime |
所有支持的框架 | On.Days.cs | 需要带时间组件(午夜零点)的完整日期时间时 |
两个系列结构完全对称,均由各自的 .tt 模板(OnDate.Days.tt 与 On.Days.tt)生成。在 Humanizer 的流式日期体系里,On/OnDate 用于"定位某年某月某日",In/InDate 则用于"当前时间加/减一段时间",例如 In.Two.Days 与 InDate.SomeTimeFrom.cs;月份全名类 API 如 On.February、On.March 均可在 On.Days.cs 中找到。更多流式日期的使用示例可参考 On 系列 API 文档 与 OnDate 系列 API 文档。
使用注意事项与最佳实践
- 确认目标框架为 .NET 6+:
OnDate.February返回DateOnly,整个OnDate类在NET6_0_OR_GREATER下才编译。若项目面向 .NET Framework 或 .NET 5,请改用返回DateTime的On.February; - 属性方法混用按场景取舍:写死的固定日期(如情人节
The14th)优先用属性,表达更自然;动态计算的天数用The(dayNumber); - 注意 2 月天数边界:
The29th只在闰年存在。非闰年构造 2 月 29 日会因超出DateOnly合法范围而抛异常,涉及 2 月 29 日时应先判断DateTime.IsLeapYear(DateTime.Now.Year); - 年份语义:所有访问器都以
DateTime.Now.Year为基准,不提供指定年份的重载。若需"某特定年份的 2 月某日",应直接使用new DateOnly(year, 2, day); - 无状态、零开销:全部为静态成员与表达式体实现,不产生实例状态,可放心在热路径与批量循环中调用。
综上,OnDate.February 以最简的 API 面解决了"拿到今年 2 月某一天"的日常需求,配合 Humanizer 的 DateOnly 支持与 T4 生成机制,是流式日期 API 中值得优先采用的表达方式。