Python+Flask气象实时采集系统：从API到页面展示的完整实践

如果你只想把一个后端项目完整跑通，体验“采集—存储—展示”这条链路是怎么闭合的，我很推荐拿“气象实时采集系统”来动手。这个话题在Python和Flask的入门圈里算不上新鲜，但很多教程只教你打印几行爬虫结果，或者做一个hello world页面，真正把数据一路从接口送到浏览器里的示例反而少。这篇文章就把我实操这套系统的过程写透：怎么选型、采集层怎么写、Flask后端怎么组织、前端怎么渲染，以及部署运行中会遇到哪些坑。无论是刚学完Python语法想练手，还是已经在做Flask项目但没碰过定时采集的，都可以参考。

1. 为什么做一套气象实时采集系统：先拆需求再定技术栈

1.1 这个系统到底要解决什么问题

很多人第一次看到“气象实时采集”会觉得有点抽象，以为要接传感器、搞硬件。实际上它解决的是一类非常典型的业务问题：我有一个远程数据源，数据变化频繁，我要稳定地把数据抓回来，存下来，再通过网页让别人随时查看。气象数据只是这类问题的载体，把载体换成股票行情、商品价格、服务器监控指标，思路完全一致。

所以我一开始并没有把自己限定在“气象”两个字里，而是把它当成一个“带定时任务的Web应用”来做。目标很明确：每隔一段时间从天气服务商的接口拉取指定城市的实时天气，解析出温度、湿度、风力、风向、天气现象等字段，写入本地数据库，并提供两个入口给用户——一个是页面展示，一个是JSON接口，方便后续被其他程序调用。

这样的需求拆解完成后，功能点就很清晰了：

• 外部数据接入：通过HTTP请求获取目标城市的天气JSON数据。
• 字段清洗与标准化：不同数据源返回的字段层级不一样，必须统一成自己的结构。
• 数据持久化：把每次采集结果存入数据库，保留时间戳，便于查历史。
• 定时调度：采集不是一次性的，需要按固定周期自动执行。
• Web展示：能通过浏览器看到当前天气和最近一段时间的采集记录。
• 接口输出：预留一个轻量API，方便前端或手机端获取结构化数据。

1.2 技术选型：为什么落在Python和Flask上

后端框架不止Flask一个，采集语言更不止Python，这里需要把我选型的逻辑说明白，不然新手很容易照抄完代码还是不知道为什么这么配。

先说采集侧。Python之所以适合做这种轻量采集，核心在于它的标准库加第三方库组合非常省事。requests库把HTTP连接、请求头、超时处理都封装得足够顺手；内置的json模块能直接处理接口返回；datetime库负责时间格式化。对于“定时抓一次JSON然后入库”这个动作，Python几乎是表达成本最低的语言。

再说Web框架。Flask的优势是“轻”和“易理解”。它不像Django那样内置了ORM、Admin后台、表单组件等一整套东西，启动一个服务只需要几行代码，路由就是一个装饰器，新手能很直观地看到请求是如何被处理的。我个人的建议是，做采集展示类的小系统，Flask的上手效率最高。如果项目后续扩展成复杂的长链条业务，再迁移到FastAPI或者Django也不迟，没必要第一步就上重型框架。

数据存储我用了SQLite，没有上MySQL。原因很朴素：这个场景的数据量一天也就几百条记录，SQLite一个文件就能搞定，不需要额外维护数据库服务。等到采集城市增多、存储期限变长，再替换成MySQL或者PostgreSQL，只需要改数据库连接层，业务代码不用大动。

前端展示则尽量用Flask自带的Jinja2模板加一点点Bootstrap样式。重点是让数据看起来清晰，而不是引入一套前后端分离的工程结构。这里我特意控制了自己“想上Vue”的冲动——项目初期用服务端渲染，页面刷新逻辑最简单，出问题的概率最低。

2. 数据入口设计：从接口拿回结构化气象数据

2.1 数据源选型的实际经验

很多教程不敢说数据源怎么选，因为实际可用的免费天气接口其实不少，但各有各的限制。我当时选型时考虑了三点：稳定性、字段完整度、是否需要Key。

公开的匿名接口优势是零门槛，拿来就能测，但限流严重，字段也经常变化，不适合做长期运行的系统。带开发者Key的服务商接口相对靠谱，会在你申请后给你一个专属地址，返回字段有文档可查，请求频率也在可接受范围内。

这里我以一个返回JSON的天气服务商API为例，字段结构是这类服务的典型风格。你实际操作时，只需按你自己申请的接口文档调整字段名和URL即可。

