增加可选高度的查询接口;增加项目文档

download
shiyi 1 month ago
parent 6a5be20d82
commit 38312fe55b

@ -0,0 +1,210 @@
# Cursor项目规范
## 基本设置
- 使用中文回答所有问题
- 按照Sequential Thinking方法进行代码设计和实现
## 依赖约束
- 使用Maven作为依赖管理工具
- 使用Maven项目结构
- 使用SpringBoot2.1.4.RELEASE作为框架
- 使用JDK1.8作为开发语言
- 使用Lombok作为代码简化工具
## 项目结构和命名规范
- 组件命名PascalCase
- 函数命名camelCase
- 常量命名UPPER_CASE
- 文件夹结构遵循Maven项目规范
- 接口命名使用I前缀如IUserService
- 类型定义使用T前缀如TUserData
- 文档类统一输出至docs文件夹并使用Markdown格式
## 代码风格
- 使用TypeScript类型定义
- 统一代码缩进和格式
- 使用ESLint和Prettier规则
## 开发流程规则
1. 问题分析:明确任务目标和约束条件
2. 设计方案:设计数据结构和算法
3. 实现步骤:自顶向下实现功能
4. 测试验证:编写单元测试和集成测试
## 代码审查标准
- 代码必须符合既定规范
- 关键函数和组件必须有注释
- 复杂算法需要解释思路
## 提交规范
- 遵循语义化提交信息格式feat:, fix:, docs:等
- 主分支只接受经过测试的代码
## 文档要求
- API接口必须有清晰文档
- 更新README文件反映最新项目状态
## 代码稳定性保障
- 修改已完成功能前必须先理解其完整设计意图
- 所有API更改必须向下兼容
- 使用单元测试保护核心功能逻辑
- 重构代码时必须保持功能等价性
- 在修改前创建功能快照或临时分支
- 每次更改后必须验证不破坏现有功能
- 使用TODO或FIXME标签清晰标记未完成修改
## 版本控制规则
- 使用语义化版本管理
- 关键功能更改必须通过代码审查
- 维护变更日志记录所有修改
- 为已稳定功能模块添加"锁定注释"标记:/* @stable - 请勿修改 */
## UI设计规范
- 遵循现代设计趋势和最佳实践
- 使用设计系统确保一致性如Material Design、Ant Design或自定义设计系统
- 实现响应式设计,确保在不同设备上显示良好
- 使用CSS变量统一管理颜色、字体、间距等设计标记
- 优先采用Flexbox或Grid布局系统
- 确保适当的留白和视觉层次
- 实现无障碍访问标准WCAG 2.1
## UI组件标准
- 使用组件库作为基础如MUI、Chakra UI、Tailwind UI等
- 自定义组件需符合现代设计审美
- 设计组件应包含默认、悬停、聚焦、禁用等状态
- 使用适当的动画和过渡效果增强用户体验
- 确保设计一致性:同类元素使用相同样式
- 使用主题系统支持亮色/暗色模式切换
- 根据用户操作提供视觉反馈
## 设计资源
- 维护设计风格指南和UI组件库
- 使用标准化图标库如Heroicons、Material Icons等
- 图片和插图需保持一致的风格
- 颜色选择须符合品牌标识并确保足够对比度
## 依赖管理规范
- 优先使用国内镜像站点安装依赖
- npm包使用淘宝镜像https://registry.npmmirror.com/
- yarn设置yarn config set registry https://registry.npmmirror.com
- pnpm设置pnpm config set registry https://registry.npmmirror.com
- pip包使用清华镜像https://pypi.tuna.tsinghua.edu.cn/simple
- Docker镜像使用阿里云https://cr.console.aliyun.com/
- Maven依赖使用阿里云https://maven.aliyun.com/repository/public
- Gradle依赖使用阿里云https://developer.aliyun.com/mvn/guide
- 安装新依赖前先验证其在国内是否可访问
- 如确实需使用国外资源,应提供备选方案或离线安装包
- package.json中添加镜像设置脚本便于团队统一配置
- 记录所有依赖的具体版本和来源以便追踪
## 测试自动化规范
- 编写单元测试覆盖所有关键功能
- 实现端到端测试验证用户流程
- 使用测试驱动开发(TDD)方法
- 每次提交前运行自动化测试
- 维护测试数据与生产环境隔离
## 调试与日志规范
- 统一使用日志级别error, warn, info, debug
- 日志信息需包含上下文和时间戳
- 生产环境禁用调试代码和console语句
- 关键流程增加日志记录点便于问题追踪
- 使用结构化日志格式便于分析
## 代码复杂度控制
- 函数不超过50行单个文件不超过300行
- 每个函数只做一件事情,保持单一职责
- 嵌套不超过3层避免过深条件嵌套
- 控制圈复杂度不超过10
- 复杂逻辑应拆分为多个小函数
## 状态管理规范
- 明确状态管理方案如Redux、MobX或Context API
- 区分本地状态和全局状态
- 避免状态冗余和重复存储
- 实现不可变状态更新模式
- 为复杂状态提供初始值和验证机制
## 异步操作规范
- 统一使用async/await或Promise
- 实现请求超时和重试机制
- 处理并发请求限制
- 取消不必要的请求以节省资源
- 使用Loading状态指示异步操作进行中
## 代码重用策略
- 提取通用逻辑为Hooks或工具函数
- 使用组合而非继承实现代码复用
- 避免复制粘贴代码,而应重构为共享组件
- 通用功能应考虑发布为内部npm包
- 明确区分业务逻辑和技术实现
## 项目文档体系
- 维护项目架构图和关键流程图
- 记录技术选型理由和限制条件
- 为API和数据模型提供详细文档
- 记录已知问题和解决方案
- 提供新开发者入门指南
## 构建与发布流程
- 使用CI/CD实现自动化构建和部署
- 区分开发、测试、预发布和生产环境
- 实现回滚机制应对紧急问题
- 使用版本化静态资源避免缓存问题
- 配置文件应随环境变化而不需修改代码
## 可访问性和兼容性规范
- 确保键盘可访问性
- 使用ARIA标签增强屏幕阅读器支持
- 确保适当的颜色对比度
- 响应式设计支持从移动到桌面的所有设备
- 针对低带宽和弱网络场景优化
## 问题追踪与修复流程
- 使用标准化的问题报告模板
- 问题修复前先编写复现步骤
- 每个bug修复应包含相应测试避免回归
- 重大问题需进行根本原因分析
- 定期审查常见错误类型并改进开发流程
## 代码注释最佳实践
- 写清楚为什么这样做,而不仅是做了什么
- 用注释标记未来需要优化的地方
- 所有公共API必须有注释文档
- 复杂业务逻辑需要解释业务规则
- 避免废弃或过时的注释
## 数据处理与安全
- 敏感数据传输必须加密
- 用户输入必须验证和清洗
- 实现数据备份和恢复策略
- 遵循数据最小化原则,只收集必要信息
- 实现适当的数据过期和销毁机制
## 性能优化指南
- 实现资源懒加载和按需加载
- 优化关键渲染路径提高首屏加载速度
- 使用适当的缓存策略减少网络请求
- 批量处理DOM操作避免重排和重绘
- 定期进行性能审计和优化
## 可维护性原则
- 优先考虑代码可理解性而非简洁性
- 避免过早优化和不必要的抽象
- 关键决策需在代码中记录理由
- 避免使用黑魔法和难以理解的技巧
- 团队培训和知识共享机制
## 技术债务管理
- 使用TODO和FIXME标记需要改进的地方
- 定期安排时间清理技术债务
- 新功能实现前评估现有代码质量
- 记录所有已知问题和临时解决方案
- 使用代码质量工具定期评估项目健康度
## 用户体验设计规范
- 所有操作必须提供用户反馈
- 错误信息应该清晰并提供解决方案
- 降低操作复杂度,减少用户认知负担
- 界面风格保持一致性
- 考虑边缘情况和用户出错恢复路径

