weather-data-api/README.md

Weather Data API

FastAPI 服务，用于接收气象站观测数据并存入 PostgreSQL，同时提供查询接口。

快速开始

1. 准备数据库

createdb weather_data

2. 配置环境变量

复制 .env.example 为 .env 并填入实际值：

cp .env.example .env

.env 内容：

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASSWORD=your_password_here
DATABASE_NAME=weather_data

3. 安装依赖

uv sync

4. 启动服务

uv run uvicorn app.main:app --reload

服务默认监听 http://localhost:8000，访问 /docs 查看 Swagger 文档。

---

API 端点

GET /stations — 列出所有气象站

获取所有已知气象站的列表（从观测数据中派生）。

成功响应（200）：

{
  "stations": [
    {
      "name": "北京站",
      "observation_count": 156,
      "latest_observation_at": "2026-06-19T11:45:00.654321+00:00"
    },
    {
      "name": "上海站",
      "observation_count": 89,
      "latest_observation_at": "2026-06-19T10:30:00.123456+00:00"
    }
  ],
  "count": 2
}

POST /stations/{station_name}/observations — 接收气象数据

请求体（JSON）：

{
  "temperature": 26.5,
  "pressure": 1013.2,
  "relative_humidity": 68.0
}

字段说明：

字段	类型	必填	说明
temperature	float	否	温度（摄氏度）
pressure	float	否	气压（hPa）
relative_humidity	float	否	相对湿度（%，0-100）

气象站名称从 URL 路径中获取，不再出现在请求体中。

成功响应（201）：

{
  "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 /stations/{station_name}/observations/latest — 查询最新数据

获取指定气象站的最新一条记录：

GET /stations/北京站/observations/latest

成功响应（200）：

{
  "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 /stations/{station_name}/observations — 查询历史数据

获取指定时间范围内的所有记录。支持两种查询方式：

按最近 N 小时查询：

GET /stations/北京站/observations?hours=24

按自定义时间范围查询：

GET /stations/北京站/observations?start=2026-06-19T00:00:00&end=2026-06-19T12:00:00

分页查询：

GET /stations/北京站/observations?limit=50&offset=0

参数说明：

参数	类型	说明
hours	int	从现在往前推 N 小时。如果同时指定了 start，则覆盖 start
start	datetime	时间范围起点（ISO 8601 格式，UTC），不传则不限制
end	datetime	时间范围终点（ISO 8601 格式，UTC），不传则默认到当前时刻
limit	int	返回的最大记录数
offset	int	跳过的记录数（用于分页），默认 0

成功响应（200）：

{
  "station_name": "北京站",
  "count": 2,
  "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"
    }
  ]
}

未找到匹配数据时返回空列表，气象站不存在时返回 404。

---

数据库表结构

列名	类型	说明
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 应用入口