Humanizer 流畅日期 API 指南:使用 OnDate.September 构建 9 月日期(DateOnly 版)
Humanizer 流畅日期 API 指南:使用 OnDate.September 构建 9 月日期(DateOnly 版)
导读
本文围绕 Humanizer 库中 OnDate.September 类的完整 API 展开,讲解如何以流畅(fluent)的方式表达"当年 9 月的第 N 天",返回 .NET 6+ 引入的 DateOnly 纯日期类型。你将掌握该类全部 30 个静态属性与 The(int) 方法的签名、语义与底层实现原理,并理解其与 T4 模板生成、DateTime 版本(On.September)之间的差异,从而在日程安排、业务规则计算等场景中写出更易读的日期代码。
OnDate.September 是 Humanizer 流畅日期模块(FluentDate)的一部分。该模块以"自然语言式"的静态访问器代替 new DateTime(year, 9, 1) 这类裸构造调用,让"9 月 1 日""9 月 30 日"这样的日期在代码中直接可读。
OnDate.September 类概述
在 OnDate.Days.cs 中,OnDate 是一个外层静态容器类,内部按月份嵌套了 January 到 December 共 12 个类;September 正是其中用于表达 9 月的嵌套类(定义于 OnDate.Days.cs)。
public class OnDate.September
- 返回类型:所有成员均返回
System.DateOnly(不携带时间部分)。 - 使用前提:该 API 仅在
NET6_0_OR_GREATER目标框架下编译可用,文件头部有#if NET6_0_OR_GREATER条件编译指令。 - 继承关系:
System.Object→September。 - 命名空间:
Humanizer。
使用前需在项目中引入 Humanizer 包,并在代码中 using Humanizer;。
完整 API 成员清单
静态属性:The1st ~ The30th
September 类为 9 月的每一天(1 日至 30 日,9 月无 31 日)各提供一个静态属性,属性名直接采用英文序数词后缀(st/nd/rd/th),语义为"当前年份 9 月的第 N 天":
| 属性 | 语义 | 属性 | 语义 |
|---|---|---|---|
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 The1st { get; }
public static System.DateOnly The10th { get; }
public static System.DateOnly The30th { get; }
方法:The(int dayNumber)
除固定属性外,September 还提供一个按参数取日的通用方法,语义为"当前年份 9 月的第 N 天":
public static System.DateOnly The(int dayNumber);
- 参数
dayNumber:System.Int32,表示 9 月中的第几天。 - 返回值:
System.DateOnly。 - 注意事项:
dayNumber超出 1~30 范围时,底层DateOnly构造会抛出参数异常,调用前应自行校验输入合法性(详见下文"实现原理")。
底层实现原理:一切都归结于一个构造函数
阅读源码可以发现,September 类的每个成员都只是对 DateOnly 构造函数的薄封装。以 OnDate.Days.cs 中的方法实现为例:
public static DateOnly The(int dayNumber)
=> new(DateTime.Now.Year, 9, dayNumber);
而固定属性则逐一内联展开,例如:
public static DateOnly The1st
=> new(DateTime.Now.Year, 9, 1);
public static DateOnly The10th
=> new(DateTime.Now.Year, 9, 10);
public static DateOnly The30th
=> new(DateTime.Now.Year, 9, 30);
由此可以归纳出三条关键实现事实:
- 年份取自运行时刻:月份固定为 9,年份则通过
DateTime.Now.Year动态取"当前年份"。因此OnDate.September.The1st在不同年份运行会得到不同的具体日期,它表达的是"今年 9 月 1 日"这一相对语义,而不是某个固定的绝对日期。若需要指定年份,应改用In.AprilOf(2025)这类带年份的构造(参见 PrepositionsExtensions.cs 及示例 Program.cs)。 - 所有属性均为表达式体、无缓存:每次访问都会重新求值
DateTime.Now.Year并构造新的DateOnly实例,靠近午夜执行时存在跨年边界(取值可能在新旧年份间漂移)的极小概率窗口。 - 无参数校验:方法
The(int dayNumber)直接把参数透传给DateOnly构造函数。从源码结构看,如果传入 0、负数或大于 30 的值,将由DateOnly自身的参数校验抛出异常,Humanizer 层并未做任何预检。
从 T4 模板生成到编译产物
OnDate.September 及其余 11 个月份的类并非手写维护,而是由一个 OnDate.Days.tt T4 文本模板在构建时批量生成的,生成产物即 OnDate.Days.cs(共 2336 行)。
模板核心逻辑(OnDate.Days.tt)要点:
- 以 2012 年(闰年)为基准计算每个月第一天,用
DateTime.ToString("MMMM")取得月份英文名,作为嵌套类的类名,因此类名与属性名天然采用英文文化命名; - 对每个月用
DateTime.DaysInMonth(2012, month)计算天数并循环生成属性,9 月为 30 天,因此只生成The1st~The30th; - 属性的序数后缀(
1st、2nd、3rd、21st等)通过 Humanizer 自身的day.Ordinalize()扩展方法生成,形成"用 Humanizer 生成 Humanizer 流畅 API"的自举式生成管线; - 月份数 1~12、日期范围 1~31 的全部组合由模板统一控制,保证 12 个月份的 API 形态完全一致。
这也解释了为什么 API 的一致性如此整齐:开发者只需修改模板再重新生成,即可同步刷新全部月份类。
与 DateTime 版本 On.September 的差异
仓库中还存在另一个同族容器类 On(定义于 On.Days.cs),它同样提供 On.September.The1st、On.September.The(int) 等成员,但返回的是带时间部分的 System.DateTime 而非 DateOnly:
| 对比维度 | On.September |
OnDate.September |
|---|---|---|
| 返回类型 | System.DateTime |
System.DateOnly |
| 目标框架 | 全版本可用 | NET6_0_OR_GREATER |
| 时间部分 | 携带(午夜 00:00:00) | 不携带,纯日期 |
| 文件来源 | On.Days.cs | OnDate.Days.cs |
| T4 模板 | On.Days.tt | OnDate.Days.tt |
在 .NET 6+ 项目中,若业务上只关心"哪一天"而不需要时间分量(例如生日、账单日、排程日期),优先使用 OnDate.September,可以避免 DateTime 午夜值在比较、序列化时带来的歧义;若必须与遗留 DateTime API 交互,则选用 On.September。
测试验证:API 行为有据可查
Humanizer 为流畅日期模块提供了对应的单元测试 OnDateTests.cs,其中直接断言属性值等于"用当年年份手工构造的 DateOnly":
[Fact]
public void OnJanuaryThe23rd() =>
Assert.Equal(new(DateTime.Now.Year, 1, 23), OnDate.January.The23rd);
[Fact]
public void OnDecemberThe4th() =>
Assert.Equal(new(DateTime.Now.Year, 12, 4), OnDate.December.The4th);
[Fact]
public void OnFebruaryThe() =>
Assert.Equal(new(DateTime.Now.Year, 2, 11), OnDate.February.The(11));
这些测试与 OnDateTests.cs 顶部的 #if NET6_0_OR_GREATER 条件编译保持一致,印证了 DateOnly 版本仅在 .NET 6+ 下编译与测试的约束。同类测试还包括 OnTests.cs(DateTime 版本)与 GeneratedFluentDateTests.cs(针对模板生成代码的覆盖)。
实际使用示例与注意要点
以下代码演示在 .NET 6+ 控制台应用中直接使用 OnDate.September:
using Humanizer;
// 当年 9 月的首日与末日
DateOnly firstDay = OnDate.September.The1st; // 当前年 9 月 1 日
DateOnly lastDay = OnDate.September.The30th; // 当前年 9 月 30 日
// 按参数取任意日
DateOnly mid = OnDate.September.The(15); // 当前年 9 月 15 日
// 与 System.DateOnly 无缝衔接
DateOnly dueDate = OnDate.September.The10th.AddDays(3);
Console.WriteLine(dueDate); // 当前年 9 月 13 日
使用时的三个要点:
- 相对年份语义:所有成员都基于
DateTime.Now.Year,适合表达"今年内"的日期;跨年份的固定日期请使用带年份参数的 API(如In.AprilOf(year))自行构造。 - 参数边界:
The(int)仅接受 1~30 的有效日号,调用前需自行校验,避免运行时异常。 - 框架约束:该项目(Humanizer 3.x)中该 API 仅在
NET6_0_OR_GREATER下可用;若目标是 .NET Framework 或 .NET 5 及以下,应回退到返回DateTime的On.September。
延伸阅读
- 流畅日期模块源码:src/Humanizer/FluentDate/OnDate.Days.cs、src/Humanizer/FluentDate/On.Days.cs
- 生成模板:src/Humanizer/FluentDate/OnDate.Days.tt、src/Humanizer/FluentDate/On.Days.tt
- 相关扩展:src/Humanizer/FluentDate/PrepositionsExtensions.cs
- 单元测试:tests/Humanizer.Tests/FluentDate/OnDateTests.cs、tests/Humanizer.Tests/FluentDate/OnTests.cs
- 可运行示例:website/docs/_examples/scenarios-fluent-dates/Program.cs