Humanizer 流畅日期 API 指南:使用 OnDate.September 构建 9 月日期(DateOnly 版)

原创2026-10-06 18:47:021,833 阅读
文章标签:开发工具

Humanizer 流畅日期 API 指南:使用 OnDate.September 构建 9 月日期(DateOnly 版)

导读

本文围绕 Humanizer 库中 OnDate.September 类的完整 API 展开,讲解如何以流畅(fluent)的方式表达"当年 9 月的第 N 天",返回 .NET 6+ 引入的 DateOnly 纯日期类型。你将掌握该类全部 30 个静态属性与 The(int) 方法的签名、语义与底层实现原理,并理解其与 T4 模板生成、DateTime 版本(On.September)之间的差异,从而在日程安排、业务规则计算等场景中写出更易读的日期代码。

OnDate.September 是 Humanizer 流畅日期模块(FluentDate)的一部分。该模块以"自然语言式"的静态访问器代替 new DateTime(year, 9, 1) 这类裸构造调用,让"9 月 1 日""9 月 30 日"这样的日期在代码中直接可读。

OnDate.September 类概述

在 OnDate.Days.cs 中,OnDate 是一个外层静态容器类,内部按月份嵌套了 January 到 December 共 12 个类;September 正是其中用于表达 9 月的嵌套类(定义于 OnDate.Days.cs)。

public class OnDate.September
  • 返回类型:所有成员均返回 System.DateOnly(不携带时间部分)。
  • 使用前提:该 API 仅在 NET6_0_OR_GREATER 目标框架下编译可用,文件头部有 #if NET6_0_OR_GREATER 条件编译指令。
  • 继承关系:System.Object → September。
  • 命名空间:Humanizer。

使用前需在项目中引入 Humanizer 包,并在代码中 using Humanizer;。

完整 API 成员清单

静态属性:The1st ~ The30th

September 类为 9 月的每一天(1 日至 30 日,9 月无 31 日)各提供一个静态属性,属性名直接采用英文序数词后缀(st/nd/rd/th),语义为"当前年份 9 月的第 N 天":

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

每个属性的声明形式完全一致,例如:

public static System.DateOnly The1st { get; }
public static System.DateOnly The10th { get; }
public static System.DateOnly The30th { get; }

方法:The(int dayNumber)

除固定属性外,September 还提供一个按参数取日的通用方法,语义为"当前年份 9 月的第 N 天":

public static System.DateOnly The(int dayNumber);
  • 参数 dayNumber:System.Int32,表示 9 月中的第几天。
  • 返回值:System.DateOnly。
  • 注意事项:dayNumber 超出 1~30 范围时,底层 DateOnly 构造会抛出参数异常,调用前应自行校验输入合法性(详见下文"实现原理")。

底层实现原理:一切都归结于一个构造函数

阅读源码可以发现,September 类的每个成员都只是对 DateOnly 构造函数的薄封装。以 OnDate.Days.cs 中的方法实现为例:

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

而固定属性则逐一内联展开,例如:

public static DateOnly The1st
    => new(DateTime.Now.Year, 9, 1);
public static DateOnly The10th
    => new(DateTime.Now.Year, 9, 10);
public static DateOnly The30th
    => new(DateTime.Now.Year, 9, 30);

由此可以归纳出三条关键实现事实:

  1. 年份取自运行时刻:月份固定为 9,年份则通过 DateTime.Now.Year 动态取"当前年份"。因此 OnDate.September.The1st 在不同年份运行会得到不同的具体日期,它表达的是"今年 9 月 1 日"这一相对语义,而不是某个固定的绝对日期。若需要指定年份,应改用 In.AprilOf(2025) 这类带年份的构造(参见 PrepositionsExtensions.cs 及示例 Program.cs)。
  2. 所有属性均为表达式体、无缓存:每次访问都会重新求值 DateTime.Now.Year 并构造新的 DateOnly 实例,靠近午夜执行时存在跨年边界(取值可能在新旧年份间漂移)的极小概率窗口。
  3. 无参数校验:方法 The(int dayNumber) 直接把参数透传给 DateOnly 构造函数。从源码结构看,如果传入 0、负数或大于 30 的值,将由 DateOnly 自身的参数校验抛出异常,Humanizer 层并未做任何预检。