python复制import requests

# 示例配置，实际请使用你自己的API地址和Key
API_URL = "https://your-weather-provider.example/api/weather/now"
API_KEY = "你的_Key"

params = {
    "location": "101010100",      # 城市代码，不同服务商格式不同
    "key": API_KEY,
    "unit": "metric"
}

resp = requests.get(API_URL, params=params, timeout=10)
print(resp.status_code)
print(resp.json())

从我的实测经验看，这类接口返回的数据通常包裹在两层结构里，最外层是状态码和消息，内层才是真正的业务数据。写代码前一定要先打印一次完整返回值，对着真实结构再写解析，不要靠猜。

2.2 用requests抓数据时容易忽略的三个细节

抓取接口本身不难，难的是让它稳定地跑上几天不出幺蛾子。我踩过的坑基本集中在这三个地方。

第一是请求必须设超时。requests.get()如果不传timeout，默认会一直等下去，一旦服务端连接异常，你的定时任务就会被卡死，后面的采集全部积压。我通常设10秒，并配合异常捕获。

第二是请求头要模拟浏览器。有些服务商对裸的Python请求会做拦截，主动带上User-Agent、Accept等请求头之后，通过率明显提高。

第三是状态码和业务状态码要双重校验。服务商接口即使返回200，业务字段里也可能提示当前Key异常、超过限额等。所以代码里不能只看HTTP状态，还要解析业务码。

python复制import logging
import requests

HEADERS = {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "Accept": "application/json"
}

def fetch_weather(location_code: str) -> dict:
    params = {
        "location": location_code,
        "key": API_KEY,
        "unit": "metric"
    }
    try:
        resp = requests.get(API_URL, params=params, headers=HEADERS, timeout=10)
        resp.raise_for_status()
        payload = resp.json()
    except requests.exceptions.Timeout:
        logging.error("请求天气接口超时")
        return {}
    except requests.exceptions.RequestException as e:
        logging.error(f"请求失败: {e}")
        return {}
    except ValueError:
        logging.error("返回内容不是合法JSON")
        return {}

    # 业务状态码校验
    if payload.get("code") != "200":
        logging.error(f"接口业务异常: {payload.get('code')}")
        return {}

    return payload.get("data", {})

这样的采集函数返回空的dict时，上层定时任务就可以选择跳过本次写入，而不是把脏数据存进数据库。

2.3 字段清洗：把接口数据变成统一结构

不同的天气服务商，温度字段可能是temp，可能是temperature，还可能是摄氏度与华氏度并存。风速有的给windSpeed，有的给windSpeedLevel。如果代码和字段强耦合，后期换服务商会非常痛苦。

我的做法是在采集函数下面加一层清洗逻辑，把外部字段映射成自己系统的内部结构。以后就算服务商改了字段，也只需要改这一层映射函数，其他代码完全不用动。

python复制def clean_weather_data(raw: dict) -> dict:
    return {
        "city_code": raw.get("cityCode", ""),
        "city_name": raw.get("city", "未知"),
        "temperature": raw.get("temp", 0),
        "feels_like": raw.get("feelsLike", 0),
        "humidity": raw.get("humidity", 0),
        "wind_dir": raw.get("windDir", ""),
        "wind_scale": raw.get("windScale", ""),
        "weather_desc": raw.get("text", ""),
        "collect_time": datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    }

这段代码里我把采集时间放到了最后，意味着每条记录从生成那一刻就带着时间戳。后面做时序查询时，这个字段就是排序和过滤的核心依据。

3. Flask应用怎么组织：路由、定时任务与本地存储

3.1 一个值得借鉴的目录结构

Flask项目最怕的就是把所有代码塞进一个app.py里。前期确实方便，但一旦你加入定时任务、数据采集、数据库操作、页面路由，这一个文件很快就会超过几百行，越改越乱。

我建议哪怕是练手项目，也用下面这种简单的分层结构。不炒概念，但能让你一眼看清“采集逻辑”和“Web逻辑”的边界。

text复制weather_project/
├── app.py                  # Flask应用入口，注册路由
├── weather_crawler.py      # 采集与清洗逻辑
├── database.py             # 数据库连接与初始化
├── scheduler.py            # 定时任务启动
├── requirements.txt
├── templates/
│   └── index.html
└── weather.db              # SQLite数据库文件（运行后生成）

把采集模块拆出来之后，你可以在命令行单独测试天气抓取逻辑，而不用启动整个Web服务。这种“模块可以独立调试”的状态，是代码结构好坏的一个重要指标。

