@happyvertical/weather

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 5162

HappyVertical SDK 的天气数据提供者抽象

中文使用文档
文档目录17 节
  1. 概览
  2. 支持供应商
  3. 安装
  4. Claude 代码背景
  5. 使用量
  6. 基本示例
  7. 打开WeatherMap( 自由地层)
  8. OpenWeatherMap 一个呼叫( 援助级别)
  9. 环境可变配置
  10. API 参考
  11. getWeatherAdapter(options?): Promise<IWeatherAdapter>
  12. IWeatherAdapter
  13. WeatherForecast
  14. 环境变量
  15. 测试
  16. 提供者比较
  17. 许可证

@ 喜悦的垂直/ 天气

HappyVertical SDK的天气数据提供者抽象.

概览

这个 @happyvertical/weather 软件包为从多个供应商获取天气预报提供了统一的接口。 它遵循的建筑模式与 @happyvertical/ai, (中文(简体) ), @happyvertical/files,以及 @happyvertical/sql。 。 。 .

支持供应商

  • 加拿大环境部 - 为加拿大各地提供政府气象服务(免费)
  • 打开WeatherMap - 免费和付费的全球气象数据
    • 标准API:5天/3小时预报(免费分级)
    • 1呼叫API 3.0:48小时+8天每日预报(付费级)

安装

pnpm add @happyvertical/weather

Claude 代码背景

为 AI 辅助开发安装 Claude 代码上下文文件 :

npx have-weather-context

这个复制包 AGENT.md 文献和记录 metadata.json 元数据到您的项目 .claude/ 目录,使克洛德能够在使用该套件时提供更好的帮助.

使用量

基本示例

import { getWeatherAdapter } from '@happyvertical/weather';

// Create adapter for Environment Canada
const weather = await getWeatherAdapter({
  provider: 'environment-canada'
});

// Fetch forecast for a location (latitude, longitude)
const forecasts = await weather.fetchForLocation(51.0447, -114.0719);

forecasts.forEach(forecast => {
  console.log(`${forecast.timestamp}: ${forecast.temperature}°C - ${forecast.conditions}`);
});

打开WeatherMap( 自由地层)

const weather = await getWeatherAdapter({
  provider: 'openweathermap',
  apiKey: process.env.OPENWEATHER_API_KEY
});

const forecasts = await weather.fetchForLocation(51.0447, -114.0719);

OpenWeatherMap 一个呼叫( 援助级别)

const weather = await getWeatherAdapter({
  provider: 'openweathermap-onecall',
  apiKey: process.env.OPENWEATHER_API_KEY
});

const forecasts = await weather.fetchForLocation(51.0447, -114.0719);

环境可变配置

# .env
HAVE_WEATHER_PROVIDER=openweathermap
OPENWEATHER_API_KEY=your-api-key-here
HAVE_WEATHER_TIMEOUT=15000
// Automatically uses environment variables
const weather = await getWeatherAdapter();
const forecasts = await weather.fetchForLocation(51.0447, -114.0719);

API 参考

getWeatherAdapter(options?): Promise<IWeatherAdapter>

工厂用于创建天气适配器的功能.

选项 :

  • provider数字 : 'environment-canada' | 'openweathermap' | 'openweathermap-onecall'
  • apiKey: API 密钥( OpenWeatherMap 提供者需要此密钥)
  • timeout: 请求超时, 以毫秒计( 默认: 1 000)

IWeatherAdapter

interface IWeatherAdapter {
  fetchForLocation(
    latitude: number,
    longitude: number,
    options?: FetchOptions
  ): Promise<WeatherForecast[]>

  testConnection(): Promise<boolean>

  supportsLocation(latitude: number, longitude: number): Promise<boolean>
}

WeatherForecast

interface WeatherForecast {
  timestamp: Date
  temperature: number      // °C
  feelsLike?: number       // °C
  temperatureMin?: number  // °C
  temperatureMax?: number  // °C
  conditions: string       // Human-readable description
  humidity: number         // Percentage 0-100
  windSpeed: number        // km/h
  windDirection?: number   // Degrees 0-360
  windGust?: number        // km/h
  pressure?: number        // hPa
  cloudCover?: number      // Percentage 0-100
  visibility?: number      // km
  precipProbability?: number  // Percentage 0-100
  precipAmount?: number    // mm
  confidence?: number      // Provider's confidence 0-100
  raw: any                 // Provider-specific raw data
}

环境变量

变量类型说明
HAVE_WEATHER_PROVIDER字符串提供者名称
OPENWEATHER_API_KEY字符串打开WeatherMap API 密钥
HAVE_WEATHER_TIMEOUT编号请求超时( 毫秒)

测试

默认的套房是离线的和决定性的,有一个按键的例外. 提供方的答复来自所记录的固定装置 src/__tests__/fixtures/这样 没有在清洁环境中试验 test 到达网络 :

pnpm turbo run test --filter=@happyvertical/weather

例外的是 google-weather.spec.ts打开门 GOOGLE_API_KEY按 寄存器 : 已存在 —— 见“ 默认套房中的网络隔离 ” .github/CI.md与 键未设置, 它的活块跳过, 离线保证 中情局负责 随密钥导出, 它调用实时 Google Weather API from test。 。 。 .

其他现场服务的覆盖率 *.optional.test.ts 已经 跳过,除非你选择加入。 在其 API 密钥上打开 WeatherMap 门; 环境 加拿大不需要钥匙,所以它在一面明快的旗帜上登出大门:

ENVIRONMENT_CANADA_INTEGRATION=1 pnpm --filter @happyvertical/weather test:optional

在重新录制固定装置后运行活套房,以确认上游有效载荷 仍然符合离线套房的形状。 见 src/__tests__/fixtures/README.md 记录每个固定.

提供者比较

特性加拿大环境部打开WeatherMapOWM 一通电话
费用免费可自由分级已支付
覆盖范围仅加拿大全球全球
预测每日/夜间3小时5天小时+每日
API 密钥无需需求需求
更新频率~小时~3小时小时

许可证

麻省理工学院

版本与发布记录

@happyvertical/weather 共发布 131 个版本,首次发布于 2026/06/23;过去 12 个月发布了 131 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.02026/11/125 天前
0.112.12026/11/125 天前

关于 @happyvertical/weather 的常见问题

@happyvertical/weather 是什么?

HappyVertical SDK 的天气数据提供者抽象

如何安装 @happyvertical/weather?

在项目目录运行 npm install @happyvertical/weather,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-weather-context,可以用 npx have-weather-context 直接运行。

@happyvertical/weather 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/weather 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/weather 可以商用吗?

@happyvertical/weather 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/weather 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/weather 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,162 次,日均约 172 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/weather 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 131 个版本,其中过去 12 个月发布了 131 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。