## 📋 目录

- 一、工具类功能
- 二、所需环境
- 三、方法与调用示例（按需调用）
- 四、工具类源码（可直接复制）

## 一、工具类功能

把一个日期摊成它所在的自然周期闭区间：周（周一起始，不随服务器区域变）、月、季、年，再判断相差几天、有没有交集、某天落不落在区间里，结果统一是不可变 record。

## 二、所需环境

JDK 17或以上

## 三、方法与调用示例（按需调用）

🔢 **方法序号**：1

🎯 **方法用途**：
- 手工装配一个闭区间，起止两端都含在区间内
- 周期不是自然周月季年时（自定义活动期），用构造器直接给两端

🧩 **方法定义**：`public record DateRange(LocalDate start, LocalDate end)`

🗣️ **入参解释**：`public record DateRange(起始日期, 结束日期)`

📤 **返回值解释**：`DateRange`，不可变的闭区间记录

💡 **边界口径**：
- 紧凑构造器保证两端非空且起始不晚于结束，非法区间在构造点就失败
- 端点为 null 抛 `NullPointerException`，区间倒序抛 `IllegalArgumentException`
- 是 record，同起止的两份区间 `equals` 相等，可以直接进 Set 与 Map key
- 判断方法里不再逐字段防御，拿到对象就假定它合法

🧪 **方法示例**：
- `new DateRange(LocalDate.of(2026, 10, 1), LocalDate.of(2026, 10, 31))` 拿到 `DateRange[start=2026-10-01, end=2026-10-31]`
- 同起止再构造一份比相等，拿到 `true`
- 起止写反抛 `起始日期不能晚于结束日期: start=2026-11-01, end=2026-10-01`
- 结束端传 null 抛 `end 不能为null`

---

🔢 **方法序号**：2

🎯 **方法用途**：
- 取某个日期所在周的闭区间，固定周一起始、周日结束
- 周报表、按周归档这类要把日期归到自然周的场合用

🧩 **方法定义**：`public static DateRange weekOf(LocalDate date)`

🗣️ **入参解释**：`public static DateRange weekOf(任意日期)`

📤 **返回值解释**：`DateRange`，该日期所在周的周一到周日

💡 **边界口径**：
- 周起始日与 JVM 默认 `Locale` 无关，区域换成美国仍然是周一起始
- 跨月的那一周按所在日期归属，允许横跨两个自然月，区间恒为 7 天
- 以传入日期为准，不读服务器时钟
- `date` 传 null 抛 `IllegalArgumentException`

🧪 **方法示例**：
- `weekOf(LocalDate.of(2026, 10, 5))` 拿到 `DateRange[start=2026-10-05, end=2026-10-11]`，跨度 7 天
- `weekOf(LocalDate.of(2026, 10, 31))` 拿到 `DateRange[start=2026-10-26, end=2026-11-01]`，横跨两个自然月
- `weekOf(null)` 抛 `date 不能为null`

---

🔢 **方法序号**：3

🎯 **方法用途**：
- 取某个日期所在自然月的第一天到最后一天
- 月度结算、账单周期这类按自然月切的场景用

🧩 **方法定义**：`public static DateRange monthOf(LocalDate date)`

🗣️ **入参解释**：`public static DateRange monthOf(任意日期)`

📤 **返回值解释**：`DateRange`，该月首日到该月末日

💡 **边界口径**：
- 月末按真实天数收口，闰年 2 月到 29 日、平年到 28 日
- 与周不同，月区间不跨月，天数在 28 到 31 之间
- `date` 传 null 抛 `IllegalArgumentException`

🧪 **方法示例**：
- `monthOf(LocalDate.of(2026, 10, 5))` 拿到 `DateRange[start=2026-10-01, end=2026-10-31]`，含端点共 31 天
- 闰年 `monthOf(LocalDate.of(2024, 2, 14))` 拿到 `DateRange[start=2024-02-01, end=2024-02-29]`
- 平年 `monthOf(LocalDate.of(2023, 2, 10))` 拿到 `DateRange[start=2023-02-01, end=2023-02-28]`

---

🔢 **方法序号**：4

🎯 **方法用途**：
- 取某个日期所在季度的第一天到最后一天
- 季度考核、财报口径按 1-3、4-6、7-9、10-12 月划分时用

🧩 **方法定义**：`public static DateRange quarterOf(LocalDate date)`

🗣️ **入参解释**：`public static DateRange quarterOf(任意日期)`

📤 **返回值解释**：`DateRange`，该季度首日与末日

💡 **边界口径**：
- 季度划分是自然季，不看财年，也不读任何日历配置
- 季末按所在月份的最后一天收口，闰年二月也不改变 Q1 末日是 3 月 31 日
- `date` 传 null 抛 `IllegalArgumentException`

