Humanizer 流式日期 API 详解:On.June 六月日期访问器完全指南
Humanizer 流式日期 API 详解:On.June 六月日期访问器完全指南
本篇技术指南围绕 Humanizer 流式日期(Fluent Date)API 中 On.June 类的完整用法展开,说明如何用一行代码获得当前年份 6 月任意一天的 DateTime,并深入其 T4 模板生成机制、On/OnDate/In 三类 API 的协作关系,以及底层实现与测试验证。读完本文,你将掌握 Humanizer 流式日期 API 的调用方式、生成原理与边界条件,可直接在 .NET 业务代码中落地使用。
一、On.June 类速览
On.June 是 Humanizer 提供的流式日期访问器之一,位于命名空间 Humanizer 下。它用于以自然语言风格构造"当前年份 6 月的某一天":
public class On.June
该类型继承自 System.Object(即普通类,无特殊基类),内部封装 30 个静态属性(The1st~The30th)与一个带参静态方法 The(int dayNumber)。它的生成源码位于 src/Humanizer/FluentDate/On.Days.cs,所有成员返回的都是 System.DateTime。
// 获取今年 6 月 1 日
var d1 = On.June.The1st;
// 获取今年 6 月 30 日
var d30 = On.June.The30th;
// 动态指定任意日
var d15 = On.June.The(15);
注意:On.June 系列 API 返回值是"当前年份"的 6 月日期。年份取自 DateTime.Now.Year,因此每年运行结果不同;要构造任意年份的日期,可配合 PrepositionsExtensions.In 扩展方法(见下文第五节)替换年份。
二、属性与方法的完整清单
1. 静态属性 The1st~The30th
On.June 提供 30 个静态只读属性,每个属性对应 6 月的一天,命名采用英文序数词缩写(1st、2nd、3rd、4th……),签名统一为:
public static System.DateTime The10th { get; }
例如属性 The10th 表示"今年 6 月 10 日",文档声明与源码实现一致(src/Humanizer/FluentDate/On.Days.cs):
public static DateTime The10th
=> new(DateTime.Now.Year, 6, 10);
完整属性清单如下(均为 DateTime 类型,年份取 DateTime.Now.Year):
| 属性 | 含义 | 属性 | 含义 |
|---|---|---|---|
The1st |
6 月 1 日 | The16th |
6 月 16 日 |
The2nd |
6 月 2 日 | The17th |
6 月 17 日 |
The3rd |
6 月 3 日 | The18th |
6 月 18 日 |
The4th |
6 月 4 日 | The19th |
6 月 19 日 |
The5th |
6 月 5 日 | The20th |
6 月 20 日 |
The6th |
6 月 6 日 | The21st |
6 月 21 日 |
The7th |
6 月 7 日 | The22nd |
6 月 22 日 |
The8th |
6 月 8 日 | The23rd |
6 月 23 日 |
The9th |
6 月 9 日 | The24th |
6 月 24 日 |
The10th |
6 月 10 日 | The25th |
6 月 25 日 |
The11th |
6 月 11 日 | The26th |
6 月 26 日 |
The12th |
6 月 12 日 | The27th |
6 月 27 日 |
The13th |
6 月 13 日 | The28th |
6 月 28 日 |
The14th |
6 月 14 日 | The29th |
6 月 29 日 |
The15th |
6 月 15 日 | The30th |
6 月 30 日 |
6 月恰有 30 天,因此该月属性的数量与月份天数一致(这是 T4 模板自动生成的结果,见第四节)。
2. 参数化方法 The(int dayNumber)
除固定属性外,On.June 还提供动态方法:
public static System.DateTime The(int dayNumber);
- 参数:
dayNumber,类型System.Int32,表示要取 6 月的第几天。 - 返回值:
System.DateTime。
源码实现:
public static DateTime The(int dayNumber)
=> new(DateTime.Now.Year, 6, dayNumber);
使用示例:
var d = On.June.The(15); // 今年 6 月 15 日
var d2 = On.June.The(DateTime.Now.Day); // 今年 6 月的"今天"
边界提示:与属性不同,The(int) 不做范围校验,直接透传给 DateTime 构造函数。若传入 0、负数或大于 30 的值,会抛出 ArgumentOutOfRangeException;例如 On.June.The(31) 会因 6 月没有 31 天而抛异常。这一点从实现 new(DateTime.Now.Year, 6, dayNumber) 可以直接推断得出。
三、实际应用场景
On.June 适合在业务代码中替代硬编码日期。典型场景包括:
- 定时任务/批处理:每月 6 月固定日期执行结算、报表生成或归档任务:
var cutoff = On.June.The30th; // 今年 6 月 30 日作为截止时间
if (now > cutoff) { /* 触发结算逻辑 */ }
- 业务规则中的固定日期:如会员权益日、活动起止日:
var campaignStart = On.June.The1st;
var campaignEnd = On.June.The30th;
- 测试与模拟数据:快速生成今年 6 月任意一天的日期:
var sampleDate = On.June.The(DateTime.Now.Day);
如果需要的是"今年 6 月 1 日"这类整月起点,还可以直接用 In.June(见下文),两者分工不同。
四、源码级原理:T4 模板自动生成
On.June 并非手工编写,而是由 T4 文本模板在编译时生成。模板位于 src/Humanizer/FluentDate/On.Days.tt,核心逻辑:
- 以闰年 2012 为基准枚举 1~12 月,
new DateTime(leapYear, month, 1).ToString("MMMM")得到月份英文名(如 "June"),并据此生成public class June之类的嵌套类; - 每个类内部先生成
The(int dayNumber)方法,再通过DateTime.DaysInMonth(leapYear, month)循环生成 1 号到月末每一天的序数属性(The1st、The2nd……); - 属性名中的序数后缀由
day.Ordinalize()产生——这正是 Humanizer 的OrdinalizeExtensions扩展(src/Humanizer/OrdinalizeExtensions.cs)的典型内部复用。
因此,On.June.The1st~The30th 的命名规律、数量(30 个)与实现 new(DateTime.Now.Year, 6, n) 全部由模板一次性生成,保证了 12 个月 API 的一致性,也解释了为何 6 月没有 The31st。模板文件与生成文件(src/Humanizer/FluentDate/On.Days.cs)同目录存放,方便对照。
五、与相关流式日期 API 的协作
On.June 隶属于 Humanizer 流式日期(FluentDate)家族,同族 API 包括:
On(当前年份,DateTime):On.June.The15th、On.December.The4th等,覆盖 12 个月,见 src/Humanizer/FluentDate/On.Days.cs。OnDate(当前年份,DateOnly):.NET 6+的DateOnly变体,同样提供The(int)与The1st~The30th,返回DateOnly,见 src/Humanizer/FluentDate/OnDate.Days.cs。若项目面向 .NET 6 及以上且不需要时间分量,优先使用OnDate.June.The15th。In(整月起点):In.June返回今年 6 月 1 日DateTime,In.JuneOf(int year)返回指定年份 6 月 1 日,见 src/Humanizer/FluentDate/In.Months.cs。InDate(整月起点,DateOnly):对应DateOnly版本,见 src/Humanizer/FluentDate/InDate.Months.cs。PrepositionsExtensions:At(hour, min, second, millisecond)、AtMidnight()、AtNoon()、In(int year)等扩展,可对On.June.The15th的结果追加时间或替换年份,见 src/Humanizer/FluentDate/PrepositionsExtensions.cs。
组合使用示例:
// 今年 6 月 15 日中午 12:00
var noon = On.June.The15th.AtNoon();
// 今年 6 月 15 日 14:30
var at = On.June.The15th.At(14, 30);
// 2030 年 6 月 15 日(替换年份)
var in2030 = On.June.The15th.In(2030);
// .NET 6+:DateOnly 版本
DateOnly d = OnDate.June.The15th;
六、测试验证与注意事项
仓库测试对 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));
虽然测试样本选取了其他月份,但 On.June 与它们是同一 T4 模板生成的同构 API,行为规则完全一致:返回值总是以 DateTime.Now.Year 为年份、以 6 为月份、以指定天数为日。
使用注意事项:
- 年份语义:所有属性与方法都基于"当前年份",跨年运行结果会变化。若要固定年份,用
.In(year)扩展(见第五节)。 - 时区与本地时间:
On.June使用DateTime.Now(本地时间);而In.June、InDate.June使用DateTime.UtcNow(UTC 时间),两者取年来源不同,跨时区场景下要注意区别。 The(int)无参数校验:非法日号会由DateTime构造函数抛出ArgumentOutOfRangeException,调用方需自行保证1 ≤ dayNumber ≤ 30。- 不可变、无副作用:
On.June的所有成员均为静态、只读表达式体,线程安全,可在任意并发场景使用。
七、小结
On.June 用最少的代码表达了"当前年份 6 月的任意一天"这一常见需求:30 个序数属性(The1st~The30th)覆盖固定日期,The(int) 覆盖动态日期。它由 T4 模板 src/Humanizer/FluentDate/On.Days.tt 自动生成,与 OnDate(DateOnly 版)、In/InDate(整月起点)以及 PrepositionsExtensions(时间与年份修饰)共同构成完整的流式日期表达体系。理解其生成原理与边界行为,可以让你在 .NET 项目中写出更接近自然语言、更不易出错的日期代码。