Humanizer 流式日期 API 详解:用 `On.October` 一行代码生成当年 10 月的任意日期

原创2026-09-28 12:43:231,351 阅读
文章标签:开发工具

Humanizer 流式日期 API 详解:用 On.October 一行代码生成当年 10 月的任意日期

导读

Humanizer 的 Fluent Date(流式日期)体系为 .NET 开发者提供了一套近乎自然语言的日期构造 API。本文以 On.October 类为切入点,完整梳理其 31 个静态日期属性与 The(int) 方法的签名、语义与返回值,并结合仓库源码(On.Days.cs、On.Days.tt)与测试用例(OnTests.cs)剖析其生成原理与实战用法。读完本文,你将能直接使用 On.October.The31st、On.October.The(15) 这类表达式在业务代码中快速构造日期,并理解其与 OnDate、PrepositionsExtensions 等相邻 API 的配合方式。

On 类与 Fluent Date 体系概览

在 Humanizer 中,On 是一个位于 src/Humanizer/FluentDate/On.Days.cs 的公共类,其作用是"提供指定月份的流式日期访问器"。它内部以嵌套类的形式定义了 12 个以英文月份命名的子类:January、February、March、April、May、June、July、August、September、October、November、December。每个子类的职责完全一致:以静态成员的形式暴露"当前年份中该月的第 N 天"。

On 类本身在 API 参考文档中的定义极为精简,仅声明了类结构,没有可调用的实例成员——所有实际能力都承载于各月份子类的静态属性与方法之上。与之同族的还有 OnDate 类(见 OnDate.Days.cs),它提供基于 DateOnly 的同类 API,适合不需要时间分量的场景。

On.October 类声明与继承关系

public class On.October
  • 所属命名空间:Humanizer
  • 继承关系:System.Object → October
  • 成员性质:全部为 static,无需实例化即可调用
  • 返回类型:所有属性与方法均返回 System.DateTime

October 是嵌套在 On 类内部的公共类,因此完整的引用写法为 On.October.XXX。由于全部成员均为静态,使用时不产生任何对象分配成本,属于纯计算型 API。

完整属性清单:The1st ~ The31st

On.October 为 10 月的每一天都预置了一个以序数词命名的静态属性,覆盖 1 日到 31 日(10 月有 31 天,一个不缺)。每个属性的语义都是 "当前年份 10 月的该日",返回值的 Time 部分恒为 00:00:00(午夜)。

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

所有属性的签名形式统一为:

public static System.DateTime The10th { get; }

即:公共、静态、只读(get only)属性,无 setter,无法修改其返回值语义。

动态日期方法:On.October.The(int dayNumber)

除了预置的 31 个属性,On.October 还提供一个参数化方法,用于获取 10 月任意第 N 天:

public static System.DateTime The(int dayNumber);
  • 参数:dayNumber,类型 System.Int32,表示目标日期在 10 月中的序号(1 ~ 31)
  • 返回值:System.DateTime,即当年 10 月第 dayNumber 天

典型调用:

var d = On.October.The(15);   // 当年 10 月 15 日
var d2 = On.October.The(1);   // 当年 10 月 1 日,等价于 On.October.The1st

边界行为提示:方法内部直接以 dayNumber 作为日期构造参数(见下文源码),因此传入超出 1~31 的数值时(如 0、32、负数),DateTime 构造函数会抛出 ArgumentOutOfRangeException,调用方应在业务侧自行校验参数合法性。

源码级实现原理

手写文件中的真实实现

在 src/Humanizer/FluentDate/On.Days.cs 中,October 类的实现一目了然:

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

    /// <summary>
    /// The 1st day of October of the current year
    /// </summary>
    public static DateTime The1st
        => new(DateTime.Now.Year, 10, 1);

    // ... The2nd ~ The31st 依此类推

    /// <summary>
    /// The 31st day of October of the current year
    /// </summary>
    public static DateTime The31st
        => new(DateTime.Now.Year, 10, 31);
}

从中可以提炼出三个关键事实:

  1. 年份永远取"当前年":所有成员都基于 DateTime.Now.Year 构造,意味着返回的日期随系统时钟自动变化——今天调用 On.October.The1st 得到的是今年 10 月 1 日,明年再调用则自动是明年的 10 月 1 日。这非常适合"今年内的相对日期"场景,但不适合固定日期的归档需求。
  2. 月份固定为 10:构造参数硬编码为 new(DateTime.Now.Year, 10, N),与类名一一对应,不存在偏移或换算逻辑。
  3. 时间分量为零:DateTime 构造的默认时间为午夜 00:00:00,若需指定具体时刻,要配合 PrepositionsExtensions(见下文)。

T4 模板:整个 On 家族的生成来源

