Humanizer 流式日期 API 详解:用 `On.October` 一行代码生成当年 10 月的任意日期
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);
}
从中可以提炼出三个关键事实:
- 年份永远取"当前年":所有成员都基于
DateTime.Now.Year构造,意味着返回的日期随系统时钟自动变化——今天调用On.October.The1st得到的是今年 10 月 1 日,明年再调用则自动是明年的 10 月 1 日。这非常适合"今年内的相对日期"场景,但不适合固定日期的归档需求。 - 月份固定为 10:构造参数硬编码为
new(DateTime.Now.Year, 10, N),与类名一一对应,不存在偏移或换算逻辑。 - 时间分量为零:
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 日"等相对/绝对时间表达,二者定位不同,按语义选用。
延伸阅读
- Humanizer.On 类总览:
On根类的声明结构 - On.Days.tt 生成模板:12 个月份类的批量生成逻辑
- On.Days.cs 完整源码:包含
October在内的全部月份实现 - OnDate.Days.cs:基于
DateOnly的无时间分量版本 - PrepositionsExtensions.cs:
At/AtMidnight/AtNoon/In等时间组装扩展 - OnTests.cs:
On家族行为测试
小结
On.October 是 Humanizer Fluent Date 设计中"按日历语义预生成静态成员"的典型样本:31 个序数命名属性 + 1 个参数化方法,全部基于 DateTime.Now.Year 返回当年 10 月的对应日期。理解它的源码实现(T4 生成、序数命名、静态计算)后,你可以举一反三地使用其余 11 个月份类,并在需要具体时刻时借助 PrepositionsExtensions 完成从"日期"到"完整时间戳"的组装。