Humanizer OnDate.September 流式日期 API 完全指南:用 DateOnly 表达"九月第 N 天"
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 依此类推,仅日期不同
}
关键点有三:
- 年份取自
DateTime.Now.Year:返回值始终是"当前年份"的九月日期。跨年(如 12 月 31 日调用)后,同一表达式会返回新一年的日期。从源码结构可以推断,若需要特定年份,应改用InDate.SeptemberOf(2025)这类带年份参数的 API(见下文)。 - 返回
DateOnly:与On类(返回DateTime)形成互补。OnDate系整套类被#if NET6_0_OR_GREATER条件编译指令包裹(见 src/Humanizer/FluentDate/OnDate.Days.cs 第 1 行),仅在 .NET 6 及以上目标框架可用,因为DateOnly类型自 .NET 6 才引入。 - 零分配、无缓存:每个属性调用即构造,逻辑上是纯计算,没有状态与共享可变数据。
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) |
对应源码与测试:
On类位于 src/Humanizer/FluentDate/On.Days.cs,其September嵌套类(第 1568 行起)实现与OnDate.September完全同构,仅返回DateTime。In.September的语义由 tests/Humanizer.Tests/FluentDate/InTests.cs 验证:In.September等于new(DateTime.Now.Year, 9, 1),In.SeptemberOf(2009)等于new(2009, 9, 1)。- 官方文档示例(website/docs/_examples/scenarios-fluent-dates/Program.cs)展示了流式日期的完整用法:
In.Two.MonthsFrom(startingPoint)、In.AprilOf(2025).AddDays(2).At(14, 30)等,说明In/InDate侧重"相对时间与指定年份",而On/OnDate侧重"当前年份的绝对日期"。
选型建议:需要纯日期(无时间部分)且年份取当前年,用 OnDate.September;需要 DateTime 或后续要叠加时间,用 On.September;需要指定特定年份,改用 InDate.SeptemberOf(year) 或 In.SeptemberOf(year)。
五、测试验证:生成式 API 如何被保证正确
Humanizer 对该类 API 的正确性验证非常系统。两个测试文件覆盖了"成员存在性"与"返回值正确性"两个层面:
-
tests/Humanizer.Tests/FluentDate/OnDateTests.cs:手写断言,验证
OnDate.January.The23rd、OnDate.December.The4th、OnDate.February.The(11)均返回"当前年份 + 对应月 + 对应日"的DateOnly。 -
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 日"的语义保持一致。
六、使用注意事项与限制
- 目标框架限制:
OnDate整套 API 需要 .NET 6+(DateOnly类型的前提)。在 .NET Framework 或 .NET 5 及以下项目中不可用,此时请使用返回DateTime的On.September。 - 年份是运行时当前年:返回值随调用时刻变化,不能用于表示固定年份的日期;跨年进程或午夜边界调用时结果可能变化。
- 参数范围:
The(int dayNumber)只接受 1~30;越界会抛ArgumentOutOfRangeException。官方文档与源码均未提供"超出后自动钳制"或"滚入下月"的行为。 - 无时间分量:返回的是
DateOnly(午夜零点语义),若业务需要具体时刻(如"9 月 10 日 8:30 开课"),可组合ToDateTime(TimeOnly)或改用On.September系列。 - 区域性无关:类名与属性名是固定的英文序数词命名,不受当前线程
CultureInfo影响,任何区域下调用结果一致。
七、小结
OnDate.September 是 Humanizer 流式日期体系在 DateOnly 时代的典型代表:30 个语义直白的静态属性加一个参数化方法,把"当前年份九月第 N 天"这一高频构造场景封装成近乎自然语言的代码。它的实现极简(一行 DateOnly 构造)、来源可溯(T4 模板生成、测试反射全量校验),与 On/In/InDate 系列共同构成一套完整的日期表达工具链。需要进一步了解整体设计,可阅读仓库根目录的 ARCHITECTURE.md 与 DESIGN.md;完整的流式日期使用示例参见 website/docs/_examples/scenarios-fluent-dates/Program.cs。