Humanizer OnDate.September 流式日期 API 完全指南:用 DateOnly 表达"九月第 N 天"

原创2026-09-24 10:36:541,903 阅读
文章标签:开发工具

Humanizer OnDate.September 流式日期 API 完全指南:用 DateOnly 表达"九月第 N 天"

本文是 Humanizer 流式日期(Fluent Date)API 的实战指南,聚焦 OnDate.September 这一为 .NET 6+ 的 DateOnly 类型设计的九月日期访问器:它用 30 个静态属性(The1st~The30th)和 1 个参数化方法 The(int),把"当前年份的 9 月某天"变成自然语言般的强类型代码。读完本文,你将掌握该 API 的完整成员清单、底层实现原理(含 T4 模板生成机制)、边界行为、测试验证方式,以及如何与 InDate、In、On 等其他流式 API 配合,写出可读性极高的日期代码。

一、OnDate.September 是什么

OnDate.September 是 Humanizer 中 OnDate 静态类(位于 src/Humanizer/FluentDate/OnDate.Days.cs)的嵌套类,专门用于构造当前年份九月的任意一天,返回类型为 System.DateOnly。

其 API 文档(website/versioned_docs/version-2.11.10/api/Humanizer.OnDate.September.md)给出的类声明为:

public class OnDate.September

继承关系为 System.Object → September,所有成员均为 public static。与 OnDate.January、OnDate.December 等其余 11 个月份嵌套类一样,它把"某年某月某日"这一最常见的日期构造场景,简化成一句近乎口语的表达式,例如:

using Humanizer;

// 当前年份 9 月 23 日
DateOnly nationalDay = OnDate.September.The23rd;

这段代码等价于手写 new DateOnly(DateTime.Now.Year, 9, 23),但语义一目了然:无需关注年份、月份与日期构造参数的顺序,读到代码即知"九月二十三号"。

二、成员全览:30 个静态属性 + 1 个参数化方法

OnDate.September 的公开 API 分为两部分,全部为静态成员,无需实例化即可调用。

2.1 静态属性 The1st ~ The30th

九月共 30 天,因此该类提供 The1st 到 The30th 共 30 个静态只读属性,每个属性返回当前年份对应日期的 DateOnly。下表按日期顺序完整列出(属性名均遵循英语序数词后缀规则:1 用 st、2 用 nd、3 用 rd、其余用 th):

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

每个属性的签名统一为:

public static System.DateOnly The30th { get; }

2.2 参数化方法 The(int dayNumber)

当目标日期不是"常用固定日"、或希望以变量方式传入时,使用 The(int) 方法:

public static System.DateOnly The(int dayNumber);
  • 参数 dayNumber:System.Int32,表示九月的第几天(1~30)。
  • 返回值:System.DateOnly。
int day = 5;
DateOnly date = OnDate.September.The(day); // 等价于 OnDate.September.The5th

注意:传入超出 1~30 范围的数值(如 0、31、-1)时,DateOnly 构造函数会抛出 ArgumentOutOfRangeException,这一点由 tests/Humanizer.Tests/FluentDate/GeneratedFluentDateTests.cs 中的反射测试显式捕获验证(见下文"测试验证"一节)。

三、底层实现:一行表达式 + T4 模板生成

3.1 属性与方法的真实实现

OnDate.September 的源码位于 src/Humanizer/FluentDate/OnDate.Days.cs 第 1561 行起。每个成员都只是"当前年份 + 固定月份 9 + 目标日"的 DateOnly 构造表达式:

public class September
{
    /// <summary>
    /// The nth day of September of the current year
    /// </summary>
    public static DateOnly The(int dayNumber)
        => new(DateTime.Now.Year, 9, dayNumber);

    /// <summary>
    /// The 1st day of September of the current year
    /// </summary>
    public static DateOnly The1st
        => new(DateTime.Now.Year, 9, 1);
    // The2nd ... The30th 依此类推,仅日期不同
}

关键点有三:

  1. 年份取自 DateTime.Now.Year:返回值始终是"当前年份"的九月日期。跨年(如 12 月 31 日调用)后,同一表达式会返回新一年的日期。从源码结构可以推断,若需要特定年份,应改用 InDate.SeptemberOf(2025) 这类带年份参数的 API(见下文)。
  2. 返回 DateOnly:与 On 类(返回 DateTime)形成互补。OnDate 系整套类被 #if NET6_0_OR_GREATER 条件编译指令包裹(见 src/Humanizer/FluentDate/OnDate.Days.cs 第 1 行),仅在 .NET 6 及以上目标框架可用,因为 DateOnly 类型自 .NET 6 才引入。
  3. 零分配、无缓存:每个属性调用即构造,逻辑上是纯计算,没有状态与共享可变数据。

3.2 T4 模板:12 个月份类的来源

OnDate.Days.cs 并非手写,而是由 T4 文本模板 src/Humanizer/FluentDate/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 <monthName>
    public static DateOnly The(int dayNumber)
        => new(DateTime.Now.Year, <month>, dayNumber);
    // 用 Ordinalize() 生成 The1st/The2nd/... 属性名
    for (var day = 1; day <= DateTime.DaysInMonth(leapYear, month); day++)
    {
        var ordinalDay = day.Ordinalize();
        public static DateOnly The<ordinalDay>
            => new(DateTime.Now.Year, <month>, <day>);
    }
}

