WeatherServer/weather-service/docs/技术实现文档.md

Weather Service 技术实现文档

1. Weather Service 项目结构

src/main/java/com/htfp/weather/
├── WeatherServiceApplication.java  # 应用程序入口
├── config/                        # 配置类
├── download/                      # 数据下载模块
├── griddata/                      # 网格数据处理
├── info/                         # 信息处理模块
├── schedule/                     # 定时任务模块
├── utils/                        # 工具类
└── web/                         # Web接口模块

2. 核心模块分析

2.1 应用程序入口

文件：WeatherServiceApplication.java

@EnableRetry // 开启重试机制
@EnableScheduling // 开启定时任务
@SpringBootApplication
public class WeatherServiceApplication {
    public static void main(String[] args) {
        TimeZone.setDefault(TimeZone.getTimeZone("Asia/Shanghai"));
        SpringApplication.run(WeatherServiceApplication.class, args);
    }
}

主要特性：

1. 启用Spring Boot自动配置
2. 启用重试机制，支持失败操作重试
3. 启用定时任务调度功能
4. 设置默认时区为亚洲/上海

2.2 数据下载模块

目录：download/

2.2.1 基础下载器（BaseDataDownloader）

文件：BaseDataDownloader.java

@Data
@ToString
public abstract class BaseDataDownloader {
    private String startTimeStr;        // 起始时间（北京时UTC+8）
    private LocalDateTime startTime;    // 起始时间对象
    private String refTimeStr;          // 参考时间字符串
    private OffsetDateTime refTime;     // 数据实际起报UTC时间

    // 获取所有下载文件信息
    public abstract List<DownLoadFileInfo> getFilesInfo();
    
    // 单个文件下载
    public abstract DownLoadFileInfo download(DownLoadFileInfo downLoadFileInfo) throws IOException;
    
    // 批量下载所有文件
    public abstract List<DownLoadFileInfo> downloadAll(List<DownLoadFileInfo> downLoadFileInfoList);
}

2.2.2 下载文件信息（DownLoadFileInfo）

文件：DownLoadFileInfo.java

@Data
@ToString
public class DownLoadFileInfo {
    private String fileName;            // 保存文件名
    private String refTimeStr;          // 数据起报时间
    private Integer forecastHour;       // 预报时效
    private String forecastBJTimeStr;   // 预报时效对应的北京时间
    private String forecastUTCTimeStr;  // 预报时效对应的UTC时间
    private String url;                 // 下载链接
    private String savePath;            // 保存路径
    private boolean isDownloadSuccess;  // 下载是否成功
    private String errorMsg;            // 错误信息
}

2.2.3 GFS数据下载

目录：download/gfs/

该模块实现了GFS（全球预报系统）气象数据的下载功能：

1. 支持配置下载起始时间
2. 提供单文件和批量下载能力
3. 包含下载状态跟踪和错误处理
4. 支持UTC和北京时间的转换

2.3 网格数据处理模块

目录：griddata/

2.3.1 数据表配置（TableConfig）

文件：griddata/common/TableConfig.java

@Data @Component @Slf4j
public class TableConfig {
    private String dataTableName;      // 数据表名
    private String metaTableName;      // 元数据表名
    private String dataIndexName;      // 数据索引名
    private String metaIndexName;      // 元数据索引名
    private String dataDir;            // 数据目录
    private List<String> variableList; // 变量列表
    private int lonSize;               // 经度网格数
    private int latSize;               // 纬度网格数
    private int levSize;               // 层次数
    private int timeToLive;            // 数据生存时间
    
    // 网格参数
    private double[] lonList;          // 经度列表
    private double[] latList;          // 纬度列表
    private int[] pressureList;        // 气压层次
    private int[] heightList;          // 高度层次
}

2.3.2 数据导入（GfsDataImport）

文件：griddata/operation/GfsDataImport.java

主要功能：

1. 网格数据导入到阿里云表格存储
2. 支持多维度数据处理：
   • 时间维度
   • 空间维度（经纬度）
   • 垂直维度（气压层/高度层）
3. 数据处理流程：
   • 初始化元数据
   • 读取NC文件
   • 数据单位转换
   • 网格数据写入
   • 更新元数据状态

关键特性：

1. 支持并发导入
2. 错误处理和状态跟踪
3. 支持断点续传
4. 数据完整性验证

