QDAirPortBackend0122/doc/guide/configuration_guide.md

碰撞避免系统配置文件说明文档

本文档详细描述了碰撞避免系统中的各种配置文件，按照它们在项目中的位置进行组织说明。不同位置的配置文件负责系统不同方面的功能配置。

1. 配置文件结构概览

系统的配置文件按照以下目录结构组织：

com.dongni.collisionavoidance/
├── common/config/            # 通用配置
├── config/                   # 应用级全局配置
├── dataCollector/config/     # 数据采集模块配置
├── dataProcessing/config/    # 数据处理模块配置
└── webSocket/config/         # WebSocket通信模块配置

2. 通用配置 (common/config)

通用配置位于com.dongni.collisionavoidance.common.config包下，提供了系统中通用的基础设施配置。

2.1 SchedulerConfig.java

功能: 定时任务线程池配置

说明:

• 创建自定义线程池，避免定时任务单线程阻塞的情况
• 启用Spring的异步支持（@EnableAsync）
• 配置ThreadPoolTaskScheduler以执行定时任务

关键配置:

@Configuration
@EnableAsync  // 启用异步支持
public class SchedulerConfig {

    @Bean
    public ThreadPoolTaskScheduler taskScheduler() {
        ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
        // 设置线程池大小，根据需求调整
        scheduler.setPoolSize(3);
        // 设置线程名称前缀
        scheduler.setThreadNamePrefix("ScheduledTask-");
        return scheduler;
    }
}

用途:

• 用于管理系统中的各种定时任务，如定期数据采集、数据清理等
• 通过线程池提高系统定时任务的并发处理能力
• 防止单个定时任务阻塞导致其他任务延迟执行

3. 应用级全局配置 (config)

应用级全局配置位于com.dongni.collisionavoidance.config包下，提供了影响整个应用的核心配置。

3.1 RedisConfig.java

功能: Redis缓存配置

说明:

• 配置RedisTemplate，用于与Redis交互
• 配置序列化器，处理Java对象与Redis数据的转换
• 特别针对VehicleLocationInfo类进行了优化

关键配置:

@Configuration
public class RedisConfig {
    
    @Bean
    public RedisTemplate<String, VehicleLocationInfo> redisTemplate(RedisConnectionFactory connectionFactory) {
        RedisTemplate<String, VehicleLocationInfo> template = new RedisTemplate<>();
        template.setConnectionFactory(connectionFactory);
        
        // 使用Jackson2JsonRedisSerializer来序列化和反序列化redis的value值
        Jackson2JsonRedisSerializer<VehicleLocationInfo> serializer = 
            new Jackson2JsonRedisSerializer<>(VehicleLocationInfo.class);
        
        ObjectMapper mapper = new ObjectMapper();
        mapper.registerModule(new JavaTimeModule());
        serializer.setObjectMapper(mapper);
        
        template.setValueSerializer(serializer);
        template.setHashValueSerializer(serializer);
        
        // 使用StringRedisSerializer来序列化和反序列化redis的key值
        template.setKeySerializer(new StringRedisSerializer());
        template.setHashKeySerializer(new StringRedisSerializer());
        
        template.afterPropertiesSet();
        return template;
    }
}

用途:

• 提供高效的车辆位置信息缓存机制
• 支持实时数据快速读写
• 通过JavaTimeModule支持Java 8日期时间类型序列化

3.2 ThreadPoolConfig.java

功能: 数据处理线程池配置

说明:

• 创建用于数据处理的线程池执行器
• 配置核心线程数、最大线程数和队列容量
• 为线程设置有意义的名称前缀

关键配置:

@Configuration
public class ThreadPoolConfig {

    @Bean(name = "processingExecutor")
    public Executor processingExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(10);
        executor.setMaxPoolSize(100);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("data-process-");
        executor.initialize();
        return executor;
    }
}

用途:

• 用于处理大量并发的数据处理任务
• 避免数据处理任务阻塞主线程
• 优化系统资源利用，提高处理效率

3.3 道路网络配置 (RoadNetworkConfig & Properties)

功能: 加载和管理机场道路网络静态配置

配置源: src/main/resources/config/airport_roads.yaml

说明:

• 定义了一套 POJO 类（位于 com.dongni.collisionavoidance.config.properties 包下，如 AirportRoadsProperties, RoadProperties 等）来精确映射 airport_roads.yaml 文件的结构。
• AirportRoadsProperties 类使用 @ConfigurationProperties 注解（无前缀）来声明其属性来源于配置文件。
• RoadNetworkConfig.java 类（位于 com.dongni.collisionavoidance.config 包下）使用 @Configuration, @EnableConfigurationProperties(AirportRoadsProperties.class) 和 @PropertySource 注解。
• @PropertySource 指定加载 airport_roads.yaml 文件，并指定 YamlPropertySourceFactory.java 作为解析工厂。
• @EnableConfigurationProperties 激活 AirportRoadsProperties 成为一个 Spring Bean，其属性值会自动从加载的 YAML 文件中填充。

关键组件:

