Humanizer 流式日期 API 详解:On.June 六月日期访问器完全指南

原创2026-09-27 12:22:192,263 阅读
文章标签:开发工具

Humanizer 流式日期 API 详解:On.June 六月日期访问器完全指南

本篇技术指南围绕 Humanizer 流式日期(Fluent Date)API 中 On.June 类的完整用法展开,说明如何用一行代码获得当前年份 6 月任意一天的 DateTime,并深入其 T4 模板生成机制、On/OnDate/In 三类 API 的协作关系,以及底层实现与测试验证。读完本文,你将掌握 Humanizer 流式日期 API 的调用方式、生成原理与边界条件,可直接在 .NET 业务代码中落地使用。

一、On.June 类速览

On.June 是 Humanizer 提供的流式日期访问器之一,位于命名空间 Humanizer 下。它用于以自然语言风格构造"当前年份 6 月的某一天":

public class On.June

该类型继承自 System.Object(即普通类,无特殊基类),内部封装 30 个静态属性(The1st~The30th)与一个带参静态方法 The(int dayNumber)。它的生成源码位于 src/Humanizer/FluentDate/On.Days.cs,所有成员返回的都是 System.DateTime。

// 获取今年 6 月 1 日
var d1 = On.June.The1st;

// 获取今年 6 月 30 日
var d30 = On.June.The30th;

// 动态指定任意日
var d15 = On.June.The(15);

注意:On.June 系列 API 返回值是"当前年份"的 6 月日期。年份取自 DateTime.Now.Year,因此每年运行结果不同;要构造任意年份的日期,可配合 PrepositionsExtensions.In 扩展方法(见下文第五节)替换年份。

二、属性与方法的完整清单

1. 静态属性 The1st~The30th

On.June 提供 30 个静态只读属性,每个属性对应 6 月的一天,命名采用英文序数词缩写(1st、2nd、3rd、4th……),签名统一为:

public static System.DateTime The10th { get; }

例如属性 The10th 表示"今年 6 月 10 日",文档声明与源码实现一致(src/Humanizer/FluentDate/On.Days.cs):

public static DateTime The10th
    => new(DateTime.Now.Year, 6, 10);

完整属性清单如下(均为 DateTime 类型,年份取 DateTime.Now.Year):

属性 含义 属性 含义
The1st 6 月 1 日 The16th 6 月 16 日
The2nd 6 月 2 日 The17th 6 月 17 日
The3rd 6 月 3 日 The18th 6 月 18 日
The4th 6 月 4 日 The19th 6 月 19 日
The5th 6 月 5 日 The20th 6 月 20 日
The6th 6 月 6 日 The21st 6 月 21 日
The7th 6 月 7 日 The22nd 6 月 22 日
The8th 6 月 8 日 The23rd 6 月 23 日
The9th 6 月 9 日 The24th 6 月 24 日
The10th 6 月 10 日 The25th 6 月 25 日
The11th 6 月 11 日 The26th 6 月 26 日
The12th 6 月 12 日 The27th 6 月 27 日
The13th 6 月 13 日 The28th 6 月 28 日
The14th 6 月 14 日 The29th 6 月 29 日
The15th 6 月 15 日 The30th 6 月 30 日

6 月恰有 30 天,因此该月属性的数量与月份天数一致(这是 T4 模板自动生成的结果,见第四节)。

2. 参数化方法 The(int dayNumber)

除固定属性外,On.June 还提供动态方法:

public static System.DateTime The(int dayNumber);
  • 参数:dayNumber,类型 System.Int32,表示要取 6 月的第几天。
  • 返回值:System.DateTime。

源码实现:

public static DateTime The(int dayNumber)
    => new(DateTime.Now.Year, 6, dayNumber);

使用示例:

var d = On.June.The(15);      // 今年 6 月 15 日
var d2 = On.June.The(DateTime.Now.Day);  // 今年 6 月的"今天"

边界提示:与属性不同,The(int) 不做范围校验,直接透传给 DateTime 构造函数。若传入 0、负数或大于 30 的值,会抛出 ArgumentOutOfRangeException;例如 On.June.The(31) 会因 6 月没有 31 天而抛异常。这一点从实现 new(DateTime.Now.Year, 6, dayNumber) 可以直接推断得出。

三、实际应用场景

On.June 适合在业务代码中替代硬编码日期。典型场景包括:

  • 定时任务/批处理:每月 6 月固定日期执行结算、报表生成或归档任务:
