Humanizer OnDate.August 使用指南:用流畅 API 生成 8 月日期(DateOnly)

原创2026-09-27 14:49:341,851 阅读
文章标签:开发工具

Humanizer OnDate.August 使用指南:用流畅 API 生成 8 月日期(DateOnly)

本篇技术指南围绕 Humanizer 的 OnDate.August 静态嵌套类展开,它提供了一套面向 8 月的流畅日期访问器:既可以用 OnDate.August.The(15) 按数字取日,也可以用 OnDate.August.The15th 这类按序数命名的强类型属性直接取值,返回类型为 System.DateOnly。读完本文,你将掌握该 API 的完整成员清单、源码实现原理、适用的 .NET 版本前提,以及它与 On、InDate 等相邻 API 的异同,并能在自己的项目中直接用起来。

OnDate.August 类概览

OnDate.August 是 Humanizer FluentDate 命名空间(Humanizer)下 OnDate 静态类中的一个嵌套类,用于提供 8 月日期的流畅访问器。它的 API 签名如下:

public class OnDate.August

从类层级看,它继承自 System.Object,所有成员均为 static 只读属性或静态方法,无需实例化即可直接调用。每个成员返回的都是当前年份(DateTime.Now.Year)中 8 月对应日期的 System.DateOnly 值。

完整声明:

public static System.DateOnly The10th { get; }
public static System.DateOnly The11th { get; }
public static System.DateOnly The12th { get; }
// …… The1st ~ The31st 共 31 个属性
public static System.DateOnly The(int dayNumber);

核心成员清单:The1st ~ The31st 属性与 The(int) 方法

OnDate.August 一共提供两类成员:31 个按序数命名的静态属性(The1st 到 The31st)和一个带参数的 The(int dayNumber) 方法。8 月固定为 31 天,因此访问器覆盖 1 日至 31 日完整范围。

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

其中 year 即 DateTime.Now.Year,也就是调用发生时的当前年份。所有属性均为 static 且仅含 get,这意味着它们可以被多次读取而不会产生状态;不过要注意它们基于“当前年份”计算,若程序跨年运行,同一段代码在不同年份会得到不同结果。

The(int dayNumber) 方法

public static System.DateOnly The(int dayNumber);

The(int) 是动态取值入口,适合日期号由变量、配置或运行时输入决定的场景:

int day = 15;
DateOnly target = OnDate.August.The(day); // 当年 8 月 15 日

从实现来看,The(dayNumber) 与 31 个属性一样,最终都归结为 new DateOnly(DateTime.Now.Year, 8, dayNumber)(见下文源码)。由于底层使用 DateOnly 构造函数,可以推断:当 dayNumber 超出合法范围(小于 1 或大于 31)时,会抛出 ArgumentOutOfRangeException,与直接构造非法日期行为一致,调用方应做好参数校验。

源码实现:OnDate.Days.cs 中的 August 类

OnDate.August 的实现位于 src/Humanizer/FluentDate/OnDate.Days.cs。整个 August 嵌套类的代码模式非常统一:

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 以此类推
}

从源码可以确认几个关键事实:

  • 硬编码月份为 8:所有表达式第二个参数固定为 8,与文档中“Provides fluent date accessors for August”的定位一致;
  • 基于 DateTime.Now.Year:年份实时取自系统当前时间,而非固定常量,所以属性值会随运行年份变化;
  • 月份天数完整:8 月恒为 31 天,因此 The1st 到 The31st 全覆盖,不存在像 2 月那样的闰年/平年天数差异问题;
  • #if NET6_0_OR_GREATER 编译条件:OnDate.Days.cs 整个文件被该条件编译指令包裹(见文件首行),因为 System.DateOnly 是 .NET 6 才引入的类型。这意味着 OnDate.August 仅在面向 .NET 6 及更高版本(含 .NET 8、.NET 10 等)的目标框架下可用。

此外,整个 OnDate 静态类(含 January ~ December 十二个嵌套月份类)都在同一个文件中生成,August 只是其中的第 8 个嵌套类。

与 On.August、InDate 家族的关系

OnDate 并非孤立存在,Humanizer 的 FluentDate 目录下还有配套 API,理解它们能帮你选对工具:

API 入口 返回类型 年份基准 源码位置
OnDate.August.* DateOnly 当前年份 src/Humanizer/FluentDate/OnDate.Days.cs
On.August.* DateTime 当前年份 src/Humanizer/FluentDate/On.Days.cs
InDate.* / In.* DateOnly / DateTime 未来相对时间(如“三天后”) src/Humanizer/FluentDate/InDate.SomeTimeFrom.cs、src/Humanizer/FluentDate/In.SomeTimeFrom.cs

关键差异:

  • OnDate vs On:两者成员命名完全一致(The1st~The31st、The(int)),区别仅在返回类型——OnDate 系返回 DateOnly(无时间部分、无时区,适合“纯日期”业务语义),On 系返回 DateTime(带 00:00:00 时间部分)。从 src/Humanizer/FluentDate/On.Days.cs 可以看到 On.August.The(int) 的实现为 new DateTime(DateTime.Now.Year, 8, dayNumber),与 OnDate 仅类型不同;
  • OnDate vs InDate:OnDate 定位“某年某月某日”(绝对日期,年份取当前),InDate 定位“从现在起多久之后”(相对日期),语义方向不同;
  • DateOnly 的适配场景:当你只需要日历日期(如排期、账单日、纪念日)而不关心时分秒与本地时区换算时,OnDate.August 比 On.August 更精确、更不易引发时间比较歧义。

测试验证:OnDate.August 的正确性依据

仓库测试对 OnDate 家族的行为做了明确验证:

使用前提与实战示例

环境前提

  • 目标框架为 .NET 6 及以上(OnDate.Days.cs 由 #if NET6_0_OR_GREATER 保护,DateOnly 类型在更早框架不存在);
  • 项目引用 Humanizer 包,并 using Humanizer;(OnDate 类位于 Humanizer 命名空间)。

代码示例

using Humanizer;

// 静态属性:可读性最强的写法
DateOnly openingDay = OnDate.August.The1st;   // 当年 8 月 1 日
DateOnly midMonth   = OnDate.August.The15th;  // 当年 8 月 15 日
DateOnly lastDay    = OnDate.August.The31st;  // 当年 8 月 31 日

// 动态方法:日期号来自变量/配置
int configuredDay = int.Parse("28");
DateOnly deadline = OnDate.August.The(configuredDay); // 当年 8 月 28 日

// 与 On.August 对比:后者返回带时间的 DateTime
DateTime legacy = On.August.The15th; // 当年 8 月 15 日 00:00:00

典型应用场景包括:月度结算日、订阅扣款日、营销活动排期、节假日/纪念日计算等“只看年月日”的业务。配合 DateOnly 的格式化能力(如 ToString("yyyy-MM-dd"))即可直接输出展示或入库。

注意事项

  • The(int dayNumber) 与 The1st~The31st 的取值都基于调用时刻的“当前年份”,同一行代码在不同年份运行结果不同,跨年调度场景需留意;
  • 传入非法日号会触发 DateOnly 构造异常,建议对动态输入做 1 <= dayNumber <= 31 的校验;
  • 若需要固定年份(而非当前年份)的 8 月日期,应直接使用 new DateOnly(year, 8, day),OnDate.August 不提供年份参数。

相关文档与源码索引

登录后查看全文
Humanizer