Humanizer FluentDate 指南:OnDate.February 类完整解析(2 月日期访问器的实现与用法)

原创2026-09-24 20:50:151,905 阅读
文章标签:开发工具

Humanizer FluentDate 指南:OnDate.February 类完整解析(2 月日期访问器的实现与用法)

Humanizer 的 OnDate.February 是流式日期 API(FluentDate)家族中专门提供当年 2 月任意日期访问的嵌套类:通过 The1st~The29th 共 29 个静态属性和一个 The(int dayNumber) 方法,即可用纯英文序数语义直接拿到 System.DateOnly 值。本篇基于 website/versioned_docs/version-2.11.10/api/Humanizer.OnDate.February.md 的 API 定义,结合 T4 生成源码与单元测试,讲清它的完整成员清单、底层实现机制、与 On.February/InDate.February 的差异,以及闰年边界行为,读完即可在 .NET 6+ 项目中熟练使用这套"口语化日期构造"方案。

一、类定位:FluentDate 家族中的 2 月访问器

OnDate.February 是 Humanizer.OnDate 的嵌套公共类,官方文档定义其职责为 "Provides fluent date accessors for February"(为 2 月提供流式日期访问器),继承链为 System.Object → OnDate.February。

在 Humanizer 的 FluentDate 体系中,四组核心入口各有分工:

入口类 返回类型 语义 实现文件
On.Month.The(n)(如 On.February.The11th) System.DateTime 当年某月某日 src/Humanizer/FluentDate/On.Days.cs
OnDate.Month.The(n)(如 OnDate.February.The11th) System.DateOnly 当年某月某日(仅日期) src/Humanizer/FluentDate/OnDate.Days.cs
In.Month / In.MonthOf(year) System.DateTime 某月第一天 In.Months.cs
InDate.Month / InDate.TheYear(year) System.DateOnly 某月第一天(仅日期) InDate.Months.cs、src/Humanizer/FluentDate/InDate.cs

OnDate.February 即上表中的第二类——专为 2 月设计、以 DateOnly 为返回类型的静态访问器,适合不需要时间分量、只关心"哪一天"的业务场景。

二、完整成员清单:29 个属性 + 1 个方法

该类共提供 29 个静态只读属性(The1st ~ The29th,对应 2 月的全部可能天数,含闰年)与 1 个静态方法 The(int)。所有成员均返回 System.DateOnly,语义统一为"当前年份的 2 月第 N 天"。

2.1 静态属性一览

属性 含义 属性 含义
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 日

典型声明形式(与文档 API 签名一致):

public static System.DateOnly The11th { get; }

2.2 通用方法:The(int dayNumber)

public static System.DateOnly The(int dayNumber);

参数 dayNumber 为 System.Int32,表示 2 月内的日序号,返回对应的 System.DateOnly。它用于无法用固定属性表达的动态日期场景,例如循环生成某月每一天:

for (var day = 1; day <= 28; day++)
{
    var date = OnDate.February.The(day); // 平年的 2 月 1 日~28 日
    Console.WriteLine(date);
}

三、源码级实现原理

3.1 手写还是生成?—— T4 模板批量产出

OnDate.February 并非手写代码,而是由 T4 文本模板 src/Humanizer/FluentDate/OnDate.Days.tt 在编译期生成的。模板核心逻辑(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");
    // 输出 public class February { ... }
    for (var day = 1; day <= DateTime.DaysInMonth(leapYear, month); day++)
    {
        var ordinalDay = day.Ordinalize();
        // 输出 public static DateOnly The11th => new(DateTime.Now.Year, 2, 11);
    }
}

两个关键设计点:

  • 用 2012 闰年作为枚举基准:DateTime.DaysInMonth(2012, 2) 返回 29,因此 2 月访问器恰好生成 The1st~The29th,闰日属性天然覆盖;而其他月份按 30/31 天生成。
  • 序数后缀由 Ordinalize() 决定:模板调用 Humanizer 的 Ordinalize()(见 src/Humanizer/InflectorExtensions.cs),把 1→1st、2→2nd、3→3rd、21→21st、22→22nd、23→23rd,其余为 th,这正是 The21st/The22nd/The23rd 等特殊拼写的来源。

3.2 生成结果的真实形态

在 src/Humanizer/FluentDate/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);

    // ... 依此类推至
    public static DateOnly The29th
        => new(DateTime.Now.Year, 2, 29);
}