4
.gitignore vendored

@ -1,6 +1,6 @@
/GFSData/
/tablestoreConf.json
/log/
/log*/
/*/target/
/tablestore-grid-master/tableConf.json
/tablestore-grid-master/tablestoreConf.json
@ -23,3 +23,5 @@
*.ipr
*.json
*.cursor

@ -0,0 +1,24 @@
package com.aliyun.tablestore.example.grid.common;
import ucar.ma2.DataType;
public class ExampleConfig {
/**
* index
*/
public static String GRID_DATA_TABLE_NAME = "GRID_DATA_TABLE_EXAMPLE1";
public static String GRID_META_TABLE_NAME = "GRID_META_TABLE_EXAMPLE1";
public static String GRID_META_INDEX_NAME = "GRID_META_INDEX";
/**
* ID
*/
public static String EXAMPLE_GRID_DATA_SET_ID = "test_echam_spectral_example";
public static String EXAMPLE_GRID_DATA_SET_NC_FILE_PATH = "test_echam_spectral.nc";
public static String EXAMPLE_GRID_DATA_VARIABLE = "tpot";
public static int[] EXAMPLE_GRID_DATA_SHAPE = new int[]{8, 47, 96, 192};
public static DataType EXAMPLE_GRID_DATA_TYPE = DataType.FLOAT;
}

