Humanizer 流式日期 API 详解:OnDate.August 快速生成 8 月任意日期的 DateOnly 访问器

原创2026-09-24 22:09:301,857 阅读
文章标签:开发工具

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 自动生成的。模板的关键设计:

  1. 固定闰年样本:模板以 const int leapYear = 2012; 作为样本年,对 1..12 共 12 个月做循环(for (var month = 1; month <= 12; month++));
  2. 月份名称本地化:通过 new DateTime(leapYear, month, 1).ToString("MMMM") 取得英文月份名,直接用作嵌套类名(January、August 等);
  3. 天数精确计算:用 DateTime.DaysInMonth(leapYear, month) 获得该月天数(在 2012 闰年中 2 月为 29 天,从而保证 29 日、30 日、31 日的属性在 12 个月中都齐全);
  4. 序数词自动生成:对每一天调用 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 双版本设计。

登录后查看全文
Humanizer