README

一个支持多数据源、带缓存、提供标准化 DTO 响应的 PHP 天气 SDK。内置 Web 演示站点，可一键部署为天气查询服务。

在线演示：http://weather.snowmannunu.top/

✨ 特性

• 多数据源支持：高德地图、和风天气、OpenWeatherMap，可自由切换
• 标准化响应：统一 CurrentWeather / Forecast DTO，无需适配各平台差异
• PSR-16 缓存：支持 Redis / File / Array 等缓存驱动，减少 API 调用
• Laravel 集成：ServiceProvider + Facade 开箱即用
• Web 演示：内置 SPA 天气查询页面，支持 IP 自动定位与中英文切换
• 多语言 i18n：SDK 与演示站点均支持 zh / en，通过环境变量或 URL 参数切换
• 并发请求：内置 fetchAll() 批量接口，6 个 API 并行发送，响应时间从 ~1.5s 降至 ~0.3s
• 自动重试：网络超时 / 服务端 5xx / 429 限流时自动指数退避重试（最多 2 次）
• 精细化异常：InvalidKeyException / RateLimitException / HttpException，便于调用方精准处理
• 代码质量：PHPUnit + PHPStan Level 8 + PHPCS PSR-12，CI 全自动检查

📦 安装

composer require snowmannunu/weather

🚀 快速开始

基础用法

use SnowmanNunu\Weather\Weather;
use SnowmanNunu\Weather\Providers\AMapProvider;

// 使用高德地图（默认）
$weather = new Weather('your-amap-key');
$current = $weather->getLiveWeather('北京');

echo $current->city;        // 北京市
echo $current->temperature; // 26
echo $current->weather;     // 晴

// 获取未来预报
$forecast = $weather->getForecastsWeather('北京');
foreach ($forecast->casts as $day) {
    echo $day->date . ' ' . $day->dayWeather . ' ' . $day->dayTemp . '°';
}

切换数据源

use SnowmanNunu\Weather\Providers\QWeatherProvider;
use SnowmanNunu\Weather\Providers\OpenWeatherMapProvider;

$weather = new Weather(new QWeatherProvider('your-qweather-key'));
$current = $weather->getLiveWeather('深圳');

// OpenWeatherMap（海外城市更准确）
$weather = new Weather(new OpenWeatherMapProvider('your-owm-key'));
$current = $weather->getLiveWeather('London');

⚠️ 注意：和风天气的标准版 / 商业版 key 通常绑定私有 API 主机（如 xxx.re.qweatherapi.com）， 而不是默认的 devapi.qweather.com。如果遇到 403 Invalid Host，可在构造时传入 host 参数：

$weather = new Weather(new QWeatherProvider('your-qweather-key', [
    'host' => 'https://xxx.re.qweatherapi.com',
]));

host 参数同时支持 http:// 或裸域名（会自动补全 https://）。 也可以在 Nginx / PHP-FPM 中通过环境变量全局配置：

fastcgi_param QWEATHER_KEY your-key;
fastcgi_param QWEATHER_API_HOST https://xxx.re.qweatherapi.com;

添加缓存

use Symfony\Component\Cache\Adapter\RedisAdapter;
use Symfony\Component\Cache\Psr16Cache;

$redis = new RedisAdapter($redisConnection);
$cache = new Psr16Cache($redis);

$weather = new Weather('your-key');
$weather->withCache($cache, 600); // 缓存 10 分钟

切换语言

SDK 支持中英文输出，通过 setLang() 链式调用即可切换：

use SnowmanNunu\Weather\Weather;
use SnowmanNunu\Weather\Providers\QWeatherProvider;

$weather = (new Weather(new QWeatherProvider('your-key')))->setLang('en');
$current = $weather->getLiveWeather('Beijing');

echo $current->weather;     // Sunny
echo $current->windDirection; // NW

支持的 Provider：和风天气（zh/en）、OpenWeatherMap（多语言）、高德地图（返回中文）。 语言信息会自动写入缓存 key，中英文缓存互不干扰。

批量并发查询

一次性获取所有数据（实时天气 + 预报 + 生活指数 + AQI + 预警 + 分钟降水），SDK 内部并行发送请求：

$all = $weather->getAll('北京');

echo $all['current']->temperature;   // 26
echo $all['forecast']->casts[0]->dayWeather; // 晴
echo $all['aqi']->aqi;              // 45

异常处理

SDK 对常见错误做了分类，方便调用方精准处理：

use SnowmanNunu\Weather\Exceptions\InvalidKeyException;
use SnowmanNunu\Weather\Exceptions\RateLimitException;
use SnowmanNunu\Weather\Exceptions\HttpException;

try {
    $current = $weather->getLiveWeather('北京');
} catch (InvalidKeyException $e) {
    // API Key 无效
} catch (RateLimitException $e) {
    // 超过调用频次，建议稍后重试
} catch (HttpException $e) {
    // 网络错误或其他 HTTP 异常
}

🔌 Laravel 集成

在 config/services.php 中添加：

'weather' => [
    'key'    => env('WEATHER_KEY'),
    'driver' => env('WEATHER_DRIVER', 'amap'),
    'cache'  => [
        'store' => env('WEATHER_CACHE_STORE'),
        'ttl'   => env('WEATHER_CACHE_TTL', 300),
    ],
],

// 任意位置调用
app('weather')->getLiveWeather('上海');

🌐 Web 演示部署

项目内置 public/ 目录可直接作为站点根目录部署：

cp public/.env.example public/.env
# 编辑 .env 填入 WEATHER_KEY、WEATHER_PROVIDER 和可选的 WEATHER_LANG

Nginx 配置示例：

server {
    listen 80;
    server_name weather.example.com;
    root /www/wwwroot/weather/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/tmp/php-cgi-82.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param WEATHER_KEY your_api_key;
        fastcgi_param WEATHER_PROVIDER amap;
        include fastcgi_params;
    }
}

🧪 测试

composer test          # PHPUnit
composer phpstan       # 静态分析
composer phpcs         # 代码风格
composer check         # 全部检查

📋 支持的 Provider

各 Provider API 支持对比

说明

• 高德：生活指数和 AQI 取决于 Key 是否开通对应权限，SDK 已做容错（报错时返回空，不抛异常）
• 和风：AQI 和预警接口免费开发版直接 403；分钟降水需传入经纬度坐标，传 LocationID 会报 400
• OpenWeatherMap：只覆盖了实时天气 + 预报，其余 feature 没有对应免费接口

📄 License

MIT