Humanizer `OnDate.January` 流式 API 详解:用一行代码构造当年 1 月的任意 `DateOnly` 日期
Humanizer OnDate.January 流式 API 详解:用一行代码构造当年 1 月的任意 DateOnly 日期
Humanizer 的 FluentDate 家族提供了一套可读性极强的日期构造 API,而 OnDate.January 正是其中负责"当年 1 月某一天"的专用入口:它把 new DateOnly(DateTime.Now.Year, 1, 23) 这样的底层构造封装成 OnDate.January.The23rd 的声明式写法。本文基于 Humanizer v2.13.14 的 API 参考文档 Humanizer.OnDate.January,完整梳理该类的 31 个静态日期属性与动态构造方法,并结合 T4 模板生成源码 与单元测试揭示其底层实现机制,读完即可在业务代码中直接落地使用。
一、OnDate.January 类速览
OnDate.January 是嵌套在 OnDate 类内部的公开静态访问器类,官方文档将其定位为:
Provides fluent date accessors for January(为一月提供流式日期访问器)
public class OnDate.January
它直接继承自 System.Object,自身不含任何实例成员或构造函数,全部成员均为 public static,因此使用时无需实例化,直接以 OnDate.January.xxx 形式调用即可。类的完整结构如下:
| 成员类别 | 数量 | 签名形态 | 返回值 |
|---|---|---|---|
| 静态日期属性 | 31 个 | The1st ~ The31st |
System.DateOnly |
| 动态构造方法 | 1 个 | The(int dayNumber) |
System.DateOnly |
从命名空间看,OnDate 与 InDate 是配套出现的两个 DateOnly 入口:InDate 负责"未来某月的 1 号"(如 InDate.February 表示来年 2 月 1 日),OnDate 负责"当年某月的具体日期"。FluentDate 场景文档 fluent-dates-and-time-spans.mdx 也明确指出:InDate 和 OnDate 在兼容框架上提供与 In、On 对应的 DateOnly 值。
二、31 个静态日期属性:The1st 到 The31st
OnDate.January 为 1 月的每一天都预生成一个静态只读属性,命名规则是 The 加英文序数后缀(1st、2nd、3rd、4th、5th …)。每个属性返回当前年份对应日期的 DateOnly,签名统一为:
public static System.DateOnly The10th { get; }
完整属性清单如下(均表示"当前年份的 1 月第 N 天"):
| 属性 | 返回日期(当年) | 属性 | 返回日期(当年) |
|---|---|---|---|
The1st |
1 月 1 日 | The17th |
1 月 17 日 |
The2nd |
1 月 2 日 | The18th |
1 月 18 日 |
The3rd |
1 月 3 日 | The19th |
1 月 19 日 |
The4th |
1 月 4 日 | The20th |
1 月 20 日 |
The5th |
1 月 5 日 | The21st |
1 月 21 日 |
The6th |
1 月 6 日 | The22nd |
1 月 22 日 |
The7th |
1 月 7 日 | The23rd |
1 月 23 日 |
The8th |
1 月 8 日 | The24th |
1 月 24 日 |
The9th |
1 月 9 日 | The25th |
1 月 25 日 |
The10th |
1 月 10 日 | The26th |
1 月 26 日 |
The11th |
1 月 11 日 | The27th |
1 月 27 日 |
The12th |
1 月 12 日 | The28th |
1 月 28 日 |
The13th |
1 月 13 日 | The29th |
1 月 29 日 |
The14th |
1 月 14 日 | The30th |
1 月 30 日 |
The15th |
1 月 15 日 | The31st |
1 月 31 日 |
The16th |
1 月 16 日 |
注意两点:其一,属性的年份永远是 DateTime.Now.Year,即调用时刻所在的自然年,跨年调用会自动切换到新年份;其二,1 月固定有 31 天,因此属性从 The1st 到 The31st 完整覆盖,不存在像 2 月那样按闰年变化的属性数量问题。
三、The(int dayNumber) 动态构造方法
除了预生成的 31 个属性,该类还提供一个通用方法,用于动态构造当年 1 月的第 N 天:
public static System.DateOnly The(int dayNumber);
- 参数:
dayNumber(System.Int32),表示目标日期在 1 月中的天数序号; - 返回值:
System.DateOnly,即当年 1 月dayNumber日的日期。
典型用法:
// 等价于 OnDate.January.The10th,但天数由变量决定
var day = 10;
DateOnly target = OnDate.January.The(day);
该方法的实际实现位于 src/Humanizer/FluentDate/OnDate.Days.cs:
public static DateOnly The(int dayNumber)
=> new(DateTime.Now.Year, 1, dayNumber);
DateOnly 构造函数会对参数做范围校验:当月数值不在 1~31 范围内时抛出 ArgumentOutOfRangeException。测试 GeneratedFluentDateTests.cs 中专门捕获了 TargetInvocationException 并断言其内部异常类型为 ArgumentOutOfRangeException,从测试层面确认了这一边界行为——因此在业务中使用动态天数时,应先校验 dayNumber 的合法性。
四、源码实现:一次 T4 模板生成,覆盖全部属性
31 个属性并非手写代码,而是由 T4 文本模板批量生成的。模板文件 src/Humanizer/FluentDate/OnDate.Days.tt 的核心逻辑如下:
const int leapYear = 2012;
for (var month = 1; month <= 12; month++)
{
// ... 按月份生成嵌套类,类名取自 DateTime 的 "MMMM" 格式
public class <#= monthName #>
{
public static DateOnly The(int dayNumber)
=> new(DateTime.Now.Year, <#= month #>, dayNumber);
for (var day = 1; day <= DateTime.DaysInMonth(leapYear, month); day++)
{
var ordinalDay = day.Ordinalize();
// 生成 The1st、The2nd ... The31st 属性
public static DateOnly The<#= ordinalDay #>
=> new(DateTime.Now.Year, <#= month #>, <#= day #>);
}
}
}
几个值得注意的实现细节:
- 闰年基准 2012:模板用
const int leapYear = 2012作为计算基准,DateTime.DaysInMonth(2012, 1)得到 31,确保生成的属性数量覆盖当月的全部天数(1 月因此恰好生成 31 个属性)。 - 序数后缀由
Ordinalize()生成:属性名中的1st、2nd、3rd等后缀并非硬编码,而是调用 Humanizer 自身的Ordinalize()扩展方法(定义见 OrdinalizeExtensions.cs),这也解释了为什么属性名遵循The1st、The2nd、The3rd、The4th… 的英文序数习惯。 #if NET6_0_OR_GREATER编译保护:DateOnly类型自 .NET 6 起才可用,因此OnDate系列以及生成的代码文件整体包在#if NET6_0_OR_GREATER中(见 OnDate.Days.cs),在 .NET Framework 等旧目标上不会编译该 API。生成的最终代码位于同目录的 OnDate.Days.cs,January类在文件第 9~202 行,与模板一一对应。
这套"模板驱动 + 源码生成"的机制意味着:项目维护者只需修改 T4 模板即可同步更新全部 12 个月的访问器,生成代码与模板保持严格一致,人工手写很容易产生遗漏或序数拼写错误,这正是该设计想要避免的。
五、与 On.January(DateTime 版本)的关系
OnDate.January 并不是唯一的一月访问器,Humanizer 同时提供了返回 DateTime 的对应版本 On.January。两者生成逻辑完全相同,仅返回类型不同:
| 入口 | 返回类型 | 框架要求 | 典型返回示例 |
|---|---|---|---|
On.January.The10th |
DateTime |
全框架 | 2026-01-10 00:00:00 |
OnDate.January.The10th |
DateOnly |
.NET 6+ | 2026-01-10 |
实现对照(On.Days.cs):
public static DateTime The(int dayNumber)
=> new(DateTime.Now.Year, 1, dayNumber);
选择建议:当业务只关心"日期"本身、不涉及时间分量时,优先使用 OnDate.January 的 DateOnly,类型上更能表达语义,也避免与 DateTime 时间部分混淆;需要完整 DateTime(如后续与时间运算、序列化)时再选用 On.January。两者都基于 DateTime.Now.Year,即"当前年份"语义,与具体调用时刻绑定。
六、测试验证:API 契约被完整锁定
Humanizer 为 FluentDate 家族建立了双层测试保障,OnDate.January 均被覆盖:
- 手工用例:tests/Humanizer.Tests/FluentDate/OnDateTests.cs 中的
OnJanuaryThe23rd直接断言:
Assert.Equal(new(DateTime.Now.Year, 1, 23), OnDate.January.The23rd);
- 反射全量校验:GeneratedFluentDateTests.cs 中的
OnDateDayPropertiesCoverAllGeneratedDayAccessors通过反射遍历OnDate下全部月份嵌套类的所有静态属性,逐一解析属性名中的日期序号并断言返回值等于new DateOnly(year, month, day);OnDateTheMethodsCoverAllGeneratedMonthFactories则对每个月份类的The(int)方法以参数1调用并断言结果。这意味着哪怕模板生成逻辑发生变化,只要有任何属性缺失或数值错误,测试就会失败。
这两层测试共同锁定了 OnDate.January 的公共 API 契约,也为你放心在业务中直接使用提供了依据。
七、实战示例与适用前提
结合以上内容,给出一个完整的落地示例:
using Humanizer;
// 1. 预生成属性:直接表达"当年 1 月 15 日"
DateOnly midJanuary = OnDate.January.The15th;
// 2. 动态方法:按运行期变量构造
int dayOfMonth = GetDayFromConfig(); // 例如 23
DateOnly scheduled = OnDate.January.The(dayOfMonth);
// 3. 与日期运算无缝衔接(DateOnly 自带 AddDays/AddMonths)
DateOnly deadline = OnDate.January.The31st.AddDays(7);
// 4. 需要完整时间值时改用 DateTime 版本
DateTime exact = On.January.The31st;
适用前提(务必确认):
- 目标框架须为 .NET 6 或更高版本(
DateOnly可用性约束,源码以#if NET6_0_OR_GREATER保护); - 返回值年份取自调用时刻的
DateTime.Now.Year,即"当年 1 月",无法通过该 API 直接构造其他年份的 1 月日期(跨年需求可参考同家族In.JanuaryOf(year)/InDate.JanuaryOf(year)模式,见 In.SomeTimeFrom.cs); - 传入
The(int)的天数超出 1~31 时抛出ArgumentOutOfRangeException,建议先做参数校验。
一句话总结:OnDate.January 把"当年 1 月的某一天"压缩为一个自解释的属性或方法调用,既消除手写 DateOnly 构造的样板代码,又让日期意图在代码中直接可读,是 Humanizer FluentDate 中处理单月日期的标准写法。