@ -0,0 +1,62 @@
package com.aliyun.tablestore.example.grid.common;
import com.google.gson.Gson;
import org.apache.commons.io.IOUtils;
import java.io.FileInputStream;
import java.io.InputStream;
public class TableStoreConf {
private String endpoint;
private String accessId;
private String accessKey;
private String instanceName;
/**
* instance
*/
public static TableStoreConf newInstance(String path) {
try {
InputStream f = new FileInputStream(path);
Gson gson = new Gson();
return gson.fromJson(IOUtils.toString(f), TableStoreConf.class);
} catch (Exception ex) {
throw new RuntimeException(ex);
}
}
public String getEndpoint() {
return endpoint;
}
public void setEndpoint(String endpoint) {
this.endpoint = endpoint;
}
public String getAccessId() {
return accessId;
}
public void setAccessId(String accessId) {
this.accessId = accessId;
}
public String getAccessKey() {
return accessKey;
}
public void setAccessKey(String accessKey) {
this.accessKey = accessKey;
}
public String getInstanceName() {
return instanceName;
}
public void setInstanceName(String instanceName) {
this.instanceName = instanceName;
}
}

@ -0,0 +1,33 @@
package com.aliyun.tablestore.example.grid.common;
import com.aliyun.tablestore.grid.TableStoreGrid;
import com.aliyun.tablestore.grid.TableStoreGridConfig;
public abstract class TableStoreGridExample {
protected TableStoreGrid tableStoreGrid;
// private String pathSeperator = "/";
public TableStoreGridExample(String dataTableName, String metaTableName) {
// String os = System.getProperty("os.name");
// if (os.toLowerCase().startsWith("win")) {
// pathSeparator = "\\";
// }
String pathSeparator = System.getProperty("file.separator");
TableStoreConf conf = TableStoreConf.newInstance(System.getProperty("user.dir") + pathSeparator + "tablestoreConf.json");
TableStoreGridConfig config = new TableStoreGridConfig();
config.setTableStoreEndpoint(conf.getEndpoint());
config.setAccessId(conf.getAccessId());
config.setAccessKey(conf.getAccessKey());
config.setTableStoreInstance(conf.getInstanceName());
config.setDataTableName(dataTableName);
config.setMetaTableName(metaTableName);
tableStoreGrid = new TableStoreGrid(config);
}
public void close() {
if (tableStoreGrid != null) {
tableStoreGrid.close();
}
}
}