2.3.3 数据操作类

目录：griddata/operation/

1. BaseTableOperation：表操作基类
2. CreateTable：创建数据表
3. GfsDataFetcher：数据获取
4. QueryMeta：元数据查询
5. UpdateTable：表更新
6. DataDeleter：数据删除

2.4 定时任务模块

目录：schedule/

2.4.1 网格数据处理器（GridDataProcessor）

文件：schedule/GridDataProcessor.java

@Component
@Slf4j
@DependsOn({"gfsDataImport", "gfsDownloader"})
public class GridDataProcessor {
    // 定时任务：每日北京时0,8,12,18点30分执行
    @Scheduled(cron = "0 30 0,8,12,18 * * ?")
    public void dailyDataProcess() {
        if (download()) {           // 下载数据
            importToTableStore();    // 导入数据库
        }
        clearExpiredData();         // 清理过期数据
    }
}

主要功能：

1. 数据下载管理
   • 获取文件信息
   • 执行下载
   • 处理下载失败
2. 数据导入管理
   • 导入表格存储
   • 处理导入失败
3. 数据清理
   • 清理3天前的过期数据
   • 日志记录

2.4.2 错误报告服务（ErrorReportService）

文件：schedule/ErrorReportService.java

@Service
@Slf4j
public class ErrorReportService {
    // 邮件发送，支持重试
    @Retryable(maxAttempts = 4, backoff = @Backoff(delay = 2000, multiplier = 2))
    public void sendSimpleEmail(final Mail mail) {
        // 发送邮件逻辑
    }
    
    // 远程报告，支持重试
    @Retryable(maxAttempts = 4, backoff = @Backoff(delay = 2000, multiplier = 2))
    public void reportToRemote(final ErrorReport report) {
        // 发送远程报告逻辑
    }
}

特性：

1. 支持邮件通知
2. 支持远程报告
3. 失败重试机制
4. 多种通知方式

2.5 Web接口模块

目录：web/

2.5.1 地面天气控制器（SurfaceWeatherController）

文件：web/controller/SurfaceWeatherController.java

@RestController
@RequestMapping("/htfp/weather/v1/surface/")
public class SurfaceWeatherController {
    // 地面实时气象信息查询
    @PostMapping("/querySurfaceNowWeather")
    public Result queryNowWeather(@Validated @RequestBody Position2D position2D)
    
    // 地面24小时预报结果查询
    @PostMapping("/querySurfaceForecast")
    public Result querySurfaceForecast(@Validated @RequestBody Position2D position2D)
    
    // 地面气象预警信息查询
    @PostMapping("/queryWeatherWarning")
    public Result queryWeatherWarning(@Validated @RequestBody Position2D position2D)
    
    // 全国地面气象预警信息查询
    @PostMapping("/queryAllWeatherWarning")
    public Result queryWeatherWarning()
}

主要功能：

1. 地面实时天气查询
2. 24小时天气预报
3. 气象预警信息
4. 支持多数据源切换（和风天气、彩云天气等）

2.5.2 高空天气控制器（UpperWeatherController）

文件：web/controller/UpperWeatherController.java

@RestController
@RequestMapping("/htfp/weather/v1/upper/")
public class UpperWeatherController {
    // 高空实时气象信息查询
    @PostMapping("/queryUpperNowWeather")
    public Result queryUpperNowWeather(@Validated @RequestBody Position3D position3D)
    
    // 高空航点实时气象信息查询
    @PostMapping("/queryUpperNowWeatherInMultiPoints")
    public Result queryUpperNowWeatherInMultiPoints(@Validated @RequestBody MultiPointsRequest request)
    
    // 高空24小时预报结果查询
    @PostMapping("/queryUpperForecast")
    public Result queryUpperForecast(@Validated @RequestBody Position3D position3D)
    
    // 高度廓线查询
    @RequestMapping("/queryProfileByPressure")
    public Result queryProfileByAndPressure(@Validated @RequestBody ProfileRequest request)
    
    // 平面网格数据查询
    @PostMapping("/queryPlaneGrid")
    public Result queryPlaneGrid(@Validated @RequestBody PlaneRequest request)
}

主要功能：

1. 高空实时天气查询
   • 单点查询
   • 多点查询（航线）
2. 高空天气预报
   • 24小时预报
   • 多点预报
