工作日历落库：用day_detail表替代考勤硬编码

简介：一份面向Java后端开发者的轻量级示例代码，聚焦年度日历数据的生成与持久化：按日期逐天判定工作日、周末与法定节假日，并将结果写入数据库表，适合需要排班、考勤、工期计算或业务日历初始化的项目参考。压缩包为7z格式，仅含1个Java源文件，体积约2KB，以单类形式集中呈现日期遍历、节假日判断、表结构字段设计、JDBC连接与批量插入、事务回滚等关键环节，结构紧凑，便于直接阅读和嵌入现有工程。目前已有3741人学习。读者可从中了解java.time中LocalDate与DayOfWeek的用法、节假日规则的接入方式、工作日/周末/节假日多标识字段的建表思路，以及批量提交与异常处理的取舍，并据此扩展闰年、调休等边界场景，改造成符合自身业务的数据初始化工具。

1. 为什么把工作日历落库：一张 day_detail 表替掉满屏 if-else

每年放假安排一公布，考勤系统就得跟着改一遍：调休补班的周末被算成休息、连休里夹着的那两天被当成全勤，结算出来的天数差一天，排查起来能耗掉半天。这个 Java 项目干的事很朴素——把一年 365 或 366 天的日期、星期、日类型（工作日 / 周末 / 法定节假日 / 调休补班）、节日名称，逐条写进数据库表，让「今天是不是工作日」变成一次走唯一索引的查询，而不是散落在各个 Service 里的 if-else。

适合的人群很明确：做考勤打卡、排班轮值、请假额度、工单 SLA 计时、结算周期计算的后端同学。节假日和周末的判定规则一年动一次，但每次动都要翻代码改常量，血泪经验就是这种硬编码的日期判断最难维护。落库之后，业务侧只认一张表，规则变了改数据不改代码，历史年份也留得下证据，回头查「去年 10 月 8 号到底算不算上班」时不用再翻聊天记录。

2. 表结构与工程分层：day_detail 一年 366 行怎么设计才够用

2.1 字段设计与索引取舍

一年最多 366 行，十年也才三千多行，这个数据量小到几乎不用考虑分库分表，但字段类型和索引选错，后面统计和工作日推算会一路难受。我把日期存成DATE而不是DATETIME，把日类型存成TINYINT而不是VARCHAR，把「是否工作日」单独冗余一列，这三条是这张表的地基。

CREATE TABLE day_detail ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键', calendar_date DATE NOT NULL COMMENT '日历日期，只到天', year SMALLINT NOT NULL COMMENT '年份，冗余便于按年清理与筛选', month TINYINT NOT NULL COMMENT '月份 1-12', day_of_month TINYINT NOT NULL COMMENT '当月第几天', day_of_week TINYINT NOT NULL COMMENT '1=周一 ... 7=周日', day_type TINYINT NOT NULL COMMENT '1 工作日 2 周末 3 法定节假日 4 调休补班', is_workday TINYINT NOT NULL COMMENT '1 上班 0 休息，统计专用冗余列', holiday_name VARCHAR(32) DEFAULT NULL COMMENT '节日名称，如春节、国庆', remark VARCHAR(128) DEFAULT NULL COMMENT '备注，人工调整原因写这里', create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_date (calendar_date), KEY idx_year_workday (year, is_workday), KEY idx_workday_date (is_workday, calendar_date) ) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT ='年度工作日历明细';

uk_date是整张表的幂等基石，批量写入走ON DUPLICATE KEY UPDATE，重复执行不会产生第二条 2025-01-01。idx_year_workday服务「今年一共多少个工作日」这类按年聚合，idx_workday_date服务「从某天往后找第 N 个工作日」这类范围扫描，两个索引覆盖了 90% 的查询场景。

is_workday这个冗余列值得单独说一句。day_type已经能推出是否上班（1 和 4 是上班，2 和 3 是休息），但业务 SQL 里到处写day_type in (1,4)迟早会漏掉一个分支。冗余一列is_workday，统计语句就变成where is_workday = 1，简单到不会写错，代价只是生成时多赋一次值。

