Humanizer FluentDate 指南:OnDate.February 类完整解析(2 月日期访问器的实现与用法)
Humanizer FluentDate 指南:OnDate.February 类完整解析(2 月日期访问器的实现与用法)
Humanizer 的 OnDate.February 是流式日期 API(FluentDate)家族中专门提供当年 2 月任意日期访问的嵌套类:通过 The1st~The29th 共 29 个静态属性和一个 The(int dayNumber) 方法,即可用纯英文序数语义直接拿到 System.DateOnly 值。本篇基于 website/versioned_docs/version-2.11.10/api/Humanizer.OnDate.February.md 的 API 定义,结合 T4 生成源码与单元测试,讲清它的完整成员清单、底层实现机制、与 On.February/InDate.February 的差异,以及闰年边界行为,读完即可在 .NET 6+ 项目中熟练使用这套"口语化日期构造"方案。
一、类定位:FluentDate 家族中的 2 月访问器
OnDate.February 是 Humanizer.OnDate 的嵌套公共类,官方文档定义其职责为 "Provides fluent date accessors for February"(为 2 月提供流式日期访问器),继承链为 System.Object → OnDate.February。
在 Humanizer 的 FluentDate 体系中,四组核心入口各有分工:
| 入口类 | 返回类型 | 语义 | 实现文件 |
|---|---|---|---|
On.Month.The(n)(如 On.February.The11th) |
System.DateTime |
当年某月某日 | src/Humanizer/FluentDate/On.Days.cs |
OnDate.Month.The(n)(如 OnDate.February.The11th) |
System.DateOnly |
当年某月某日(仅日期) | src/Humanizer/FluentDate/OnDate.Days.cs |
In.Month / In.MonthOf(year) |
System.DateTime |
某月第一天 | In.Months.cs |
InDate.Month / InDate.TheYear(year) |
System.DateOnly |
某月第一天(仅日期) | InDate.Months.cs、src/Humanizer/FluentDate/InDate.cs |
OnDate.February 即上表中的第二类——专为 2 月设计、以 DateOnly 为返回类型的静态访问器,适合不需要时间分量、只关心"哪一天"的业务场景。
二、完整成员清单:29 个属性 + 1 个方法
该类共提供 29 个静态只读属性(The1st ~ The29th,对应 2 月的全部可能天数,含闰年)与 1 个静态方法 The(int)。所有成员均返回 System.DateOnly,语义统一为"当前年份的 2 月第 N 天"。
2.1 静态属性一览
| 属性 | 含义 | 属性 | 含义 |
|---|---|---|---|
The1st |
当年 2 月 1 日 | The16th |
当年 2 月 16 日 |
The2nd |
当年 2 月 2 日 | The17th |
当年 2 月 17 日 |
The3rd |
当年 2 月 3 日 | The18th |
当年 2 月 18 日 |
The4th |
当年 2 月 4 日 | The19th |
当年 2 月 19 日 |
The5th |
当年 2 月 5 日 | The20th |
当年 2 月 20 日 |
The6th |
当年 2 月 6 日 | The21st |
当年 2 月 21 日 |
The7th |
当年 2 月 7 日 | The22nd |
当年 2 月 22 日 |
The8th |
当年 2 月 8 日 | The23rd |
当年 2 月 23 日 |
The9th |
当年 2 月 9 日 | The24th |
当年 2 月 24 日 |
The10th |
当年 2 月 10 日 | The25th |
当年 2 月 25 日 |
The11th |
当年 2 月 11 日 | The26th |
当年 2 月 26 日 |
The12th |
当年 2 月 12 日 | The27th |
当年 2 月 27 日 |
The13th |
当年 2 月 13 日 | The28th |
当年 2 月 28 日 |
The14th |
当年 2 月 14 日 | The29th |
当年 2 月 29 日(仅闰年有效) |
The15th |
当年 2 月 15 日 |
典型声明形式(与文档 API 签名一致):
public static System.DateOnly The11th { get; }
2.2 通用方法:The(int dayNumber)
public static System.DateOnly The(int dayNumber);
参数 dayNumber 为 System.Int32,表示 2 月内的日序号,返回对应的 System.DateOnly。它用于无法用固定属性表达的动态日期场景,例如循环生成某月每一天:
for (var day = 1; day <= 28; day++)
{
var date = OnDate.February.The(day); // 平年的 2 月 1 日~28 日
Console.WriteLine(date);
}
三、源码级实现原理
3.1 手写还是生成?—— T4 模板批量产出
OnDate.February 并非手写代码,而是由 T4 文本模板 src/Humanizer/FluentDate/OnDate.Days.tt 在编译期生成的。模板核心逻辑(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 February { ... }
for (var day = 1; day <= DateTime.DaysInMonth(leapYear, month); day++)
{
var ordinalDay = day.Ordinalize();
// 输出 public static DateOnly The11th => new(DateTime.Now.Year, 2, 11);
}
}
两个关键设计点:
- 用 2012 闰年作为枚举基准:
DateTime.DaysInMonth(2012, 2)返回 29,因此 2 月访问器恰好生成The1st~The29th,闰日属性天然覆盖;而其他月份按 30/31 天生成。 - 序数后缀由
Ordinalize()决定:模板调用 Humanizer 的Ordinalize()(见 src/Humanizer/InflectorExtensions.cs),把1→1st、2→2nd、3→3rd、21→21st、22→22nd、23→23rd,其余为th,这正是The21st/The22nd/The23rd等特殊拼写的来源。
3.2 生成结果的真实形态
在 src/Humanizer/FluentDate/OnDate.Days.cs 中可以看到 February 嵌套类的生成产物:
public class February
{
/// <summary>
/// The nth day of February of the current year
/// </summary>
public static DateOnly The(int dayNumber)
=> new(DateTime.Now.Year, 2, dayNumber);
/// <summary>
/// The 1st day of February of the current year
/// </summary>
public static DateOnly The1st
=> new(DateTime.Now.Year, 2, 1);
// ... 依此类推至
public static DateOnly The29th
=> new(DateTime.Now.Year, 2, 29);
}
实现要点:
- 年份取自
DateTime.Now.Year:所有属性与方法都基于"当前年份"构造,因此OnDate.February.The11th在 2025 年返回2025-02-11,跨年后自动跟随年份。 - 返回
DateOnly:整个文件被#if NET6_0_OR_GREATER包裹(OnDate.Days.cs),因为System.DateOnly是 .NET 6 引入的类型,这也意味着OnDate系列仅在 .NET 6+ 目标框架下可用;而返回DateTime的On系列则无此限制。 - 求值时机:属性是每次访问时即时计算(
=>表达式体),并非缓存值。
3.3 与 On.February 的分工
对比 src/Humanizer/FluentDate/On.Days.cs 中的 On.February,二者结构完全一致(同样生成 The1st~The29th 与 The(int)),唯一差异是返回类型:
On.February.The11th→System.DateTime(带默认时间分量);OnDate.February.The11th→System.DateOnly(纯日期)。
业务上若仅需日期比较、日期存储或格式化 yyyy-MM-dd,优先用 OnDate 系列,可避免 DateTime 时间分量的干扰。
四、实战用法示例
在 .NET 6+ 项目中引用 Humanizer 后(命名空间 Humanizer),即可直接使用:
using Humanizer;
// 固定序数属性:情人节
DateOnly valentinesDay = OnDate.February.The14th;
Console.WriteLine(valentinesDay); // 如 2025-02-14(跟随当前年份)
// 动态方法:指定第 N 天
DateOnly day = OnDate.February.The(28);
// 与 InDate 组合:取 2 月第一天
DateOnly firstOfFebruary = InDate.February; // new(DateTime.Now.Year, 2, 1)
// 与 In 系列组合:取指定年份的 2 月 1 日
DateTime feb2009 = In.FebruaryOf(2009); // 2009-02-01
典型落地场景包括:生成"本月 2 月所有日期"的列表、按固定日期触发定时任务(如每年 2 月 29 日)、把业务逻辑中的魔法日期改写成自解释代码。
五、边界与注意事项
The29th只在闰年可用:代码层面The29th恒生成new(DateTime.Now.Year, 2, 29),但平年不存在 2 月 29 日,此时访问会由DateOnly构造函数抛出运行时异常(ArgumentOutOfRangeException一类的日期有效性校验,属 .NET 类型固有行为)。使用前应先判断闰年,例如DateTime.IsLeapYear(DateTime.Now.Year)。- 平年下
The(29)同样会抛异常:The(int dayNumber)不做额外校验,合法性完全依赖DateOnly构造函数的日期验证。 - "当前年份"是动态的:跨年期间(如 12 月 31 日与 1 月 1 日)两次访问可能得到不同年份的日期;如需固定年份,建议用
InDate系列配合TheYear(int)或直接new DateOnly(year, 2, day)。 - 框架版本约束:
OnDate系列整体受NET6_0_OR_GREATER条件编译保护,.NET 5 及以下目标无法使用,应改用On系列(返回DateTime)。
六、测试验证:行为有据可查
仓库测试为上述行为提供了直接证据:
- tests/Humanizer.Tests/FluentDate/OnDateTests.cs 验证了
OnDate.February.The(11)与new(DateTime.Now.Year, 2, 11)相等; - tests/Humanizer.Tests/FluentDate/GeneratedFluentDateTests.cs 通过反射断言
OnDate类型为每个月份(含 February)生成了完整的日期属性和The方法,防止模板改动破坏 API 完整性; - tests/Humanizer.Tests/FluentDate/InDateTests.cs 与 tests/Humanizer.Tests/FluentDate/InTests.cs 佐证了配套的
InDate.February/In.FebruaryOf(2009)语义。
七、相关 API 导航
若想横向扩展,可继续查阅仓库中的同类 API 文档与实现:
OnDate其它月份访问器:同一份 OnDate.Days.cs 内嵌的January~December嵌套类;On系列(DateTime版本):On.Days.cs;- 月首访问器:
InDate.Months.cs、In.Months.cs,以及 InDate.cs 中的TheYear(int year); - 相对日期偏移:
InDate.SomeTimeFrom.cs/In.SomeTimeFrom.cs(如InDate.Five.DaysFrom(...),见 InDateTests.cs); - 各类完整 API 定义:
website/versioned_docs/version-2.11.10/api/目录下Humanizer.OnDate.*.md、Humanizer.InDate.*.md、Humanizer.On.*.md、Humanizer.In.*.md系列文档。
总结:OnDate.February 是"用英语序数直觉写日期"的典型产物——T4 模板以闰年为基准批量生成 29 个静态属性与 1 个通用方法,统一基于 DateTime.Now.Year 构造 DateOnly。掌握它不仅能写出 OnDate.February.The14th 这类自解释代码,也理解了 Humanizer FluentDate 家族"生成式 API + 类型分工(DateOnly/DateTime)"的整体设计思路。