Humanizer On.May 完全指南:FluentDate 流式日期 API 的五月日期访问器详解

原创2026-09-27 18:37:481,664 阅读
文章标签:开发工具

Humanizer On.May 完全指南:FluentDate 流式日期 API 的五月日期访问器详解

On.May 是 Humanizer FluentDate 流式日期 API 中面向五月的日期访问器,它把「当前年份的五月第 N 天」这一常见日期构造需求压缩成一行可读性极强的静态属性或方法调用。本文以 Humanizer 3.0.1 版本的 API 参考文档 Humanizer.On.May.md 为主体,结合 On.Days.cs 的源码实现与 OnTests.cs 测试用例,系统讲解该类型全部 31 个属性与 1 个方法的签名、语义、底层实现原理和使用注意事项,读完即可在项目中直接使用并理解其边界行为。

On.May 类概览

On.May 是 On 类的嵌套类,定义如下:

public class On.May

它直接继承自 System.Object,是一个仅包含静态成员的纯工具类型,不需要实例化。类中的每个成员都返回 System.DateTime,语义统一为「当前年份的五月的某一天」。

从类名与成员命名可以看到 Humanizer FluentDate 的设计哲学:用自然语言风格的命名(On.May.The15th)取代 new DateTime(DateTime.Now.Year, 5, 15) 这种样板代码,让业务代码中的日期意图一目了然。

31 个静态属性:The1st 到 The31st

On.May 为五月的每一天(1 日到 31 日,五月固定为 31 天)都准备了命名属性,属性名直接使用英文序数词缩写(1st、2nd、3rd、th 后缀),全部为 public static System.DateTime 只读属性。完整清单如下:

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

以及最后一天:The31st(当年五月 31 日)。

API 文档为每个属性都标注了「The Nth day of May of the current year」的说明与属性值类型(System.DateTime)。每个属性等价于:

new DateTime(DateTime.Now.Year, 5, N)

也就是说,它们自动取用当前年份,因此在任何一年运行都能得到「今年的五月 N 日」,无需手动传入年份。

The(int dayNumber) 方法:动态指定日期

除固定属性外,On.May 还提供了一个通用方法用于动态传入日号:

public static System.DateTime The(int dayNumber);
  • 参数 dayNumber:System.Int32,表示五月的第几天。
  • 返回值:System.DateTime,当年五月的第 dayNumber 天。

其源码实现为(见 On.Days.cs):

public class May
{
    /// <summary>
    /// The nth day of May of the current year
    /// </summary>
    public static DateTime The(int dayNumber)
        => new(DateTime.Now.Year, 5, dayNumber);
}

典型用法:

var day = On.May.The(15);      // 今年 5 月 15 日
var day2 = On.May.The(1);      // 今年 5 月 1 日

注意:dayNumber 超出 1~31 时(如 0、32、负数),DateTime 构造函数会抛出 ArgumentOutOfRangeException;这正是 The(int) 方法需要自行保证参数合法,而 31 个命名属性天然规避了该问题的原因。

底层实现原理:T4 模板批量生成

On.May 并非手写代码,而是由 T4 模板 On.Days.tt 自动生成(生成的 C# 代码落在同目录的 On.Days.cs)。模板核心逻辑如下:

  • 以闰年 2012 为基准遍历 1~12 月,new DateTime(leapYear, month, 1) 得到每月首日;
  • 用 DateTime.DaysInMonth(leapYear, month) 决定每月天数,保证生成 The1st 到 The31st(2 月只有 The1st~The29th)恰好覆盖该月全部合法日期;
  • 用 day.Ordinalize()(Humanizer 自身的序数词扩展,见 OrdinalizeExtensions.cs)生成 1st、2nd、3rd、4th 等英文序数命名;
  • 每个成员统一用 new(DateTime.Now.Year, month, day) 构造。

因此 On.May 的全部成员——无论是 The(int) 还是 31 个属性——在运行时行为完全一致:读取 DateTime.Now.Year 作为年份,固定 5 作为月份。

使用示例与测试验证

仓库在 OnTests.cs 中对该模式进行了验证,例如:

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

同样的断言模式可推广到 On.May.The1st~On.May.The31st 与 On.May.The(n)。实际业务代码示例:

using Humanizer;

// 今年五月一号
var laborDay = On.May.The1st;

// 今年五月最后一个工作日之前的日期等场景
var middleOfMay = On.May.The(15);

// 与时间组合
var meetingTime = On.May.The10th.AddHours(14); // 五月十日 14:00

与 FluentDate 家族的 In API(如 In.cs 中的 In.TheYear(int year),返回某年 1 月 1 日)配合,可以构造出「未来某年的五月某日」等更丰富的日期表达式,例如 In.TheYear(2026).AddMonths(4).AddDays(15) 与 On.May.The15th 在 2026 年运行时语义相同。

使用注意事项与边界行为

基于源码实现,以下几点需要开发者留意:

  1. 年份取自调用时刻:每个成员在访问时都重新求值 DateTime.Now.Year。若程序恰好在跨年(12 月 31 日 23:59:59 → 1 月 1 日 00:00:00)之间连续访问两次 On.May.The1st,理论上可能得到不同年份的结果;对绝大多数场景无影响,但若需固定年份,请用 In.TheYear(year) 显式指定。
  2. 依赖本地时区:DateTime.Now 返回的是本地时间,On.May 各成员的年份计算受运行机器时区影响;在服务器多时区部署时,需要结合业务时区判断「当前年份」是否符合预期。
  3. 返回的是 DateTime 而非 DateOnly:得到的是当日 00:00:00 的 DateTime,可继续调用 AddHours、At(见 PrepositionsExtensions.cs 等扩展)叠加具体时刻。
  4. 方法版参数必须合法:The(int) 传入 1~31 之外的值会抛 ArgumentOutOfRangeException;需要动态日号时建议先校验范围。
  5. 版本定位:本文所述 API 形态对应 Humanizer 3.0.1 的文档(versioned_docs 版本目录),当前主分支 API 文档位于 website/docs/api/Humanizer.On.May.md,签名保持一致,可放心使用。

小结

On.May 是 Humanizer FluentDate 设计中「以自然语言构造日期」的代表作:31 个静态属性 The1st~The31st 覆盖五月每一天,The(int dayNumber) 提供动态日号入口,全部返回当年五月的 System.DateTime。其代码由 T4 模板按 DateTime.DaysInMonth 自动生成,保证每月属性数量与历法一致。理解它的实现与边界,就能举一反三地使用 On.January、On.December 等其余 11 个月份访问器,写出可读性更高、更贴近业务语义的 .NET 日期代码。

登录后查看全文
Humanizer