2.2 模块分层：生成器、规则源、仓储

代码结构上，我不太喜欢把「日期推算」和「写库」揉在一个类里。分三层：规则源负责回答「这一年哪些日子是法定节假日、哪些周末要补班」，生成器负责把规则铺平成 366 条明细，仓储只管批量落库。中间用一层纯 POJO 传递，生成器完全不碰 SQL，测试时可以拿一个内存版规则源跑，几毫秒就验完一整年。

src/main/java/com/example/calendar ├── controller │ └── DayDetailController.java # 初始化、查询、统计接口 ├── service │ ├── DayDetailGenerator.java # 逐日打标，核心逻辑 │ └── WorkdayQueryService.java # 工作日统计与推算 ├── rule │ ├── HolidayRule.java # 一年规则的载体 │ ├── HolidayRuleProvider.java # 规则来源接口 │ └── DbHolidayRuleProvider.java # 从 holiday_rule 表读取实现 ├── mapper │ └── DayDetailMapper.java # 批量 upsert + 统计查询 ├── entity │ └── DayDetail.java └── enums └── DayType.java

HolidayRuleProvider做成接口是刻意的。开发初期规则可以来自一份 JSON 配置，上线后切到数据库表，将来接了外部接口再换实现，生成器一行都不用动。这种「先跑通再换源」的做法在小工具类项目里很省事，不用一开始就把规则管理后台做完。

public interface HolidayRuleProvider { /** 加载指定年份的节假日与调休规则 */ HolidayRule load(int year); } @Data public class HolidayRule { private int year; /** 法定节假日日期集合 */ private Set<LocalDate> holidays = new HashSet<>(); /** 调休补班日期集合，即被调成上班的周末 */ private Set<LocalDate> makeups = new HashSet<>(); /** 日期 -> 节日名称，用于展示 */ private Map<LocalDate, String> names = new HashMap<>(); }

load(year)只接收年份，内部去查该年的规则记录。这里有个隐含约定：规则本身必须是「日期绝对集合」，不能是「某月某日 + 偏移量」这种相对描述。相对描述在跨年补班时会翻车，比如元旦假期从上一年 12 月 30 日开始，用月份日号去拼就会丢失边界。

3. 生成主流程：从 1 月 1 日逐日打标到 12 月 31 日

3.1 日类型枚举与实体

先定枚举。日类型就四种，不要搞出「半天班」「值班」这种业务概念，日历层只回答这一天是上班还是休息，半天班属于排班系统的事，混进来会让这张表变得不可复用。

public enum DayType { WORKDAY(1, "工作日"), WEEKEND(2, "周末"), HOLIDAY(3, "法定节假日"), MAKEUP(4, "调休补班"); private final int code; private final String label; DayType(int code, String label) { this.code = code; this.label = label; } public int code() { return code; } public String label() { return label; } /** 只有普通工作日和被调休的补班日才需要上班 */ public boolean isWorkday() { return this == WORKDAY || this == MAKEUP; } }

isWorkday()放在枚举里而不是散在业务代码里，是这类项目最常见的减错手段。将来真要加第五种类型（比如极端天气停课停工），只需要在这个方法里补一个分支，所有调用点自动生效。

实体类对应表结构，calendarDate用LocalDate，不要用java.util.Date。这一点后面避坑章节还会展开说。