3.2 数据库表设计与写入细节

SQLite的建表语句不需要ORM就能写得非常清晰。考虑到后面要展示最近24小时的温度曲线，数据表设计必须能支撑按时间范围查询。

sql复制CREATE TABLE IF NOT EXISTS weather_records (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    city_code TEXT NOT NULL,
    city_name TEXT NOT NULL,
    temperature REAL NOT NULL,
    feels_like REAL,
    humidity INTEGER,
    wind_dir TEXT,
    wind_scale TEXT,
    weather_desc TEXT,
    collect_time TEXT NOT NULL
);

CREATE INDEX IF NOT EXISTS idx_city_time 
ON weather_records(city_code, collect_time);

这里有几个细节值得解释。温度用REAL而不是INTEGER，是因为部分接口会返回类似23.5的小数，用整型会丢失精度。collect_time用TEXT存格式化后的时间字符串，在日常展示场景下查询最简单，但如果你要做跨时区的复杂统计，更规范的做法是存Unix时间戳。我给city_code和collect_time建了联合索引，因为后续最高频的查询就是“查某个城市某段时间的记录”。

写入操作直接使用Python内置的sqlite3模块即可，不需要额外引入SQLAlchemy。需要特别注意的是，SQLite默认不允许跨线程共用连接对象，而Flask开发模式下定时任务和请求处理可能运行在不同线程中，所以要在每次写入时新建连接，用完关闭，避免sqlite3.ProgrammingError。

3.3 定时任务如何优雅地融入Flask

如果只在请求处理里写time.sleep(60)假装定时，那页面会一直转圈。正确做法是引入APScheduler库，用后台调度器在独立线程中按周期执行采集函数。

python复制from apscheduler.schedulers.background import BackgroundScheduler

scheduler = BackgroundScheduler(timezone="Asia/Shanghai")

def start_scheduler():
    scheduler.add_job(
        collect_and_save,          # 采集并入库的任务函数
        trigger="interval",
        minutes=30,
        id="weather_collect_job",
        replace_existing=True
    )
    scheduler.start()

为什么用interval而不是cron？因为这个系统关心的是“每隔多久采集一次”，不是“每天几点几分采集”，所以用固定间隔触发最简单直观。如果需要每天凌晨清点库存之类的任务，再改用cron触发器也不复杂。

这里有一个Flask特有的坑：定时任务里如果要使用Flask的配置项，不能直接在回调函数里调用current_app，因为后台调度器运行的上下文并不在Flask的请求上下文内。我当时采集模块本身不依赖Flask的配置，所有参数都是从环境变量读取的，所以没有踩进去。如果你非要在任务里访问应用配置，就得在函数外把配置保存成全局变量，或者在任务函数内部用app.app_context()手动推入上下文。

3.4 核心路由与JSON接口

系统的路由不需要复杂，我保留了三个，基本对应一个完整的展示闭环。

python复制from flask import Flask, render_template, jsonify, request
import database

app = Flask(__name__)

@app.route("/")
def index():
    latest = database.get_latest_record()
    history = database.get_recent_records(hours=24)
    return render_template("index.html", latest=latest, history=history)

@app.route("/api/weather")
def api_weather():
    city_code = request.args.get("city_code", "101010100")
    limit = int(request.args.get("limit", 10))
    records = database.get_records_by_city(city_code, limit=limit)
    return jsonify({
        "code": 0,
        "data": records
    })

if __name__ == "__main__":
    start_scheduler()
    app.run(host="0.0.0.0", port=5000, debug=False)

注意debug参数我专门设成了False。看起来无关紧要，实际影响很大：Flask的debug模式会启动一个独立的reloader进程，如果定时任务写在主模块里，reloader会导致调度器被重复启动，产生两份定时任务。这个坑我在后面会展开讲。

4. 把实时数据变成页面：渲染方案与模板实现

4.1 先页面刷新还是先Ajax轮询

项目做到这里，数据库里已经有数据了，剩下的是“怎么把数据呈现出来”。我见过不少新手一上来就磕前后端分离，非要用Vue发请求。但对这个规模的项目，最简单可靠的方式是用Jinja2模板做服务端渲染。

用户访问根路径时，后端直接从数据库取数据塞进模板，返回一个完整的HTML页面。页面里再放一段原生JavaScript，每隔30秒用fetch请求/api/weather，拿到最新数据后只更新页面上的某个区域。这样既有“实时感”，又不需要引入前端工程化工具链。