• config/properties/*.java: 配置属性 POJO 类。
• config/RoadNetworkConfig.java: 启用配置加载的主配置类。
• config/YamlPropertySourceFactory.java: 支持 @PropertySource 加载 YAML 的工厂类。

用途:

• 将静态的道路网络信息（几何、限速、限制等）加载到内存中。
• 为 RoadNetworkService 提供原始配置数据，以便其进行处理和初始化。
• 实现道路网络配置与应用程序代码的解耦。

4. 数据采集模块配置 (dataCollector/config)

数据采集模块配置位于com.dongni.collisionavoidance.dataCollector.config包下，专注于数据采集相关的配置。

4.1 RestTemplateConfig.java

功能: HTTP客户端配置

说明:

• 配置RestTemplate用于外部API调用
• 自定义ObjectMapper，忽略未知属性以增强兼容性
• 将自定义ObjectMapper应用到RestTemplate的消息转换器

关键配置:

@Configuration
public class RestTemplateConfig {

    @Bean
    public RestTemplate restTemplate(ObjectMapper objectMapper) {
        RestTemplate restTemplate = new RestTemplate();
        restTemplate.getMessageConverters().forEach(converter -> {
            if (converter instanceof MappingJackson2HttpMessageConverter) {
                ((MappingJackson2HttpMessageConverter) converter).setObjectMapper(objectMapper);
            }
        });
        return restTemplate;
    }

    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        return mapper;
    }
}

用途:

• 用于从外部系统或API获取航空器、车辆等移动物体数据
• 通过配置的ObjectMapper实现宽松的JSON解析，提高与外部系统的兼容性
• 支持数据采集模块的HTTP通信需求

5. 数据处理模块配置 (dataProcessing/config)

数据处理模块配置位于com.dongni.collisionavoidance.dataProcessing.config包下，专注于数据处理和分析相关配置。

5.1 CoordinateSystemProperties.java

功能: 坐标系统配置

说明:

• 从application.yml配置文件中读取机场中心点坐标
• 使用@ConfigurationProperties将配置值绑定到Java属性
• 提供getter/setter方法访问配置值

关键配置:

@Component
@ConfigurationProperties(prefix = "coordinate-system.airport")
public class CoordinateSystemProperties {
    
    private double centerLongitude;
    private double centerLatitude;
    
    // getter和setter方法
}

用途:

• 为坐标转换和距离计算提供基准点
• 在碰撞风险评估中作为参考坐标
• 支持局部坐标系与地理坐标系之间的转换

6. WebSocket通信模块配置 (webSocket/config)

WebSocket通信模块配置位于com.dongni.collisionavoidance.webSocket.config包下，负责实时通信相关配置。

6.1 JacksonConfig.java

功能: JSON序列化配置

说明:

• 配置Jackson2ObjectMapperBuilder
• 设置序列化选项，如缩进输出、忽略null值
• 禁用将日期写为时间戳的功能

关键配置:

@Configuration
public class JacksonConfig {

    @Bean
    public Jackson2ObjectMapperBuilder objectMapperBuilder() {
        return new Jackson2ObjectMapperBuilder()
            .indentOutput(true)
            .serializationInclusion(JsonInclude.Include.NON_NULL)
            .featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
    }
}

用途:

• 为WebSocket通信提供一致的JSON序列化行为
• 优化JSON输出格式，提高可读性
• 通过忽略null值减少传输数据量

6.2 WebSocketConfig.java

功能: WebSocket通信配置

说明:

• 启用WebSocket消息代理
• 注册STOMP端点并配置跨域访问
• 配置消息代理前缀和应用目标前缀
• 添加JSON消息转换器

关键配置:

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        // 注册STOMP端点，客户端通过此URL连接WebSocket
        registry.addEndpoint("/ws")
                .setAllowedOriginPatterns("*") // 允许跨域
                .withSockJS(); // 启用SockJS支持
    }

    @Override
    public void configureMessageBroker(MessageBrokerRegistry registry) {
        // 启用内存消息代理，客户端订阅地址前缀为/topic
        registry.enableSimpleBroker("/topic");
        // 客户端发送消息的地址前缀为/app
        registry.setApplicationDestinationPrefixes("/app");
    }

    @Override
    public boolean configureMessageConverters(List<MessageConverter> messageConverters) {
        messageConverters.add(new MappingJackson2MessageConverter());
        return false;
    }
}

用途:

• 为前端客户端提供实时数据推送功能
• 支持移动物体位置的实时更新
• 实现碰撞警告的即时通知机制
• 通过STOMP子协议规范化WebSocket通信

7. 配置之间的关系

系统中不同位置的配置文件相互协作，共同支持碰撞避免系统的运行：

1. 线程池配置 (SchedulerConfig, ThreadPoolConfig)

   • 提供异步处理能力，支持定时采集和高并发数据处理

2. 数据存储配置 (RedisConfig)

   • 为实时数据提供高效缓存机制

3. 通信配置 (RestTemplateConfig, WebSocketConfig)

   • 支持与外部系统数据交换和向客户端推送实时信息

4. 数据处理配置 (CoordinateSystemProperties)

   • 提供坐标转换和碰撞计算的基础参数

5. 序列化配置 (JacksonConfig)

   • 确保系统中JSON数据的一致性处理

6. 道路网络配置 (RoadNetworkConfig & Properties)

   • 加载静态道路几何、限速、限制等信息，为数据处理模块提供关键的环境上下文。