Humanizer OnDate.February 详解:用流畅 API 构造 DateOnly 二月日期

原创2026-09-27 10:07:372,195 阅读
文章标签:开发工具

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。模板核心逻辑:

  1. 以 leapYear = 2012(闰年)为基准,用 DateTime.DaysInMonth(leapYear, month) 获取每个月的最大天数,保证 2 月能生成 The29th;
  2. 用 monthName = firstDayOfMonth.ToString("MMMM") 生成月份类名(February);
  3. 用 day.Ordinalize() 将日号转为序数词(1st、2nd、3rd…),拼出属性名 The1st、The2nd…;
  4. 每个成员体统一为 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),编写代码时无需换算,直接按自然语言读法书写即可。

延伸阅读

登录后查看全文
Humanizer