简介一份基于Java实现时间转换生辰八字的完整代码包面向对命理与编程相结合的开发者也适合需要计算传统历法的工程人员。资源围绕时间转换项目展开借助日期时间类解析输入时间按天干地支循环规则推算出年、月、日、时四柱再组合为完整八字。包内共有11个文件含3个源码文件、4个已编译的字节码文件以及说明文档和完整的项目环境配置既可阅读源码学习算法也能直接运行验证结果。压缩包整体仅48KB非常轻巧实用目前已有1600人学习下载。通过学习这份资源既能掌握由公历时间求八字的核心推算思路也能梳理Java日期时间处理接口的使用方法并为扩展五行判断、四柱分析等命理功能提供可复用的基础结构形成可继续完善的代码框架。1. 时间转换生辰八字不是先转农历而是先查节气做一个八字排盘工具最容易踩的一个思维误区是“先把公历转农历再取农历年月日”。实际上八字命理里的年、月、日、时四柱边界不是农历的正月初一而是二十四节气里的“节”年柱看立春月柱看每个月从哪个节开始。这个标题为“时间转换成精确的生辰八字”的Java项目精确之处就在于用一张按分钟记录的节气表来定位四柱而不是拿农历日期估算。适合两类人一类是刚接触命理工具的Java开发者想弄明白四柱到底怎么算另一类是想做排盘应用后端的人需要一套能校准确认口径的八字计算引擎。2. 技术架构与数据模型节气表、换日规则和六十甲子索引先理解这个项目的设计边界。它接收一个公历时间点输出的是“年柱、月柱、日柱、时柱”四组干支每组由一个天干和一个地支组成。整个过程分三层入口层把时间点按配置的规则做一次换日归属计算层拿着时间点查节气表、推干支输出层把四个柱拼成一个结构化对象。项目里没有传统意义上的“农历转换模块”因为四柱八字的排盘核心是节气时刻农历只是附属展示信息。2.1 分层设计时间规范化、干支推算、结果装配入口层的关键是“换日规则”。同一天23点出生的人在两种口径下可能得到不同的日柱一种认为23点已经算第二天另一种认为到24点才换日。项目没有替用户选边站而是做成配置项排盘前先做一次时间归一化后续所有计算都基于归一化之后的时间点。这个设计在工程上是必要的不然同一个时间点在不同配置下会算出不同的年柱和月柱。计算层由四个独立的计算器组成各自只负责一根柱子计算器输入输出依赖YearPillarCalculator时间点、当年立春时刻年柱干支立春边界MonthPillarCalculator时间点、节气表、年干索引月柱干支节气定位、五虎遁DayPillarCalculator时间点、基准日配置日柱干支基准日偏移HourPillarCalculator时间点、日干索引时柱干支时辰映射、五鼠遁输出层只有一个BaZiResult对象四个柱各带一个Pillar对象Pillar内部保存天干名、地支名以及对应的索引。索引是整个系统的通用语言天干用0到9表示甲到癸地支用0到11表示子到亥所有公式都建立在索引上而不是字符串上。2.2 节气数据文件12个“节”精确到分钟项目的数据目录下放一个jieqi.json记录1900年到2100年每一年的12个“节”的精确时刻。为什么只用“节”不用二十四节气全部因为八字月柱的切换点只用“节”立春、惊蛰、清明、立夏、芒种、小暑、立秋、白露、寒露、立冬、大雪、小寒。十二个“气”在月柱计算里用不上。数据格式大致如下[ { year: 2024, terms: [ { name: 小寒, time: 2024-01-06 04:49 }, { name: 立春, time: 2024-02-04 16:27 }, { name: 惊蛰, time: 2024-03-05 10:23 } ] } ]这是整个项目“精确”二字的根基。节气在公历里的日期每年会有一两天的浮动有的年份立春在2月3日深夜有的在2月4日中午如果数据里只存日期不存时分那2月3日23点出生的人会被归到错误的年份和月份里。时间字符串的解析统一走LocalDateTime格式固定为yyyy-MM-dd HH:mm在代码里用一个自定义的JsonDeserializer做容错解析。2.3 天干地支的索引模型用数组下标说话四柱计算的大量逻辑是数学运算不是字符串拼接。项目里有一个GanZhiSupport类把天干地支定义成两个常量数组并提供索引转换方法public class GanZhiSupport { public static final String[] TIAN_GAN { 甲, 乙, 丙, 丁, 戊, 己, 庚, 辛, 壬, 癸 }; public static final String[] DI_ZHI { 子, 丑, 寅, 卯, 辰, 巳, 午, 未, 申, 酉, 戌, 亥 }; public static int ganIndex(String gan) { for (int i 0; i TIAN_GAN.length; i) { if (TIAN_GAN[i].equals(gan)) return i; } throw new IllegalArgumentException(非法天干: gan); } public static int zhiIndex(String zhi) { for (int i 0; i DI_ZHI.length; i) { if (DI_ZHI[i].equals(zhi)) return i; } throw new IllegalArgumentException(非法地支: zhi); } public static String ganName(int index) { return TIAN_GAN[Math.floorMod(index, 10)]; } public static String zhiName(int index) { return DI_ZHI[Math.floorMod(index, 12)]; } }注意ganName和zhiName里用了Math.floorMod而不是普通的取模运算符。Java的%对负数返回负值索引运算里经常出现“(某索引 - 1) % 12”这种表达式普通取模会导致数组下标越界Math.floorMod能把结果修正到0到11的范围内。这个细节在后续所有计算器里都会用到是一个真实的踩坑点。2.4 换日规则配置项晚子时的两种口径项目的config/bazi-config.yaml里有一个关键配置day-switch-rule: late-zi # 可选值late-zi 或 midnight day-pillar: base-date: 2000-01-01 base-index: 0 # 基准日的六十甲子序号0甲子late-zi对应命理里的“晚子时换日”23点一过日柱就按第二天计算midnight对应“0点换日”23点到24点之间仍然算当天日柱。这两套口径在命理工具圈子里各有一批拥护者项目不表态只负责按配置执行。日柱的base-date和base-index是配合使用的。日柱计算本质上是一个基准日加偏移量base-date是基准日期base-index是那一天在六十甲子里的序号。这个值需要用户自己用万年历核对填入项目没有内置默认值原因是不同万年历在晚子时这种边界时刻给的结果不一样写死任何一个都会被另一批用户骂。这个设计后面在避坑章节里还会详细展开。3. 核心模块拆解四柱干支的完整计算链路这一章把四个计算器逐一拿出来讲最后看主流程怎么把它们组合起来。每个计算器都很短难的是搞清楚它们之间的依赖关系年柱给月柱提供年干索引日柱给时柱提供日干索引主流程让它们按顺序执行。3.1 年柱立春边界上的干支切换年柱的规则只有一条立春之前出生用上一年的干支立春之后用当年的干支。干支纪年和公历纪年的差值是固定的不需要逐次推算。public class YearPillarCalculator { public Pillar calculate(LocalDateTime time, LocalDateTime liChun) { int baziYear time.isBefore(liChun) ? time.getYear() - 1 : time.getYear(); int ganZhiIndex Math.floorMod(baziYear - 4, 60); String gan GanZhiSupport.ganName(ganZhiIndex % 10); String zhi GanZhiSupport.zhiName(ganZhiIndex % 12); return new Pillar(gan, zhi); } }这里的核心是ganZhiIndex (baziYear - 4) % 60。1984年是甲子年序号0代入后(1984 - 4) % 60 0成立。2023年是癸卯年(2023 - 4) % 60 39查六十甲子表39号正好是癸卯。liChun参数是从节气表里查出来的当年立春精确时刻由主流程传入计算器自身不做数据查询。3.2 月柱节气的二分查找与五虎遁月柱比年柱复杂一步。先要确定时间点落在哪两个节之间得到月支索引再用“五虎遁”根据年干推出月干。项目里findMonthZhi用全局有序的节气列表做二分查找而不是按年份逐月比对public class MonthPillarCalculator { private static final MapString, Integer JIE_ZHI_MAP Map.of( 立春, 2, 惊蛰, 3, 清明, 4, 立夏, 5, 芒种, 6, 小暑, 7, 立秋, 8, 白露, 9, 寒露, 10, 立冬, 11, 大雪, 0, 小寒, 1 ); public Pillar calculate(LocalDateTime time, JieQiTable table, int yearGanIndex) { int monthZhi findMonthZhi(time, table); int monthGanStart Math.floorMod((yearGanIndex % 5) * 2 2, 10); int monthGan Math.floorMod(monthGanStart (monthZhi - 2), 10); return new Pillar( GanZhiSupport.ganName(monthGan), GanZhiSupport.zhiName(monthZhi) ); } private int findMonthZhi(LocalDateTime time, JieQiTable table) { ListJieQi sorted table.allTermsSorted(); int idx upperBound(sorted, time) - 1; return JIE_ZHI_MAP.get(sorted.get(idx).getName()); } }findMonthZhi的逻辑很容易讲错重点说清楚把所有节气按时间排序之后找到“最后一个早于等于输入时间”的节这个节决定月支。比如输入时间在小寒之后、立春之前最后一个节是小寒返回的月支索引是1也就是丑月。因为节气数据是跨年连续存储的1月初出生的人要落到上一年的小寒所以这里必须用全局有序列表不能只查出生当年。五虎遁的口诀是“甲己之年丙作首乙庚之岁戊为头”代码里浓缩成一句monthGanStart (yearGanIndex % 5) * 2 2。验证一下年干甲索引00 * 2 2 2寅月天干为丙正确年干戊索引4(4 % 5) * 2 2 10取模后为0寅月天干为甲同样正确。月支和月干随后同步递增所以monthGan monthGanStart (monthZhi - 2)因为寅月的月支索引是2是起点。3.3 日柱基准日配置与偏移天数日柱是整个项目里最依赖外部校准的部分。计算原理很简单选一个已知干支的基准日然后数天数偏移量对60取模。难点在于基准日的干支受换日口径影响项目干脆把它做成配置让用户自己核对。public class DayPillarCalculator { private final LocalDate baseDate; private final int baseIndex; public DayPillarCalculator(LocalDate baseDate, int baseIndex) { this.baseDate baseDate; this.baseIndex baseIndex; } public Pillar calculate(LocalDateTime time) { LocalDate targetDate time.toLocalDate(); long days ChronoUnit.DAYS.between(baseDate, targetDate); int index Math.floorMod(baseIndex (int) days, 60); return new Pillar( GanZhiSupport.ganName(index % 10), GanZhiSupport.zhiName(index % 12) ); } }这里要特别提醒如果配置的换日规则是late-zi主流程在调用日柱计算器之前已经把23点之后的时间点加了一天所以这里的time.toLocalDate()直接取日期是安全的。baseIndex填的是基准日在六十甲子里的序号0代表甲子1代表乙丑以此类推。校准方法很简单查万年历找出baseDate那一天的日柱查出它在六十甲子表里排第几个填进配置。3.4 时柱五鼠遁与时辰映射时柱的地支完全由小时决定两个小时一个时辰天干由日干通过“五鼠遁”推出。代码里时支的映射公式是(hour 1) / 2 % 12一行代码搞定public class HourPillarCalculator { public Pillar calculate(LocalDateTime time, int dayGanIndex) { int hourZhi (time.getHour() 1) / 2 % 12; int hourGanStart Math.floorMod((dayGanIndex % 5) * 2 2, 10); int hourGan Math.floorMod(hourGanStart hourZhi, 10); return new Pillar( GanZhiSupport.ganName(hourGan), GanZhiSupport.zhiName(hourZhi) ); } }验证几个边界23点(23 1) / 2 12取模后为0子时正确0点(0 1) / 2 0子时正确1点(1 1) / 2 1丑时正确。23点到0点的边界之所以不出错是因为整数除法向下取整23点先算到12再取模而0点直接算到0。五鼠遁的口诀是“甲己还加甲乙庚丙作初”代码和五虎遁共用同一个起点公式口诀格式(dayGanIndex % 5) * 2 2。日干甲索引0子时天干为甲正确日干乙索引1子时天干为丙也正确。时支从子时开始递增天干同步递增所以直接加时支索引取模10。3.5 主流程BaZiEngine把四个结果拼装成完整八字主流程是一个门面类负责把四个计算器按依赖顺序串起来返回一个完整的BaZiResultpublic class BaZiEngine { private final JieQiTable jieQiTable; private final DayPillarCalculator dayPillarCalculator; private final DaySwitchRule daySwitchRule; public BaZiResult calculate(LocalDateTime rawTime) { LocalDateTime time daySwitchRule.normalize(rawTime); LocalDateTime liChun jieQiTable.findLiChun(time.getYear()); Pillar year new YearPillarCalculator().calculate(time, liChun); Pillar month new MonthPillarCalculator() .calculate(time, jieQiTable, year.ganIndex()); Pillar day dayPillarCalculator.calculate(time); Pillar hour new HourPillarCalculator() .calculate(time, day.ganIndex()); return BaZiResult.of(year, month, day, hour); } }DaySwitchRule.normalize做两件事如果换日规则是late-zi且小时为23点日期加一天如果是midnight原样返回。这一步在最前面执行后面的年柱判断才能正确。年柱的liChun直接从节气表按当年查如果当年立春时刻在输入时间之后说明还没到下一个换年点年柱退一年。月柱需要年干的索引日柱在时柱之前算是因为时柱要用日干索引。整个链路是单向的没有循环依赖。4. 运行与验证命令行排盘和万年历核对这一章讲把项目跑起来的具体步骤。项目用Maven做构建配置文件和数据文件都放在config和data目录下命令行入口做了简单的参数解析不需要引入Spring这类重框架。4.1 项目结构与编译命令拿到源码包之后目录结构是这样的bazi-engine/ ├── pom.xml ├── README.md ├── config/ │ └── bazi-config.yaml ├── data/ │ └── jieqi.json └── src/main/java/ ├── BaZiEngine.java ├── model/ │ ├── GanZhiSupport.java │ ├── Pillar.java │ └── BaZiResult.java ├── calculator/ │ ├── YearPillarCalculator.java │ ├── MonthPillarCalculator.java │ ├── DayPillarCalculator.java │ └── HourPillarCalculator.java └── data/ ├── JieQiTable.java └── ConfigLoader.javapom.xml里只有两个依赖Jackson用于解析JSON配置和节气表JUnit 5用于跑测试。没有数据库没有网络请求打包出来是一个可以直接用java -jar执行的命令行工具。编译和运行mvn clean package -DskipTests java -jar target/bazi-engine.jar --time 2024-02-04 18:00第一次运行前需要先确认config/bazi-config.yaml里的日柱基准配置。项目不推荐直接跑而是建议先做一次校准原因在后面避坑章节会讲。先跑起来看到年柱和月柱输出再校准日柱整个流程会顺很多。4.2 命令行参数时间格式和输出模式命令行支持两个参数--time输入排盘时间--rule手动指定换日规则覆盖配置文件里的值。时间格式严格使用yyyy-MM-dd HH:mm分钟不能省略因为节气的边界能精确到分钟输入时间却不能那输出精度就无从谈起。java -jar target/bazi-engine.jar --time 2024-02-04 18:00 --rule midnight输出默认是控制台文本输入时间2024-02-04 18:00 换日规则midnight 年柱甲辰 月柱丙寅 日柱待基准校准后输出 时柱待基准校准后输出年柱甲辰和月柱丙寅这个结果是有确定依据的2024年2月4日16:27立春输入时间18点在立春之后年柱是甲辰年干甲的五虎遁正月起丙寅月柱是丙寅。这两根柱子不依赖日柱基准配置可以作为校准前的正确性验证。4.3 校准日柱基准一次配置终身使用日柱基准的校准流程其实很简单。打开配置day-pillar: base-date: 2000-01-01 base-index: 0找一个你信得过的排盘工具查出2000年1月1日那天的日柱是什么。假设你查到的结果是甲午日甲午在六十甲子里排第31位序号从0开始数就是30那就把base-index改成30。改完重新跑一次java -jar target/bazi-engine.jar --time 2000-01-01 12:00看输出的日柱是不是甲午一致就说明基准配置正确。这步校准只需要做一次之后所有日期的日柱都会基于这个基准偏移计算不会再漂移。考虑做一个一次性校准命令也是合理的java -jar target/bazi-engine.jar --calibrate --base-date 2000-01-01 --expected-ganzhi 甲午自动计算偏移量并写入配置文件省去手工换算六十甲子序号这一步。这个功能在源码包的工具类里已经预留了接口感兴趣的可以自己接上。5. 避坑指南节气精度、闰月和晚子时那些坑做这个项目的过程里踩过不少坑有些是数据问题有些是概念问题挑几个典型的整理在这里每个都是“现象-原因-解决”的结构。5.1 节气表只精确到天月柱差一位现象同一套代码有的年份排盘结果和主流排盘工具一致有的年份差一个月柱。原因节气在公历里的时刻每年不固定。以2024年立春为例精确时刻是2月4日16:27但有的年份立春在2月3日深夜。如果节气数据只存到“日”2月3日出生的人到底算不算过立春程序无法判断只能默认2月3日还没立春于是年柱和月柱同时错一位。解决节气数据全部精确到分钟并且在数据校验里加一条规则相邻两个节之间至少间隔15天如果解析出来的时间差小于15天说明数据文件某个时间写错了。这条校验能把数据录入错误挡在运行之前。5.2 日柱基准在不同万年历里对不上现象用户按文档校准日柱后运行发现个别日期的日柱又和某个排盘网站对不上了。原因项目用的基准日偏移法本身没有误差误差来自基准日本身的干支。不同万年历在晚子时、节气时分等边界上的口径不同同一个基准日可能查出来两个不同的日柱。解决基准值不内置交给用户校准这是项目最有争议也最关键的决策。校准过一次之后只要用户固定使用同一个排盘工具作为参照后续结果就稳定一致。项目在README里也明确写了这个问题提醒用户不要混用多个参照工具。5.3 23点到24点的日柱归属两种口径都有道理现象一个23点30分出生的用户用late-zi配置排出的日柱是明天的用默认配置排出来是今天的问到底哪个对。原因这不是bug是命理体系内部的历史遗留分歧。late-zi认为子时一开始就进入新的一天midnight认为完整的一天以24点为界。解决项目把规则做成配置同时要求每次输出时把换日规则一起打印出来。这样用户拿结果去和其他工具对比时先确认两边的规则是否一致不一致就是规则差异而不是程序错误。5.4 非东八区时间直接排盘会整体偏移现象一位在海外用户输入当地标准时间排出的日柱和时柱和国内工具对不上。原因干支历的时间基准是东八区标准时间海外用户输入的当地时间如果不先做时区转换直接按小时算时支偏差最大能到几个小时甚至跨过一个时辰。解决项目入口预留了一个时区归一化方法public static LocalDateTime toCst(LocalDateTime sourceTime, ZoneId sourceZone) { ZonedDateTime zoned sourceTime.atZone(sourceZone); return zoned.withZoneSameInstant(ZoneId.of(Asia/Shanghai)).toLocalDateTime(); }使用方式是在调用calculate之前先把时间从本地时区转成东八区再进入排盘流程。输出的干支默认就是东八区视角如果想标注当地时间单独存一个字段做展示不参与计算。5.5 1月初的节气查询只查当年会直接报错现象输入1月3日的时间程序抛异常提示找不到节气边界。原因1月初在小寒和立春之间但小寒可能在上一年12月立春在当年2月。如果节气查询只查当年的数据1月3日找不到它的“上一个节”。解决节气查询改成全局有序列表从1900年一直排到2100年用二分查找定位。这样1月3日的上一个节是上一年末的小寒月支正确落在丑月。这个坑在最初的按年份查询版本里坑过一轮改成全局列表之后彻底解决。6. 二次开发从命令行工具到排盘服务这个项目的核心引擎和外部依赖解耦得非常干净加上DayPillarCalculator是构造注入的二次开发可以完全不碰计算逻辑只在外层加壳。6.1 封装成HTTP接口思路是先把BaZiEngine做成Spring容器的单例然后暴露一个POST接口。请求体只需要时间字符串和可选换日规则返回结构直接复用BaZiResult的JSON序列化结果RestController RequestMapping(/bazi) public class BaZiController { private final BaZiEngine engine; public BaZiController(BaZiEngine engine) { this.engine engine; } PostMapping(/calculate) public MapString, Object calculate(RequestBody CalculateRequest request) { BaZiResult result engine.calculate(LocalDateTime.parse(request.getTime())); return result.toDisplayMap(); } }6.2 扩展纳音五行和十神BaZiResult已经存了四个柱的天干地支索引纳音五行可以按六十甲子序号直接查表。加一个NaYinTable里面放六十个纳音名索引和DayPillarCalculator用的是同一套序号规则。十神则依赖日干和其他柱天干的五行生克关系核心数据已经齐全扩展不需要动引擎内部逻辑。6.3 自测技巧连续日期冒烟测试验证这类程序的输出是否稳定连续最有效的方法是写一个循环从基准日期开始连续跑500天LocalDateTime cursor baseDate.atTime(12, 0); for (int i 0; i 500; i) { BaZiResult result engine.calculate(cursor); // 断言日柱每过一天六十甲子序号递增1取模60 // 断言月柱在跨节前后发生变化 cursor cursor.plusDays(1); }这套测试能同时验证日柱偏移计算、节气边界切换、年柱立春切换三个部分是项目里价值最高的一段测试代码。我从那以后每次拿到新的节气数据源都会强制跑一遍这个500天冒烟测试确认完全没有漂移才敢继续动别的代码。希望帮到你。本文还有配套的精品资源点击获取