🧪 **方法示例**：
- `quarterOf(LocalDate.of(2026, 10, 5))` 拿到 `DateRange[start=2026-10-01, end=2026-12-31]`
- `quarterOf(LocalDate.of(2024, 11, 20))` 拿到 `DateRange[start=2024-10-01, end=2024-12-31]`，季末按月末日收口
- `quarterOf(LocalDate.of(2026, 2, 1))` 拿到 `DateRange[start=2026-01-01, end=2026-03-31]`

---

🔢 **方法序号**：5

🎯 **方法用途**：
- 取某个日期所在自然年的 1 月 1 日到 12 月 31 日
- 年度汇总、年度配额重置这类按自然年算的场合用

🧩 **方法定义**：`public static DateRange yearOf(LocalDate date)`

🗣️ **入参解释**：`public static DateRange yearOf(任意日期)`

📤 **返回值解释**：`DateRange`，该年首日与末日

💡 **边界口径**：
- 只认自然年，财年口径要自己算好月份再调 `new DateRange`
- 平年 365 天、闰年 366 天，由 `LocalDate` 决定
- `date` 传 null 抛 `IllegalArgumentException`

🧪 **方法示例**：
- `yearOf(LocalDate.of(2026, 10, 5))` 拿到 `DateRange[start=2026-01-01, end=2026-12-31]`

---

🔢 **方法序号**：6

🎯 **方法用途**：
- 取当天的单日元区间，起止是同一天
- 「只看今天」的筛选条件、日报口径用它

🧩 **方法定义**：`public static DateRange today()`

🗣️ **入参解释**：`public static DateRange today()`（无入参）

📤 **返回值解释**：`DateRange`，起止都为今天的单日区间

💡 **边界口径**：
- 日期取 JVM 默认时区的当天，跨时区业务请自己算好日期再用 `yearOf` 这类显式入口
- 区间跨度为 0 天，`daysBetween` 两端相减得 0
- 每日零点后结果自然翻天，不缓存旧值

🧪 **方法示例**：
- `today()` 拿到 `DateRange[start=2026-10-13, end=2026-10-13]`

---

🔢 **方法序号**：7

🎯 **方法用途**：
- 取本周（周一到周日）的闭区间
- 周报表、周汇总这类以「本周」为口径的查询条件用它

🧩 **方法定义**：`public static DateRange thisWeek()`

🗣️ **入参解释**：`public static DateRange thisWeek()`（无入参）

📤 **返回值解释**：`DateRange`，本周周一与本周周日

💡 **边界口径**：
- 等价于 `weekOf(LocalDate.now())`，同样恒 7 天、周一起始
- 取的是 JVM 默认时区的当天再归到周，跨零点调用结果会不同
- 判断日期在不在本周内直接配 `contains`，别自己比字符串

🧪 **方法示例**：
- `thisWeek()` 拿到 `DateRange[start=2026-10-12, end=2026-10-18]`
- `contains(thisWeek(), LocalDate.now())` 拿到 `true`

---

🔢 **方法序号**：8

🎯 **方法用途**：
- 取本月的第一天到最后一天
- 月度账单、当月统计的默认时间范围用它

🧩 **方法定义**：`public static DateRange thisMonth()`

🗣️ **入参解释**：`public static DateRange thisMonth()`（无入参）

📤 **返回值解释**：`DateRange`，本月首日与末日

💡 **边界口径**：
- 等价于 `monthOf(LocalDate.now())`，月末按真实天数收口
- 月初月末跨月查询要各自取，别用同一个实例缓存两个月
- 时区口径同 `today()`

🧪 **方法示例**：
- `thisMonth()` 拿到 `DateRange[start=2026-10-01, end=2026-10-31]`

---

🔢 **方法序号**：9

🎯 **方法用途**：
- 取本季度的第一天到最后一天
- 季度 OKR、财报区间默认值这类需求用它

🧩 **方法定义**：`public static DateRange thisQuarter()`

🗣️ **入参解释**：`public static DateRange thisQuarter()`（无入参）

📤 **返回值解释**：`DateRange`，本季首日与末日

💡 **边界口径**：
- 等价于 `quarterOf(LocalDate.now())`，按 1-3、4-6、7-9、10-12 月划分
- 季度末不随服务器区域变化
- 要上一季或下一季，自己拿日期加减月份再调 `quarterOf`

🧪 **方法示例**：
- `thisQuarter()` 拿到 `DateRange[start=2026-10-01, end=2026-12-31]`

---

🔢 **方法序号**：10

