huisway

同穗

xyc 同穗

https://xyc.icu

weather-api/README.md

天气查询API

基于中央气象台API的Node.js天气查询服务，支持IP地址自动定位和城市天气查询，提供智能缓存、完整的API文档和测试支持。

功能特性

🌍 IP地址自动定位：根据用户IP地址自动获取所在城市天气
🏙️ 城市天气查询：支持按城市名和城市代码查询天气
💾 智能内存缓存：使用内存缓存天气数据，提高响应速度，支持智能淘汰策略
🔄 缓存预热机制：启动时预加载热门城市天气信息
📊 RESTful API：提供标准RESTful接口
🌐 跨域支持：内置CORS支持
📝 详细日志：按天记录日志，支持多级日志级别
🧪 完整测试：使用Jest进行单元测试和集成测试
📄 自动API文档：使用Swagger自动生成API文档
🔧 灵活配置：支持通过配置文件调整缓存策略、超时时间等
📈 API请求优化：支持超时和重试机制，提高API可靠性
💾 缓存持久化：定期保存缓存到文件，重启后自动恢复

快速开始

1. 克隆项目


git clone <repository-url>
cd weather

2. 安装依赖


npm install

3. 启动服务


# 开发模式
npm run dev

# 生产模式
npm start

# 启动缓存脚本
npm run cache

4. 访问服务


# 健康检查
curl http://localhost:3000/health

# 获取省份列表
curl http://localhost:3000/api/provinces

# 获取北京天气
curl http://localhost:3000/api/weather/北京

# 查看API文档
curl http://localhost:3000/api-docs

API文档

项目使用Swagger自动生成API文档，访问以下地址查看完整的API文档：


http://localhost:3000/api-docs

API接口

1. 健康检查


GET /health

2. 个性化天气信息页面


GET /weatherInfo

3. 根据IP获取天气


GET /api/weather

4. 根据城市名称获取天气


GET /api/weather/:city

5. 根据城市代码获取天气


GET /api/weather/code/:cityCode

6. 获取省份列表


GET /api/provinces

7. 获取城市列表


GET /api/cities/:provinceCode

8. 获取缓存统计


GET /api/cache/stats

9. 清空缓存


DELETE /api/cache/clear

10. 批量缓存所有城市天气


POST /api/cache/all-cities

测试

1. 运行测试


# 运行所有测试
npm test

# 运行测试并查看覆盖率
npm run test:coverage

# 运行测试并监听文件变化
npm run test:watch

2. 测试文件

cityMatcher.test.js：城市匹配器测试
weatherCache.test.js：天气缓存测试

配置文件

通过 config.json 文件配置系统行为：


{
  "cache": {
    "enabled": true,
    "ttl": 43200000,          // 缓存过期时间（毫秒）
    "checkPeriod": 600000,      // 缓存检查周期（毫秒）
    "autoRefresh": true,        // 是否自动刷新缓存
    "refreshInterval": 1800000,  // 自动刷新间隔（毫秒）
    "maxCacheSize": 1000,        // 最大缓存大小
    "disableWarming": false      // 是否禁用缓存预热
  },
  "weatherApi": {
    "baseUrl": "http://www.nmc.cn/f/rest",
    "timeout": 10000,           // API请求超时时间（毫秒）
    "retryAttempts": 3          // API请求重试次数
  },
  "logging": {
    "level": "info",
    "enableConsole": true,
    "enableFile": true,
    "file": "logs/app.log"
  },
  "server": {
    "port": 3000,               // 服务器端口
    "corsEnabled": true
  }
}

缓存管理

缓存特性

内存缓存：使用Map存储缓存数据，高效访问
智能淘汰：结合访问次数和最后访问时间，智能淘汰不常用的缓存项
自动过期：根据TTL自动清理过期缓存
定期保存：每5分钟自动保存缓存到文件
持久化恢复：启动时从文件加载缓存
缓存预热：预加载热门城市天气信息

缓存文件

文件路径: ./cache_data.json
包含内容: 天气缓存、省份缓存、城市缓存、保存时间戳

日志系统

日志级别

ERROR：红色输出，记录错误信息
WARN：黄色输出，记录警告信息
INFO：绿色输出，记录普通信息
DEBUG：青色输出，记录调试信息

日志文件

存储路径: ./logs/
命名格式: YYYY-MM-DD.log
自动按天分割

项目结构


weather/
├── app.js                  # 主应用文件
├── WeatherCache.js         # 天气缓存管理
├── cityMatcher.js          # 城市匹配器
├── logger.js               # 日志系统
├── cacheWeather.js         # 缓存脚本
├── config.json             # 配置文件
├── china_cities.json       # 中国城市数据
├── cache_data.json         # 缓存持久化文件
├── package.json            # 项目配置
├── .env.example            # 环境变量示例
├── README.md               # 项目文档
├── cityMatcher.test.js     # 城市匹配器测试
├── weatherCache.test.js    # 天气缓存测试
├── test-api.js             # API测试脚本
└── logs/                   # 日志文件夹

API请求优化

超时和重试机制

默认超时时间：10秒
默认重试次数：3次
重试延迟：指数退避（1秒、2秒、4秒...）
可重试状态码：429, 500, 502, 503, 504

响应格式

成功响应


{
  "success": true,
  "data": {
    "location": {
      "ip": "0.0.0.0",
      "country": "中国",
      "province": "北京市",
      "city": "北京",
      "isp": "中国电信"
    },
    "weather": {
      "city": "北京",
      "code": "ABJ",
      "temperature": "25",
      "humidity": "60",
      "pressure": "1013",
      "wind": "东北风3级",
      "weather": "晴",
      "updated_at": "2025-10-01T12:00:00Z",
      "source": "中央气象台"
    }
  },
  "meta": {
    "response_time": 100,
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

错误响应


{
  "success": false,
  "message": "查询天气信息失败",
  "error": "未找到城市: 未知城市",
  "meta": {
    "response_time": 50,
    "timestamp": "2025-10-01T12:00:00Z"
  }
}