@ -0,0 +1,210 @@
# Cursor项目规范
## 基本设置
- 使用中文回答所有问题
- 按照Sequential Thinking方法进行代码设计和实现
## 依赖约束
- 使用Maven作为依赖管理工具
- 使用Maven项目结构
- 使用SpringBoot2.1.4.RELEASE作为框架
- 使用JDK1.8作为开发语言
- 使用Lombok作为代码简化工具
## 项目结构和命名规范
- 组件命名PascalCase
- 函数命名camelCase
- 常量命名UPPER_CASE
- 文件夹结构遵循Maven项目规范
- 接口命名使用I前缀如IUserService
- 类型定义使用T前缀如TUserData
- 文档类统一输出至docs文件夹并使用Markdown格式
## 代码风格
- 使用TypeScript类型定义
- 统一代码缩进和格式
- 使用ESLint和Prettier规则
## 开发流程规则
1. 问题分析:明确任务目标和约束条件
2. 设计方案:设计数据结构和算法
3. 实现步骤:自顶向下实现功能
4. 测试验证:编写单元测试和集成测试
## 代码审查标准
- 代码必须符合既定规范
- 关键函数和组件必须有注释
- 复杂算法需要解释思路
## 提交规范
- 遵循语义化提交信息格式feat:, fix:, docs:等
- 主分支只接受经过测试的代码
## 文档要求
- API接口必须有清晰文档
- 更新README文件反映最新项目状态
## 代码稳定性保障
- 修改已完成功能前必须先理解其完整设计意图
- 所有API更改必须向下兼容
- 使用单元测试保护核心功能逻辑
- 重构代码时必须保持功能等价性
- 在修改前创建功能快照或临时分支
- 每次更改后必须验证不破坏现有功能
- 使用TODO或FIXME标签清晰标记未完成修改
## 版本控制规则
- 使用语义化版本管理
- 关键功能更改必须通过代码审查
- 维护变更日志记录所有修改
- 为已稳定功能模块添加"锁定注释"标记:/* @stable - 请勿修改 */
## UI设计规范
- 遵循现代设计趋势和最佳实践
- 使用设计系统确保一致性如Material Design、Ant Design或自定义设计系统
- 实现响应式设计,确保在不同设备上显示良好
- 使用CSS变量统一管理颜色、字体、间距等设计标记
- 优先采用Flexbox或Grid布局系统
- 确保适当的留白和视觉层次
- 实现无障碍访问标准WCAG 2.1
## UI组件标准
- 使用组件库作为基础如MUI、Chakra UI、Tailwind UI等
- 自定义组件需符合现代设计审美
- 设计组件应包含默认、悬停、聚焦、禁用等状态
- 使用适当的动画和过渡效果增强用户体验
- 确保设计一致性:同类元素使用相同样式
- 使用主题系统支持亮色/暗色模式切换
- 根据用户操作提供视觉反馈
## 设计资源
- 维护设计风格指南和UI组件库
- 使用标准化图标库如Heroicons、Material Icons等
- 图片和插图需保持一致的风格
- 颜色选择须符合品牌标识并确保足够对比度
## 依赖管理规范
- 优先使用国内镜像站点安装依赖
- npm包使用淘宝镜像https://registry.npmmirror.com/
- yarn设置yarn config set registry https://registry.npmmirror.com
- pnpm设置pnpm config set registry https://registry.npmmirror.com
- pip包使用清华镜像https://pypi.tuna.tsinghua.edu.cn/simple
- Docker镜像使用阿里云https://cr.console.aliyun.com/
- Maven依赖使用阿里云https://maven.aliyun.com/repository/public
- Gradle依赖使用阿里云https://developer.aliyun.com/mvn/guide
- 安装新依赖前先验证其在国内是否可访问
- 如确实需使用国外资源,应提供备选方案或离线安装包
- package.json中添加镜像设置脚本便于团队统一配置
- 记录所有依赖的具体版本和来源以便追踪
## 测试自动化规范
- 编写单元测试覆盖所有关键功能
- 实现端到端测试验证用户流程
- 使用测试驱动开发(TDD)方法
- 每次提交前运行自动化测试
- 维护测试数据与生产环境隔离
## 调试与日志规范
- 统一使用日志级别error, warn, info, debug
- 日志信息需包含上下文和时间戳
- 生产环境禁用调试代码和console语句
- 关键流程增加日志记录点便于问题追踪
- 使用结构化日志格式便于分析
## 代码复杂度控制
- 函数不超过50行单个文件不超过300行
- 每个函数只做一件事情,保持单一职责
- 嵌套不超过3层避免过深条件嵌套
- 控制圈复杂度不超过10
- 复杂逻辑应拆分为多个小函数
## 状态管理规范
- 明确状态管理方案如Redux、MobX或Context API
- 区分本地状态和全局状态
- 避免状态冗余和重复存储
- 实现不可变状态更新模式
- 为复杂状态提供初始值和验证机制
## 异步操作规范
- 统一使用async/await或Promise
- 实现请求超时和重试机制
- 处理并发请求限制
- 取消不必要的请求以节省资源
- 使用Loading状态指示异步操作进行中
## 代码重用策略
- 提取通用逻辑为Hooks或工具函数
- 使用组合而非继承实现代码复用
- 避免复制粘贴代码,而应重构为共享组件
- 通用功能应考虑发布为内部npm包
- 明确区分业务逻辑和技术实现
## 项目文档体系
- 维护项目架构图和关键流程图
- 记录技术选型理由和限制条件
- 为API和数据模型提供详细文档
- 记录已知问题和解决方案
- 提供新开发者入门指南
## 构建与发布流程
- 使用CI/CD实现自动化构建和部署
- 区分开发、测试、预发布和生产环境
- 实现回滚机制应对紧急问题
- 使用版本化静态资源避免缓存问题
- 配置文件应随环境变化而不需修改代码
## 可访问性和兼容性规范
- 确保键盘可访问性
- 使用ARIA标签增强屏幕阅读器支持
- 确保适当的颜色对比度
- 响应式设计支持从移动到桌面的所有设备
- 针对低带宽和弱网络场景优化
## 问题追踪与修复流程
- 使用标准化的问题报告模板
- 问题修复前先编写复现步骤
- 每个bug修复应包含相应测试避免回归
- 重大问题需进行根本原因分析
- 定期审查常见错误类型并改进开发流程
## 代码注释最佳实践
- 写清楚为什么这样做,而不仅是做了什么
- 用注释标记未来需要优化的地方
- 所有公共API必须有注释文档
- 复杂业务逻辑需要解释业务规则
- 避免废弃或过时的注释
## 数据处理与安全
- 敏感数据传输必须加密
- 用户输入必须验证和清洗
- 实现数据备份和恢复策略
- 遵循数据最小化原则,只收集必要信息
- 实现适当的数据过期和销毁机制
## 性能优化指南
- 实现资源懒加载和按需加载
- 优化关键渲染路径提高首屏加载速度
- 使用适当的缓存策略减少网络请求
- 批量处理DOM操作避免重排和重绘
- 定期进行性能审计和优化
## 可维护性原则
- 优先考虑代码可理解性而非简洁性
- 避免过早优化和不必要的抽象
- 关键决策需在代码中记录理由
- 避免使用黑魔法和难以理解的技巧
- 团队培训和知识共享机制
## 技术债务管理
- 使用TODO和FIXME标记需要改进的地方
- 定期安排时间清理技术债务
- 新功能实现前评估现有代码质量
- 记录所有已知问题和临时解决方案
- 使用代码质量工具定期评估项目健康度
## 用户体验设计规范
- 所有操作必须提供用户反馈
- 错误信息应该清晰并提供解决方案
- 降低操作复杂度,减少用户认知负担
- 界面风格保持一致性
- 考虑边缘情况和用户出错恢复路径