从 T4 模板生成到编译产物

OnDate.September 及其余 11 个月份的类并非手写维护,而是由一个 OnDate.Days.tt T4 文本模板在构建时批量生成的,生成产物即 OnDate.Days.cs(共 2336 行)。

模板核心逻辑(OnDate.Days.tt)要点:

  • 以 2012 年(闰年)为基准计算每个月第一天,用 DateTime.ToString("MMMM") 取得月份英文名,作为嵌套类的类名,因此类名与属性名天然采用英文文化命名;
  • 对每个月用 DateTime.DaysInMonth(2012, month) 计算天数并循环生成属性,9 月为 30 天,因此只生成 The1st~The30th;
  • 属性的序数后缀(1st、2nd、3rd、21st 等)通过 Humanizer 自身的 day.Ordinalize() 扩展方法生成,形成"用 Humanizer 生成 Humanizer 流畅 API"的自举式生成管线;
  • 月份数 1~12、日期范围 1~31 的全部组合由模板统一控制,保证 12 个月份的 API 形态完全一致。

这也解释了为什么 API 的一致性如此整齐:开发者只需修改模板再重新生成,即可同步刷新全部月份类。

与 DateTime 版本 On.September 的差异

仓库中还存在另一个同族容器类 On(定义于 On.Days.cs),它同样提供 On.September.The1st、On.September.The(int) 等成员,但返回的是带时间部分的 System.DateTime 而非 DateOnly:

对比维度 On.September OnDate.September
返回类型 System.DateTime System.DateOnly
目标框架 全版本可用 NET6_0_OR_GREATER
时间部分 携带(午夜 00:00:00) 不携带,纯日期
文件来源 On.Days.cs OnDate.Days.cs
T4 模板 On.Days.tt OnDate.Days.tt

在 .NET 6+ 项目中,若业务上只关心"哪一天"而不需要时间分量(例如生日、账单日、排程日期),优先使用 OnDate.September,可以避免 DateTime 午夜值在比较、序列化时带来的歧义;若必须与遗留 DateTime API 交互,则选用 On.September。

测试验证:API 行为有据可查

Humanizer 为流畅日期模块提供了对应的单元测试 OnDateTests.cs,其中直接断言属性值等于"用当年年份手工构造的 DateOnly":

[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));

这些测试与 OnDateTests.cs 顶部的 #if NET6_0_OR_GREATER 条件编译保持一致,印证了 DateOnly 版本仅在 .NET 6+ 下编译与测试的约束。同类测试还包括 OnTests.cs(DateTime 版本)与 GeneratedFluentDateTests.cs(针对模板生成代码的覆盖)。

实际使用示例与注意要点

以下代码演示在 .NET 6+ 控制台应用中直接使用 OnDate.September:

using Humanizer;

// 当年 9 月的首日与末日
DateOnly firstDay = OnDate.September.The1st;   // 当前年 9 月 1 日
DateOnly lastDay  = OnDate.September.The30th;  // 当前年 9 月 30 日

// 按参数取任意日
DateOnly mid = OnDate.September.The(15);       // 当前年 9 月 15 日

// 与 System.DateOnly 无缝衔接
DateOnly dueDate = OnDate.September.The10th.AddDays(3);
Console.WriteLine(dueDate); // 当前年 9 月 13 日

使用时的三个要点:

  1. 相对年份语义:所有成员都基于 DateTime.Now.Year,适合表达"今年内"的日期;跨年份的固定日期请使用带年份参数的 API(如 In.AprilOf(year))自行构造。
  2. 参数边界:The(int) 仅接受 1~30 的有效日号,调用前需自行校验,避免运行时异常。
  3. 框架约束:该项目(Humanizer 3.x)中该 API 仅在 NET6_0_OR_GREATER 下可用;若目标是 .NET Framework 或 .NET 5 及以下,应回退到返回 DateTime 的 On.September。

延伸阅读

登录后查看全文
Humanizer