当前位置： 代码网 > it编程>前端脚本>Python > 基于Python+Flask实现农历转换API实战指南

基于Python+Flask实现农历转换API实战指南

2025年12月31日 • Python •我要评论
在国内业务系统中，农历（阴历） 仍然被广泛使用，例如：农历生日、纪念日传统节日（春节、除夕、中秋）日历 / 黄历 / 命理类应用本地化系统展示本文基于 lunar-python 农历算法库，使用 fl

在国内业务系统中，农历（阴历） 仍然被广泛使用，例如：

  • 农历生日、纪念日
  • 传统节日（春节、除夕、中秋）
  • 日历 / 黄历 / 命理类应用
  • 本地化系统展示

本文基于 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内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

赞 (0)

相关文章:

版权声明：本文内容由互联网用户贡献，该文观点仅代表作者本人。本站仅提供信息存储服务，不拥有所有权，不承担相关法律责任。 如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 2386932994@qq.com 举报，一经查实将立刻删除。

发表评论

验证码：
最近更新的文章
推荐阅读
大家感兴趣的文章
Copyright © 2017-2026  代码网 保留所有权利. 粤ICP备2024248653号
站长QQ:2386932994 | 联系邮箱：2386932994@qq.com