Humanizer 流畅日期 API 详解:用 On.June 类优雅生成六月的任意日期

原创2026-09-28 20:23:112,246 阅读
文章标签:开发工具

Humanizer 流畅日期 API 详解:用 On.June 类优雅生成六月的任意日期

On.June 是 Humanizer FluentDate(流畅日期)体系中的一个静态嵌套类,它以"自然语言"风格为开发者提供六月的全部日期访问器:30 个强类型静态属性(On.June.The1st ~ On.June.The30th)加上一个通用方法 On.June.The(int dayNumber),全部返回当前年份六月的对应 System.DateTime。读完本文,你将掌握这一 API 的完整签名、底层生成机制(T4 模板)、时间语义(当前年 + 午夜零点)、边界行为,以及它与 At/AtMidnight/AtNoon 等扩展组合出的实际用法。

一、类概览:On.June 是什么

On.June 是嵌套在 On 类内部的静态类,官方文档对其的定位是:"Provides fluent date accessors for June"(为六月提供流畅的日期访问器)。其声明与继承关系如下:

public class On.June
  • 继承关系:System.Object → On.June(普通引用类型,无特殊基类);
  • 命名空间:Humanizer;
  • 性质:On.June 与其所有成员均为 static,无需实例化即可直接通过类型名调用,例如 On.June.The10th。

它属于 Humanizer 中 src/Humanizer/FluentDate/ 目录下的 On 系列(On 表示"在某个日期的某一天",与 In/InDate/OnDate 系列共同构成 FluentDate 的时间表达式 DSL)。你可以从 API 参考文档 与 源码目录 中进一步核对。

二、属性完整参考:The1st ~ The30th

On.June 一共暴露 30 个静态只读属性,每个属性对应六月中的一天。所有属性语义一致:"The nth day of June of the current year"(当前年份六月的第 N 天),返回类型均为 System.DateTime,且时间部分恒为午夜零点(00:00:00,因为 DateTime 构造函数 new(year, month, day) 默认不带时间分量)。

下表按日期顺序完整列出全部属性(签名均为 public static System.DateTime <名称> { get; }):

属性 返回日期(当前年) 属性 返回日期(当前年)
On.June.The1st 6 月 1 日 On.June.The16th 6 月 16 日
On.June.The2nd 6 月 2 日 On.June.The17th 6 月 17 日
On.June.The3rd 6 月 3 日 On.June.The18th 6 月 18 日
On.June.The4th 6 月 4 日 On.June.The19th 6 月 19 日
On.June.The5th 6 月 5 日 On.June.The20th 6 月 20 日
On.June.The6th 6 月 6 日 On.June.The21st 6 月 21 日
On.June.The7th 6 月 7 日 On.June.The22nd 6 月 22 日
On.June.The8th 6 月 8 日 On.June.The23rd 6 月 23 日
On.June.The9th 6 月 9 日 On.June.The24th 6 月 24 日
On.June.The10th 6 月 10 日 On.June.The25th 6 月 25 日
On.June.The11th 6 月 11 日 On.June.The26th 6 月 26 日
On.June.The12th 6 月 12 日 On.June.The27th 6 月 27 日
On.June.The13th 6 月 13 日 On.June.The28th 6 月 28 日
On.June.The14th 6 月 14 日 On.June.The29th 6 月 29 日
On.June.The15th 6 月 15 日 On.June.The30th 6 月 30 日

以 The10th 为例,其标准声明如下(其余 29 个属性结构完全一致,仅数字与序数后缀不同):

public static System.DateTime The10th { get; }
// 语义:The 10th day of June of the current year

注意属性名的序数后缀是严格遵循英文序数规则的:1st、2nd、3rd、21st、22nd、23rd、31st 等,六月恰好到 30th(六月固定为 30 天,因此没有 The31st)。

三、通用方法:The(int dayNumber)

除了 30 个命名属性,On.June 还提供一个参数化入口,用于以变量方式表达"六月的第 N 天":

