1.公历与农历互转

一灰灰blogQuickMediadate-plugin约 2297 字大约 8 分钟

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:

  1. 先确定目标日期落在哪个农历年:取 solar_1_1 中"正月初一小于等于目标日期"的那一项
  2. 计算目标日期与当年正月初一之间的天数差
  3. 从正月开始,逐月用"该月是 30 天还是 29 天"去扣减天数差,扣不动了就说明落在了当前月
  4. 最后根据闰月位置做修正:如果落在闰月之后,月序号要减 1,并给 isleap 标记赋值

3. 农历转公历

反过来,ChineseDateTool.lunarToSolar 就是正向累加:

  1. 查表拿到当年闰月位置,按"目标农历月在闰月之前还是之后"确定要累加的月序范围
  2. 累加前面每个月的天数(30 或 29),再加上日
  3. 把这个天数偏移加到"当年正月初一的公历日期"上,直接得到目标公历日期

整个转换没有任何浮点和迭代逼近,就是查表 + 位运算 + 累加,所以性能可以忽略不计。

位运算的核心是 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、solarDay
  • Lunar:农历日期,四个字段 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. 使用边界与注意点

  1. 支持年份范围是 1887~2111 年。查表的数组每个农历年一项,超出范围会直接数组越界,所以别拿它去算 2112 年之后的排期。
  2. 只做日期维度,不处理节气、干支月/干支时。hourToChinese 输出的是"地支时"(如辰时),但年只有干支年,没有干支月,严格八字起盘的场景需要更专业的库。
  3. getLunarDateByTimestamp 使用系统默认时区转 LocalDateTime,如果服务时区不是东八区,传入时间戳时请与 readme 示例一样显式换算(toInstant(ZoneOffset.ofHours(8)).toEpochMilli()),否则时辰可能差一档。
  4. 闰月前缀是"润",如果业务对用字敏感("闰"才是标准写法),拿到 lunarMonthToChinese 的结果后可以自行替换。
  5. 农历日的"初一"输出为"初壹",同理"十一"是"壹壹",做前端展示时如果习惯"初一/十八"的写法,需要再做一层映射。

VI. 小结

本篇介绍了 date-plugin 的实现原理和完整用法:ChineseDateTool 用查表法(月天数表 + 正月初一对照表)完成公历与农历的互转,ChineseDateExtendTool 在其上封装了干支年、大写月日、十二时辰的中文输出,一行 getNowLunarDate() 就能得到 己亥年伍月壹捌 辰时 这样的结果。

项目地址: https://github.com/liuyueyi/quick-mediaopen in new window

Loading...