Humanizer 流式日期 API 详解：In.Seven「从现在起 7 天/小时」全接口参考与生成机制

开发工具【免费下载链接】HumanizerHumanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities项目地址https://gitcode.com/gh_mirrors/hu/Humanizer点击查看免费下载本篇技术指南以 Humanizer 2.13.14 版本 API 文档中的Humanizer.In.Seven类为骨架完整覆盖它的 7 个静态属性和 7 个*From方法并结合当前仓库中的源码T4 模板 生成代码与单元测试讲清这些成员的实现原理、时间基准UTC、周与月/年的换算细节以及如何在相对时间人性化humanize场景中组合使用它们。读完后你将能够准确使用In.Seven的每个成员、理解它从何而来代码生成并避开时区与月末钳位等常见陷阱。一、In.Seven 在流式日期 API 中的定位Humanizer 的 FluentDate 模块提供了一组可读性极强的流式日期 API。In类部分类public partial class In见 In.cs内部按数量词嵌套了One到Ten共十个静态嵌套类In.Seven就是其中表示从现在起 7 个单位时间的那一个。原始 API 文档页 Humanizer.In.Seven.md 描述的完整类型签名为public static class In.Seven其继承链为System.Object → Seven即它本身不实例化、只提供静态成员这是 Humanizer 流式日期 API 的典型形态所有成员都是静态的通过In.Seven.XXX这种类名 属性名的路径形成可读的伪自然语言表达。二、属性参考从现在起 7 个单位的 7 个静态属性文档页完整列出了 7 个只读静态属性全部返回System.DateTime。逐一对照 In.SomeTimeFrom.cs 中的实际实现属性签名文档语义底层实现In.Seven.Secondspublic static DateTime Seconds { get; }7 seconds from nowDateTime.UtcNow.AddSeconds(7)In.Seven.Minutespublic static DateTime Minutes { get; }7 minutes from nowDateTime.UtcNow.AddMinutes(7)In.Seven.Hourspublic static DateTime Hours { get; }7 hours from nowDateTime.UtcNow.AddHours(7)In.Seven.Dayspublic static DateTime Days { get; }7 days from nowDateTime.UtcNow.AddDays(7)In.Seven.Weekspublic static DateTime Weeks { get; }7 weeks from nowDateTime.UtcNow.AddDays(49)In.Seven.Monthspublic static DateTime Months { get; }7 months from nowDateTime.UtcNow.AddMonths(7)In.Seven.Yearspublic static DateTime Years { get; }7 years from nowDateTime.UtcNow.AddYears(7)三个值得注意的实现细节均可在 In.SomeTimeFrom.cs 中直接验证时间基准是DateTime.UtcNow。所有from now属性都基于 UTC 时间计算因此返回值的Kind为Utc。如果你的业务以本地时间展示需要在消费端自行转换时区不要把这些值与DateTime.Now直接混算。Weeks 不走AddWeeks而是AddDays(49)。模板对周的处理是i * 7天Seven.Weeks即 49 天这与BCL中DateTime没有AddWeeks的事实一致语义上等价于 7 周。属性是表达式体、每次访问重新求值。例如In.Seven.Days每次访问都会重新读取DateTime.UtcNow再偏移 7 天所以在跨越午夜/秒的时间窗口里两次访问结果可能有细微差别——它不是一个缓存下来的固定时间点。三、方法参考以任意日期为基准的 7 个 *From 方法文档页同时列出了 7 个与属性一一对应的实例基准方法参数均为System.DateTime date返回值也为System.DateTime方法签名文档语义SecondsFrompublic static DateTime SecondsFrom(DateTime date)7 seconds from the provided dateMinutesFrompublic static DateTime MinutesFrom(DateTime date)7 minutes from the provided dateHoursFrompublic static DateTime HoursFrom(DateTime date)7 hours from the provided dateDaysFrompublic static DateTime DaysFrom(DateTime date)7 days from the provided dateWeeksFrompublic static DateTime WeeksFrom(DateTime date)7 weeks from the provided dateMonthsFrompublic static DateTime MonthsFrom(DateTime date)7 months from the provided dateYearsFrompublic static DateTime YearsFrom(DateTime date)7 years from the provided date以 In.SomeTimeFrom.cs 中的实现为例所有*From方法都是对入参直接调用 BCL 的AddXxx方法public static DateTime DaysFrom(DateTime date) date.AddDays(7); public static DateTime WeeksFrom(DateTime date) date.AddDays(49); public static DateTime MonthsFrom(DateTime date) date.AddMonths(7);*From方法不做任何当前时间相关的计算因此是确定性的给定相同的date结果可复现这也是它比属性更适合单元测试的原因。单元测试如何验证 DaysFrom仓库测试 InTests.cs 用In.Five演示了同一模式的验证方式In.Seven的逻辑与之完全同构[Fact] public void InFiveDays() { var baseDate On.January.The21st; var date In.Five.DaysFrom(baseDate); Assert.Equal(baseDate.AddDays(5), date); }该测试说明两件事一是*From方法可以与On某天API 组合出从某月某日起 7 天这类链式表达式二是断言直接用date.AddDays(N)作为期望值印证了*From方法就是纯偏移、无副作用的语义。四、源码级原理In.Seven 是由 T4 模板生成的代码从源码结构看In.Seven并不是手写类。In.SomeTimeFrom.tt 是一个 T4 文本模板它对i从 1 遍历到 10为每个数字生成一个静态嵌套类类名由 Humanizer 自己的ToWords()Dehumanize()反推7的英文词形经反人性化处理得到Seven从而批量产出One到Ten#for (var i 1; i 10; i){ var plural i 1 ? s : ; var second Second plural; ... # public static class # i.ToWords().Dehumanize() # { public static DateTime # second # DateTime.UtcNow.AddSeconds(# i #); ... public static DateTime # week #From(DateTime date) date.AddDays(# i * 7 #); ... }模板生成的产物即 In.SomeTimeFrom.cs共 897 行含One至Ten十个类Seven类位于第 543–628 行。这一机制解释了 API 文档中的几个特征命名规则One内部成员用单数Second、Minute、Hour…而Two到Ten内部成员统一用复数Seconds、Days…。所以In.Seven.Days是复数形式而In.One.Day是单数形式成员覆盖面每个数量类固定拥有 7 个时间单位Second(s)、Minute(s)、Hour(s)、Day(s)、Week(s)、Month(s)、Year(s)× 2属性 *From方法 14 个成员In.Seven文档页的 7 属性 7 方法正对应这个矩阵In部分类的另一半是月份 APIIn.January、In.July等见 In.Months.cs与In.TheYear(int)返回指定年份的 1 月 1 日见 In.cs与数量类共同构成完整的In命名空间。理解这一点的实用价值在于当你在 IDE 中跳转到定义时看到的就是生成文件而非手写代码如果未来需要为所有数量类统一修改行为比如换成AddDays(49)以外的周换算修改点在 T4 模板而不是十个类。五、实战用法与注意事项典型调用场景结合文档 fluent-dates-and-time-spans.mdx 对 Fluent Date 场景的描述In.Seven最常见的用法是作为目标日期参与相对时间人性化using Humanizer; // 从现在起 7 天随后用 TimeSpanHumanize 得到 in 7 days 之类的可读文本 DateTime deadline In.Seven.Days; string display deadline.TimeSpanHumanize(); // 以任意日期为基准从 2009 年 1 月 21 日起 7 周 DateTime baseDate On.January.The21st; DateTime target In.Seven.WeeksFrom(baseDate); // baseDate.AddDays(49)这里的相对时间展示能力来自In.Seven产出的DateTime与 DateHumanizeExtensions.cs 提供的人性化扩展方法组合两者各司其职前者负责算出目标时刻后者负责把两个时刻的差距说成人话。需要注意的三个边界UTC 语义如前所述属性基于DateTime.UtcNow。跨时区展示时请显式转换例如对结果调用.ToLocalTime()而不是改用DateTime.Now自行重算。AddMonths/AddYears 的月末钳位In.Seven.Months底层是AddMonths(7)遵循 BCL 规则——若基准日是月末如 1 月 31 日加 7 个月会钳位到目标月的最后一天8 月 31 日。这是 BCL 固有行为In.Seven未做特殊处理。属性非缓存值In.Seven.XXX每次访问都重新求值。若一个业务流程中多处需要同一个 7 天后时刻应当只访问一次并保存到局部变量避免多处求值产生不一致。六、相关文档与源码路径索引本文对应的版本化 API 文档Humanizer.In.Seven.md当前版本的同名 API 文档Humanizer.In.Seven.md手写入口与TheYearIn.cs模板生成的数量类One–TenIn.SomeTimeFrom.csT4 生成模板In.SomeTimeFrom.tt行为验证测试InTests.cs同系列兄弟类文档One/Two/…/Ten各有独立的 API 文档页如 Humanizer.In.md 所在的 api 目录结构与本文一致可对照查阅赞分享开发工具【免费下载链接】HumanizerHumanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities项目地址https://gitcode.com/gh_mirrors/hu/Humanizer点击查看免费下载相关推荐Census Reporter响应式设计揭秘从桌面到移动设备的无缝体验Census Reporter响应式设计揭秘从桌面到移动设备的无缝体验 Census Reporter是一款由Knight News Challenge资助的开发工具Humanizer 流式日期 API 详解In.Seven 的 7 个时间单位属性与方法Humanizer 流式日期 API 详解In.Seven 的 7 个时间单位属性与方法 本篇技术指南围绕 Humanizer 流式日期FluentDate开发工具Humanizer In.Four 完整指南用流式 API 计算从现在起 4 秒/分钟/小时/天/周/月/年的日期Humanizer In.Four 完整指南用流式 API 计算从现在起 4 秒/分钟/小时/天/周/月/年的日期 In.Four 是 Humanizer开发工具上一篇Immutables 与反应式编程RxJava2 和 Reactor 集成方案下一篇如何为Rust Lambda函数添加分布式追踪OpenTelemetry集成终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考