实现要点:

  • 年份取自 DateTime.Now.Year:所有属性与方法都基于"当前年份"构造,因此 OnDate.February.The11th 在 2025 年返回 2025-02-11,跨年后自动跟随年份。
  • 返回 DateOnly:整个文件被 #if NET6_0_OR_GREATER 包裹(OnDate.Days.cs),因为 System.DateOnly 是 .NET 6 引入的类型,这也意味着 OnDate 系列仅在 .NET 6+ 目标框架下可用;而返回 DateTime 的 On 系列则无此限制。
  • 求值时机:属性是每次访问时即时计算(=> 表达式体),并非缓存值。

3.3 与 On.February 的分工

对比 src/Humanizer/FluentDate/On.Days.cs 中的 On.February,二者结构完全一致(同样生成 The1st~The29th 与 The(int)),唯一差异是返回类型:

  • On.February.The11th → System.DateTime(带默认时间分量);
  • OnDate.February.The11th → System.DateOnly(纯日期)。

业务上若仅需日期比较、日期存储或格式化 yyyy-MM-dd,优先用 OnDate 系列,可避免 DateTime 时间分量的干扰。

四、实战用法示例

在 .NET 6+ 项目中引用 Humanizer 后(命名空间 Humanizer),即可直接使用:

using Humanizer;

// 固定序数属性:情人节
DateOnly valentinesDay = OnDate.February.The14th;
Console.WriteLine(valentinesDay); // 如 2025-02-14(跟随当前年份)

// 动态方法:指定第 N 天
DateOnly day = OnDate.February.The(28);

// 与 InDate 组合:取 2 月第一天
DateOnly firstOfFebruary = InDate.February; // new(DateTime.Now.Year, 2, 1)

// 与 In 系列组合:取指定年份的 2 月 1 日
DateTime feb2009 = In.FebruaryOf(2009); // 2009-02-01

典型落地场景包括:生成"本月 2 月所有日期"的列表、按固定日期触发定时任务(如每年 2 月 29 日)、把业务逻辑中的魔法日期改写成自解释代码。

五、边界与注意事项

  1. The29th 只在闰年可用:代码层面 The29th 恒生成 new(DateTime.Now.Year, 2, 29),但平年不存在 2 月 29 日,此时访问会由 DateOnly 构造函数抛出运行时异常(ArgumentOutOfRangeException 一类的日期有效性校验,属 .NET 类型固有行为)。使用前应先判断闰年,例如 DateTime.IsLeapYear(DateTime.Now.Year)。
  2. 平年下 The(29) 同样会抛异常:The(int dayNumber) 不做额外校验,合法性完全依赖 DateOnly 构造函数的日期验证。
  3. "当前年份"是动态的:跨年期间(如 12 月 31 日与 1 月 1 日)两次访问可能得到不同年份的日期;如需固定年份,建议用 InDate 系列配合 TheYear(int) 或直接 new DateOnly(year, 2, day)。
  4. 框架版本约束:OnDate 系列整体受 NET6_0_OR_GREATER 条件编译保护,.NET 5 及以下目标无法使用,应改用 On 系列(返回 DateTime)。

六、测试验证:行为有据可查

仓库测试为上述行为提供了直接证据:

七、相关 API 导航

若想横向扩展,可继续查阅仓库中的同类 API 文档与实现:

  • OnDate 其它月份访问器:同一份 OnDate.Days.cs 内嵌的 January~December 嵌套类;
  • On 系列(DateTime 版本):On.Days.cs;
  • 月首访问器:InDate.Months.cs、In.Months.cs,以及 InDate.cs 中的 TheYear(int year);
  • 相对日期偏移:InDate.SomeTimeFrom.cs / In.SomeTimeFrom.cs(如 InDate.Five.DaysFrom(...),见 InDateTests.cs);
  • 各类完整 API 定义:website/versioned_docs/version-2.11.10/api/ 目录下 Humanizer.OnDate.*.md、Humanizer.InDate.*.md、Humanizer.On.*.md、Humanizer.In.*.md 系列文档。

总结:OnDate.February 是"用英语序数直觉写日期"的典型产物——T4 模板以闰年为基准批量生成 29 个静态属性与 1 个通用方法,统一基于 DateTime.Now.Year 构造 DateOnly。掌握它不仅能写出 OnDate.February.The14th 这类自解释代码,也理解了 Humanizer FluentDate 家族"生成式 API + 类型分工(DateOnly/DateTime)"的整体设计思路。

登录后查看全文
Humanizer