public static System.DateTime The(int dayNumber);
  • 参数 dayNumber:System.Int32,表示六月中的第几天;
  • 返回值:System.DateTime,即当前年份 6 月 dayNumber 日 的零点时刻。

该方法与命名属性是同一底层实现的两种表达方式:On.June.The1st 等价于 On.June.The(1),On.June.The15th 等价于 On.June.The(15)。当日期号由变量或计算得出(例如循环遍历、配置文件读取、与用户输入联动)时,The(int) 是唯一可行写法。

// 等价关系示例
DateTime a = On.June.The5th;   // 当前年 6 月 5 日
DateTime b = On.June.The(5);   // 与上面完全相等

四、底层实现:T4 模板生成与源码真相

4.1 源码中的真实定义

On.June 的实现在 src/Humanizer/FluentDate/On.Days.cs 中(June 类位于该文件第 980~1168 行)。其核心逻辑非常朴素:用 DateTime.Now.Year 取当前年份,配合固定的月份 6,构造 DateTime。

public class June
{
    // 通用入口
    public static DateTime The(int dayNumber)
        => new(DateTime.Now.Year, 6, dayNumber);

    // 命名属性示例(The1st ~ The30th 逐一展开)
    public static DateTime The1st
        => new(DateTime.Now.Year, 6, 1);

    public static DateTime The2nd
        => new(DateTime.Now.Year, 6, 2);

    // ... 依此类推

    public static DateTime The30th
        => new(DateTime.Now.Year, 6, 30);
}

这段源码揭示了三个关键事实:

  1. "当前年份"语义来自 DateTime.Now.Year:属性在每次访问时动态读取系统当前年份,因此 2026 年 1 月访问 On.June.The10th 得到 2026-06-10 00:00:00,到了 2027 年再访问则得到 2027-06-10 00:00:00。它不缓存、不依赖任何配置,是纯粹的"今年六月第 N 天";
  2. 时间部分为零点:new DateTime(year, month, day) 构造出的时间恒为午夜,适合作为"日期"参与比较与运算;
  3. 没有 The31st:六月只有 30 天,命名属性到 The30th 为止,这一点与文档完全吻合。

4.2 这些代码是怎么来的:T4 模板

如此规整、重复度极高的代码并非手工逐行编写,而是由 T4 文本模板 src/Humanizer/FluentDate/On.Days.tt 生成。模板的核心逻辑如下:

const int leapYear = 2012;                        // 以闰年 2012 为基准计算每月天数
for (var month = 1; month <= 12; month++)
{
    var firstDayOfMonth = new DateTime(leapYear, month, 1);
    var monthName = firstDayOfMonth.ToString("MMMM");   // 得到月份英文名
    // 生成 public class <monthName> { ... }
    for (var day = 1; day <= DateTime.DaysInMonth(leapYear, month); day++)
    {
        var ordinalDay = day.Ordinalize();              // 1 -> "1st", 2 -> "2nd", 21 -> "21st"
        // 生成 public static DateTime The<ordinalDay> => new(DateTime.Now.Year, <month>, <day>);
    }
}

从中可以读出两层设计:

  • 月份与天数由闰年基准推导:模板选定 2012 年(闰年)作为基准,DateTime.DaysInMonth(2012, 6) 得到 30,从而为六月生成恰好 30 个属性;这也是为什么 2 月会生成 The29th(闰年 2 月 29 天)的原因;
  • 序数后缀复用 Humanizer 的 Ordinalize():The1st/The2nd/The3rd/The21st/The22nd/The23rd 这些英文序数正是由 OrdinalizeExtensions 提供的 Ordinalize() 扩展方法批量产出的,体现了 Humanizer"用自己格式化自己"的生成方式。

也就是说,On.June 的 30 个属性 + 1 个方法是"模板生成 + 编译期展开"的产物,API 参考文档只是对这一组编译后静态成员的自动提取。

五、实战组合:从"日期"到"时刻"

On.June.* 返回的是纯日期(午夜零点)。若要表达六月某一天的某个具体时刻,可以结合 FluentDate 的 PrepositionsExtensions(src/Humanizer/FluentDate/PrepositionsExtensions.cs)中的扩展方法:

