简体中文
反无前端
本文记录我在该项目中承担的 Web 前端开发工作。后端感知、识别与算法部分不在我的职责范围内,本文不作涉及。
一、项目概况
项目是一套面向低空安防的无人机探测与反制平台,业务链路为探测发现、识别定位、预警告警、反制处置四个环节。
前端在这个系统中承担三项职责:
- 实时态势呈现。在地图上持续刷新无人机轨迹、侦察单元与干扰单元位置,并输出频谱图、雨图与测向结果。
- 目标处置操作。由操作员在地图上选定目标,配置策略与参数,下发干扰指令。
- 系统配置管理。提供数据管理、设备管理、系统设置等后台页面。
二、我的职责与投入
我于 2026 年 4 月 28 日进项目,2026 年 7 月 24 日结束,负责 Web 前端。接手时前端只有基础框架,页面主体尚未搭建。
具体负责范围包括:数据管理模块从零搭建、国际化方案落地、主地图实时交互、策略与处置流程、系统自检面板、态势复盘、登录与权限,以及 API 层重构。
仓库累计 605 次提交,其中我提交 133 次,剔除合并提交后为 110 次,共涉及 121 个文件。
三、技术栈
| 分类 | 选型 | 版本 |
|---|---|---|
| 框架 | React + Umi | 18 / 4 |
| UI 组件 | Ant Design | 4.24.16 |
| 地图 | OpenLayers | 10.6.1 |
| 实时通信 | socket.io-client | 2.2.0 |
| 图表 | ECharts | 5.5.1 |
| 坐标转换 | coordtransform | 2.1.2 |
| 工具库 | ahooks、lodash | 3.8.4 / 4.17 |
| 运行时 | Node(Volta 锁定) | 18.20.8 |
需要说明的是 socket.io 客户端锁定在 2.2.0,不是当前常见的 4.x,升级会导致与服务端协议不兼容。
四、具体工作
4.1 数据管理模块(从零搭建)
接手时该目录为空,我逐个模块搭建,最终交付 13 个功能页面。
| 模块 | 主要能力 |
|---|---|
| 用户管理 | 用户增删改查、重置密码、按钮级权限控制 |
| 角色管理 | 角色列表、权限分配 |
| 操作日志 | 分页查询、详情、导出、清空 |
| 系统日志 | 分页查询、下载、清空 |
| 目标历史 | 查询、导出、单条删除、批量删除、清空 |
| 机型库 | 机型增删改查、批量导入导出、模板下载 |
| 数据库管理 | 备份、还原、单库备份、拖拽上传 SQL |
| 系统设置 | 系统时间与对时、设备位置、作战模式、信号阈值、罗盘校准、LoRa 信道配置 |
| 态势复盘 | 地图回放、目标历史重放 |
| 频谱回放 | 回放文件管理与回放弹窗 |
| IQ 采集 | 采集启停、下载、删除、IQ 回放 |
| 无人值守 | 频段模板配置、方向与处置方式位掩码映射 |
| 导航菜单 | 数据管理模块左侧导航 |
在模块推进过程中同步做了三项结构治理:
第一,统一搜索栏。早期每个页面各写一套查询表单与请求逻辑,写到第三个模块时重复度已经无法维护,抽成统一的 SearchBar 组件,样式与查询参数走同一套。
第二,统一弹窗。原先是自研的 Modal 组件,后改用 Ant Design 原生 Modal,弹窗状态集中管理。
第三,目录结构调整。早期模块全部堆在 component 子目录下,层级嵌套过深,后统一提升为按模块平铺的目录结构。
4.2 国际化
项目要求支持中文、英文、法文、俄文四种语言,整套方案由我落地。
基于 Umi 的 locale 插件,语言包放在 src/locales 目录,中文语言包约一千条词条。设计上采用中文原文直接作为 key:
jsx
{intl.formatMessage({ id: '确定要切换到' }, { 模式: modeName })}这样翻译时可直接对照中文查找,不必额外维护映射表,代价是 key 较长。相应的维护成本是新增文案需同步四个语言包,早期存在遗漏,后期形成固定习惯,仅语言包同步相关的提交就有二十余次。
4.3 主地图与实时态势
主地图页面是整个前端最重的部分,单文件三千七百余行。
实时数据全部通过 socket 推送,页面订阅并处理六类事件:无人机实时位置、侦察单元位置、设备状态、设备位置、测向信号、国标识别结果。
地图部分处理了四个关键点:
- 坐标转换。后端提供 WGS84 坐标,地图使用 GCJ-02,封装 toMapCoord 完成 wgs84togcj02 到 WebMercator 的链路转换。由于不同部署环境的底图不一致,GCJ-02 环节做成运行时可开关,配置从运行时配置文件读取。
- 图标样式。抽取三个样式生成函数,分别负责图标、线条与网格。无人机图标选中态变色、方向图标按角度旋转均调用同一套函数。
- 渲染性能。socket 推送频率为秒级多次,轨迹点与地图图标全部存放在 ref 中,不进入 React 渲染流程,仅界面状态使用 state。这是该页面能保持流畅的前提。
- 动画与清理。雷达扫描圈使用 requestAnimationFrame 实现,组件卸载时统一执行取消动画帧与解绑地图监听,否则重复进入页面会出现动画叠加。
4.4 策略、处置与参数
策略管理面板按频段配置干扰策略。原有频率校验是全局粒度,我改为按单个频段组校验,跨度超过 400MHz 时提示。
处置抽屉包含导航干扰设备选择、处置方式(压制、驱离、迫降、防御)、四组导航频点、驱离角度与频段保护,配置持久化在浏览器本地存储。
其余还有频段保护弹窗与侦察管理面板,后者重构为支持多组侦察参数与全景模式。
4.5 系统自检面板
自检面板分左右两栏,分别展示干扰单元与侦察单元的运行状态,字段包括温度、电压、频段电流、功放告警与电子罗盘角度。
该面板的难点在位语义判断。以侦察单元为例,异常字段按位定义:bit0 超温、bit1 欠压、bit2 超压、bit3 频段一电流过小、bit4 频段一过流;干扰单元额外包含五个频段的过流标志位。电压与电流数值均以十分之一为单位存储,展示时需还原。
我在此处补充了一项改动:将干扰与侦察各自的检测时间戳分开展示。此前两者共用一个时间字段,无法判断具体是哪一侧执行过自检。
4.6 态势复盘
该页面同样基于 OpenLayers,增加回放控制条。我完成的工作包括表单条件记忆、重放按钮、正北方向线箭头、图例样式调整以及取消地图旋转。此外修复了目标历史无法渲染的问题,并将测向线绘制逻辑与主地图对齐。
4.7 登录、权限与 API 层
登录部分完成登录页、登录布局与认证逻辑,密码采用 MD5 处理。路由守卫基于 permission 工具与 auth 包装层,按钮级权限通过统一的权限判断函数控制显隐。
API 层做了一次重构,将原先集中在单个 service 文件中的接口按业务模块拆分到子目录,一个模块一个文件。
4.8 其他
数据库管理支持备份还原与 SQL 文件拖拽上传,无人值守配置完成自动模式接口对接,修复了生产环境地图配置问题,并将频谱图扫描的开始与停止按钮改为状态互斥联动。
五、关键问题与处理
5.1 实时订阅重复绑定
socket.on 每次调用都会新增一个监听,页面重进或组件重渲染会导致监听叠加,回调被重复触发。
处理方式是在订阅函数内先执行一次解除绑定,再重新绑定;若此时连接尚未建立,则注册一次性连接回调,待连接成功后再绑定。
此外还有一个隐藏问题:订阅函数没有返回值,而自检面板中存在 const unsubscribe = subscribe(...) 的写法,取到的是 undefined,后续的退订语句从未生效。正确做法是使用单独导出的退订函数。该问题在代码评审阶段发现。
5.2 组件库版本差异
Ant Design 从 v4 升级到 v5 后,尺寸类名由 lg 改为 large,导致整体样式偏差一档,排查耗时较长。
5.3 文档与代码不一致
仓库根目录的前端交接文档内容较完整,但其中的目录结构已经过期,文档提到的部分组件在当前代码中并不存在,实际对应的是另外的组件。接手人员按文档查找文件会无法定位。
六、量化结果
| 指标 | 数值 |
|---|---|
| 仓库提交总数 | 605 |
| 本人提交数(含合并) | 133 |
| 本人提交数(不含合并) | 110 |
| 涉及文件数 | 121 |
| 交付管理模块 | 13 |
按月份分布:4 月 13 次、5 月 90 次、6 月 9 次、7 月 21 次。5 月投入最集中,主要落在数据管理模块。
按提交类型分布:功能新增 43 次、重构 23 次、缺陷修复 18 次、样式调整 18 次、工程杂项 3 次、文档 1 次,其余 27 次为不规范提交信息。
七、遗留问题
文档维护未跟上代码迭代。交接文档的目录结构与实际代码已有偏差,项目内的 docs 目录建成后一直为空。这类工作前期未纳入计划,后期补齐成本较高。
