1.公历与农历互转
date-plugin 解决的是公历与农历互转的问题,比如给用户的订单时间打上"己亥年伍月壹捌"这种农历标签、做生肖营销、展示生辰八字风格的文案。纯 Java 实现,不依赖任何第三方库,也不依赖数据库——秘密在于它把农历规则编码成了两张整数表,查表即可完成互转。
本篇会先讲清楚"查表法"的实现原理,再手把手过一遍 ChineseDateTool / ChineseDateExtendTool 的用法和输出格式,最后把使用边界(支持哪些年份、闰月怎么判)交代清楚。
I. 农历互转的实现原理
农历是一套"阴阳合历"的体系,比公历麻烦得多:
- 公历一年固定 12 个月、每月天数规则简单
- 农历的每个月是 29 天(小月)或 30 天(大月),由"朔"(月相)决定,没有规律可套公式
- 闰月的位置和几年一闰也不固定,遵循"无中气置闰"的规则
- 农历正月初一对应的公历日期,每年都不同
所以 date-plugin 没有采用天文历法实时计算(那套东西的复杂度和出错率都很高),而是查表法:预先把 1887~2111 年的农历规则压缩编码,每个农历年占一个整数,共 225 项,转换时查表 + 位运算即可,快且不依赖任何外部资源。
1. 两张核心表
ChineseDateTool 里有两个关键的静态数组:
lunar_month_days:每一项对应一个农历年(下标 0 对应 1887 年),记录了这一年农历每个月的天数和闰月信息,编码规则是:
|----4位闰月|-------------13位1为30天,0为29天|
- 高 4 位:当年的闰月是农历几月(比如
0x6表示闰六月),为 0 表示当年没有闰月 - 低 13 位:从高位到低位依次表示第 1 到第 13 个月,为 1 表示 30 天的大月,为 0 表示 29 天的小月
solar_1_1:同样是每个农历年一项,编码的是"当年农历正月初一对应的公历日期":
- 12 位:公历年
- 4 位:公历月
- 5 位:公历日
2. 公历转农历
有了这两张表,公历转农历的思路就非常直白了,对应 ChineseDateTool.solarToLunar:
- 先确定目标日期落在哪个农历年:取
solar_1_1中"正月初一小于等于目标日期"的那一项 - 计算目标日期与当年正月初一之间的天数差
- 从正月开始,逐月用"该月是 30 天还是 29 天"去扣减天数差,扣不动了就说明落在了当前月
- 最后根据闰月位置做修正:如果落在闰月之后,月序号要减 1,并给
isleap标记赋值
3. 农历转公历
反过来,ChineseDateTool.lunarToSolar 就是正向累加:
- 查表拿到当年闰月位置,按"目标农历月在闰月之前还是之后"确定要累加的月序范围
- 累加前面每个月的天数(30 或 29),再加上日
- 把这个天数偏移加到"当年正月初一的公历日期"上,直接得到目标公历日期
整个转换没有任何浮点和迭代逼近,就是查表 + 位运算 + 累加,所以性能可以忽略不计。
位运算的核心是
getBitInt(data, length, shift):从整数的第shift位开始,取length位的值。两张表的编码和解析全靠它。
II. 依赖引入
项目已发布到 maven 中央仓库,直接依赖即可,请注意使用最新版本:
<!-- https://mvnrepository.com/artifact/com.github.liuyueyi.media/date-plugin -->
<dependency>
<groupId>com.github.liuyueyi.media</groupId>
<artifactId>date-plugin</artifactId>
<version>3.1.0</version>
</dependency>
gradle 用户:
// https://mvnrepository.com/artifact/com.github.liuyueyi.media/date-plugin
implementation 'com.github.liuyueyi.media:date-plugin:3.1.0'
旧版本坐标为
com.github.hui.media:date-plugin,使用旧版本时需要额外引入作者的 maven 仓库源:<repositories> <repository> <id>yihui-maven-repo</id> <url>https://raw.githubusercontent.com/liuyueyi/maven-repository/master/repository</url> </repository> </repositories>
III. 基础转换:ChineseDateTool
ChineseDateTool 提供了两个互逆的静态方法,以及两个数据载体类:
// 公历转农历
public static Lunar solarToLunar(Solar solar);
// 农历转公历
public static Solar lunarToSolar(Lunar lunar);
Solar:公历日期,三个字段solarYear、solarMonth、solarDayLunar:农历日期,四个字段lunarYear(农历年)、lunarMonth(农历月)、lunarDay(农历日)、isleap(是否闰月)
直接看可运行的测试代码(对应测试类 ChineseDateTest 里的场景):
@Test
public void testDateTool() {
// 公历 2019-06-20
ChineseDateTool.Solar solar = new ChineseDateTool.Solar(2019, 6, 20);
// 公历 -> 农历
ChineseDateTool.Lunar lunar = ChineseDateTool.solarToLunar(solar);
System.out.println(lunar);
// 输出: Lunar{isleap=false, lunarYear=2019, lunarMonth=5, lunarDay=18}
// 农历 -> 公历(可逆验证)
ChineseDateTool.Solar solar2 = ChineseDateTool.lunarToSolar(lunar);
System.out.println(solar2);
// 输出: Solar{solarYear=2019, solarMonth=6, solarDay=20}
}
即公历 2019 年 6 月 20 日对应农历 2019 年五月十八,来回转换无损。
闰月的判断会体现在 isleap 上:假设某天落在闰四月,那么返回的 Lunar 中 lunarMonth = 4、isleap = true,业务代码里可以据此给月份加"闰"前缀。
IV. 中文输出:ChineseDateExtendTool
ChineseDateTool 返回的是数字结构,直接展示给用户不友好。ChineseDateExtendTool 在它之上封装了一层中文输出,提供的方法如下:
| 方法 | 说明 | 输出示例 |
|---|---|---|
lunarYearToGanZhi(int lunarYear) | 农历年份转干支纪年 | 2019 -> 己亥年 |
lunarMonthToChinese(int month, boolean isleap) | 农历月转中文,闰月加前缀 | 5, false -> 伍月 |
lunarDayToChinese(int day) | 农历日转中文 | 18 -> 壹捌 |
hourToChinese(int hour) | 24 小时制转十二时辰 | 8 -> 辰时 |
parseLunar(Lunar) | Lunar 对象拼成中文字符串 | 己亥年伍月壹捌 |
getNowLunarDate(LocalDateTime, boolean containHour) | 指定时间转农历描述,第二个参数控制是否带时辰 | 己亥年伍月壹捌 辰时 |
getNowLunarDate() | 当前系统时间转生辰八字风格的农历描述 | 己亥年伍月壹捌 辰时 |
getLunarDateByTimestamp(long timestamp) | 毫秒时间戳转农历描述 | 己亥年伍月壹捌 辰时 |
4.1 组合方法示例
这是官方 readme 中的用例:
@Test
public void testDate2Lunar() {
LocalDateTime now = LocalDateTime.now();
System.out.println(now + ">>>" + ChineseDateExtendTool.getNowLunarDate());
System.out.println(now + ">>>" +
ChineseDateExtendTool.getLunarDateByTimestamp(now.toInstant(ZoneOffset.ofHours(8)).toEpochMilli()));
}
输出结果如下(以 2019-06-20 08:08 为例):
2019-06-20T08:08:19.758>>>己亥年伍月壹捌 辰时
2019-06-20T08:08:19.758>>>己亥年伍月壹捌 辰时
4.2 各转换规则说明
干支纪年:公式是 天干[(year-4)%10] + 地支[(year-4)%12] + "年",所以 2019 年取 (2019-4)%10 = 5 号天干"己"、(2019-4)%12 = 11 号地支"亥",即"己亥年"。因为公式里固定减 4,传入的是农历年份而不是公历年份。
农历月:1~10 月直接映射"壹月~拾月",11、12 月为"拾壹月"、"拾贰月";闰月在前面加前缀,输出形如"润肆月"(源码里的前缀字用的是"润")。
农历日:
| 农历日 | 输出 |
|---|---|
| 1~10 | 初壹 ~ 初拾 |
| 11~19 | 壹壹 ~ 壹玖 |
| 20 | 贰拾 |
| 21~29 | 贰壹 ~ 贰玖 |
| 30 | 叁拾 |
注意输出风格是大写数字直拼(如"壹捌"),不是我们日常说的"十八",这是为了贴合生辰八字/黄历的书写习惯。
十二时辰:hourToChinese(hour) 的映射关系如下(与传统的两小时一个时辰一致,23 点和 0 点都算子时):
| 时间 | 时辰 | 时间 | 时辰 |
|---|---|---|---|
| 23点 / 0点 | 子时 | 12点 | 午时 |
| 1~2点 | 丑时 | 13~14点 | 未时 |
| 3~4点 | 寅时 | 15~16点 | 申时 |
| 5~6点 | 卯时 | 17~18点 | 酉时 |
| 7~8点 | 辰时 | 19~20点 | 戌时 |
| 9~10点 | 巳时 | 21~22点 | 亥时 |
| 11点 | 午时 |
4.3 手动组装输出
如果转换和格式化想分开控制(比如只要"己亥年五月十八"、不要时辰),可以拆开用:
ChineseDateTool.Lunar lunar = ChineseDateTool.solarToLunar(new ChineseDateTool.Solar(2019, 6, 20));
// 只拼 年+月+日,不带时辰
String text = ChineseDateExtendTool.parseLunar(lunar); // 己亥年伍月壹捌
// 或者单独取干支年
String ganZhi = ChineseDateExtendTool.lunarYearToGanZhi(lunar.getLunarYear()); // 己亥年
V. 使用边界与注意点
- 支持年份范围是 1887~2111 年。查表的数组每个农历年一项,超出范围会直接数组越界,所以别拿它去算 2112 年之后的排期。
- 只做日期维度,不处理节气、干支月/干支时。
hourToChinese输出的是"地支时"(如辰时),但年只有干支年,没有干支月,严格八字起盘的场景需要更专业的库。 getLunarDateByTimestamp使用系统默认时区转LocalDateTime,如果服务时区不是东八区,传入时间戳时请与 readme 示例一样显式换算(toInstant(ZoneOffset.ofHours(8)).toEpochMilli()),否则时辰可能差一档。- 闰月前缀是"润",如果业务对用字敏感("闰"才是标准写法),拿到
lunarMonthToChinese的结果后可以自行替换。 - 农历日的"初一"输出为"初壹",同理"十一"是"壹壹",做前端展示时如果习惯"初一/十八"的写法,需要再做一层映射。
VI. 小结
本篇介绍了 date-plugin 的实现原理和完整用法:ChineseDateTool 用查表法(月天数表 + 正月初一对照表)完成公历与农历的互转,ChineseDateExtendTool 在其上封装了干支年、大写月日、十二时辰的中文输出,一行 getNowLunarDate() 就能得到 己亥年伍月壹捌 辰时 这样的结果。