如果你刚好需要在业务后台接入天气展示能力或者想用一个小而完整的项目把接口开发、第三方数据源对接、缓存设计、前端页面整个串起来那么从零写一个“天气系统初版”是非常合适的切入点。它不像支付、订单那样涉及复杂状态机也没有太高的算法门槛但完整覆盖了一个后端服务从设计到上线的关键环节。需要先说明这里的“初版”并不是要做成一个完整的气象信息平台而是先交付一个能跑通主流程的最小系统。我们的目标很明确用户输入一个城市名系统能返回当前的气温、天气现象、湿度和风向重复查询时能命中缓存避免每次都去请求外部数据源接口结构清晰日志完整后续可以平滑替换真实天气服务商。本文会按照真实项目里的开发次序从需求拆分、架构设计、环境准备到完整代码实现、运行验证、常见问题排查最后给出初版系统向工程化演进的最佳实践。代码可以直接复制到本地运行即使没有真实天气 API Key也能通过 Mock 数据源先把流程跑通。1. 天气系统初版先想清楚边界1.1 初版到底做什么所谓“初版”核心目标是验证主流程而不是堆功能。我建议第一版只做这三类能力提供 HTTP 接口支持通过城市名查询实时天气对查询结果做短时间缓存减少第三方接口调用次数提供一个简单的可视化页面方便人工验证和演示。接口返回的数据结构可以先固定下来。比如统一返回气温、天气现象、相对湿度、风向、更新时间、数据来源这几个字段。页面不需要多精致能把 JSON 结果展示出来即可。至于用户登录、历史天气、未来预报、天气预警推送、多城市收藏等功能应该放在初版范围之外。过早加入太多功能会让项目陷入“接口写不完、异常测不全”的状态。先让主链路跑通比一次性设计一个庞大系统更重要。1.2 为什么适合作为入门实战项目天气系统是一个很经典的第三方数据集成场景它具备以下特点边界清晰业务规则不复杂适合初学者理解数据源可以替换可以先 Mock 后接真实 API便于本地开发和测试涉及缓存、超时、异常处理、日志等工程问题能训练后端基础能力结果可视化直观容易获得正向反馈。“初版”这个名字本身就代表了一种工程策略不做过度设计但设计上保留演进空间。所以我们会在代码中引入数据源适配层和缓存层而不是把所有逻辑都堆在一个函数里。1.3 需要先理解的两个概念第一个概念是 Mock 数据源。真实天气接口通常需要申请 Key、配置白名单、还可能受调用次数限制。为了本地开发和联调方便我们先编写一个返回固定数据的 Provider等系统跑通后再切换成真实 HTTP 数据源。这样做的好处是开发早期不会被外部接口的不确定性阻塞。第二个概念是数据源适配层。业务代码不应该关心数据到底是来自 Mock 还是来自第三方 HTTP 接口它只面向一个统一的数据获取方法。后续要切真实服务商时只需要新增一个 Provider 实现不需要改动业务层和 Web 层代码。2. 系统整体设计2.1 模块如何划分参考分层思路我们把天气系统初版拆成四层Web 层Flask 路由负责接收请求、参数校验、统一响应业务层天气服务负责先查缓存、再查数据源、组装返回值数据源层负责从 Mock 或第三方 HTTP 接口获取原始天气数据缓存层负责提供带过期时间的数据读写能力。请求流转路径可以理解为浏览器 / curl 请求 ↓ Flask 接口层 ↓ 天气服务层 WeatherService ↓ ↘ 数据源 Provider 缓存 Cache业务层是核心。它决定了一个请求是先返回缓存结果还是需要回源到数据源重新获取。数据源层相对独立后续替换为真实服务商时只需要替换依赖的 Provider 实现。2.2 查询主流程一次正常的天气查询会经历下面几步用户传入城市名Web 层做基础校验业务层根据城市名构造缓存 Key如果缓存有值直接反序列化返回如果缓存没有值调用 Provider 获取最新数据拿到数据后写入缓存并设置过期时间回到 Web 层统一包装成 JSON 响应。需要注意写入缓存的是返回给用户的数据并非简单地把第三方接口原始 JSON 原样放入。这样做的原因是为了隔离数据源差异。一旦服务商修改了字段结构只需要改 Provider 的组装逻辑缓存和接口层都不受影响。2.3 缓存策略如何设计天气数据本身具备短时有效性对于一个展示型页面来说10 分钟以内的缓存通常可以接受。如果遇到强对流天气等场景再考虑单独设计预警通道而不是让常规查询接口实时回源。缓存 Key 建议带上 Provider 名称和城市名避免切换数据源后读到旧数据。比如weather:mock:北京 weather:http:北京初版并不强制依赖 Redis。为了降低本地启动成本我提供两种缓存实现本地内存缓存和 Redis 缓存。如果 Redis 可用优先使用 Redis如果 Redis 没有启动自动降级到内存缓存。这样不同环境下的同学都能跑通项目。2.4 为什么先做 Mock 数据源接入真实第三方服务时你会发现不同天气服务商的请求参数、鉴权方式、返回字段、错误码都不太一样。如果一开始就绑定具体平台后续更换成本会很高。先实现 Mock 数据源可以先把“业务接口设计、 JSON 结构、缓存逻辑、前端展示”这些我们可控的部分开发完。等确认主流程没有问题再集中精力处理真实数据源的字段映射和鉴权逻辑排查范围会小很多。3. 环境准备与项目初始化3.1 环境说明与依赖版本本文示例使用 Python 开发推荐 Python 3.9 及以上版本。涉及的第三方库如下Flask用于提供 Web 接口requests用于调用真实天气 HTTP 接口redis用于 Redis 客户端连接pytest仅用于自动化测试非运行必需。版本号建议使用如下范围。具体版本会根据你的系统环境略有差异请以实际安装结果为准flask2.2,3.1 requests2.28,3 redis4.5,5 pytest7.0,9我没有把 pytest 和运行依赖混在一起。实际项目中可以将测试依赖单独放到requirements-dev.txt避免生产环境安装多余的包。本文为了便于演示统一写在 requirements.txt 中。3.2 项目目录结构建议按照下面的目录结构组织项目weather-system/ ├── app.py # Flask 入口 ├── config.py # 配置读取 ├── requirements.txt # 依赖清单 ├── services/ │ ├── __init__.py │ ├── cache_service.py # 缓存实现与自动降级 │ ├── weather_client.py # 数据源 Provider │ └── weather_service.py # 业务服务 ├── templates/ │ └── index.html # 演示页面 └── tests/ └── test_weather_service.pyservices目录用来存放核心业务代码templates目录用来存放页面模板tests目录用来存放自动化测试。这样每个文件职责单一便于后续扩展。如果你的项目后期变大还可以继续拆分出api、routers、schemas等目录。3.3 创建虚拟环境与安装依赖在项目根目录执行cd weather-system python -m venv venv source venv/bin/activate pip install -r requirements.txtWindows 系统激活虚拟环境的命令是venv\Scripts\activate依赖安装完成后我们可以先启动 Redis 用于验证缓存降级和命中效果。如果本地没有 Redis也没有关系代码会自动降级到内存缓存。3.4 配置项一览为了让配置项更清晰我通过环境变量来管理配置。以下是初版涉及的配置项配置项默认值说明WEATHER_DATA_SOURCEmock数据源类型可选 mock 或 httpWEATHER_API_URL空第三方天气接口地址WEATHER_APP_ID空第三方平台应用 IDWEATHER_APP_SECRET空第三方平台密钥CACHE_ENABLEDtrue是否开启缓存CACHE_TYPEautoauto / memory / redisCACHE_TTL600缓存过期时间单位秒REDIS_HOST127.0.0.1Redis 地址REDIS_PORT6379Redis 端口REDIS_DB0Redis 数据库编号REDIS_PASSWORD空Redis 密码在“mock”模式下即使不配置天气服务商和 Redis服务也能正常启动。只有在切换为“http”模式时才需要填写真实的数据源信息。4. 核心代码实现4.1 配置文件 config.py文件路径config.pyimport os from pathlib import Path BASE_DIR Path(__file__).resolve().parent class Config: # 数据源配置 WEATHER_DATA_SOURCE os.getenv(WEATHER_DATA_SOURCE, mock).lower() WEATHER_API_URL os.getenv(WEATHER_API_URL, ) WEATHER_APP_ID os.getenv(WEATHER_APP_ID,