Humanizer OnDate.February 详解:用流畅 API 构造 DateOnly 二月日期
Humanizer OnDate.February 详解:用流畅 API 构造 DateOnly 二月日期
导读
Humanizer.OnDate.February 是 Humanizer 流畅日期(Fluent Date)API 中专门用于构造二月份 DateOnly 日期值的静态访问器类。它把 new DateOnly(year, 2, day) 这类样板代码折叠成语义化的 OnDate.February.The14th 或 OnDate.February.The(14),让代码自注释、贴近自然语言。本文以该类的公开 API 为骨架,结合仓库源码与其生成的 T4 模板,完整列出全部 29 个命名属性与 1 个参数化方法,并讲解其实现原理、闰年语义、与 On.February(DateTime 版本)的差异以及测试验证方式,读完即可直接在 .NET 6+ 项目中落地使用。
类概览:OnDate.February 是什么
OnDate.February 定义在 Humanizer 命名空间下,是嵌套在 OnDate 类内部的公共类,继承自 System.Object:
public class OnDate.February
该类提供对二月份的流畅日期访问器(fluent date accessors),其所有成员均为 static,返回值类型是 System.DateOnly。由于 DateOnly 自 .NET 6 起才引入,整个 OnDate 系列(含 OnDate.February)的源码被 #if NET6_0_OR_GREATER 条件编译指令包裹,即仅在 .NET 6 及以上目标框架可用,详见 OnDate.Days.cs。
它与 On.February(On.Days.cs)是一对姊妹实现:前者返回 DateOnly(无时区、无时刻的纯日期),后者返回 DateTime(带时刻,默认午夜 00:00:00)。从源码结构看,二者均由同一套 T4 文本模板生成,模板按月份和日期批量产出成员,保证 12 个月类的 API 形状完全一致。
属性成员:2 月 1 日至 2 月 29 日的完整清单
OnDate.February 提供 29 个静态只读属性,覆盖平年的 28 天和闰年的 2 月 29 日,属性名直接采用英文序数词(1st/2nd/3rd/4th…),无需记忆数字与序数的映射规则。每个属性返回当年 2 月对应日期的 DateOnly 值。
| 属性 | 说明 | 等价构造表达式 |
|---|---|---|
The1st |
当年 2 月 1 日 | new DateOnly(DateTime.Now.Year, 2, 1) |
The2nd |
当年 2 月 2 日 | new DateOnly(DateTime.Now.Year, 2, 2) |
The3rd |
当年 2 月 3 日 | new DateOnly(DateTime.Now.Year, 2, 3) |
The4th – The10th |
当年 2 月 4 日至 10 日 | new DateOnly(DateTime.Now.Year, 2, 4..10) |
The11th – The19th |
当年 2 月 11 日至 19 日 | new DateOnly(DateTime.Now.Year, 2, 11..19) |
The20th |
当年 2 月 20 日 | new DateOnly(DateTime.Now.Year, 2, 20) |
The21st |
当年 2 月 21 日(注意序数词尾缀为 st) |
new DateOnly(DateTime.Now.Year, 2, 21) |
The22nd |
当年 2 月 22 日(序数词尾缀为 nd) |
new DateOnly(DateTime.Now.Year, 2, 22) |
The23rd |
当年 2 月 23 日(序数词尾缀为 rd) |
new DateOnly(DateTime.Now.Year, 2, 23) |
The24th – The28th |
当年 2 月 24 日至 28 日 | new DateOnly(DateTime.Now.Year, 2, 24..28) |
The29th |
当年 2 月 29 日(仅闰年有效) | new DateOnly(DateTime.Now.Year, 2, 29) |
以 The14th 为例,源码中的实现极为直白:
/// <summary>
/// The 14th day of February of the current year
/// </summary>
public static DateOnly The14th
=> new(DateTime.Now.Year, 2, 14);
源码位置:OnDate.Days.cs。所有属性都遵循同一模式:DateTime.Now.Year 提供"当前年份",月份固定为 2,日号由属性名决定。
方法成员:The(int dayNumber) 动态取日
除命名属性外,OnDate.February 还提供一个参数化方法,用于在运行时按编号取任意日期的值:
public static DateOnly The(int dayNumber);
- 参数:
dayNumber(System.Int32),即要取的 2 月第几天; - 返回值:
System.DateOnly,当年 2 月该编号对应的日期; - 实现:
=> new(DateTime.Now.Year, 2, dayNumber)。
典型用法:
using Humanizer;
// 动态计算:取当前年份 2 月第 11 天
DateOnly day = OnDate.February.The(11);
注意该方法是无校验透传的:它直接把 dayNumber 交给 DateOnly 构造函数,因此传入 0、负数或超过当月天数的值(如 The(30))会触发 ArgumentOutOfRangeException,传入 29 在平年会因 2 月没有 29 日而抛出同样的异常。从源码结构可以推断,调用方需要在传入前自行校验业务合法性。
实现原理:T4 模板批量生成
OnDate.February 及其 11 个同类(January 到 December)并非手写,而是由 T4 文本模板 OnDate.Days.tt 自动生成后输出为 OnDate.Days.cs。模板核心逻辑:
- 以
leapYear = 2012(闰年)为基准,用DateTime.DaysInMonth(leapYear, month)获取每个月的最大天数,保证 2 月能生成The29th; - 用
monthName = firstDayOfMonth.ToString("MMMM")生成月份类名(February); - 用
day.Ordinalize()将日号转为序数词(1st、2nd、3rd…),拼出属性名The1st、The2nd…; - 每个成员体统一为
new(DateTime.Now.Year, month, day)。
这意味着"属性名序数词"与"属性取值日号"的对应关系完全由 Ordinalize() 生成,无需人工维护 29 个手写属性,也解释了为什么文档与源码中 The1st、The21st、The22nd、The23rd 的尾缀变化完全符合英文序数词规则。
使用示例与测试验证
在 .NET 6+ 项目中安装 Humanizer 后即可直接使用:
using Humanizer;
// 语义化构造:当前年份的 2 月 14 日
DateOnly valentinesDay = OnDate.February.The14th;
// 与等价手工写法完全一致
DateOnly manual = new DateOnly(DateTime.Now.Year, 2, 14);
Console.WriteLine(valentinesDay == manual); // True
// 运行时动态取日
DateOnly dynamicDay = OnDate.February.The(28);
仓库测试 OnDateTests.cs 对参数化方法给出了直接验证:
[Fact]
public void OnFebruaryThe() =>
Assert.Equal(new(DateTime.Now.Year, 2, 11), OnDate.February.The(11));
该测试断言 OnDate.February.The(11) 与手工构造的 new DateOnly(DateTime.Now.Year, 2, 11) 相等,确认"当前年份 + 固定月份 2 + 传入日号"的求值语义。由于测试文件同样以 #if NET6_0_OR_GREATER 保护,说明这套断言只在 .NET 6+ 目标下编译运行。
Humanizer 官方场景文档(fluent-dates-and-time-spans.mdx)将 On.April.The3rd 这类写法概括为"围绕 DateTime 的可读构造函数",并指出 InDate 与 OnDate 在兼容框架上提供对应的 DateOnly 值——这正是 OnDate.February 的定位:把日期构造变成可读的自然语句。
关键注意事项
- 框架要求:
OnDate.February仅在NET6_0_OR_GREATER目标框架下编译可用;需要返回DateTime而非DateOnly时,请使用 On.February。 - 年份语义:所有成员取
DateTime.Now.Year,即"当前年份"。跨年夜之后调用,返回值会随系统时钟自动切换到新一年,这一点与固定年份构造有明显差异,适合"今年情人节/今年 2 月第 N 天"这类相对当前时间的场景。 - 参数边界:
The(int)不做范围校验,dayNumber超出 1–29 会由DateOnly构造函数抛出ArgumentOutOfRangeException;The(29)在平年同样失败。 - 序数命名:属性名遵循英文序数词规则(
The1st、The21st、The22nd、The23rd),编写代码时无需换算,直接按自然语言读法书写即可。
延伸阅读
- 同类 API:
OnDate系列其余 11 个月份类的 API 文档位于 website/versioned_docs/version-3.0.1/api/ 目录,如Humanizer.OnDate.January.md、Humanizer.OnDate.March.md; - 流畅日期全貌:fluent-dates-and-time-spans.mdx 与 dates-times-durations-and-age.mdx;
DateTime版本:On.Days.cs、In/InDate/On相关实现见 src/Humanizer/FluentDate/ 目录;- 生成机制:OnDate.Days.tt T4 模板及配套的 On.Days.tt。