一刻天气API返回数据为空或404错误如何排查？

Question

**一刻天气API返回空数据或404错误的常见原因及排查要点：** 首先确认请求URL是否正确——一刻天气已停止公开服务（官网于2023年下线，API域名`api.yiketianqi.com`已不可用），多数404实为服务终止所致；其次检查是否误用旧版文档中的测试key或未迁移至其合作平台（如和风、心知等）；若仍能访问，需验证`cityid`/`location`参数格式是否符合当前接口规范（如新版要求`lang=zh`、`unit=c`显式声明）；使用curl或Postman复现请求，查看响应头`X-Api-Status`及完整body，排除因HTTPS跳转、Referer限制或IP频控导致的静默空响应；最后确认SDK版本是否过时（v1.x已废弃）。建议优先切换至高德、彩云或OpenWeather等稳定替代方案，并在代码中增加`404/empty`兜底降级逻辑。

Answer 1

```html

一、现象层：HTTP 404 与空响应的表征识别

当调用 https://api.yiketianqi.com/... 返回 404 Not Found 或 HTTP 200 但 body 为空（{}、null、空白字符串），即触发第一级告警。此阶段无需深究逻辑，仅做可观测性确认：检查浏览器开发者工具 Network 面板状态码、响应体长度、Content-Type 及是否发生 301/302 重定向。注意部分 CDN 会返回“伪装 200”的空 JSON，需结合 Response Headers 中 X-Api-Status: offline 等自定义字段交叉验证。

二、基础设施层：服务存续性与域名生命周期审计

• ✅ 官网于 2023年9月正式下线，备案主体注销，api.yiketianqi.com DNS 解析已失效（dig api.yiketianqi.com 返回 NXDOMAIN）
• ✅ 历史 SSL 证书已于 2023-Q4 过期，强制 HTTPS 访问将触发 TLS 握手失败（curl -v 可见 SSL certificate problem）
• ❌ 尝试 ping 或 telnet 该域名端口（80/443）均超时，证实服务物理下线，非临时故障

三、协议与参数层：请求合规性深度校验

维度	旧版（已失效）	当前有效替代方案要求
认证方式	testkey=xxx（公开测试密钥）	需注册和风天气（dev.heweather.com）或彩云天气开放平台获取正式 key
城市标识	cityid=101010100（纯数字编码）	必须使用标准 GeoID（如和风：location=101010100 或 adcode=110000；OpenWeather：q=Beijing, CN）
必选参数	无显式 lang/unit	lang=zh&unit=m/s（和风）、units=metric（OpenWeather）——缺失则返回 400 或静默降级为英文

四、传输与中间件层：静默失败根因定位流程图

flowchart TD
    A[发起请求] --> B{DNS 解析成功？}
    B -->|否| C[404/ERR_NAME_NOT_RESOLVED]
    B -->|是| D{TLS 握手通过？}
    D -->|否| E[SSL_ERROR_SSL / 证书过期]
    D -->|是| F[发送 HTTP 请求]
    F --> G{响应头含 X-Api-Status？}
    G -->|是| H[X-Api-Status: deprecated → 迁移指引]
    G -->|否| I[检查 Referer/CORS/UA 限制]
    I --> J[模拟 curl -H 'Referer: https://example.com' ...]

五、客户端与集成层：SDK 与代码治理实践

遗留项目中若仍引用 yiketianqi-sdk-js@1.2.5 或 Android com.yiketianqi:weather:v1.0，其内部硬编码了已失效 endpoint 且无 fallback 机制。建议执行以下操作：

1. 全局搜索 api.yiketianqi.com 并替换为高德地图 API：https://restapi.amap.com/v3/weather/weatherInfo?city=110000&key=YOUR_KEY
2. 在 Axios/Fetch 封装层统一注入兜底逻辑：
   if (res.status === 404 || !res.data || Object.keys(res.data).length === 0) { return getFallbackWeather(); }
3. 对所有天气接口调用添加 Sentry 异常监控标签：weather_provider: yiketianqi_deprecated

六、架构演进层：替代方案选型决策矩阵

基于稳定性（SLA ≥99.95%）、中文支持、免费额度及 SDK 成熟度综合评估：

• 高德地图天气 API：国内覆盖率最高，支持行政区划树+实况+预报+生活指数，免费 1000 次/日
• 彩云天气 OpenAPI：分钟级降水预报精度行业领先，提供雷达图与短临预警，需企业资质认证
• OpenWeatherMap：全球覆盖，支持多语言与历史数据回溯，但国内城市 ID 映射需额外维护

七、运维保障层：自动化巡检与熔断策略

在 CI/CD 流水线中嵌入健康检查脚本（Bash 示例）：

#!/bin/bash
# check_yiketianqi.sh
if curl -s -o /dev/null -w "%{http_code}" https://api.yiketianqi.com/ | grep -q "404\|000"; then
  echo "[CRITICAL] yiketianqi API is dead. Trigger migration alert." | mail -s "Weather API Down" [e-mail]
  exit 1
fi

同时在服务网格（如 Istio）中配置超时 + 重试 + 降级路由规则，将失败请求自动转发至备用天气源。

```