腾讯天气API返回数据为空或404错误，如何排查？

Question

腾讯天气API返回空数据或404错误，常见原因有三：一是请求URL拼写错误或端点已下线（如旧版`weather.map.qq.com`已停用，需切换至新版`api.inews.qq.com`或官方开放平台接口）；二是AppID/Key未正确配置或权限未开通（需登录腾讯位置服务控制台确认配额、地域白名单及天气服务是否启用）；三是请求参数缺失或非法（如`location`格式不符规范、`region`非标准行政区编码、`time`超出支持范围）。建议按序排查：① 用Postman直调带完整Header（含Authorization）的请求，比对文档示例；② 检查响应Headers中的`X-Request-ID`与腾讯控制台日志匹配；③ 验证Token有效期及签名算法（HMAC-SHA256）实现是否合规。404多指向路径错误，空响应则常因城市无气象站覆盖或返回字段被静默过滤——务必查阅最新API文档的「响应说明」章节。

Answer 1

```html

一、现象层：HTTP状态码与响应体的表征特征

404错误明确指向服务端资源不可达，典型于请求路径（path）拼写错误、协议升级后旧域名停用（如weather.map.qq.com已于2022年Q4全量下线），或API版本路由变更未同步更新；而空响应（HTTP 200 + 空JSON body 或 {"ret":0,"data":{}}）则无网络层异常，但业务逻辑层未返回有效气象数据。二者需区分诊断——前者属基础设施连通性问题，后者属数据供给链路中断。

二、协议层：URL结构与认证机制的合规性校验

• 新版腾讯天气API统一入口为：https://api.inews.qq.com/weather/（含/v1/weather、/v2/forecast等子端点）
• 必须携带Authorization: QQ-Access-Token {token} Header，且Token需通过AppID+AppKey+nonce+timestamp+signature五元组动态生成
• 签名算法强制使用HMAC-SHA256，密钥为AppKey，待签原文格式：GET\n{path}\n{query_string}\n{timestamp}

三、配置层：腾讯位置服务控制台的权限拓扑验证

检查项	关键路径	风险提示
服务启用状态	控制台 → 应用管理 → 对应App → 开通服务 → 勾选「天气服务」	未勾选将返回403而非404
地域白名单	应用设置 → IP白名单 / 地域限制 → 支持「全国」或指定省级行政区编码（GB/T 2260）	若传入region=110000（北京）但白名单仅设440000（广东），响应为空

四、参数层：地理标识与时间语义的标准化约束

腾讯天气API对核心参数执行强校验：

• location：必须为标准经纬度字符串（"116.404,39.915"），不接受城市名、拼音或GeoHash；逗号为半角，空格将导致400
• region：仅接受6位国标行政区划代码（如110101为北京市东城区），非标准值（如beijing）触发静默过滤
• time：历史查询限最近30天，预报查询限未来7天，超范围返回空forecast数组

五、诊断层：可复现的三层排查工作流

graph TD A[第一步：Postman直调] --> B[携带完整Header
Authorization + Content-Type] B --> C[比对官方文档示例请求
URL/Query/Body/Signature] C --> D[第二步：X-Request-ID溯源] D --> E[控制台 → API调用日志
匹配ID查具体失败原因] E --> F[第三步：Token与签名审计] F --> G[用Python脚本重算signature
对比响应Header中X-Signature]

六、数据层：气象覆盖盲区与字段过滤策略

即使请求完全合规，仍可能返回空数据——根本原因在于腾讯天气数据源依赖合作气象站网络。截至2024年Q2，全国约18%的县级行政区（尤其西部牧区、海岛、高原乡镇）无实时观测站接入，此时API返回{"ret":0,"data":{"now":{}}}而非报错。此外，当某字段因数据质量不达标被平台主动过滤（如能见度vis在沙尘暴期间置空），文档「响应说明」章节明确标注：“字段存在即有效，缺失即无数据”，开发者不可假设必填。

七、演进层：从V1到V2接口的迁移关键点

// V1旧接口（已废弃）
GET https://weather.map.qq.com/weather?location=116.404,39.915&key=YOUR_KEY

// V2新接口（强制HTTPS + Token认证）
GET https://api.inews.qq.com/weather/v2/now?location=116.404,39.915
Headers:
  Authorization: QQ-Access-Token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  Content-Type: application/json

八、工程层：生产环境可观测性增强方案

建议在SDK中嵌入以下能力：

• 自动捕获并上报X-Request-ID至ELK日志系统，关联前端埋点与后端调用链
• 对空响应做二次探测：降级调用中国气象局公开API（http://www.nmc.cn/rest/weather）作兜底
• 建立参数合法性预检中间件，拦截region非法编码、location格式错误等客户端问题

```