README.md

---
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. 克隆项目

```bash
cd C:\Users\Eleven\Desktop\exchangeRates
```

### 2. 创建虚拟环境

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

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置环境变量

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

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

# 基准货币
BASE_CURRENCY=CNY

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

### 5. 启动服务

```bash
python run.py
```

或者使用 uvicorn 直接启动：

```bash
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 配置：

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

#### 2. 创建 Dockerfile

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

```dockerfile
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. 部署步骤

1. 在 [Hugging Face](https://huggingface.co/) 创建新的 Space
2. 选择 Docker SDK
3. 上传项目文件或连接 Git 仓库
4. 在 Settings 中配置 Secrets
5. Space 将自动构建和部署

#### 5. 访问服务

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

## 📡 API 接口

### 获取所有汇率

```http
GET /api/rates
```

响应示例：
```json
{
  "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
}
```

### 获取特定货币汇率

```http
GET /api/rates/{currency}
```

示例：`GET /api/rates/USD`

### 货币换算

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

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

或使用 GET 方式：

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

### 批量换算

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

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

或使用 GET 方式：

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

### 获取货币列表

```http
GET /api/currencies
```

### 服务状态

```http
GET /api/status
```

### 强制刷新缓存

```http
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 获取

1. 访问 [ExchangeRate-API](https://www.exchangerate-api.com/)
2. 注册账号（免费版每月 1500 次请求）
3. 获取 API Key
4. 配置到 `.env` 文件中

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

## 📝 注意事项

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

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License