🎯 **方法用途**：
- 取本年的 1 月 1 日到 12 月 31 日
- 年度累计、年度配额的默认时间窗用它

🧩 **方法定义**：`public static DateRange thisYear()`

🗣️ **入参解释**：`public static DateRange thisYear()`（无入参）

📤 **返回值解释**：`DateRange`，本年首日与末日

💡 **边界口径**：
- 等价于 `yearOf(LocalDate.now())`
- 跨年任务要注意调用时刻，年底最后一天与年初第一天取到的是两个不同区间
- 服务器时区不是本地时区时，日期归属可能差一天

🧪 **方法示例**：
- `thisYear()` 拿到 `DateRange[start=2026-01-01, end=2026-12-31]`

---

🔢 **方法序号**：11

🎯 **方法用途**：
- 算两个日期相差多少天，按「结束减开始」计，带符号
- 计算工期、账龄、逾期天数这类要看方向的日子差用它

🧩 **方法定义**：`public static long daysBetween(LocalDate start, LocalDate end)`

🗣️ **入参解释**：`public static long daysBetween(开始日期, 结束日期)`

📤 **返回值解释**：`long`，结束与开始之间的天数，可为负

💡 **边界口径**：
- 同一天得 0，结束早于开始得负数，不取绝对值
- 算的是日历天差，不是工作日差，含节假日
- 参数为 null 抛 `IllegalArgumentException`，消息点出参数名

🧪 **方法示例**：
- `daysBetween(LocalDate.of(2026, 10, 1), LocalDate.of(2026, 11, 1))` 拿到 `31 天`
- 两个参数对调拿到 `-31`
- 同一天 `daysBetween(date, date)` 拿到 `0 天`

---

🔢 **方法序号**：12

🎯 **方法用途**：
- 判断两个区间有没有公共日期，端点相接也算重叠
- 排期冲突、优惠期撞车这类「能不能同时生效」的判断用它

🧩 **方法定义**：`public static boolean overlaps(DateRange r1, DateRange r2)`

🗣️ **入参解释**：`public static boolean overlaps(区间一, 区间二)`

📤 **返回值解释**：`boolean`，有公共日期返回 `true`

💡 **边界口径**：
- 闭区间口径：只共享一个端点（10-31 与 10-31）也算重叠
- 相邻但不共点的两段（10 月与 11 月）判为不重叠
- 结果对称，交换两个入参结论一致
- 任一区间为 null 抛 `IllegalArgumentException`，消息点出是 r1 还是 r2

🧪 **方法示例**：
- 相邻但不共点的两个月区间做 `overlaps(r1, r2)` 拿到 `false`
- 端点相接的两个季度 `overlaps(q1, touching)` 拿到 `true`，相接点是 `2026-03-31` 与 `2026-03-31`
- 包含关系与跨区间重叠都拿到 `true`，交换两个入参结论一致
- 第二个区间传 null 抛 `r2 不能为null`

---

🔢 **方法序号**：13

🎯 **方法用途**：
- 判断某个日期是否落在闭区间内，两个端点都算在内
- 活动是否在进行中、生日是否在查询区间里这类判定用它

🧩 **方法定义**：`public static boolean contains(DateRange range, LocalDate date)`

🗣️ **入参解释**：`public static boolean contains(区间, 日期)`

📤 **返回值解释**：`boolean`，日期落在区间内返回 `true`

💡 **边界口径**：
- 闭区间判定，起止两端那天都算命中
- 出界一天就返回 `false`，不做容差
- 区间由构造器保证合法，这里不再判起止顺序
- 参数为 null 抛 `IllegalArgumentException`

🧪 **方法示例**：
- 起止两端分别 `contains(range, date)` 都拿到 `true`
- 出界一天拿到 `false`
- `contains(weekOf(date), date)` 拿到 `true`，基准日必在自己那周里

## 四、工具类源码（可直接复制）

📦 见评论区或本专栏简介



把一个日期摊成它所在的自然周期闭区间：周（周一起始，不随服务器区域变）、月、季、年，再判断相差几天、有没有交集、某天落不落在区间里，结果统一是不可变 record。

13个方法搞定日期区间，周一起始不随服务器时区变

编程语言

后端

开发工具

JDK17日期工具类，提供周/月/季/年自然周期区间计算、区间重叠判断、天数差计算等13个方法，支持自定义闭区间构造，自动处理闰年与跨月周边界，代码可直接复制使用。

服务器

让每一个 Agent，都跑在云上

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

13个方法搞定日期区间，周一起始不随服务器时区变-腾讯云开发者社区-腾讯云

13个方法搞定日期区间，周一起始不随服务器时区变

13个方法搞定日期区间，周一起始不随服务器时区变

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