实时天气数据api接口-openweather

想给应用加个实时天气，很多人第一反应是找接口、拼 URL、拿到 JSON 就完事。真接进项目才发现问题一堆：接口偶尔慢半拍，页面跟着卡；没做缓存，一刷新就打一次外网；上游挂了，整个首页白屏。这篇不讲概念，只讲把实时天气接进生产环境要提前定好的几个动作和判断标准。

想给应用加个实时天气，很多人第一反应是找接口、拼 URL、拿到 JSON 就完事。真接进项目才发现问题一堆：接口偶尔慢半拍，页面跟着卡；没做缓存，一刷新就打一次外网；上游挂了，整个首页白屏。这篇不讲概念，只讲把实时天气接进生产环境要提前定好的几个动作和判断标准。

下面按「先跑通、再定边界、再做兜底、最后验收」的顺序走。每一步都给判断标准和落地动作，你可以照着抄进自己的接入清单，也可以按项目实际情况裁剪。

先把请求发出去：Key、端点与最小可用调用

拿到密钥后别急着封装 SDK，先在命令行或 Postman 里跑通一次，确认返回结构就是你预期的那几个字段。很多接入问题其实出在这一步没做：字段名对不上、嵌套层级猜错、单位不是你要的，后面写代码全是返工。

1. 先跑通一次原始请求用最朴素的方式发一次请求，把返回体完整看一遍，圈出你真正要用的字段。确认无误再动手写封装。
2. 核对端点与参数名调用地址、参数名、计量单位以官方文档为准。单位制、语言、城市写法这三项最容易导致「明明有 Key 却返回空数组」，逐个对一遍。
3. 把「能调通」和「调用量怎么算」分开验调通看的是状态码与返回体；计费口径去 /official-api 对照当时的口径说明，不要用自己的猜测估额度。

超时、重试与限流的边界怎么定

天气接口对大多数应用来说只是辅助信息，不值得让主流程等它。所以第一件事是给它设一个明显短于主流程的超时，并确保主流程里有「拿不到就跳过」的分支，而不是让页面干等。

同一时间批量拉多个城市时，先把并发压到个位数跑一轮，看返回速度和失败率，再决定要不要往上加。延迟基线可以参考 /tools/speed-test 量出的当时数字，别凭感觉定上限。

缓存与降级：让页面在上游抽风时还能看

天气数据天然适合缓存：按城市加一个短周期缓存，命中就直接返回，既省调用量也压延迟。周期多长取决于你对「实时」的容忍度——展示型页面可以放宽，做提醒或预警类的就别缓存太久。

• 缓存里存「最后一次成功的结果 + 时间戳」，上游失败时降级返回这份旧数据。
• 降级时在界面上标一个「数据可能延迟」的提示，比直接报错体验好得多。
• 降级策略要写进代码而不是写在文档里：判断条件是「上游连续失败几次」或「超时超过多少」，触发后走哪条分支，提前定好。
• 缓存和降级都要能单独关闭，方便排查问题时快速回归原始调用。

需要说明一个不适用的情况：如果你的场景对时效性要求极高、旧数据反而会误导用户，那宁可显式报错也不要降级返回旧值。这类场景要把「无数据」当成一个正常状态来设计界面。

日志字段与上线前的自查清单

上线之后出问题，能救你的只有日志。别等出事了才发现日志里什么都没有。每次调用至少记下面这六个字段，覆盖绝大多数事后排查场景。

请求时间

用来对齐上游故障时段和限流窗口

城市参数

确认是不是某个城市的写法有问题

耗时

判断是上游慢还是自己这边排队

状态码

区分参数错、鉴权错还是上游故障

是否命中缓存

确认缓存真的在工作，而不是形同虚设

是否走了降级

出问题时能快速判断用户看到的是新数据还是旧数据

上线前跑一遍三种场景：正常返回、故意写错 Key、故意断网。三种都能按预期表现（有数据 / 明确报错 / 走降级），才算接入完成。若走的是中转或代理通道，先确认接口通不通再谈业务逻辑，验证方法参考 /tools/verify；换通道后要重跑上面三种场景。

接入完成的标志不是「能拿到数据」，而是「拿不到数据时你知道会发生什么」。