Humanizer OnDate.August 使用指南:用流畅 API 生成 8 月日期(DateOnly)
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 |
关键差异:
OnDatevsOn:两者成员命名完全一致(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仅类型不同;OnDatevsInDate:OnDate定位“某年某月某日”(绝对日期,年份取当前),InDate定位“从现在起多久之后”(相对日期),语义方向不同;DateOnly的适配场景:当你只需要日历日期(如排期、账单日、纪念日)而不关心时分秒与本地时区换算时,OnDate.August比On.August更精确、更不易引发时间比较歧义。
测试验证:OnDate.August 的正确性依据
仓库测试对 OnDate 家族的行为做了明确验证:
- tests/Humanizer.Tests/FluentDate/OnDateTests.cs 中的用例将
OnDate.January.The23rd与new(DateTime.Now.Year, 1, 23)做相等断言,验证了“当前年份 + 硬编码月日”的实现约定;同一文件对OnDate.February.The(11)验证了The(int)方法的动态取值行为。虽然该测试文件以 1 月、12 月、2 月为例,但August走的是完全相同的代码生成模式; - tests/Humanizer.Tests/FluentDate/GeneratedFluentDateTests.cs 中的月份矩阵明确包含
("August", 8),说明包括 8 月在内的 12 个月份访问器由生成逻辑统一产出,月份号映射与源码中new(DateTime.Now.Year, 8, …)的硬编码 8 一致; - 公共 API 快照文件(如 tests/Humanizer.Tests/ApiApprover/PublicApiApprovalTest.Approve_Public_Api.DotNet8_0.verified.txt)用于守护
OnDate.August等公开 API 签名的稳定性,防止意外变更。
使用前提与实战示例
环境前提
- 目标框架为 .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不提供年份参数。