和风天气API返回数据格式如何解析？

Question

使用和风天气API时，常见问题是：如何正确解析其返回的JSON数据结构？特别是当接口返回多层嵌套的实时天气、预报数据及空气质量等信息时，开发者常因未准确识别`now`、`daily`、`aqi`等关键字段层级而导致解析失败。此外，不同城市或语言参数下字段命名差异也易引发空值或解析异常。

Answer 1

一、和风天气API数据结构解析：从基础认知到深度实践

在现代Web与移动端开发中，集成第三方气象服务已成为提升用户体验的重要手段。和风天气（qweather.com）作为国内领先的气象数据服务商，提供了丰富的API接口，涵盖实时天气、逐日预报、空气质量、生活指数等多维度信息。然而，许多开发者在使用其API时，常因对JSON响应结构理解不深而导致解析失败。

1.1 基础结构认知：理解标准返回格式

和风天气API的返回数据遵循统一的JSON结构，核心字段包括：

• code：状态码，表示请求是否成功（如"200"为成功）
• updateTime：数据更新时间
• city 或 location：城市名称或ID
• now：实时天气数据对象
• daily：逐日预报数组
• aqi：空气质量数据对象

例如，获取实时天气的典型响应如下：

{
  "code": "200",
  "updateTime": "2024-05-10T12:30:00+08:00",
  "city": "北京",
  "now": {
    "temp": "26",
    "text": "晴",
    "icon": "100"
  }
}

1.2 多层嵌套结构解析策略

当处理包含now、daily、aqi等嵌套字段时，需明确其层级关系。以下为常见接口返回结构对比：

接口类型	主数据字段	关键子字段	数据类型
实时天气	now	temp, text, windSpeed	Object
7天预报	daily	tempMax, tempMin, humidity	Array[Object]
空气质量	aqi	aqi, pm2p5, level	Object
生活指数	lifestyle	category, text	Array[Object]

1.3 解析失败的常见原因分析

开发者在实际调用中常遇到以下问题：

1. 未校验code值即直接访问now字段，导致空指针异常
2. 误将daily当作单个对象而非数组进行遍历
3. 忽略语言参数影响，如lang=zh与lang=en下text字段内容不同
4. 城市ID错误或未授权城市导致返回默认空数据
5. 网络异常后未做容错处理，直接解析null响应
6. 未考虑时区差异，updateTime解析出错
7. 空气质量aqi字段在某些城市可能缺失
8. 字段命名在不同版本API中存在变更（如v7与v9差异）
9. HTTPS证书验证问题导致请求中断
10. 并发请求超过免费额度被限流

1.4 安全稳健的数据提取模式设计

为避免上述问题，推荐采用防御性编程方式提取数据。以下为JavaScript中的安全访问示例：

function extractCurrentWeather(data) {
    if (data.code !== '200') {
        throw new Error(`API error: ${data.code}`);
    }

    const now = data.now;
    if (!now) {
        console.warn('No "now" field in response');
        return null;
    }

    return {
        temperature: now.temp || '--',
        condition: now.text || 'Unknown',
        iconCode: now.icon || '999',
        windSpeed: now.windSpeed || '0'
    };
}

1.5 动态适配不同语言与区域配置

和风天气支持通过lang参数切换返回语言（如zh、en、ja），这会影响text类字段的输出。建议在客户端根据用户偏好设置动态调整请求参数，并在解析时预留默认值：

const lang = userPreferences.language; // 'en' or 'zh'
fetch(`https://api.qweather.com/v7/weather/now?location=101010100&lang=${lang}&key=YOUR_KEY`)
    .then(r => r.json())
    .then(data => {
        const condition = data.now?.text || 'N/A';
        displayWeather(condition);
    });

1.6 数据一致性校验与异常监控流程图

为保障生产环境稳定性，应建立完整的数据校验机制。以下是推荐的处理流程：

graph TD
            A[发起API请求] --> B{响应状态码==200?}
            B -- 否 --> C[记录错误日志]
            B -- 是 --> D[解析JSON主体]
            D --> E{code字段=="200"?}
            E -- 否 --> F[触发告警通知]
            E -- 是 --> G[提取now/daily/aqi数据]
            G --> H{字段是否存在?}
            H -- 否 --> I[使用默认值填充]
            H -- 是 --> J[格式化并渲染UI]
            J --> K[更新本地缓存]

1.7 高级技巧：构建通用解析器适配多个API版本

面对和风天气v7、v9等不同版本接口，可设计抽象解析层。例如定义映射规则：

const FIELD_MAPPINGS = {
        v7: { now: 'now', daily: 'daily_forecast' },
        v9: { now: 'now', daily: 'daily' }
    };

    function parseForecast(apiVersion, rawData) {
        const mapping = FIELD_MAPPINGS[apiVersion];
        const dailyData = rawData[mapping.daily];
        return Array.isArray(dailyData) ? dailyData.slice(0, 7) : [];
    }

1.8 缓存策略与性能优化建议

由于气象数据更新频率较低（通常每小时一次），建议实施以下缓存机制：

• 本地内存缓存：使用LRU算法存储最近查询的城市数据
• 持久化缓存：IndexedDB或SQLite保存离线可用数据
• ETag校验：利用HTTP缓存头减少重复请求
• 批量预加载：根据用户地理位置预取周边城市数据
• 节流控制：限制单位时间内API调用次数

1.9 跨平台开发中的兼容性处理

在React Native、Flutter或小程序等跨平台场景中，需特别注意：

平台	注意事项	推荐工具
微信小程序	需配置request合法域名	Promise封装 + 工具类
React Native	Android需启用明文流量	axios + interceptors
Flutter	Dart模型类需手动序列化	json_serializable
Vue.js	避免在模板中直接访问深层属性	computed properties

1.10 持续集成中的自动化测试方案

为确保API变更不影响系统稳定性，建议在CI/CD流程中加入契约测试：

// Jest测试示例
test('should parse real-time weather correctly', () => {
    const mockResponse = require('./mocks/weather-now.json');
    const result = extractCurrentWeather(mockResponse);
    expect(result.temperature).toBe('26');
    expect(result.condition).toMatch(/晴|clear/);
});