Humanizer `OnDate.January` 流式 API 详解:用一行代码构造当年 1 月的任意 `DateOnly` 日期

原创2026-09-25 16:15:122,122 阅读
文章标签:开发工具

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 #>);
        }
    }
}

几个值得注意的实现细节:

  1. 闰年基准 2012:模板用 const int leapYear = 2012 作为计算基准,DateTime.DaysInMonth(2012, 1) 得到 31,确保生成的属性数量覆盖当月的全部天数(1 月因此恰好生成 31 个属性)。
  2. 序数后缀由 Ordinalize() 生成:属性名中的 1st、2nd、3rd 等后缀并非硬编码,而是调用 Humanizer 自身的 Ordinalize() 扩展方法(定义见 OrdinalizeExtensions.cs),这也解释了为什么属性名遵循 The1st、The2nd、The3rd、The4th… 的英文序数习惯。
  3. #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 均被覆盖:

  1. 手工用例:tests/Humanizer.Tests/FluentDate/OnDateTests.cs 中的 OnJanuaryThe23rd 直接断言:
Assert.Equal(new(DateTime.Now.Year, 1, 23), OnDate.January.The23rd);
  1. 反射全量校验: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 中处理单月日期的标准写法。

登录后查看全文
Humanizer