Humanizer 流式日期 API 详解:OnDate.August 快速生成 8 月任意日期的 DateOnly 访问器
Humanizer 流式日期 API 详解:OnDate.August 快速生成 8 月任意日期的 DateOnly 访问器
本篇技术指南聚焦 Humanizer 流式日期(FluentDate)体系中的 OnDate.August 类,完整梳理其 31 个静态日期属性与 The(int) 方法,并结合仓库源码剖析其实现原理与 T4 模板生成机制。读完本文,你将掌握如何用一行链式代码构造"当前年份 8 月的指定日期"(返回 System.DateOnly),理解它与 On.August(DateTime 版本)的区别,以及相关的边界行为与测试验证方式。
OnDate.August 在 Humanizer 流式日期体系中的位置
Humanizer 在 src/Humanizer/FluentDate 目录下提供了一套流式日期(FluentDate)API,核心包含四个静态入口类:
| 入口类 | 返回类型 | 用途 |
|---|---|---|
On |
DateTime |
指定"某年某月的第几天" |
OnDate |
DateOnly |
同 On,但返回无时间分量的 DateOnly |
In / InDate |
DateTime / DateOnly |
相对当前时间的偏移表达(如"三小时后") |
其中 OnDate 与 On 都按月份嵌套了 12 个子类(January ~ December),OnDate.August 就是专门面向 8 月的日期访问器。依据 version-2.11.10 版 API 文档,该类的官方定位是:
Provides fluent date accessors for August(为 8 月提供流式日期访问器)
public class OnDate.August
它是一个嵌套在 public class OnDate 内部的 public class,所有成员均为静态成员,无需实例化即可直接调用。该类仅存在于 NET6_0_OR_GREATER 目标框架下(因为 System.DateOnly 自 .NET 6 起才引入),源码开头以 #if NET6_0_OR_GREATER 条件编译保护(见 OnDate.Days.cs)。
完整 API 清单:31 个静态属性与 The(int) 方法
OnDate.August 的成员完全由"当前年份 + 8 月"这一组合决定:31 个静态属性 The1st ~ The31st 覆盖 8 月的每一天(8 月恒为 31 天,故属性数量固定),外加一个通用方法 The(int dayNumber)。所有属性返回类型均为 System.DateOnly。
31 个静态日期属性
| 属性 | 签名 | 对应日期(当前年份的 8 月) |
|---|---|---|
The1st |
public static DateOnly The1st { get; } |
8 月 1 日 |
The2nd |
public static DateOnly The2nd { get; } |
8 月 2 日 |
The3rd |
public static DateOnly The3rd { get; } |
8 月 3 日 |
The4th |
public static DateOnly The4th { get; } |
8 月 4 日 |
The5th |
public static DateOnly The5th { get; } |
8 月 5 日 |
The6th |
public static DateOnly The6th { get; } |
8 月 6 日 |
The7th |
public static DateOnly The7th { get; } |
8 月 7 日 |
The8th |
public static DateOnly The8th { get; } |
8 月 8 日 |
The9th |
public static DateOnly The9th { get; } |
8 月 9 日 |
The10th |
public static DateOnly The10th { get; } |
8 月 10 日 |
The11th |
public static DateOnly The11th { get; } |
8 月 11 日 |
The12th |
public static DateOnly The12th { get; } |
8 月 12 日 |
The13th |
public static DateOnly The13th { get; } |
8 月 13 日 |
The14th |
public static DateOnly The14th { get; } |
8 月 14 日 |
The15th |
public static DateOnly The15th { get; } |
8 月 15 日 |
The16th |
public static DateOnly The16th { get; } |
8 月 16 日 |
The17th |
public static DateOnly The17th { get; } |
8 月 17 日 |
The18th |
public static DateOnly The18th { get; } |
8 月 18 日 |
The19th |
public static DateOnly The19th { get; } |
8 月 19 日 |
The20th |
public static DateOnly The20th { get; } |
8 月 20 日 |
The21st |
public static DateOnly The21st { get; } |
8 月 21 日 |
The22nd |
public static DateOnly The22nd { get; } |
8 月 22 日 |
The23rd |
public static DateOnly The23rd { get; } |
8 月 23 日 |
The24th |
public static DateOnly The24th { get; } |
8 月 24 日 |
The25th |
public static DateOnly The25th { get; } |
8 月 25 日 |
The26th |
public static DateOnly The26th { get; } |
8 月 26 日 |
The27th |
public static DateOnly The27th { get; } |
8 月 27 日 |
The28th |
public static DateOnly The28th { get; } |
8 月 28 日 |
The29th |
public static DateOnly The29th { get; } |
8 月 29 日 |
The30th |
public static DateOnly The30th { get; } |
8 月 30 日 |
The31st |
public static DateOnly The31st { get; } |
8 月 31 日 |
属性名的序数后缀(st / nd / rd / th)由 Humanizer 的 Ordinalize() 扩展生成,与英文自然语言习惯一致:1 → 1st、2 → 2nd、3 → 3rd、其余 → th。
The(int dayNumber) 方法
当需要动态指定日期(如来自变量、配置或用户输入)时,使用通用方法:
public static System.DateOnly The(int dayNumber);
| 项目 | 说明 |
|---|---|
参数 dayNumber |
System.Int32,8 月内的日号,合法取值范围为 1 ~ 31 |
| 返回值 | System.DateOnly,即"当前年份 8 月 dayNumber 日" |
该方法是 31 个属性的动态等价形式,二者内部实现完全一致(见下文源码剖析)。
源码实现:从 T4 模板生成到最终代码
最终生成的 C# 实现
OnDate.August 的实现位于 OnDate.Days.cs。核心逻辑非常简洁——以本地当前时间为基准取年份,再用 DateOnly 构造函数拼出 8 月的日期:
public class August
{
/// <summary>
/// The nth day of August of the current year
/// </summary>
public static DateOnly The(int dayNumber)
=> new(DateTime.Now.Year, 8, dayNumber);
/// <summary>
/// The 1st day of August of the current year
/// </summary>
public static DateOnly The1st
=> new(DateTime.Now.Year, 8, 1);
// The2nd ... The31st 依此类推,仅 day 参数不同
}
可见每个成员都是 new(DateTime.Now.Year, 8, day) 的变体:
- 年份取自
DateTime.Now.Year:属性与方法的输出日期年份永远等于"运行时刻的当前年",而非固定年份。因此在 2026 年调用OnDate.August.The1st得到2026-08-01,跨年后自动变为新年份; DateOnly无时间分量:不会像DateTime那样携带 00:00:00 的时间信息,适合仅关注日历日期的业务场景;- 月份固定为 8:这正是该类专属于 August 的原因,与
OnDate.January(月份参数为 1)、OnDate.December(月份参数为 12)形成对称的 12 个子类结构。
T4 模板如何"批量生产"这 31 个成员
这 31 个属性并非手写,而是由 T4 文本模板 OnDate.Days.tt 自动生成的。模板的关键设计:
- 固定闰年样本:模板以
const int leapYear = 2012;作为样本年,对1..12共 12 个月做循环(for (var month = 1; month <= 12; month++)); - 月份名称本地化:通过
new DateTime(leapYear, month, 1).ToString("MMMM")取得英文月份名,直接用作嵌套类名(January、August等); - 天数精确计算:用
DateTime.DaysInMonth(leapYear, month)获得该月天数(在 2012 闰年中 2 月为 29 天,从而保证 29 日、30 日、31 日的属性在 12 个月中都齐全); - 序数词自动生成:对每一天调用
day.Ordinalize()得到1st、2nd、3rd……再拼出属性名The<#= ordinalDay #>。
从源码结构可以推断:只要修改模板并重新运行 T4 转换,即可为全部 12 个月批量重新生成同名结构的访问器,这正是 OnDate(以及 On)类族能保持高度一致性的工程化原因。
OnDate.August 与 On.August:DateOnly 与 DateTime 两种选择
OnDate 并非唯一入口。Humanizer 还提供了返回 DateTime 的 On 类族(实现见 On.Days.cs),其 On.August 结构与 OnDate.August 一一对应,区别仅在于返回值类型:
// On.Days.cs 中 January 的对照实现
public static DateTime The1st
=> new(DateTime.Now.Year, 1, 1);
| 对比维度 | On.August |
OnDate.August |
|---|---|---|
| 返回类型 | System.DateTime |
System.DateOnly |
| 年份来源 | DateTime.Now.Year(相同) |
DateTime.Now.Year(相同) |
| 时间分量 | 00:00:00 | 无 |
| 目标框架 | 全框架可用 | 需 NET6_0_OR_GREATER |
选择建议:若后续需要与 DateTime 体系(如 DateTimeOffset、TimeSpan 运算、数据库 datetime 字段)直接交互,用 On.August;若业务只关心日历日期(如排期、生日、节日计算),用 OnDate.August 能避免携带无意义的时间分量,也更贴合 .NET 6+ 的 DateOnly 语义。从模板设计看,二者由同一套 T4 逻辑(OnDate.Days.tt 与 On.Days.tt)分别驱动生成,结构完全平行。
实战用法与测试验证
典型用法示例
using Humanizer;
// 静态属性:直接表达"8 月的某一天"
DateOnly summerHoliday = OnDate.August.The1st; // 当前年份的 8 月 1 日
DateOnly midAugust = OnDate.August.The15th; // 当前年份的 8 月 15 日
DateOnly monthEnd = OnDate.August.The31st; // 当前年份的 8 月 31 日
// 动态日号:适用于参数化场景
int day = GetDayFromConfig(); // 例如 8
DateOnly target = OnDate.August.The(day); // 当前年份的 8 月 8 日
测试用例佐证
Humanizer 的流式日期测试位于 OnDateTests.cs,虽然未逐月穷举,但已用典型月份验证了该类族的统一行为模式:
[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));
这些断言直接证实了"属性/方法返回 当前年份 对应月日"的实现语义(测试同样以 #if NET6_0_OR_GREATER 条件编译,与 OnDate 的框架要求一致)。OnDate.August 各成员与 OnDate.January.The23rd 等遵循完全相同的 new(DateTime.Now.Year, month, day) 实现路径。
与 InDate 配合完成"某月某日"的流式表达
OnDate 负责"绝对日",而 InDate.cs 提供 TheYear(int year) 用于指定年份。二者组合即可构造任意完整日期:
DateOnly birthday = OnDate.August.The20th; // 今年 8 月 20 日
DateOnly anniversary = InDate.TheYear(2030); // 2030 年 1 月 1 日
需要精确到具体年份的 8 月日期时,可直接用 DateOnly 构造器 new DateOnly(year, 8, day),OnDate.August 的价值在于省去月份数字 8 的记忆成本,让代码读起来更接近自然语言。
使用注意与边界
dayNumber取值范围:8 月固定 31 天,故The(int)的合法输入为 1 ~ 31,恰好与 31 个静态属性一一对应。从实现new(DateTime.Now.Year, 8, dayNumber)看,传入 0 或大于 31 的值会由DateOnly构造函数抛出ArgumentOutOfRangeException(这是 .NET 框架自身行为,可从构造器语义推断,非 Humanizer 单独校验);- 年份基于本地时区:实现取自
DateTime.Now.Year,因此结果年份依赖运行机器本地时间;若跨时区部署且对"当天"有严格定义,需自行评估时间来源,Humanizer 未在此处注入时区抽象; - 只在 .NET 6+ 可用:
OnDate.August整体被#if NET6_0_OR_GREATER保护,面向net48或更早框架的项目不可用,应改用On.August(DateTime版本); - 每次访问实时求值:属性是
{ get; }计算属性而非缓存字段,每次读取都会重新执行DateTime.Now.Year取值——若程序跨越新年边界持续运行,前后两次读取可能返回不同年份,这与测试中"与new(DateTime.Now.Year, ...)相等"的断言语义是一致的。
总结:OnDate.August 是 Humanizer FluentDate 体系中最具代表性的单月日期访问器之一,通过 31 个语义化属性与 1 个动态方法,把"当前年份 8 月的任意一天"压缩为一次自然语言级的链式调用;其背后是 T4 模板驱动的全月生成机制,以及与 On 类族平行的 DateOnly / DateTime 双版本设计。