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

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

git clone <repository-url>
cd weather

npm install

# 开发模式
npm run dev

# 生产模式
npm start

# 启动缓存脚本
npm run cache

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

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

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

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

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

http://localhost:3000/api-docs

GET /health

GET /weatherInfo

GET /api/weather

GET /api/weather/:city

GET /api/weather/code/:cityCode

GET /api/provinces

GET /api/cities/:provinceCode

GET /api/cache/stats

DELETE /api/cache/clear

POST /api/cache/all-cities

# 运行所有测试
npm test

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

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

• 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/                   # 日志文件夹

• 默认超时时间：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"
  }
}

1. IP定位：使用 http://ip.api.xyc.ink/ 获取用户IP对应城市
2. 城市匹配：使用城市匹配器将定位结果匹配到中央气象台的城市代码
3. 省份查询：从 http://www.nmc.cn/f/rest/province 获取省份列表
4. 城市查询：从 http://www.nmc.cn/f/rest/province/{省份代码} 获取城市列表
5. 天气查询：从 http://www.nmc.cn/f/rest/real/{城市代码} 获取实时天气
6. 数据缓存：将天气数据缓存到内存，定期保存到文件

• 使用 npm run dev 启动开发模式，支持热重载
• 定期检查日志文件，监控系统运行状态
• 根据实际需求调整配置文件中的缓存策略
• 开发新功能时添加相应的测试用例
• 使用 npm run test:coverage 查看测试覆盖率
• 通过Swagger文档了解API接口的详细信息

1. API限制：中央气象台API可能有访问频率限制，建议合理使用缓存
2. IP定位：IP定位服务可能不完全准确，建议提供城市名查询作为备选
3. 缓存策略：根据实际访问量调整缓存大小和过期时间
4. 错误处理：系统会自动处理各种异常情况并返回友好错误信息
5. 日志管理：定期清理旧日志文件，避免占用过多磁盘空间

• Node.js：JavaScript运行时
• Express：Web框架
• Axios：HTTP客户端
• Jest：测试框架
• Swagger：API文档生成
• dotenv：环境变量管理
• CORS：跨域支持

MIT License