On 下 12 个月份子类的代码并非全部手写,而是由 T4 模板 src/Humanizer/FluentDate/On.Days.tt 批量生成。模板的核心逻辑是:

for (var month = 1; month <= 12; month++)
{
    var firstDayOfMonth = new DateTime(leapYear, month, 1);
    var monthName = firstDayOfMonth.ToString("MMMM");
    // 生成 public class <月名> { ... }

    for (var day = 1; day <= DateTime.DaysInMonth(leapYear, month); day++)
    {
        var ordinalDay = day.Ordinalize();
        // 生成 public static DateTime The<序数词> => new(DateTime.Now.Year, <月>, <日>);
    }
}

几个值得注意的实现细节:

  • 模板以 2012 年(闰年)为基准计算每月天数,因此像 10 月这样有 31 天的月份,生成的类包含完整的 The1st ~ The31st 属性;而 2 月生成的类只会到 The29th(闰年上限),调用方在平年访问 On.February.The29th 时才会触发 ArgumentOutOfRangeException——这属于模板生成带来的固有语义。
  • Ordinalize() 是 Humanizer 自身的扩展方法(见 OrdinalizeExtensions.cs),负责把 1 转为 1st、2 转为 2nd、3 转为 3rd,其余转为 th,这正是属性命名中 The1st、The2nd、The3rd、The21st、The22nd、The23rd 等不规则后缀的来源。
  • 修改模板后需重新运行 T4 转换以重新生成 On.Days.cs,二者保持同步关系。

实战用法:从日期到完整时间戳的组装

On.October 系列只产出"当天零点"的 DateTime。若要表达"10 月某日的某个具体时刻",可叠加 Humanizer 的 PrepositionsExtensions(PrepositionsExtensions.cs)中的扩展方法:

using Humanizer;

// 今年 10 月 31 日 23:59:59
var halloweenEve = On.October.The31st.At(23, 59, 59);

// 今年 10 月 1 日零点(等价于直接使用 On.October.The1st)
var midnight = On.October.The1st.AtMidnight();

// 今年 10 月 1 日正午
var noon = On.October.The1st.AtNoon();

// 把日期整体挪到指定年份(如 2030 年 10 月 15 日)
var in2030 = On.October.The(15).In(2030);

其中:

  • At(int hour, int min = 0, int second = 0, int millisecond = 0):为指定日期设置时、分、秒、毫秒;
  • AtMidnight():等价于 At(0),将时间置为午夜;
  • AtNoon():等价于 At(12),将时间置为正午;
  • In(int year):返回同一月日、但年份替换为指定值的 DateTime。

配合使用即可在一条链式表达式中完成"自然语言式"的完整时间戳构造:

var deadline = On.October.The(15).At(18, 30);
var anniversary = On.October.The23rd.In(2024).AtMidnight();

如果业务只关心日期而不关心时间分量,可改用 OnDate 家族(OnDate.Days.cs),它以 DateOnly 返回同样的"当年某月某日",例如 OnDate.October.The31st。

测试用例验证

仓库中的 OnTests.cs 为整个 On 家族的行为提供了直接佐证:

public class OnTests
{
    [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));
}

测试模式清晰可复用:把 On.Xxx.TheN(或 The(N))与 new DateTime(DateTime.Now.Year, 月, 日) 做相等断言,验证了属性的返回值语义确为"当前年份 + 固定月日 + 午夜时间"。同理可推,On.October.The31st 等价于 new DateTime(DateTime.Now.Year, 10, 31),On.October.The(15) 等价于 new DateTime(DateTime.Now.Year, 10, 15)。

使用注意与适用边界

  • 年份动态性:返回值依赖 DateTime.Now.Year,同一表达式在不同年份执行结果不同;对固定历史日期,请改用显式构造或 In(year) 指定年份。
  • 参数校验:The(int dayNumber) 不做范围校验,非法值由 DateTime 构造函数抛出 ArgumentOutOfRangeException。
  • 线程安全:所有成员均为无状态的静态计算,天然线程安全,可放心在并发环境下调用。
  • 与 In 家族的区别:On 表示"当年某月某日";In(In.cs、In.Months.cs)则用于"从现在起 N 个时间单位之后"或"指定年份的 1 月 1 日"等相对/绝对时间表达,二者定位不同,按语义选用。

延伸阅读

小结

On.October 是 Humanizer Fluent Date 设计中"按日历语义预生成静态成员"的典型样本:31 个序数命名属性 + 1 个参数化方法,全部基于 DateTime.Now.Year 返回当年 10 月的对应日期。理解它的源码实现(T4 生成、序数命名、静态计算)后,你可以举一反三地使用其余 11 个月份类,并在需要具体时刻时借助 PrepositionsExtensions 完成从"日期"到"完整时间戳"的组装。

登录后查看全文
Humanizer