var cutoff = On.June.The30th;   // 今年 6 月 30 日作为截止时间
if (now > cutoff) { /* 触发结算逻辑 */ }
  • 业务规则中的固定日期:如会员权益日、活动起止日:
var campaignStart = On.June.The1st;
var campaignEnd = On.June.The30th;
  • 测试与模拟数据:快速生成今年 6 月任意一天的日期:
var sampleDate = On.June.The(DateTime.Now.Day);

如果需要的是"今年 6 月 1 日"这类整月起点,还可以直接用 In.June(见下文),两者分工不同。

四、源码级原理:T4 模板自动生成

On.June 并非手工编写,而是由 T4 文本模板在编译时生成。模板位于 src/Humanizer/FluentDate/On.Days.tt,核心逻辑:

  1. 以闰年 2012 为基准枚举 1~12 月,new DateTime(leapYear, month, 1).ToString("MMMM") 得到月份英文名(如 "June"),并据此生成 public class June 之类的嵌套类;
  2. 每个类内部先生成 The(int dayNumber) 方法,再通过 DateTime.DaysInMonth(leapYear, month) 循环生成 1 号到月末每一天的序数属性(The1st、The2nd……);
  3. 属性名中的序数后缀由 day.Ordinalize() 产生——这正是 Humanizer 的 OrdinalizeExtensions 扩展(src/Humanizer/OrdinalizeExtensions.cs)的典型内部复用。

因此,On.June.The1st~The30th 的命名规律、数量(30 个)与实现 new(DateTime.Now.Year, 6, n) 全部由模板一次性生成,保证了 12 个月 API 的一致性,也解释了为何 6 月没有 The31st。模板文件与生成文件(src/Humanizer/FluentDate/On.Days.cs)同目录存放,方便对照。

五、与相关流式日期 API 的协作

On.June 隶属于 Humanizer 流式日期(FluentDate)家族,同族 API 包括:

组合使用示例:

// 今年 6 月 15 日中午 12:00
var noon = On.June.The15th.AtNoon();

// 今年 6 月 15 日 14:30
var at = On.June.The15th.At(14, 30);

// 2030 年 6 月 15 日(替换年份)
var in2030 = On.June.The15th.In(2030);

// .NET 6+:DateOnly 版本
DateOnly d = OnDate.June.The15th;

六、测试验证与注意事项

仓库测试对 On 系列行为做了直接验证(tests/Humanizer.Tests/FluentDate/OnTests.cs):

[Fact]
public void OnJanuaryThe23rd() =>
    Assert.Equal(new(DateTime.Now.Year, 1, 23), On.January.The23rd);

[Fact]
public void OnDecemberThe4th() =>
    Assert.Equal(new(DateTime.Now.Year, 12, 4), On.December.The4th);

[Fact]
public void OnFebruaryThe() =>
    Assert.Equal(new(DateTime.Now.Year, 2, 11), On.February.The(11));

虽然测试样本选取了其他月份,但 On.June 与它们是同一 T4 模板生成的同构 API,行为规则完全一致:返回值总是以 DateTime.Now.Year 为年份、以 6 为月份、以指定天数为日。

使用注意事项:

  1. 年份语义:所有属性与方法都基于"当前年份",跨年运行结果会变化。若要固定年份,用 .In(year) 扩展(见第五节)。
  2. 时区与本地时间:On.June 使用 DateTime.Now(本地时间);而 In.June、InDate.June 使用 DateTime.UtcNow(UTC 时间),两者取年来源不同,跨时区场景下要注意区别。
  3. The(int) 无参数校验:非法日号会由 DateTime 构造函数抛出 ArgumentOutOfRangeException,调用方需自行保证 1 ≤ dayNumber ≤ 30。
  4. 不可变、无副作用:On.June 的所有成员均为静态、只读表达式体,线程安全,可在任意并发场景使用。

七、小结

On.June 用最少的代码表达了"当前年份 6 月的任意一天"这一常见需求:30 个序数属性(The1st~The30th)覆盖固定日期,The(int) 覆盖动态日期。它由 T4 模板 src/Humanizer/FluentDate/On.Days.tt 自动生成,与 OnDate(DateOnly 版)、In/InDate(整月起点)以及 PrepositionsExtensions(时间与年份修饰)共同构成完整的流式日期表达体系。理解其生成原理与边界行为,可以让你在 .NET 项目中写出更接近自然语言、更不易出错的日期代码。

登录后查看全文
Humanizer