# 三方天气对接

**Repository Path**: mj-study/weather

## Basic Information

- **Project Name**: 三方天气对接
- **Description**: 一个基于 Spring Boot 的可扩展天气 API 统一接入平台，支持多厂商接入、配置驱动映射、动态缓存与上下文透传
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-04
- **Last Updated**: 2025-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌤️ 天气服务系统（Weather Service）

> 一个基于 Spring Boot 的可扩展天气 API 统一接入平台，支持多厂商接入、配置驱动映射、动态缓存与上下文透传。

![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7+-6DB33F?logo=spring&logoColor=white)
![Java](https://img.shields.io/badge/Java-8+-ED8B00?logo=openjdk&logoColor=white)
![Gitee](https://img.shields.io/badge/Hosted%20on-Gitee-0052B4?logo=gitee&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)

本项目旨在构建一个**统一、灵活、可维护**的天气数据查询服务，支持接入墨迹天气、和风天气等多个第三方 API，通过 **YAML 配置驱动** 实现字段映射与缓存策略，无需修改代码即可扩展新厂商或新接口。

---

## 📋 项目特性

| 特性 | 说明 |
|------|------|
| ✅ 多厂商支持 | 支持墨迹、和风等多家天气服务商，通过策略模式动态路由 |
| ✅ 配置驱动映射 | 使用 YAML 配置 JSON 字段到 Java 对象的映射规则 |
| ✅ 动态缓存 | 支持按接口动态设置缓存 Key 与 TTL（如：实况 5min，预报 30min） |
| ✅ 上下文透传 | 基于 `TransmittableThreadLocal` 实现 traceId、缓存 key 等上下文传递 |
| ✅ 统一入口 | 所有天气接口共用 `execute()` 方法，高度复用 |
| ✅ 字段注入 | 支持将列表数据注入到目标对象的指定字段（如 `condition`、`hourlyList`） |
| ✅ 可扩展性强 | 新增厂商只需实现接口 + 添加配置，无需修改核心逻辑 |

---

## 🧩 核心架构
```
+------------------+     +-----------------------+
|   Controller     | --> | WeatherQueryCommonService |
| (condition,      |     |   .execute()            |
|  forecast, alert) |     +-----------+-----------+
+------------------+                 |
                                     v
                     +-------------------------------+
                     |    Dynamic Routing & Caching  |
                     |  @DynamicCacheable(key=..., ttl=...) |
                     +-------------------------------+
                                     |
                                     v
                     +-------------------------------+
                     |       doExecuteApi(...)       |
                     |  - 构建请求 (URL/Headers)     |
                     |  - 发送 HTTP 请求             |
                     |  - 检查响应状态               |
                     |  - 回调 resultMapper 处理数据 |
                     +-------------------------------+
                                     |
                                     v
                     +-------------------------------+
                     |       weatherMappingFiled     |
                     |  - 根据 provider + type 配置  |
                     |    动态映射 JSON → Java 对象  |
                     |  - injectListField 注入字段   |
                     +-------------------------------+
                                     |
                                     v
                     +-------------------------------+
                     |     RequestContextHolder      |
                     |  - 存放 traceId / cacheKey /  |
                     |    ttl / provider / type 等   |
                     +-------------------------------+
```


---

## 🛠️ 功能接口

| 接口 | 描述 | 示例 |
|------|------|------|
| `GET /api/v1/weather/condition` | 天气实况 | `?provider=moji&city=北京` |
| `GET /api/v1/weather/forecast24hours` | 24小时预报 | `?provider=moji&city=上海` |
| `GET /api/v1/weather/forecast15days` | 15天预报 | `?provider=moji&city=广州` |
| `GET /api/v1/weather/alert` | 天气预警 | `?provider=moji&city=深圳` |
| `GET /api/v1/weather/forecast60minutes` | 短时降水（60分钟） | `?provider=moji&lat=39.9&lon=116.4` |

---

## ⚙️ 配置说明

### 1. 请求路由配置 `application.yml`

```yaml
weather:
  providers-request-mapping:
    appCode: 33bf46d7a06e45b199b5e0b31773ae2
    providers:
      - provider: moji
        type: condition-city
        url: https://aliv18.data.moji.com/whapi/json/alicityweather/condition
        token: 50b53ff8dd7d9fa320d3d3ca32cf8ed1
        requestURI: /api/v1/weather/condition
        classPath: com.sdses.weather.model.WeatherConditionInfo$WeatherCondition
```        
### 2. 字段映射配置 weather-moji-config.yaml
```yaml
weather:
  providers:
    moji:
      base-path: "$.data"
      condition:
        target-field: "condition"
        arrayFlag: false
        fields:
          - json: "city.name"     -> java: "cityName"
          - json: "condition.tmp" -> java: "temperature"
      hourly:
        target-field: "hourlyList"
        arrayFlag: true
        fields:
          - json: "tmp" -> java: "temperature"
          - json: "time" -> java: "forecastTime"
```