3. 高度廓线分析
   • 气压坐标
   • 近地面高度坐标
4. 平面网格数据查询

2.5.3 接口特性

1. RESTful API设计
2. 跨域支持（@CrossOrigin）
3. 参数验证（@Validated）
4. 统一响应格式（Result）
5. 接口日志记录（@ControllerLog）
6. 异常处理（ControllerExceptionAdvice）

2.5.4 数据模型

1. 请求参数：

   • Position2D：二维位置（经纬度）
   • Position3D：三维位置（经纬度+高度）
   • MultiPointsRequest：多点请求
   • ProfileRequest：廓线请求
   • PlaneRequest：平面网格请求

2. 响应数据：

   • NowWeatherStatus：实时天气状态
   • TimeSeriesDataset：时间序列数据
   • SurfaceWeatherWarning：天气预警信息
   • ProfileResponse：廓线响应
   • PlaneResponse：平面网格响应

2.6 工具类模块

目录：utils/

2.6.1 HTTP客户端工具（HttpClientUtils）

文件：utils/HttpClientUtils.java

提供HTTP请求相关功能：

1. GET请求
2. POST请求
3. SSL证书处理
4. 请求头管理
5. 响应处理

2.6.2 JSON工具（JSONUtils）

文件：utils/JSONUtils.java

JSON数据处理工具：

1. 对象序列化
2. JSON解析
3. 文件读写
4. 类型转换

2.6.3 气象工具（MeteoUtils）

文件：utils/MeteoUtils.java

气象数据处理工具：

1. 气压高度转换
2. 温度单位转换
3. 风向风速计算
4. 气象要素计算

2.6.4 时间工具（DateTimeUtils）

文件：utils/DateTimeUtils.java

时间处理工具：

1. 时区转换
2. 格式化处理
3. 时间计算
4. UTC时间处理

2.6.5 数组工具（NdArrayUtils）

文件：utils/NdArrayUtils.java

多维数组处理工具：

1. 数组维度转换
2. 数据提取
3. 数组操作

2.6.6 Spring工具（SpringUtil）

文件：utils/SpringUtil.java

Spring相关工具：

1. Bean管理
2. 上下文处理
3. 配置加载

3. 系统功能概述

3.1 核心功能

1. GFS气象数据处理

   • 数据下载
   • 数据解析
   • 数据存储
   • 数据查询

2. 天气信息服务

   • 地面天气查询
   • 高空天气查询
   • 天气预警
   • 天气预报

3. 数据分析能力

   • 高度廓线分析
   • 多点数据分析
   • 网格数据分析
   • 时序数据分析

3.2 技术特点

1. 数据处理

   • 支持多维度数据
   • 高效数据存储
   • 实时数据更新
   • 数据质量控制

2. 系统架构

   • 模块化设计
   • 可扩展性好
   • 高可用性
   • 易维护性

3. 接口设计

   • RESTful规范
   • 参数验证
   • 异常处理
   • 日志记录

4. 运维特性

   • 监控告警
   • 错误追踪
   • 性能优化
   • 安全保障

4. 后续开发建议

4.1 功能增强

1. 数据源扩展

   • 增加更多气象数据源
   • 支持数据源动态切换
   • 实现数据源备份

2. 分析能力提升

   • 增加更多气象要素分析
   • 提供数据可视化能力
   • 支持自定义分析模型

3. 接口优化

   • 增加批量处理接口
   • 优化接口响应时间
   • 提供WebSocket接口

4.2 性能优化

1. 数据处理

   • 优化数据存储结构
   • 实现数据缓存
   • 提高并发处理能力

2. 系统架构

   • 引入微服务架构
   • 实现服务集群
   • 优化负载均衡

3. 运维能力

   • 完善监控系统
   • 优化告警机制
   • 提升系统可用性

4.3 安全加强

1. 访问控制

   • 实现用户认证
   • 细化权限管理
   • 加强接口安全

2. 数据安全

   • 加密敏感数据
   • 实现数据备份
   • 审计日志完善

4.4 文档完善

1. 接口文档

   • 详细API说明
   • 示例代码
   • 错误码说明

2. 运维文档

   • 部署说明
   • 配置说明
   • 故障处理

3. 开发文档

   • 架构说明
   • 开发规范
   • 测试用例