模板以闰年 2012 为基准计算各月天数(2 月 29 天),因此生成的每个月份类都恰好拥有 The1st 至 The<当月天数> 的属性;九月的 30 天对应 30 个属性。属性名中的序数词(st/nd/rd/th)由 Humanizer 自身的 Ordinalize() 扩展生成——这正是"Humanizer 用 Humanizer 来生成自己"的一个有趣体现。

四、为什么用 OnDate.September:使用场景与对比

4.1 典型业务场景

OnDate.September 最适用于**代码中固定引用某些"日期敏感日"**的场景,例如:

  • 开学日、教师节(9 月 10 日):OnDate.September.The10th
  • 每月账单日、发布日、巡检日等固定日期的 9 月版本
  • 与 DateOnly 相关的领域模型字段赋值、测试夹具中的固定日期

示例:

using Humanizer;

// 教师节:当前年份 9 月 10 日
DateOnly teachersDay = OnDate.September.The10th;

// 用变量构造:第 15 个工作日标记
int businessDay = 15;
DateOnly target = OnDate.September.The(businessDay);

4.2 与其他流式 API 的对比

Humanizer 的 FluentDate 体系(目录 src/Humanizer/FluentDate/)提供四套风格互补的入口:

入口类 返回类型 表达语义 代表性示例
OnDate.September DateOnly 当前年份 9 月某天 OnDate.September.The1st
On.September DateTime 当前年份 9 月某天(带时间分量) On.September.The1st
InDate.September / InDate.SeptemberOf(year) DateOnly 当前年份 / 指定年份 9 月 1 日 InDate.SeptemberOf(2025)
In.September / In.SeptemberOf(year) DateTime 当前年份 / 指定年份 9 月 1 日 In.SeptemberOf(2009)

对应源码与测试:

选型建议:需要纯日期(无时间部分)且年份取当前年,用 OnDate.September;需要 DateTime 或后续要叠加时间,用 On.September;需要指定特定年份,改用 InDate.SeptemberOf(year) 或 In.SeptemberOf(year)。

五、测试验证:生成式 API 如何被保证正确

Humanizer 对该类 API 的正确性验证非常系统。两个测试文件覆盖了"成员存在性"与"返回值正确性"两个层面:

  1. tests/Humanizer.Tests/FluentDate/OnDateTests.cs:手写断言,验证 OnDate.January.The23rd、OnDate.December.The4th、OnDate.February.The(11) 均返回"当前年份 + 对应月 + 对应日"的 DateOnly。

  2. tests/Humanizer.Tests/FluentDate/GeneratedFluentDateTests.cs:通过反射自动遍历所有生成成员:

    • OnDateDayPropertiesCoverAllGeneratedDayAccessors:遍历 OnDate 下所有月份嵌套类的全部静态属性,用 TryParseDayProperty 解析 TheNNth 形式的属性名并断言其值等于 new DateOnly(当前年, 月, 日);
    • OnDateTheMethodsCoverAllGeneratedMonthFactories:遍历每个月份类的 The(int) 方法并断言 The(1) 等于当月 1 日;
    • 当属性构造抛异常时(如传入非法日期),测试会捕获 TargetInvocationException 并断言其内部异常为 ArgumentOutOfRangeException;
    • 月份表(Months 数组)中 "September" 对应数字 9,作为反射断言的依据。

这两个测试共同保证了:只要 T4 模板生成逻辑不变,OnDate.September 的 30 个属性与 The(int) 方法就始终与"当前年份 9 月 N 日"的语义保持一致。

六、使用注意事项与限制

  1. 目标框架限制:OnDate 整套 API 需要 .NET 6+(DateOnly 类型的前提)。在 .NET Framework 或 .NET 5 及以下项目中不可用,此时请使用返回 DateTime 的 On.September。
  2. 年份是运行时当前年:返回值随调用时刻变化,不能用于表示固定年份的日期;跨年进程或午夜边界调用时结果可能变化。
  3. 参数范围:The(int dayNumber) 只接受 1~30;越界会抛 ArgumentOutOfRangeException。官方文档与源码均未提供"超出后自动钳制"或"滚入下月"的行为。
  4. 无时间分量:返回的是 DateOnly(午夜零点语义),若业务需要具体时刻(如"9 月 10 日 8:30 开课"),可组合 ToDateTime(TimeOnly) 或改用 On.September 系列。
  5. 区域性无关:类名与属性名是固定的英文序数词命名,不受当前线程 CultureInfo 影响,任何区域下调用结果一致。

七、小结

OnDate.September 是 Humanizer 流式日期体系在 DateOnly 时代的典型代表:30 个语义直白的静态属性加一个参数化方法,把"当前年份九月第 N 天"这一高频构造场景封装成近乎自然语言的代码。它的实现极简(一行 DateOnly 构造)、来源可溯(T4 模板生成、测试反射全量校验),与 On/In/InDate 系列共同构成一套完整的日期表达工具链。需要进一步了解整体设计,可阅读仓库根目录的 ARCHITECTURE.md 与 DESIGN.md;完整的流式日期使用示例参见 website/docs/_examples/scenarios-fluent-dates/Program.cs。

登录后查看全文
Humanizer