Humanizer 的 OnDate.February:用 DateOnly 流式访问 2 月每一天的完整指南

原创2026-10-06 17:47:462,493 阅读
文章标签:开发工具

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, 月份, 天);
    }
}

这段模板揭示了两个设计细节:

  1. 模板以 2012 年(闰年)为基准计算每月天数:DateTime.DaysInMonth(2012, 2) 返回 29,因此 2 月恰好生成 The1st~The29th 共 29 个属性;其他月份如 4 月则只生成到 The30th。也就是说,"每个属性对应合法的一天"这一正确性由生成逻辑保证;
  2. 属性名中的序数词由 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 文档。

使用注意事项与最佳实践

  1. 确认目标框架为 .NET 6+:OnDate.February 返回 DateOnly,整个 OnDate 类在 NET6_0_OR_GREATER 下才编译。若项目面向 .NET Framework 或 .NET 5,请改用返回 DateTime 的 On.February;
  2. 属性方法混用按场景取舍:写死的固定日期(如情人节 The14th)优先用属性,表达更自然;动态计算的天数用 The(dayNumber);
  3. 注意 2 月天数边界:The29th 只在闰年存在。非闰年构造 2 月 29 日会因超出 DateOnly 合法范围而抛异常,涉及 2 月 29 日时应先判断 DateTime.IsLeapYear(DateTime.Now.Year);
  4. 年份语义:所有访问器都以 DateTime.Now.Year 为基准,不提供指定年份的重载。若需"某特定年份的 2 月某日",应直接使用 new DateOnly(year, 2, day);
  5. 无状态、零开销:全部为静态成员与表达式体实现,不产生实例状态,可放心在热路径与批量循环中调用。

综上,OnDate.February 以最简的 API 面解决了"拿到今年 2 月某一天"的日常需求,配合 Humanizer 的 DateOnly 支持与 T4 生成机制,是流式日期 API 中值得优先采用的表达方式。

登录后查看全文
Humanizer