Spaces:

Hugo-Jiang
/

exchangeRates

Sleeping

App Files Files Community

exchangeRates / README.md

Hugo-Jiang

update README.md file

8704848 about 1 month ago

preview code

raw

history blame contribute delete

6.91 kB

metadata

title: Exchange Rates Service
emoji: 💱
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit

💱 汇率换算服务

基于 Python + FastAPI 开发的实时汇率换算服务，支持多 API Key 轮询、数据缓存、实时换算等功能。

✨ 功能特性

🔄 多 API Key 轮询 - 支持配置多个 API Key，自动轮询切换，防止单个 Key 超限
💾 智能缓存 - 定时任务自动更新汇率数据，避免频繁请求 API
🌍 161 种货币 - 支持全球 161 种货币的汇率查询和换算
💱 实时换算 - 前端页面支持实时输入实时计算，用户体验流畅
🎨 美观界面 - 响应式设计，支持搜索过滤，常用货币优先展示
📊 RESTful API - 提供完整的 API 接口，支持第三方集成

🛠️ 技术栈

后端: Python 3.9+, FastAPI, Uvicorn
定时任务: APScheduler
HTTP 客户端: httpx
数据验证: Pydantic
日志: Loguru
前端: 原生 HTML/CSS/JavaScript

📁 项目结构

exchangeRates/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI 应用入口
│   ├── config.py               # 配置管理
│   ├── models.py               # 数据模型
│   ├── api/
│   │   ├── __init__.py
│   │   └── routes.py           # API 路由
│   ├── services/
│   │   ├── __init__.py
│   │   ├── exchange_service.py # 汇率服务核心
│   │   └── scheduler.py        # 定时任务
│   └── utils/
│       ├── __init__.py
│       ├── logger.py           # 日志工具
│       └── currency_names.py   # 货币名称映射
├── static/
│   ├── css/
│   │   └── style.css           # 样式文件
│   └── js/
│       └── app.js              # 前端交互
├── templates/
│   └── index.html              # 前端页面
├── .env                        # 环境变量配置
├── .env.example                # 环境变量示例
├── requirements.txt            # Python 依赖
├── run.py                      # 启动脚本
└── README.md                   # 项目说明

🚀 快速开始

本地部署

1. 克隆项目

cd C:\Users\Eleven\Desktop\exchangeRates

2. 创建虚拟环境

python -m venv .venv
.venv\Scripts\activate

3. 安装依赖

pip install -r requirements.txt

4. 配置环境变量

编辑 .env 文件，配置你的 API Key：

# 多个 API Key 用逗号分隔
API_KEYS=your_api_key_1,your_api_key_2

# 基准货币
BASE_CURRENCY=CNY

# 缓存更新间隔（秒）
CACHE_UPDATE_INTERVAL=3600

5. 启动服务

python run.py

或者使用 uvicorn 直接启动：

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

6. 访问服务

🌐 首页: http://localhost:8000
📚 API 文档: http://localhost:8000/docs
📖 ReDoc: http://localhost:8000/redoc

Hugging Face Spaces 部署

本项目支持一键部署到 Hugging Face Spaces。

1. 创建 README.md 头部配置

在项目根目录的 README.md 文件顶部添加以下 YAML 配置：

---
title: Exchange Rates Service
emoji: 💱
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
---

2. 创建 Dockerfile

项目需要包含 Dockerfile 用于 Spaces 部署：

FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 7860

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

3. 配置环境变量

在 Hugging Face Spaces 设置中添加 Secrets：

API_KEYS: 你的 ExchangeRate-API Keys（逗号分隔）
BASE_CURRENCY: 基准货币（默认 CNY）
CACHE_UPDATE_INTERVAL: 缓存更新间隔（默认 3600）

4. 部署步骤

在 Hugging Face 创建新的 Space
选择 Docker SDK
上传项目文件或连接 Git 仓库
在 Settings 中配置 Secrets
Space 将自动构建和部署

5. 访问服务

部署成功后，可通过 https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME 访问服务。

📡 API 接口

获取所有汇率

GET /api/rates

响应示例：

{
  "success": true,
  "base_currency": "CNY",
  "rates": {
    "USD": 0.1413,
    "EUR": 0.1212,
    ...
  },
  "last_update": "Fri, 05 Dec 2025 00:00:01 +0000",
  "cached_at": "2025-12-05T10:30:00",
  "currencies_count": 161
}

获取特定货币汇率

GET /api/rates/{currency}

示例：GET /api/rates/USD

货币换算

POST /api/convert
Content-Type: application/json

{
  "from_currency": "USD",
  "to_currency": "CNY",
  "amount": 100
}

或使用 GET 方式：

GET /api/convert/USD/CNY?amount=100

批量换算

POST /api/batch-convert
Content-Type: application/json

{
  "base_currency": "USD",
  "amount": 100
}

或使用 GET 方式：

GET /api/batch-convert/USD?amount=100

获取货币列表

GET /api/currencies

服务状态

GET /api/status

强制刷新缓存

POST /api/refresh

⚙️ 配置说明

配置项	说明	默认值
API_KEYS	API Key 列表（逗号分隔）	-
BASE_CURRENCY	基准货币	CNY
CACHE_UPDATE_INTERVAL	缓存更新间隔（秒）	3600
REQUEST_TIMEOUT	请求超时时间（秒）	10
MAX_RETRIES	最大重试次数	3
SERVER_PORT	服务端口	8000

Hugging Face Spaces 配置参数

参数	说明	示例值
sdk	SDK 类型	docker
app_port	应用端口（Spaces 默认 7860）	7860
title	Space 标题	Exchange Rates Service
emoji	Space 图标	💱
colorFrom	渐变起始色	blue
colorTo	渐变结束色	green
pinned	是否固定在个人主页	false
license	开源协议	mit

🔑 API Key 获取

访问 ExchangeRate-API
注册账号（免费版每月 1500 次请求）
获取 API Key
配置到 .env 文件中

建议配置 3-5 个 API Key 以实现轮询，避免单个 Key 超限。

📝 注意事项

API 限制: 免费版 API 每月 1500 次请求，请合理设置缓存更新间隔
缓存策略: 汇率数据每日更新一次（UTC 00:00），建议缓存间隔设为 1 小时
Key 管理: 系统自动管理 Key 状态，失败的 Key 会进入冷却期
错误处理: API 请求失败时会自动重试并切换 Key

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License