适用场景

当你的应用需要获取全国 3 万+ 城市的实时天气、未来 7 天预报、24 小时逐小时趋势、空气质量指数（AQI）、9 项生活指数（穿衣、防晒、限行等）以及气象预警与农历信息时，墨迹天气 API 是一个一站式的选择。它支持按城市名或内部 ID 查询，也提供历史天气追溯功能。然而，在实际接入过程中，由于参数拼写错误、查询模式混用、鉴权配置不当等原因，开发者可能会遇到各种返回错误。本文将从实战角度出发，系统梳理这些常见问题及其排查方法。

接口能力边界

在开始排错前，你需要理解该接口的核心规则：

• 请求方法：GET
• 基准地址：https://v1.apizero.cn/api/moji-weather
• QPS 限制：5 次/秒，超出后返回 429 状态码
• 缓存策略：
  • 实况数据：缓存 5 分钟
  • 当月历史：缓存 30 分钟
  • 过去月份历史：缓存 24 小时
• 数据用途：由墨迹天气官方提供，不能用于农业、保险、航运、防灾等专业决策场景

所有返回数据均以 JSON 格式包裹在code/msg/data结构中。code: 0表示成功，非零值表示错误。

参数与鉴权

请求支持两种鉴权方式（二选一无需同时使用）：

1. Header 方式：添加Authorization: YOUR_API_KEY
2. Query 方式：添加?api_key=YOUR_API_KEY（建议使用 Header，更规范）

核心 Query 参数：

请求示例（curl）

获取实况天气：

curl -sS \ -X GET \ -H "Authorization: YOUR_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?city=北京"

按 internal_id 查询（更快）：

curl -sS \ -X GET \ -H "Authorization: YOUR_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?id=33"

搜索城市列表获取 id：

curl -sS \ -X GET \ -H "Authorization: YOUR_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?op=search&keyword=大化&limit=5"

查询历史天气：

curl -sS \ -X GET \ -H "Authorization: YOUR_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?op=history&city=北京&day=2026-05-12"

响应数据解读

成功时返回如下结构（已精简）：

{ "code": 0, "msg": "成功", "data": { "_cached": false, "city": { "id": 1205, "name": "大化瑶族自治县", "parent": "广西壮族自治区", "pinyin": "dahuayaozuzizhixian", "timezone": 8 }, "condition": { "temperature": 32, "condition": "多云", "humidity": 62, "wind_dir": "南风", "wind_level": 3 }, "aqi": { "value": 29, "level": 1, "description": "优" }, "forecast_day": [ /* 7 天预报 */ ], "forecast_hour": [ /* 24 小时 */ ], "index": [ /* 生活指数 */ ], "summary": "大化瑶族自治县，多云，32℃，南风3级，空气优。" } }

注意_cached字段标识本次是否命中缓存。condition中的lunar_date为农历日期。

常见错误与排错

以下列出接入过程中的高频问题，按错误来源分类。

1. 城市参数错误：city 与 id 冲突或都缺失

现象：返回code: 400，msg: "参数错误，city 与 id 必填其一"（示意）

原因：请求未提供city也未提供id，或同时提供了两者但值不一致。

排查步骤：

• 检查请求 URL 中是否包含?city=xxx或?id=xxx
• 确认城市名无编码问题（如空格被编码为%20仍可接受，但优先使用正确中文）
• 如果同时使用city和id，API 会优先使用id，但建议只传一个以避免混淆

2. 无效的 internal_id

现象：返回code: 404，msg: "未找到该城市"，且data为空

原因：传入的id在数据库中不存在，可能从旧版本或第三方复制而来。

排查步骤：

• 先用op=search&keyword=城市名获取正确的id
• 注意id是 number 类型，不要用字符串 "33" 导致类型不匹配（但 API 通常会自动转换，推荐仍传 number）
• id是内部整数，不同环境可能不同，请以当前接口搜索为准

3. 鉴权失败

现象：返回 HTTP 401 或 403，响应 JSON 中code: 10001（示意），msg: "无效的 API Key"

原因：

• 未提供AuthorizationHeader 或api_keyQuery 参数
• API Key 过期、被禁用或密钥错误

排查步骤：

• 确认 Header 名称为Authorization，而非X-API-Key（部分早期文档可能不同，以最新文档为准）
• 检查 Key 是否包含多余空格或换行符
• 尝试在浏览器中直接访问https://v1.apizero.cn/api/moji-weather?city=北京&api_key=YOUR_KEY排查
• 如果使用环境变量注入，确保变量已正确导出

4. 查询模式错误：op 参数与必要参数不匹配

现象：

• 请求?op=search但缺少keyword，返回code: 400，msg: "search 模式需要 keyword 参数"
• 请求?op=history但缺少day或month，返回类似错误

排查步骤：

• 确认op取值只能是search或history，拼写错误（如“seach”）会导致被当作实况查询，此时keyword或day参数会被忽略
• 若想只查实况，不要传op参数或传空
• 对于历史查询，若只传day而不传month，API 会尝试从day中提取月份；建议明确传递month参数

5. 历史日期超出范围

现象：返回code: 400，msg: "日期超出可查询范围"

原因：

• 请求的未来日期（只能查过去）
• 请求的月份过于久远（接口建议查近 40 天以内）
• 当前月只能查到昨天，今天的数据尚未产生

排查步骤：

• 确认day格式为YYYY-MM-DD，且是过去日期
• 对于整月查询，month格式为YYYYMM，且不超过上月（当前月只能返回 1 号至昨天）
• 如果仍失败，尝试缩小日期范围

6. QPS 超出限制

现象：HTTP 429 Too Many Requests，响应体可能为空或包含错误描述

原因：短时间请求超过 5 次/秒

排查步骤：

• 检查调用逻辑，是否在循环中无间隔调用
• 添加本地限流：使用令牌桶或固定窗口，每秒最多 5 次
• 对于批量任务，适当加入time.Sleep(200ms)或使用协程池控制并发
• 如果业务确实需要高并发，关注文档是否有更高 QPS 的申请通道（以文档为准）

7. 服务端缓存导致数据滞后

现象：查询实况天气，但数据和本地其他源差距超过 5 分钟

原因：实况数据缓存 5 分钟，历史数据缓存更久

排查步骤：

• 观察响应中的_cached字段：true表示缓存命中
• 不应依赖实时性要求高于 5 分钟的场景
• 如果数据明显有问题（如温度与官方 App 差异巨大），可能是缓存未刷新，稍后再试

工程化注意事项

• 参数校验：在后端调用前，先检查city或id是否为空，避免浪费网络请求
• 错误重试：对于 429 或 5xx 错误，建议指数退避重试（最多 3 次）
• 日志记录：记录每次请求的 URL（去掉 API Key）、响应code、msg和耗时，便于排错
• 缓存友好：合理利用本地缓存，减少对 API 的重复调用，例如将实况天气缓存 3 分钟
• 时区处理：返回的timezone为数字（如 8），所有时间戳均为 Unix 毫秒，使用时注意转换为本地时间
• 文档对齐：客户端与服务端使用同一份 API 文档，尤其关注Authorization字段名和参数类型

参考文档

• 接口文档主页：https://apizero.cn/aidocs/moji-weather
• 原始文档（Markdown）：https://apizero.cn/aidocs/moji-weather/raw.md