基于Python+Flask實現(xiàn)農歷轉換API實戰(zhàn)指南
更新時間：2025年12月31日 14:23:27 作者：weixin_46244623
這篇文章主要為大家詳細介紹了如何基于 lunar-python 農歷算法庫,使用 Flask 封裝了一套 完整、可直接部署的農歷轉換 REST API,感興趣的小伙伴可以了解下
在國內業(yè)務系統(tǒng)中，農歷（陰歷） 仍然被廣泛使用，例如：
- 農歷生日、紀念日
- 傳統(tǒng)節(jié)日（春節(jié)、除夕、中秋）
- 日歷 / 黃歷 / 命理類應用
- 本地化系統(tǒng)展示
本文基于 lunar-python 農歷算法庫，使用 Flask 封裝了一套 完整、可直接部署的農歷轉換 REST API，支持：
- 公歷 → 農歷
- 農歷 → 公歷（支持閏月）
- 當前農歷日期查詢
- 干支、生肖、節(jié)氣、節(jié)日
- 完整中文描述
支持時間范圍：1900 – 2100 年
一、技術選型說明
lunar-python
選擇 lunar-python 的原因：
- 農歷算法成熟、權威
- API 設計清晰
- 支持干支、生肖、節(jié)氣、節(jié)日
- 支持閏月（負數(shù)月份表示）
- 純 Python，無外部依賴
pip install lunar-python
Flask
- 輕量
- 易于部署
- 非常適合工具型 API / 內部服務
pip install flask
二、API 設計說明
本示例實現(xiàn)了 4 個接口：
| 接口 | 說明 |
|---|---|
| /api/to_lunar | 公歷 → 農歷 |
| /api/to_solar | 農歷 → 公歷（支持閏月） |
| /api/today_lunar | 獲取當前農歷 |
| / | 服務狀態(tài) & 接口說明 |
三、核心設計：統(tǒng)一農歷數(shù)據(jù)結構
為了方便前端或其他系統(tǒng)使用，先對 lunar-python 的返回結果進行統(tǒng)一格式化。
農歷信息格式化函數(shù)
def format_lunar(lunar):
"""統(tǒng)一格式化農歷信息（完全適配 lunar_python 最新版）"""
month = lunar.getMonth() # 可能為負數(shù)（閏月）
is_leap_month = month < 0
abs_month = abs(month)
festivals = lunar.getFestivals() # 標準農歷節(jié)日
other_festivals = lunar.getOtherFestivals() # 其他擴展節(jié)日
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
節(jié)日區(qū)分：
- getFestivals()：傳統(tǒng)節(jié)日（春節(jié)、除夕）
- getOtherFestivals()：擴展節(jié)日
輸出結構穩(wěn)定，方便前端直接使用
四、公歷 → 農歷 API
接口定義
GET /api/to_lunar
參數(shù)
| 參數(shù) | 說明 |
|---|---|
| year | 公歷年 |
| month | 公歷月 |
| day | 公歷日 |
代碼實現(xiàn)
@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
參數(shù)
| 參數(shù) | 說明 |
|---|---|
| year | 農歷年 |
| month | 農歷月 |
| day | 農歷日 |
| leap | 是否閏月（true / false） |
關鍵點：閏月處理
lunar_month = -month if leap else month
這是 lunar-python 的標準用法。
代碼實現(xiàn)
@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
代碼實現(xiàn)
@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": ["春節(jié)"]
}
九、完整代碼
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):
"""統(tǒng)一格式化農歷信息（完全適配 lunar_python 最新版）"""
month = lunar.getMonth() # 可能為負數(shù)（閏月）
is_leap_month = month < 0
abs_month = abs(month)
festivals = lunar.getFestivals() # 標準農歷節(jié)日（如春節(jié)、除夕）
other_festivals = lunar.getOtherFestivals() # 其他擴展節(jié)日
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, # 傳統(tǒng)農歷節(jié)日列表
"other_festivals": other_festivals if other_festivals else None # 其他節(jié)日
}
@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)
十、適用場景
日歷 / 黃歷系統(tǒng)
農歷生日管理
中國本土化應用
Web / 小程序后端
內部工具 API
總結
本文基于 lunar-python + Flask 實現(xiàn)了一套功能完整、結構清晰、可直接部署的農歷轉換 API
特點：
- 不依賴外部命令
- 支持閏月
- 返回結構友好
- 易于擴展
非常適合用于實際生產項目。
到此這篇關于基于Python+Flask實現(xiàn)農歷轉換API實戰(zhàn)指南的文章就介紹到這了,更多相關Python農歷轉換API內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！
相關文章
這篇文章主要介紹了python腳本設置系統(tǒng)時間的兩種方法，其一是調用socket直接發(fā)送udp包到國家授時中心，其二是調用ntplib包，感興趣的小伙伴們可以參考一下2016-02-02
本文介紹了一個功能強大的文件頭簽名分析工具的實現(xiàn)原理和開發(fā)過程,該工具通過讀取文件頭部二進制簽名來識別文件真實類型,即使用戶修改了文件擴展名也能準確判斷,文章詳細解析了核心算法、GUI設計以及技術實現(xiàn)細節(jié),為開發(fā)類似工具提供了完整參考,需要的朋友可以參考下2025-05-05
經常會遇到圖片格式需要轉換的情況，這篇文章主要為大家詳細介紹了Python實現(xiàn)圖片格式轉換，文中示例代碼介紹的非常詳細、實用，具有一定的參考價值，感興趣的小伙伴們可以參考一下2022-08-08
Python的正則表達式(re模塊)是完成這個任務的利器,但你知道怎么寫才能準確匹配各種合法的IP地址嗎,今天我們就來詳細探討這個問題,感興趣的朋友一起看看吧2025-04-04
這篇文章主要為大家介紹了Python for循環(huán)，具有一定的參考價值，感興趣的小伙伴們可以參考一下，希望能夠給你帶來幫助2021-11-11
Python 帶星號(* 或 **)的函數(shù)參數(shù)詳解
這篇文章主要介紹了Python 帶星號(* 或 **)的函數(shù)參數(shù)詳解，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2021-02-02
tensorflow實現(xiàn)在函數(shù)中用tf.Print輸出中間值
今天小編就為大家分享一篇tensorflow實現(xiàn)在函數(shù)中用tf.Print輸出中間值，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2020-01-01
這篇文章主要介紹了pandas 使用merge實現(xiàn)百倍加速的操作，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2021-04-04
今天小編就為大家分享一篇關于Python數(shù)據(jù)可視化之畫圖，小編覺得內容挺不錯的，現(xiàn)在分享給大家，具有很好的參考價值，需要的朋友一起跟隨小編來看看吧2019-01-01
Python使用email?庫創(chuàng)建和解析電子郵件詳解
在現(xiàn)代軟件開發(fā)中,處理電子郵件是一項常見的任務,本文將介紹如何使用Python的??email??庫來創(chuàng)建和解析電子郵件,有需要的小伙伴可以參考一下2025-09-09