Humanizer 流畅日期 API 详解:用 On.June 类优雅生成六月的任意日期
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);
}
这段源码揭示了三个关键事实:
- "当前年份"语义来自
DateTime.Now.Year:属性在每次访问时动态读取系统当前年份,因此 2026 年 1 月访问On.June.The10th得到2026-06-10 00:00:00,到了 2027 年再访问则得到2027-06-10 00:00:00。它不缓存、不依赖任何配置,是纯粹的"今年六月第 N 天"; - 时间部分为零点:
new DateTime(year, month, day)构造出的时间恒为午夜,适合作为"日期"参与比较与运算; - 没有
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))可以推断出以下边界行为,使用时需注意:
dayNumber越界会抛异常:The(int)方法最终走DateTime构造函数,六月只有 30 天,因此On.June.The(0)、On.June.The(31)或更大的值都会触发ArgumentOutOfRangeException。传入前应对业务输入做 1~30 的范围校验;- 结果依赖系统当前年份:API 没有"指定年份"的参数,若需要历史或未来年份的六月日期,应改用
On.June.The(n).In(year)(PrepositionsExtensions的In(int year))自行调整年份; - 类型是可变语义的
DateTime:每次访问属性都会重新计算DateTime.Now.Year,在极少数跨年边界(12 月 31 日 23:59:59 附近)连续访问时可能出现年份不一致,若对一致性有强要求,建议先取一次DateTime.Now.Year再做构造; - 命名属性是编译期常量名:
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 系列。