为什么不全靠浏览器自动刷新？因为整页刷新会闪烁，而且会白等网络加载；为什么不直接全用WebSocket？因为技术跨度太大，对新手不友好，且天气数据每分钟变化不大，轮询完全够用。

我给页面设计的信息区块主要有三块：当前实时天气的大卡片、最近24小时记录表格、以及一个简单的提示文案。样式用了Bootstrap的卡片和表格，稍微写一点自定义CSS，不用额外下载图标库。

4.2 模板里怎么写才有扩展性

直接展示单条最新记录很容易，难的是让模板结构能平缓扩展。我在编写index.html时把“单条最新记录”和“历史记录表”分成了两个独立区域，这样后续加城市切换、加图表时不用推翻整体布局。

html复制<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>实时气象监测</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css">
    <style>
        body { background: #f0f4f8; }
        .weather-card { max-width: 700px; margin: 40px auto; }
        .temp-num { font-size: 48px; font-weight: 700; }
    </style>
</head>
<body>
<div class="container">
    <div class="card weather-card">
        <div class="card-body text-center">
            <h2 id="cityName">{{ latest.city_name }}</h2>
            <div class="temp-num" id="temp">{{ latest.temperature }}&deg;C</div>
            <p class="text-secondary" id="weatherDesc">{{ latest.weather_desc }}</p>
            <div class="row mt-3">
                <div class="col-4">湿度 <span id="humidity">{{ latest.humidity }}%</span></div>
                <div class="col-4">风向 <span id="windDir">{{ latest.wind_dir }}</span></div>
                <div class="col-4">风力 <span id="windScale">{{ latest.wind_scale }}级</span></div>
            </div>
            <div class="text-muted mt-3" id="collectTime">采集时间：{{ latest.collect_time }}</div>
        </div>
    </div>

    <div class="card">
        <div class="card-header">最近24小时采集记录</div>
        <div class="card-body">
            <table class="table table-sm table-striped">
                <thead>
                    <tr>
                        <th>采集时间</th>
                        <th>温度</th>
                        <th>湿度</th>
                        <th>天气</th>
                        <th>风向风力</th>
                    </tr>
                </thead>
                <tbody>
                    {% for item in history %}
                    <tr>
                        <td>{{ item.collect_time }}</td>
                        <td>{{ item.temperature }}</td>
                        <td>{{ item.humidity }}%</td>
                        <td>{{ item.weather_desc }}</td>
                        <td>{{ item.wind_dir }} {{ item.wind_scale }}级</td>
                    </tr>
                    {% endfor %}
                </tbody>
            </table>
        </div>
    </div>
</div>
<script>
function refresh() {
    fetch('/api/weather?limit=1')
        .then(res => res.json())
        .then(result => {
            if (result.code === 0 && result.data.length > 0) {
                const d = result.data[0];
                document.getElementById('cityName').textContent = d.city_name;
                document.getElementById('temp').innerHTML = d.temperature + '&deg;C';
                document.getElementById('weatherDesc').textContent = d.weather_desc;
                document.getElementById('humidity').textContent = d.humidity + '%';
                document.getElementById('windDir').textContent = d.wind_dir;
                document.getElementById('windScale').textContent = d.wind_scale + '级';
                document.getElementById('collectTime').textContent = '采集时间：' + d.collect_time;
            }
        })
        .catch(err => console.error(err));
}
setInterval(refresh, 30000);
</script>
</body>
</html>

这段模板有几点当初我写的时候踩过坑。Jinja2的{{ latest.temperature }}之后不要再加单位，单位放到HTML里，避免数据库数据和展示格式耦合。Ajax更新页面时，textContent和innerHTML各用各的，温度里带°特殊符号时只能用innerHTML。

4.3 历史记录表格要留分页的口子

表格区域现在看起来简单，但如果系统跑了一周，记录数很可能上千条。继续用get_recent_records(hours=24)虽然没问题，但如果把范围扩大到“全部历史”，页面就会变得沉重。所以我把数据库查询函数的参数设计成可传小时数、城市代码、条数限制，后续改造成分页时，只需要加offset和limit，模板不用动。

实际上，在模板的表格下方我预留了一个页码占位区，只是当前没有填充内容。这是刻意的——很多项目改着改着就需要分页，提前在HTML里留位置能省很多事。

5. 运行部署与踩坑汇总：把系统真正跑起来

5.1 首次启动全流程

本项目不引入Docker，保持最低部署门槛。依赖只有四个核心库，写进requirements.txt：

text复制flask>=2.2
requests>=2.28
apscheduler>=3.10

首次启动的关键步骤大概是这样的。首先准备好Python 3.8以上环境，建议用虚拟环境隔离依赖：

bash复制python -m venv venv
source venv/bin/activate   # Windows下使用 venv\Scripts\activate
pip install -r requirements.txt
python weather_crawler.py  # 先手动测试采集函数是否正常
python app.py              # 启动Flask应用并启动定时任务

浏览器访问http://127.0.0.1:5000，如果看到当前天气数据，说明链路已通。此时强制刷新几次页面，观察表格中的记录是否在增长。要注意，定时任务默认30分钟执行一次，等第一条新记录入库可能需要几分钟，如果你想快速验证，可以把调度间隔临时改成1分钟。

5.2 踩坑记录一：debug模式导致的定时任务双开

这是我碰到过最迷惑的问题。系统跑起来后发现数据库里每隔很短时间就会多出两条几乎一样的记录，而且两条记录的间隔只有一两秒。排查了很久才意识到，根因是启动时用了debug=True。

Flask的debug模式下会启动一个监视代码变更的reloader进程，它会重新加载主模块。如果主模块顶部直接实例化了BackgroundScheduler并立即start，那么这个调度器会在父进程和儿子进程各启动一次。解决办法有三个：直接设debug=False；或者把定时任务启动放在一个独立函数里只在主进程中调用；或者用环境变量判断当前是否处于Werkzeug的reloader子进程中。新手最省心的方案就是开发调试和正式运行都用debug=False，改代码后手动重启服务，不依赖热加载。

5.3 踩坑记录二：写入SQLite时的线程报错

系统连续运行几个小时后，我在日志里看到了sqlite3.ProgrammingError: SQLite objects created in a thread can only be used in that same thread。这是因为APScheduler的后台线程里创建了数据库连接并用它写入，但Flask请求线程或另一个调度周期里又尝试复用了这个连接。

我之前提过一个原则：不缓存sqlite3连接，在每次读写时临时创建连接。这里用代码表达会更直观：

python复制import sqlite3

def save_weather_record(record: dict):
    conn = sqlite3.connect("weather.db")
    cursor = conn.cursor()
    cursor.execute(
        """
        INSERT INTO weather_records
        (city_code, city_name, temperature, feels_like, humidity,
         wind_dir, wind_scale, weather_desc, collect_time)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
        """,
        (
            record["city_code"], record["city_name"],
            record["temperature"], record["feels_like"],
            record["humidity"], record["wind_dir"],
            record["wind_scale"], record["weather_desc"],
            record["collect_time"]
        )
    )
    conn.commit()
    conn.close()

频繁开关连接确实有一定性能开销，但在这个数据量下完全无所谓。换来的好处是彻底规避了跨线程连接复用问题，代码也更干净。如果未来并发量上来，再换成带连接池的数据库不迟。

5.4 踩坑记录三：采集时间与本地时间不一致

服务商接口返回的utc时间字段直接存进去之后，页面展示的采集时间会比本地时间慢8小时。刚开始我以为是时区配置问题，后来发现是自己在清洗层用了接口回传的时间，而不是本机的datetime.now()。

这事的教训是：采集系统里的记录时间应该以采集行为发生时间为准，不是以数据源返回的字段时间为准。如果你要分析的是气象本身的时间维度，那另当别论；但如果是衡量“系统多久采一次”，就必须使用本地采集时间。我的清洗函数里直接写成datetime.now().strftime(...)，彻底不信任数据源的utc字段。

5.5 系统运行稳定性与后续扩展方向

系统已经稳定跑了一阵子后，我回头看，觉得有几点可以再往深处扩展。温度数据是连续变化的，如果保存了足够长的历史，完全可以用前端图表库展示一段时间内的温度折线。这个实践切到ECharts非常快：在页面里引入ECharts的CDN，后端新增一个返回时间序列的接口，几十行代码就能把曲线画出来。这也是我建议保留历史数据而不只是存“当前值”的原因——数据的价值在积累中才会体现。

还可以把采集周期从30分钟改成5分钟，只要调用服务商接口的频率不超限就可以。对于多城市采集，最简单的做法是维护一个城市代码列表，循环调度每个城市。这种情况下，数据库查询的联合索引就会真正发挥作用。

跑这类系统的过程中，我最明显的感受是：天气预报本身并不是难点，难点在各种外围问题——数据源稳定性、任务是否重复执行、线程间的状态隔离、时间字段口径统一。这些问题只靠读文档很难遇到，非得自己把系统跑上几天才会暴露。好在这些问题都不深，理清一次之后，这类“采集+调度+展示”的应用结构就再也难不住你了。