192 lines
4.0 KiB
Markdown
192 lines
4.0 KiB
Markdown
# Weather Data API
|
||
|
||
FastAPI 服务，用于接收气象站观测数据并存入 PostgreSQL，同时提供查询接口。
|
||
|
||
## 快速开始
|
||
|
||
### 1. 准备数据库
|
||
|
||
```bash
|
||
createdb weather_data
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
复制 `.env.example` 为 `.env` 并填入实际值：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
`.env` 内容：
|
||
|
||
```
|
||
DATABASE_HOST=localhost
|
||
DATABASE_PORT=5432
|
||
DATABASE_USER=postgres
|
||
DATABASE_PASSWORD=your_password_here
|
||
DATABASE_NAME=weather_data
|
||
```
|
||
|
||
### 3. 安装依赖
|
||
|
||
```bash
|
||
uv sync
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
```bash
|
||
uv run uvicorn app.main:app --reload
|
||
```
|
||
|
||
服务默认监听 `http://localhost:8000`，访问 `/docs` 查看 Swagger 文档。
|
||
|
||
---
|
||
|
||
## API 端点
|
||
|
||
### POST `/data` — 接收气象数据
|
||
|
||
请求体（JSON）：
|
||
|
||
```json
|
||
{
|
||
"station_name": "北京站",
|
||
"temperature": 26.5,
|
||
"pressure": 1013.2,
|
||
"relative_humidity": 68.0
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `station_name` | string | 是 | 气象站名称 |
|
||
| `temperature` | float | 否 | 温度（摄氏度） |
|
||
| `pressure` | float | 否 | 气压（hPa） |
|
||
| `relative_humidity` | float | 否 | 相对湿度（%，0-100） |
|
||
|
||
成功响应（201）：
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"station_name": "北京站",
|
||
"temperature": 26.5,
|
||
"pressure": 1013.2,
|
||
"relative_humidity": 68.0,
|
||
"received_at": "2026-06-19T10:30:00.123456+00:00"
|
||
}
|
||
```
|
||
|
||
`received_at` 由服务端在收到数据时自动记录。
|
||
|
||
### GET `/data/{station_name}` — 查询最新数据
|
||
|
||
获取指定气象站的最新一条记录。站名支持中文，直接放在 URL 路径中即可：
|
||
|
||
```
|
||
GET /data/北京站
|
||
```
|
||
|
||
成功响应（200）：
|
||
|
||
```json
|
||
{
|
||
"id": 42,
|
||
"station_name": "北京站",
|
||
"temperature": 27.1,
|
||
"pressure": 1012.8,
|
||
"relative_humidity": 65.0,
|
||
"received_at": "2026-06-19T11:45:00.654321+00:00"
|
||
}
|
||
```
|
||
|
||
未找到数据时返回 404。
|
||
|
||
### GET `/data/{station_name}/history` — 查询历史数据
|
||
|
||
获取指定时间范围内的所有记录。支持两种查询方式：
|
||
|
||
**按最近 N 小时查询：**
|
||
|
||
```
|
||
GET /data/北京站/history?hours=24
|
||
```
|
||
|
||
**按自定义时间范围查询：**
|
||
|
||
```
|
||
GET /data/北京站/history?start=2026-06-19T00:00:00&end=2026-06-19T12:00:00
|
||
```
|
||
|
||
参数说明：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `hours` | int | 从现在往前推 N 小时。如果同时指定了 `start`，则仅影响 `start` |
|
||
| `start` | datetime | 时间范围起点（ISO 8601 格式，UTC），不传则不限制 |
|
||
| `end` | datetime | 时间范围终点（ISO 8601 格式，UTC），不传则默认到当前时刻 |
|
||
|
||
成功响应（200）：
|
||
|
||
```json
|
||
{
|
||
"station_name": "北京站",
|
||
"records": [
|
||
{
|
||
"id": 42,
|
||
"station_name": "北京站",
|
||
"temperature": 27.1,
|
||
"pressure": 1012.8,
|
||
"relative_humidity": 65.0,
|
||
"received_at": "2026-06-19T11:45:00.654321+00:00"
|
||
},
|
||
{
|
||
"id": 40,
|
||
"station_name": "北京站",
|
||
"temperature": 26.8,
|
||
"pressure": 1013.0,
|
||
"relative_humidity": 67.0,
|
||
"received_at": "2026-06-19T10:30:00.123456+00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
未找到匹配数据时返回空列表。
|
||
|
||
---
|
||
|
||
## 数据库表结构
|
||
|
||
| 列名 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | `BIGSERIAL` | 主键，自增 |
|
||
| `station_name` | `TEXT` | 气象站名称 |
|
||
| `temperature` | `DOUBLE PRECISION` | 温度 |
|
||
| `pressure` | `DOUBLE PRECISION` | 气压 |
|
||
| `relative_humidity` | `DOUBLE PRECISION` | 相对湿度 |
|
||
| `received_at` | `TIMESTAMPTZ` | 数据接收时间（服务端自动填充） |
|
||
|
||
表上有 `(station_name, received_at DESC)` 组合索引，支持按站名和时间的高效查询。
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
weather-data-api/
|
||
├── .env.example # 配置模板
|
||
├── pyproject.toml # 依赖声明
|
||
├── README.md
|
||
└── app/
|
||
├── __init__.py
|
||
├── config.py # 从 .env 加载数据库配置
|
||
├── database.py # asyncpg 连接池 + 数据库操作
|
||
├── models.py # Pydantic 模型
|
||
└── main.py # FastAPI 应用入口
|
||
```
|