基于Python+Flask实现农历转换API实战指南
更新时间：2025年12月31日 14:23:27 作者：weixin_46244623
这篇文章主要为大家详细介绍了如何基于 lunar-python 农历算法库,使用 Flask 封装了一套 完整、可直接部署的农历转换 REST API,感兴趣的小伙伴可以了解下
在国内业务系统中，农历（阴历） 仍然被广泛使用，例如：
- 农历生日、纪念日
- 传统节日（春节、除夕、中秋）
- 日历 / 黄历 / 命理类应用
- 本地化系统展示
本文基于 lunar-python 农历算法库，使用 Flask 封装了一套 完整、可直接部署的农历转换 REST API，支持：
- 公历 → 农历
- 农历 → 公历（支持闰月）
- 当前农历日期查询
- 干支、生肖、节气、节日
- 完整中文描述
支持时间范围：1900 – 2100 年
一、技术选型说明
lunar-python
选择 lunar-python 的原因：
- 农历算法成熟、权威
- API 设计清晰
- 支持干支、生肖、节气、节日
- 支持闰月（负数月份表示）
- 纯 Python，无外部依赖
pip install lunar-python
Flask
- 轻量
- 易于部署
- 非常适合工具型 API / 内部服务
pip install flask
二、API 设计说明
本示例实现了 4 个接口：
| 接口 | 说明 |
|---|---|
| /api/to_lunar | 公历 → 农历 |
| /api/to_solar | 农历 → 公历（支持闰月） |
| /api/today_lunar | 获取当前农历 |
| / | 服务状态 & 接口说明 |
三、核心设计：统一农历数据结构
为了方便前端或其他系统使用，先对 lunar-python 的返回结果进行统一格式化。
农历信息格式化函数
def format_lunar(lunar):
"""统一格式化农历信息（完全适配 lunar_python 最新版）"""
month = lunar.getMonth() # 可能为负数（闰月）
is_leap_month = month < 0
abs_month = abs(month)
festivals = lunar.getFestivals() # 标准农历节日
other_festivals = lunar.getOtherFestivals() # 其他扩展节日
return {
"lunar_year": lunar.getYear(),
"lunar_month": abs_month,
"lunar_day": lunar.getDay(),
"is_leap_month": is_leap_month,
"chinese_string": lunar.toFullString(),
"full_info": lunar.toFullString(),
"ganzhi_year": lunar.getYearInChinese(),
"ganzhi_month": lunar.getMonthInChinese(),
"ganzhi_day": lunar.getDayInChinese(),
"shengxiao": lunar.getYearShengXiao(),
"jieqi": lunar.getJieQi() if lunar.getJieQi() else None,
"festivals": festivals if festivals else None,
"other_festivals": other_festivals if other_festivals else None
}
设计说明
闰月判断：month < 0
节日区分：
- getFestivals()：传统节日（春节、除夕）
- getOtherFestivals()：扩展节日
输出结构稳定，方便前端直接使用
四、公历 → 农历 API
接口定义
GET /api/to_lunar
参数
| 参数 | 说明 |
|---|---|
| year | 公历年 |
| month | 公历月 |
| day | 公历日 |
代码实现
@app.route('/api/to_lunar', methods=['GET'])
def to_lunar():
try:
year = int(request.args.get('year'))
month = int(request.args.get('month'))
day = int(request.args.get('day'))
solar = Solar.fromYmd(year, month, day)
lunar = solar.getLunar()
return jsonify({
"success": True,
"solar_date": f"{year}-{month:02d}-{day:02d}",
"lunar": format_lunar(lunar)
})
except Exception as e:
return jsonify({
"success": False,
"error": str(e)
}), 400
示例请求
/api/to_lunar?year=2025&month=2&day=1
五、农历 → 公历 API（支持闰月）
接口定义
GET /api/to_solar
参数
| 参数 | 说明 |
|---|---|
| year | 农历年 |
| month | 农历月 |
| day | 农历日 |
| leap | 是否闰月（true / false） |
关键点：闰月处理
lunar_month = -month if leap else month
这是 lunar-python 的标准用法。
代码实现
@app.route('/api/to_solar', methods=['GET'])
def to_solar():
try:
year = int(request.args.get('year'))
month = int(request.args.get('month'))
day = int(request.args.get('day'))
leap = request.args.get('leap', 'false').lower() in ('true', '1', 'yes')
lunar_month = -month if leap else month
lunar = Lunar.fromYmd(year, lunar_month, day)
solar = lunar.getSolar()
return jsonify({
"success": True,
"lunar": format_lunar(lunar),
"solar_date": solar.toYmd()
})
except Exception as e:
return jsonify({
"success": False,
"error": str(e)
}), 400
六、获取当前农历日期 API
接口定义
GET /api/today_lunar
代码实现
@app.route('/api/today_lunar', methods=['GET'])
def today_lunar():
try:
now = datetime.now()
today_solar = Solar.fromDate(now)
today_lunar = today_solar.getLunar()
return jsonify({
"success": True,
"solar_date": today_solar.toYmd(),
"solar_datetime": today_solar.toYmdHms(),
"timestamp": now.isoformat(),
"lunar": format_lunar(today_lunar)
})
except Exception as e:
return jsonify({
"success": False,
"error": str(e)
}), 500
适合：
- 首页日历
- 今日农历展示
- 黄历 / 日签应用
七、服务启动与运行
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5006, debug=True)
启动后访问：http://localhost:5006/
即可看到接口说明。
八、返回 JSON 示例（简化）
{
"lunar_year": 2024,
"lunar_month": 12,
"lunar_day": 4,
"is_leap_month": false,
"chinese_string": "甲辰年 腊月初四",
"shengxiao": "龙",
"festivals": ["春节"]
}
九、完整代码
from flask import Flask, request, jsonify
from lunar_python import Solar, Lunar
from datetime import datetime
import traceback
app = Flask(__name__)
def format_lunar(lunar):
"""统一格式化农历信息（完全适配 lunar_python 最新版）"""
month = lunar.getMonth() # 可能为负数（闰月）
is_leap_month = month < 0
abs_month = abs(month)
festivals = lunar.getFestivals() # 标准农历节日（如春节、除夕）
other_festivals = lunar.getOtherFestivals() # 其他扩展节日
return {
"lunar_year": lunar.getYear(),
"lunar_month": abs_month,
"lunar_day": lunar.getDay(),
"is_leap_month": is_leap_month,
"chinese_string": lunar.toFullString(),
"full_info": lunar.toFullString(),
"ganzhi_year": lunar.getYearInChinese(),
"ganzhi_month": lunar.getMonthInChinese(),
"ganzhi_day": lunar.getDayInChinese(),
"shengxiao": lunar.getYearShengXiao(),
"jieqi": lunar.getJieQi() if lunar.getJieQi() else None,
"festivals": festivals if festivals else None, # 传统农历节日列表
"other_festivals": other_festivals if other_festivals else None # 其他节日
}
@app.route('/api/to_lunar', methods=['GET'])
def to_lunar():
try:
year = int(request.args.get('year'))
month = int(request.args.get('month'))
day = int(request.args.get('day'))
solar = Solar.fromYmd(year, month, day)
lunar = solar.getLunar()
return jsonify({
"success": True,
"solar_date": f"{year}-{month:02d}-{day:02d}",
"lunar": format_lunar(lunar)
})
except Exception as e:
app.logger.error(f"Error in to_lunar: {str(e)}\n{traceback.format_exc()}")
return jsonify({
"success": False,
"error": str(e),
"detail": str(e)
}), 400
@app.route('/api/to_solar', methods=['GET'])
def to_solar():
try:
year = int(request.args.get('year'))
month = int(request.args.get('month'))
day = int(request.args.get('day'))
leap = request.args.get('leap', 'false').lower() in ('true', '1', 'yes')
lunar_month = -month if leap else month
lunar = Lunar.fromYmd(year, lunar_month, day)
solar = lunar.getSolar()
return jsonify({
"success": True,
"lunar": format_lunar(lunar),
"solar_date": solar.toYmd()
})
except Exception as e:
app.logger.error(f"Error in to_solar: {str(e)}\n{traceback.format_exc()}")
return jsonify({
"success": False,
"error": str(e),
"detail": str(e)
}), 400
@app.route('/api/today_lunar', methods=['GET'])
def today_lunar():
try:
app.logger.info("Calling /api/today_lunar")
now = datetime.now()
today_solar = Solar.fromDate(now)
app.logger.info(f"Today solar: {today_solar.toYmd()} {today_solar.toYmdHms()}")
today_lunar = today_solar.getLunar()
return jsonify({
"success": True,
"solar_date": today_solar.toYmd(),
"solar_datetime": today_solar.toYmdHms(),
"timestamp": now.isoformat(),
"lunar": format_lunar(today_lunar)
})
except Exception as e:
error_msg = str(e)
tb = traceback.format_exc()
app.logger.error(f"Error in today_lunar: {error_msg}\n{tb}")
return jsonify({
"success": False,
"error": "Internal Server Error",
"detail": error_msg,
"traceback": tb
}), 500
@app.route('/', methods=['GET'])
def home():
return jsonify({
"message": "Lunar Calendar API is running! (lunar_python fully adapted)",
"current_time": datetime.now().isoformat(),
"endpoints": {
"to_lunar": "/api/to_lunar?year=2025&month=12&day=24",
"to_solar": "/api/to_solar?year=2025&month=11&day=5&leap=false",
"today_lunar": "/api/today_lunar"
}
})
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5006, debug=True)
十、适用场景
日历 / 黄历系统
农历生日管理
中国本土化应用
Web / 小程序后端
内部工具 API
总结
本文基于 lunar-python + Flask 实现了一套功能完整、结构清晰、可直接部署的农历转换 API
特点：
- 不依赖外部命令
- 支持闰月
- 返回结构友好
- 易于扩展
非常适合用于实际生产项目。
到此这篇关于基于Python+Flask实现农历转换API实战指南的文章就介绍到这了,更多相关Python农历转换API内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！
相关文章
这篇文章主要为大家详细介绍了windows下Virtualenvwrapper安装教程，具有一定的参考价值，感兴趣的小伙伴们可以参考一下2017-12-12
本文给大家分享的是由于工作需求，要求PC中安装python2和python3的开发环境。那么我们应该如何操作呢，下面我们就来探讨下。2017-05-05
模拟退火算法借鉴了统计物理学的思想，是一种简单、通用的启发式优化算法，并在理论上具有概率性全局优化性能，因而在科研和工程中得到了广泛的应用2021-10-10
网上很多关于Python协程asyncio模块的教程都是基于老版Python的, 本文将以对比方式展示新老Python版本下协程的写法有什么不同并总结了asyncio的一些高级用法, 包括如何获取协程任务执行结果，gather和wait方法的区别以及如何给任务添加回调函数。2021-05-05
这篇文章主要为大家详细介绍了python实现自动解数独小程序，具有一定的参考价值，感兴趣的小伙伴们可以参考一下2019-01-01
在本篇文章里小编给大家整理的是关于Pytorch修改ResNet模型全连接层进行直接训练相关知识点，有需要的朋友们参考下。2019-09-09
我们平时在用python写一些脚本作为工具时,经常需要在其他脚本中加载该工具,这篇文章主要给大家介绍了关于Python中添加搜索路径的相关资料,需要的朋友可以参考下2022-05-05
这篇文章主要介绍了Python中的时间格式的读取与转换(time模块),文末给大家介绍了python的时间获取与转化：time模块和datetime模块的相关知识，需要的朋友可以参考下2023-05-05
在本篇文章里小编给大家整理的是一篇关于python中子类与父类的关系基础知识点内容，对此有兴趣的朋友们可以学习下。2021-02-02
这篇文章主要给大家分享了200个Python 标准库总结，主要对文本、数据类型、数学等多个类型总结，既有一定的参考价值，需要的小伙伴可以参考一下2022-01-01
最新评论