// On.June.The15th 是 2026-06-15 00:00:00
// At(hour, min, second, millisecond) 生成指定时刻
DateTime meeting = On.June.The15th.At(14, 30);      // 2026-06-15 14:30:00
DateTime deadline = On.June.The30th.At(23, 59, 59); // 2026-06-30 23:59:59
DateTime opening = On.June.The1st.AtMidnight();     // 2026-06-01 00:00:00(即原值)
DateTime noon = On.June.The10th.AtNoon();           // 2026-06-10 12:00:00

// 还可以整体换年份:把某日期的年改成指定年份
DateTime nextYear = On.June.The20th.In(2027);       // 2027-06-20 00:00:00

这种"On.June.TheN + 介词扩展"的组合,让测试夹具、定时任务、报表日期边界等场景可以直接写出接近自然语言的代码,例如"六月的第三个周五"这类业务规则可进一步配合 DayOfWeek 判断实现。

六、边界行为与注意事项

从源码实现(new(DateTime.Now.Year, 6, dayNumber))可以推断出以下边界行为,使用时需注意:

  1. dayNumber 越界会抛异常:The(int) 方法最终走 DateTime 构造函数,六月只有 30 天,因此 On.June.The(0)、On.June.The(31) 或更大的值都会触发 ArgumentOutOfRangeException。传入前应对业务输入做 1~30 的范围校验;
  2. 结果依赖系统当前年份:API 没有"指定年份"的参数,若需要历史或未来年份的六月日期,应改用 On.June.The(n).In(year)(PrepositionsExtensions 的 In(int year))自行调整年份;
  3. 类型是可变语义的 DateTime:每次访问属性都会重新计算 DateTime.Now.Year,在极少数跨年边界(12 月 31 日 23:59:59 附近)连续访问时可能出现年份不一致,若对一致性有强要求,建议先取一次 DateTime.Now.Year 再做构造;
  4. 命名属性是编译期常量名:The1st~The30th 是具名 API,适合静态代码中可读性优先的场景;动态计算日期号时请使用 The(int)。

七、测试验证:仓库中的权威佐证

Humanizer 用单元测试锁定了 On 系列的语义,见 tests/Humanizer.Tests/FluentDate/OnTests.cs:

[Fact]
public void OnJanuaryThe23rd() =>
    Assert.Equal(new(DateTime.Now.Year, 1, 23), On.January.The23rd);

[Fact]
public void OnDecemberThe4th() =>
    Assert.Equal(new(DateTime.Now.Year, 12, 4), On.December.The4th);

[Fact]
public void OnFebruaryThe() =>
    Assert.Equal(new(DateTime.Now.Year, 2, 11), On.February.The(11));

测试明确验证了"属性/方法返回 = new(DateTime.Now.Year, 月, 日)"这一事实;On.June 的任意成员(如 On.June.The23rd 应等于 new(DateTime.Now.Year, 6, 23))都遵循同一模式。此外,On 系列还被 FluentDate 内部复用,例如 tests/Humanizer.Tests/FluentDate/InTests.cs 中以 On.January.The21st 作为基准日期参与偏移计算,可见其作为"日期锚点"的通用价值。

八、小结

On.June 是 Humanizer FluentDate 中"按月取日期"家族的一员:30 个命名静态属性(The1st~The30th)+ 通用方法 The(int dayNumber),统一返回当前年份六月对应日期的零点 DateTime。其实现由 T4 模板(On.Days.tt)基于闰年基准与 Ordinalize() 批量生成,语义由单元测试锁定。在需要以自然、可读方式表达"今年六月的某一天"时,它是最直接的选择;配合 At/AtMidnight/AtNoon/In(year) 等扩展,即可进一步构建完整的时间点表达式。同类 API(如 On.January、On.December 等其余 11 个月份)与 On.June 结构完全一致,掌握六月即掌握整个 On 系列。

登录后查看全文
Humanizer