@ -0,0 +1,474 @@
# 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`
```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`
```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`
```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`
```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`
```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`
```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`
```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`
```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. 开发文档
- 架构说明
- 开发规范
- 测试用例

@ -0,0 +1,249 @@
# 项目整体规划和逻辑结构报告
## 1. 项目概述
### 1.1 项目定位
- 名称Weather Service
- 类型:气象数据服务系统
- 目标提供GFS全球预报系统数据的获取、存储和查询服务
### 1.2 核心功能
1. GFS数据获取
2. 数据存储管理
3. 数据查询服务
4. 数据分析处理
5. 系统监控告警
## 2. 系统架构
### 2.1 技术架构
```mermaid
graph TD
A[客户端] --> B[API网关]
B --> C[Weather Service]
C --> D[数据处理服务]
C --> E[存储服务]
D --> F[GFS数据源]
E --> G[阿里云表格存储]
```
### 2.2 模块划分
1. 数据采集模块
- GFS数据下载
- 数据格式转换
- 数据质量控制
2. 数据存储模块
- 元数据管理
- 数据索引
- 数据压缩
- 数据备份
3. 查询服务模块
- REST API接口
- 数据过滤
- 结果格式化
4. 监控模块
- 系统监控
- 数据监控
- 告警管理
## 3. 数据流设计
### 3.1 数据流程
```mermaid
sequenceDiagram
participant GFS
participant Service
participant Storage
participant Client
GFS->>Service: 气象数据
Service->>Service: 数据处理
Service->>Storage: 存储数据
Client->>Service: 查询请求
Service->>Storage: 检索数据
Storage->>Service: 返回数据
Service->>Client: 响应结果
```
### 3.2 数据模型
1. 气象数据模型
- 时间维度
- 空间维度
- 气象要素
- 预报时效
2. 元数据模型
- 数据源信息
- 数据质量
- 数据统计
- 更新记录
## 4. 接口设计
### 4.1 外部接口
1. 数据获取接口
```
GET /api/v1/weather/data
参数:
- time: 时间
- location: 位置
- variables: 气象要素
```
2. 数据查询接口
```
GET /api/v1/weather/query
参数:
- startTime: 开始时间
- endTime: 结束时间
- region: 区域范围
- elements: 要素列表
```
### 4.2 内部接口
1. 数据处理接口
2. 存储接口
3. 监控接口
## 5. 存储设计
### 5.1 表结构
1. 数据表(gfs_data_table)
- 主键设计
- 分区策略
- 索引设计
2. 元数据表(gfs_meta_table)
- 配置信息
- 统计信息
- 状态信息
### 5.2 存储优化
- 数据压缩
- 冷热数据分离
- 索引优化
- 缓存策略
## 6. 部署架构
### 6.1 环境规划
1. 开发环境
2. 测试环境
3. 预发布环境
4. 生产环境
### 6.2 部署模式
```mermaid
graph TD
A[负载均衡] --> B[服务集群]
B --> C[主存储节点]
B --> D[从存储节点]
E[监控系统] --> B
E --> C
E --> D
```
## 7. 安全设计
### 7.1 访问控制
- 身份认证
- 权限管理
- 接口鉴权
- 数据加密
### 7.2 数据安全
- 传输加密
- 存储加密
- 备份策略
- 审计日志
## 8. 监控告警
### 8.1 监控指标
1. 系统指标
- CPU使用率
- 内存使用率
- 磁盘使用率
- 网络流量
2. 业务指标
- 数据更新延迟
- 查询响应时间
- 数据完整性
- 服务可用性
### 8.2 告警策略
- 告警级别
- 告警渠道
- 告警规则
- 告警升级
## 9. 项目规划
### 9.1 开发计划
1. 第一阶段:基础架构
- 框架搭建
- 核心功能实现
- 基本测试
2. 第二阶段:功能完善
- 接口开发
- 数据处理
- 存储优化
3. 第三阶段:性能优化
- 性能测试
- 负载均衡
- 监控告警
### 9.2 运维计划
1. 部署策略
2. 备份策略
3. 监控策略
4. 应急预案
## 10. 风险控制
### 10.1 技术风险
- 数据源稳定性
- 存储容量规划
- 性能瓶颈
- 系统扩展性
### 10.2 业务风险
- 数据准确性
- 服务可用性
- 用户体验
- 运维成本
## 11. 评估指标
### 11.1 性能指标
- 响应时间:<500ms
- 并发能力:>1000QPS
- 数据延迟:<5min
- 可用性:>99.9%
### 11.2 质量指标
- 代码覆盖率:>80%
- 接口可用性:>99.9%
- 数据准确率:>99.99%
- 故障恢复时间:<30min
## 12. 总结与建议
### 12.1 项目优势
1. 架构清晰,模块化设计
2. 性能优化,可扩展性好
3. 安全可靠,运维友好
4. 监控完善,风险可控
### 12.2 改进建议
1. 持续优化数据处理流程
2. 加强系统安全性
3. 完善监控告警机制
4. 优化用户体验
5. 提高系统可用性

@ -0,0 +1,164 @@
# 项目文件分析报告
## 1. 项目结构概览
```
weather-service/
├── src/ # 源代码目录
│ ├── main/ # 主要源代码
│ └── test/ # 测试代码
├── target/ # 编译输出目录
├── docs/ # 项目文档
├── GFSData/ # GFS数据存储目录
├── logError/ # 错误日志目录
├── logInfo/ # 信息日志目录
├── .idea/ # IntelliJ IDEA配置目录
├── .vscode/ # VSCode配置目录
└── 配置文件
├── pom.xml # Maven项目配置文件
├── .cursorrules # 项目规范配置
├── gfsDataConfig.json # GFS数据配置
├── tableConf.json # 表格配置
└── tablestoreConf.json # 表格存储配置
```
## 2. 核心配置文件分析
### 2.1 pom.xml
- 类型Maven配置文件
- 作用:管理项目依赖和构建配置
- 主要配置:
- SpringBoot 2.1.4.RELEASE
- JDK 1.8
- Lombok
- 其他项目依赖
### 2.2 gfsDataConfig.json
- 类型GFS数据配置文件
- 作用配置GFS气象数据的获取参数
- 主要配置:
```json
{
"duration": 30,
"minLon": 70.0,
"maxLon": 140.0,
"minLat": 0.0,
"maxLat": 55.0,
"resolution": 0.25,
"variables": ["DZDT", "RH", "TMP", "UGRD", "VGRD", "TCDC", "PRATE"],
"pressureLevels": [400-1000],
"heightLevels": [2-100],
"saveRoot": "./GFSData"
}
```
- 配置说明:
- 经纬度范围:覆盖中国及周边区域
- 分辨率0.25度
- 气象变量:包括温度、湿度、风速等
- 气压层次15个层次
- 高度层次8个层次
### 2.3 tableConf.json
- 类型:数据表配置文件
- 作用:配置数据存储表结构
- 主要配置:
```json
{
"dataTableName": "gfs_data_table",
"metaTableName": "gfs_meta_table",
"dataIndexName": "gfs_data_index",
"metaIndexName": "gfs_meta_table_index",
"dataDir": "./GFSData/",
"variableList": ["temp", "cloud", "windSpeed", "wind360", "humidity", "precip"],
"lonSize": 281,
"latSize": 221,
"levSize": 15,
"timeToLive": 1
}
```
- 配置说明:
- 数据表结构定义
- 索引配置
- 变量列表
- 网格尺寸
- 数据生命周期
### 2.4 tablestoreConf.json
- 类型:阿里云表格存储配置文件
- 作用:配置表格存储服务连接参数
- 主要配置:
- endpoint服务端点
- accessId访问ID
- accessKey访问密钥
- instanceName实例名称
- 安全说明:建议使用环境变量管理敏感信息
## 3. 目录结构分析
### 3.1 src/
- main/:主要源代码目录
- 遵循Maven标准目录结构
- 包含Java源代码和资源文件
- test/:测试代码目录
- 单元测试
- 集成测试
### 3.2 数据目录
- GFSData/
- 存储GFS气象数据
- 按配置文件中的结构组织
### 3.3 日志目录
- logError/:错误日志存储
- logInfo/:信息日志存储
- 建议:
- 实现日志轮转
- 设置日志级别
- 定期清理
### 3.4 IDE配置目录
- .idea/IntelliJ IDEA配置
- .vscode/VSCode配置
- 建议:
- 统一团队IDE配置
- 添加必要的.gitignore规则
## 4. 文件依赖关系
```mermaid
graph TD
A[pom.xml] --> B[项目依赖管理]
C[gfsDataConfig.json] --> D[GFS数据获取]
D --> E[GFSData目录]
F[tableConf.json] --> G[数据表结构]
H[tablestoreConf.json] --> I[阿里云存储服务]
G --> I
D --> G
```
## 5. 建议与改进
1. 配置文件管理
- 将敏感信息移至环境变量
- 区分开发和生产环境配置
- 添加配置文件注释说明
2. 日志管理
- 实现日志分级存储
- 添加日志轮转策略
- 规范日志格式
3. 数据存储
- 优化数据存储结构
- 实现数据备份策略
- 添加数据验证机制
4. 代码组织
- 完善单元测试
- 添加API文档
- 规范代码注释
5. 安全性
- 加密敏感配置
- 实现访问控制
- 添加数据校验

@ -0,0 +1,132 @@
# 项目规范分析报告
## 1. 技术栈规范
### 1.1 基础框架
- 开发语言JDK 1.8
- 框架选型SpringBoot 2.1.4.RELEASE
- 项目管理Maven
- 代码简化Lombok
### 1.2 前端技术规范
- 开发语言TypeScript
- 代码规范ESLint + Prettier
- UI框架支持Material Design、Ant Design等
- 状态管理支持Redux、MobX、Context API
## 2. 开发规范
### 2.1 命名规范
- 组件命名PascalCase
- 函数命名camelCase
- 常量命名UPPER_CASE
- 接口命名I前缀如IUserService
- 类型定义T前缀如TUserData
### 2.2 文件组织
- 遵循Maven标准项目结构
- 文档统一存放在docs目录
- 使用Markdown格式编写文档
### 2.3 代码质量控制
- 函数长度≤50行
- 文件长度≤300行
- 嵌套深度≤3层
- 圈复杂度≤10
- 单一职责原则:每个函数只做一件事
## 3. 工程化规范
### 3.1 版本控制
- 语义化版本管理
- 语义化提交信息feat:, fix:, docs:等)
- 主分支代码必须经过测试
- 使用锁定注释标记稳定功能
### 3.2 依赖管理
- 优先使用国内镜像源
- Maven依赖阿里云镜像
- npm包淘宝镜像
- Docker镜像阿里云
- 记录依赖版本和来源
### 3.3 测试规范
- 单元测试覆盖关键功能
- 端到端测试验证用户流程
- 采用TDD开发方法
- 测试数据与生产环境隔离
## 4. 安全规范
### 4.1 数据安全
- 敏感数据传输加密
- 用户输入验证和清洗
- 实现数据备份策略
- 遵循数据最小化原则
- 数据生命周期管理
### 4.2 代码安全
- API向下兼容
- 环境配置分离
- 避免硬编码敏感信息
- 定期安全审计
## 5. 性能规范
### 5.1 前端性能
- 资源懒加载
- 优化首屏加载
- 合理使用缓存
- 优化DOM操作
- 响应式设计
### 5.2 后端性能
- 合理使用连接池
- 优化数据库查询
- 实现请求限流
- 异步处理长任务
- 定期性能监控
## 6. 文档规范
### 6.1 必要文档
- API接口文档
- 数据模型文档
- 架构设计文档
- 部署文档
- 使用手册
### 6.2 文档要求
- 及时更新
- 版本对应
- 结构清晰
- 示例完整
- 便于维护
## 7. 协作规范
### 7.1 开发流程
1. 问题分析
2. 方案设计
3. 功能实现
4. 测试验证
5. 代码审查
6. 部署上线
### 7.2 团队协作
- 统一开发环境
- 代码审查制度
- 知识共享机制
- 技术债务管理
- 定期代码重构
## 8. 总结
该项目规范体系完整,覆盖了从开发到部署的各个环节,有助于:
1. 提高代码质量
2. 规范开发流程
3. 保障系统安全
4. 优化性能表现
5. 促进团队协作
建议在实际开发中严格执行这些规范,并根据项目实际情况进行适当调整和优化。

@ -0,0 +1,54 @@
package com.htfp.weather.web.controller;
import com.google.common.primitives.Ints;
import com.htfp.weather.griddata.common.TableConfig;
import com.htfp.weather.web.config.aspect.ControllerLog;
import com.htfp.weather.web.exception.ErrorCode;
import com.htfp.weather.web.param.response.LevelsAvailableResponse;
import com.htfp.weather.web.param.response.LevelsAvailableResponse.LevelsAvailable;
import com.htfp.weather.web.param.response.Result;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
import java.util.*;
/**
* @Author : shiyi
* @Date : 2024/4/21 15:56
* @Description :
*/
@CrossOrigin
@RestController
@Slf4j
@RequestMapping("/htfp/weather/v1/info")
public class InfoController {
@Resource
TableConfig tableConfig;
@PostMapping("/queryLevelsAvailable")
@ControllerLog(info = "可选高度查询")
public Result queryLevelsAvailable(Map<String, String> params) {
String dataSource = params.get("dataSource");
List<LevelsAvailable> levelsAvailableList = new ArrayList<>();
if (StringUtils.isEmpty(dataSource)) {
levelsAvailableList.add(
new LevelsAvailable(
"GFS",
Ints.asList(tableConfig.getPressureList()),
Ints.asList(tableConfig.getPressureHeightList()))
);
} else {
if (dataSource.equals("GFS")) {
levelsAvailableList = Collections.singletonList(
new LevelsAvailable(
"GFS",
Ints.asList(tableConfig.getPressureList()),
Ints.asList(tableConfig.getPressureHeightList()))
);
}
}
return Result.success(new LevelsAvailableResponse(levelsAvailableList));
}
}

@ -6,9 +6,6 @@ spring:
mvc:
servlet:
load-on-startup: 1 # 关闭 dispatcherServlet懒加载
# thymeleaf:
# cache: false
# encoding: UTF-8
mail:
host: smtp.exmail.qq.com
username: shiyi@htsdfp.com
@ -20,7 +17,6 @@ spring:
auth: true
enable: true
required: true
task:
scheduling:
pool:

Loading…
Cancel
Save