@Data @TableName("day_detail") public class DayDetail { @TableId(type = IdType.AUTO) private Long id; private LocalDate calendarDate; private Integer year; private Integer month; private Integer dayOfMonth; private Integer dayOfWeek; // 1=周一 ... 7=周日 private Integer dayType; // 对应 DayType.code() private Integer isWorkday; // 1 上班 0 休息 private String holidayName; private String remark; private LocalDateTime createTime; private LocalDateTime updateTime; }

3.2 逐日归类：优先级顺序是关键

归类的核心是判断顺序，顺序错了结果就错。正确顺序是：调休补班 → 法定节假日 → 周末 → 普通工作日。原因很直接——补班日通常落在周六周日，必须先于周末判定；法定节假日也可能落在周末，必须先于周末判定。如果先判周末，2025 年那些被调成上班的周六就永远进不了MAKEUP分支。

private DayDetail classify(LocalDate date, HolidayRule rule) { DayDetail d = new DayDetail(); d.setCalendarDate(date); d.setYear(date.getYear()); d.setMonth(date.getMonthValue()); d.setDayOfMonth(date.getDayOfMonth()); d.setDayOfWeek(date.getDayOfWeek().getValue()); // 1=周一 ... 7=周日 DayType type; if (rule.getMakeups().contains(date)) { // 优先级最高：被调成上班的周末 type = DayType.MAKEUP; d.setRemark("调休补班"); } else if (rule.getHolidays().contains(date)) { type = DayType.HOLIDAY; d.setHolidayName(rule.getNames().getOrDefault(date, "法定节假日")); } else if (date.getDayOfWeek().getValue() >= 6) { // 6=周六 7=周日 type = DayType.WEEKEND; } else { type = DayType.WORKDAY; } d.setDayType(type.code()); d.setIsWorkday(type.isWorkday() ? 1 : 0); return d; }

这段代码没有一行数据库操作，纯函数式的，输入日期和规则，输出一条明细。这种写法最大的好处是可测：拿 2025 年的规则丢进去，断言 1 月 1 日是HOLIDAY、某个被调休的周六是MAKEUP、3 月某个周三是WORKDAY，三条断言就能挡住绝大多数回归问题。

date.getDayOfWeek().getValue()的返回值是 1 到 7 对应周一到周日，这是java.time的固定约定，别用Calendar.DAY_OF_WEEK，那个是周日等于 1，混用必翻车。

3.3 主线跑通：Service 层事务与分批写入

生成器把 366 条明细铺出来之后，一次性塞进一条INSERT会有风险——SQL 文本长度可能超过max_allowed_packet，尤其是带节日名称和备注的时候。按 500 条一批切分，既控制了单条 SQL 体积，也让事务回滚的粒度更合理。

@Service public class DayDetailGenerator { private static final int BATCH_SIZE = 500; @Resource private DayDetailMapper dayDetailMapper; @Resource private HolidayRuleProvider ruleProvider; @Transactional(rollbackFor = Exception.class) public int generate(int year) { // 前后各扩 7 天，兜住跨年假期（如元旦从上一年 12 月底开始） LocalDate start = LocalDate.of(year, 1, 1).minusDays(7); LocalDate end = LocalDate.of(year, 12, 31).plusDays(7); HolidayRule rule = ruleProvider.load(year); List<DayDetail> rows = new ArrayList<>(380); for (LocalDate d = start; !d.isAfter(end); d = d.plusDays(1)) { rows.add(classify(d, rule)); } int affected = 0; for (int i = 0; i < rows.size(); i += BATCH_SIZE) { int to = Math.min(i + BATCH_SIZE, rows.size()); affected += dayDetailMapper.batchUpsert(rows.subList(i, to)); } return affected; } }

参数说明：year是目标年份，传 2025 就生成 2025 全年加前后各 7 天的缓冲数据；BATCH_SIZE取 500 是在 MySQL 默认max_allowed_packet4MB 下比较安全的经验值，如果节日名称字段比较长，降到 200 也可以。循环条件用!d.isAfter(end)而不是d.isBefore(end)，是为了把 12 月 31 日也包含进来——这个边界我在第一次写的时候就写错了，统计出来每年少一天。

对应的 Mapper XML 用ON DUPLICATE KEY UPDATE实现幂等写入，重复执行只会更新不会新增：

<insert id="batchUpsert"> INSERT INTO day_detail (calendar_date, year, month, day_of_month, day_of_week, day_type, is_workday, holiday_name, remark) VALUES <foreach collection="list" item="it" separator=","> (#{it.calendarDate}, #{it.year}, #{it.month}, #{it.dayOfMonth}, #{it.dayOfWeek}, #{it.dayType}, #{it.isWorkday}, #{it.holidayName}, #{it.remark}) </foreach> ON DUPLICATE KEY UPDATE day_type = VALUES(day_type), is_workday = VALUES(is_workday), holiday_name = VALUES(holiday_name), remark = VALUES(remark) </insert>

注意这里更新了remark，意味着重新跑批会覆盖掉人工填写的备注。如果业务上需要保留人工调整痕迹，就得在表里加一个manual_locked标记，更新时加AND manual_locked = 0条件，这个改造放到最后一章细说。

4. 规则来源与日期换算：法定节假日、调休补班的数据从哪来

4.1 规则表与人工确认闭环

节假日安排每年由相关部门公布一次，公布时间通常在上一年的年底。这意味着程序不可能「算」出明年的安排，只能「录」进去。所以规则源必须是可编辑的数据，不是代码里的常量数组。

我一般会建一张配套的规则表：

CREATE TABLE holiday_rule ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, rule_year SMALLINT NOT NULL COMMENT '规则所属年份', calendar_date DATE NOT NULL COMMENT '具体日期', rule_type TINYINT NOT NULL COMMENT '3 法定节假日 4 调休补班', holiday_name VARCHAR(32) DEFAULT NULL COMMENT '节日名称', PRIMARY KEY (id), UNIQUE KEY uk_year_date (rule_year, calendar_date) ) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT ='节假日与调休规则';

DbHolidayRuleProvider按rule_year查出所有记录，按rule_type分到holidays和makeups两个集合里，节日名称填进names。整个 Provider 不到三十行，但它是整条链路的「真相来源」，规则表填错了，后面生成 366 条数据全是错的。

工程上我习惯加一道保险：生成之前先做一次规则自检，检查三件事——同一日期不能既在节假日集合又在补班集合；补班日期必须是周六或周日（否则大概率录错了）；节假日集合里连续区间的长度和名称是否合理。这些校验不写死规则，只做逻辑冲突检测，发现异常直接抛异常阻断跑批，比生成完再回头查数据库强得多。

public void validate(HolidayRule rule) { Set<LocalDate> conflict = new HashSet<>(rule.getHolidays()); conflict.retainAll(rule.getMakeups()); if (!conflict.isEmpty()) { throw new IllegalStateException("日期同时被标记为节假日与补班日: " + conflict); } for (LocalDate d : rule.getMakeups()) { if (d.getDayOfWeek().getValue() < 6) { throw new IllegalStateException("补班日不在周末，请核对: " + d); } } }

这三条校验拦下的问题，比事后核对整年数据省事得多。特别是第二条，录数据时手滑把周三录成补班日，跑批前就能炸出来。

4.2 清明与农历节日的预填

规则靠人工录，但录入界面可以给「建议值」降低工作量。公历固定的元旦、劳动节、国庆不需要算，农历的春节、端午、中秋需要农历转换，清明则是节气——它既不是公历固定日也不是农历固定日，但在公历上的分布很窄，通常落在 4 月 4 日到 4 月 6 日之间。

清明的日期有个流传很广的近似公式，在 2000 到 2099 年区间内足够用：

/** 清明日期估算，仅用于录入界面的默认值，最终以人工确认为准 */ public LocalDate qingming(int year) { int y = year % 100; double c = (year >= 2000 && year <= 2099) ? 4.81 : 5.59; int day = (int) Math.floor(y * 0.2422 + c) - (int) Math.floor(y / 4.0); return LocalDate.of(year, 4, day); }

这段代码给出的是「建议值」而不是「权威值」。2024 年算出来是 4 月 4 日，2025 年也是 4 月 4 日，2023 年是 4 月 5 日，和实际公布一致，但它本质上是个拟合公式，遇到特殊年份仍可能偏一天。所以我把它定位成录入表单的预填项，操作人员看到默认值后再确认提交，而不是直接写进day_detail。

春节、端午、中秋需要农历到公历的转换，工程上两条路：引一个成熟的农历工具包，或者自己维护一张农历年转换表。我一般倾向前者，农历换算涉及闰月、大小月，自己写容易在闰月年份出问题。无论哪条路，转换结果都走同一条人工确认流程——工具算初值，人确认终值，这样即使工具在某一年多算了一天，也不会直接污染数据库。

4.3 查询侧：区间工作日天数与第 N 个工作日

数据落库之后，查询侧就变得很轻松。最常用的两个场景：统计某区间内的工作日天数，以及从某天开始往后推第 N 个工作日。

/** 统计闭区间 [start, end] 内的工作日天数 */ public long countWorkday(LocalDate start, LocalDate end) { return dayDetailMapper.selectCount(Wrappers.<DayDetail>lambdaQuery() .between(DayDetail::getCalendarDate, start, end) .eq(DayDetail::getIsWorkday, 1)); } /** 从 start 之后（不含 start）找第 n 个工作日 */ public LocalDate nthWorkdayAfter(LocalDate start, int n) { List<LocalDate> list = dayDetailMapper.selectWorkdayDatesAfter(start, n); if (list.size() < n) { throw new IllegalStateException("日历数据不足，请先初始化 " + start.getYear() + " 年之后的数据"); } return list.get(n - 1); }

nthWorkdayAfter对应的 SQL 走idx_workday_date索引：

SELECT calendar_date FROM day_detail WHERE is_workday = 1 AND calendar_date > #{start} ORDER BY calendar_date LIMIT #{n};

这里有个容易忽略的细节：LIMIT #{n}拿到的第 n 条就是目标日期，但如果目标日期跨到了还没初始化的年份，查出来的条数会少于 n，必须显式报错而不是返回 null。我见过有项目在这里默默返回 null，结果请假单的到期日变成空值，一路传到结算模块才炸，排查成本极高。

5. 避坑与排查：五个让日历数据返工的细节

5.1 数据层三个坑

坑一：日期字段用 DATETIME，跨时区少一天。现象是数据库里明明写的 2025-01-01，接口返回变成 2024-12-31 23:00:00 转出来的日期。原因是实体用了java.util.Date，JDBC 驱动按服务器时区做转换，应用和数据库不在同一时区时就会偏移。解决办法是把字段类型定成DATE、实体用LocalDate、连接串显式写serverTimezone=Asia/Shanghai，三件套缺一不可。这类问题在本地开发环境永远复现不了，一上测试环境就翻车。

坑二：重复跑批覆盖人工修正。现象是运营在页面上把某个日期改成「补班」，第二天定时任务重新生成，改动没了。原因是ON DUPLICATE KEY UPDATE无条件覆盖所有字段。解决办法是在表里加manual_locked TINYINT DEFAULT 0，人工修改时置 1，批量 SQL 的 UPDATE 子句加上day_type = IF(manual_locked = 1, day_type, VALUES(day_type))，把「机器生成」和「人工确认」这两类数据分开对待。

坑三：批量插入 SQL 过长导致整批失败。现象是初始化跑到一半报Packet for query is too large，前 500 条进去了后 500 条没进去，数据处于半成品状态。原因是单条INSERT拼了太多 value，超过了max_allowed_packet。解决办法是把批大小从 500 降到 200，或者干脆改用JdbcTemplate.batchUpdate走 JDBC 批量协议。同时把整个生成过程包在一个事务里，失败就整体回滚，不要留下半年的数据。

还有个小坑值得提：MySQL 8.0.20 之后VALUES()函数被标记为废弃，虽然还能用但会打警告。新项目可以直接用别名写法INSERT INTO ... AS new ON DUPLICATE KEY UPDATE day_type = new.day_type，老项目升级时注意这个语法差异。

5.2 时间与跑批两个坑

坑四：跨年假期被自然年切成两半。现象是元旦假期从上一年 12 月 30 日开始，生成 2025 年数据时，12 月 30 日和 31 日不在 2025 年的循环范围里，导致 2025 年 1 月 1 日前面的两天是空的，查「连续休息天数」时断掉。原因就是按LocalDate.of(year,1,1)到LocalDate.of(year,12,31)生成。解决办法是生成范围前后各扩 7 天，或者干脆提供一个generateRange(start, end)方法按区间生成，年份只作为默认参数。扩 7 天这个做法简单，但要注意扩出来的行year字段是上一年，按年清理数据时别把它们误删。

坑五：星期编号搞反、闰年漏 2 月 29 日。现象是周六被标成工作日，或者 2024 年生成出来只有 365 条。原因是混用了Calendar.DAY_OF_WEEK（周日=1）和DayOfWeek.getValue()（周一=1），以及循环边界写成了d.isBefore(end)。解决办法是统一用java.time的编号约定并在枚举或常量里注释清楚，同时补两条单元测试：断言 2024 年生成结果包含 2 月 29 日、断言某个已知周六的dayOfWeek等于 6。这两条测试写起来三十秒，能挡住后面无数次改动引入的回归。

排查这类问题时，我习惯先跑一条 SQL 看数据分布：

SELECT year, day_type, COUNT(*) AS cnt FROM day_detail GROUP BY year, day_type ORDER BY year, day_type;

正常年份的分布大概是：工作日 240 多天，周末 100 天出头，法定节假日 10 到 15 天，调休补班 5 到 10 天，四类加起来应该正好等于该年的天数。哪一类明显偏离这个量级，问题基本就定位到那个分支了。

6. 二次开发：把日历表接进排班、请假与结算链路

日历表本身只是个基础设施，真正的价值在于被别的模块依赖。二次开发时最值得先做的是给日类型加一个业务权重字段，让不同模块自己决定怎么用。

加权重字段是最小改动、最大收益的一项。比如结算模块需要按日类型给不同系数，与其在业务代码里写if (dayType == HOLIDAY) ...，不如让日历表直接给出weight，业务侧只做乘法。

第二个值得做的是工作日推算。原始实现是循环里逐日查库，取第 N 个工作日就要查 N 次，排班场景下一天几百次调用会把数据库打满。改进思路是一次性把区间内的工作日日期捞进内存再滚动：

/** 从 start 起算，向后推 n 个工作日；n 为负则向前推 */ public LocalDate plusWorkdays(LocalDate start, int n) { if (n == 0) { return start; } int step = n > 0 ? 1 : -1; int remain = Math.abs(n); LocalDate cursor = start; // 一次性取足够宽的区间，避免逐日查库 LocalDate bound = start.plusDays(step * (int) Math.ceil(remain * 2.0) + 60); List<LocalDate> workdays = dayDetailMapper.selectWorkdayBetween( step > 0 ? start : bound, step > 0 ? bound : start); for (LocalDate d : step > 0 ? workdays : workdays.reversed()) { if (step > 0 ? d.isAfter(start) : d.isBefore(start)) { if (--remain == 0) { return d; } } } throw new IllegalStateException("推算范围超出已初始化的日历数据: " + start + " n=" + n); }

区间宽度的算法是「目标工作日数 × 2 + 60 天」，一年最多 250 个工作日，所以 60 天的缓冲足够跨过春节这种长假期；真遇到超出边界的情况会抛异常，提示去初始化下一年数据，而不是悄悄返回错误日期。这个异常我宁可让它抛出来，也不要它变成一个看起来正常但错了一天的结算结果。

最后一个技巧是给日历数据加一个「健康检查」定时任务，每月跑一次，检查当年和下一年的数据是否齐全、每天是否唯一、日类型分布是否合理。我从被跨年假期坑过一次之后，每次上线新的日历年度都强制走一遍这个检查再放行——毕竟这种基础数据出错，影响的是整条结算链路上的每一张单子，事后补数据的成本远高于事前多看一眼。

希望帮到你。

本文还有配套的精品资源，点击获取