系列导航共 15 篇入门篇01 AFSIM 是什么 · 02 从零搭建环境 · 03 跑通第一个仿真 · 04 核心概念扫盲基础篇05 SDL 入门 · 06 Platform 详解 · 07 传感器与跟踪 · 08 武器与交战 · 09 机动与航线进阶篇10 通信与处理器 · 11 External Control · [12 TCP 客户端实战] · 13 Wizard 可视化高级篇14 C 插件开发 · 15 调试与最佳实践上一篇11 External Control 下一篇13 Wizard 可视化12 Java/Python 接入 AFSIMTCP 客户端开发实战第 11 篇《External Control》 里我们讲了 wsf_external_control 插件会在本机 127.0.0.1:31000 起一个 TCP server。本篇就动手——用 Java 写一个 TCP 客户端连上去把它真正驱动起来。我会给出可对照的代码片段、JSON 指令格式、Spring Boot 集成方式再附一段 Python 等价实现和踩坑清单。一、先看清通信契约在写代码前要明确我们连的是 127.0.0.1:31000 的 TCP server连接建立后双向收发管道分隔的纯文本命令真实格式为 COMMAND|keyvalue|…每条消息以换行符 \n 作为分隔行协议简单可靠。客户端主动拉取状态、主动下发指令插件主动推送 track 快照响应 DATA|…。记住这个行协议 管道文本的基调后面代码都围绕它第 11 篇 已用安装实证纠正了此前JSON的说法。为什么是 127.0.0.1环回地址而不是某个局域网 IP因为外部控制追求最低延迟与最高安全——控制程序通常和 AFSIM 引擎跑在同一台机器上走环回网卡几乎零网络开销也不会把仿真端口暴露给外部网络被人误连。如果你的架构确实需要跨机控制例如后端部署在另一台服务器那就得把插件监听地址改成可达 IP并叠加防火墙与鉴权否则等于把开火权敞开了大门。对绝大多数学习与原型场景守住 127.0.0.1 是最省心也最稳妥的选择。二、Java TCP 客户端核心代码下面是一个最小可对照的 Java 客户端骨架建立 Socket、拿到读写流、按行收发。javapublicclassAFSIMClient{privatefinalStringhost127.0.0.1;privatefinalintport31000;privateSocketsocket;privateBufferedReaderin;privateBufferedWriterout;publicvoidconnect()throwsIOException{socketnewSocket(host,port);// 连接插件 TCP serverinnewBufferedReader(newInputStreamReader(socket.getInputStream(),StandardCharsets.UTF_8));outnewBufferedWriter(newOutputStreamWriter(socket.getOutputStream(),StandardCharsets.UTF_8));System.out.println(已连接 AFSIM 外部控制端口 host:port);}// 发送一行 JSON 指令以 \n 结尾publicvoidsend(Stringjson)throwsIOException{out.write(json);out.write(\n);out.flush();}// 读取插件推送的一行track / 状态publicStringreceive()throwsIOException{returnin.readLine();}}注意务必用 StandardCharsets.UTF_8 统一编码否则中文平台名或日志可能出现乱码详见第四节坑点。三、COMMAND|keyvalue 指令封装真实线协议⚠️ 重要纠正本系列前文含 第 11 篇曾把协议示意成 JSONfly_to / fire_weapon。但 wsf_external_control 插件的真实线协议是管道分隔纯文本每条指令形如 COMMAND|keyvalue|keyvalue以换行结束响应为 OK|… / ERROR|… / DATA|…。下面代码全部改用真实格式。结合真实项目里的 UAV_01RECON_STRIKE_UAV与 Enemy_ShipENEMY_DDG一条让无人机抵近并打击的指令长这样text MOVE_TO|platformUAV_01|lat32.85|lon120.50|alt8000|speed220FIRE|platformUAV_01|weaponfox3|targetEnemy_Ship|qty1插件收到后会分别翻译成 第 11 篇 讲的 FlyToEvent 与 FireWeaponEvent入队由仿真执行。封装成方法很自然javapublicvoidmoveTo(Stringplatform,doublelat,doublelon,doublealt,doublespeed)throwsIOException{StringcmdString.format(MOVE_TO|platform%s|lat%f|lon%f|alt%f|speed%f,platform,lat,lon,alt,speed);send(cmd);}publicvoidfireWeapon(Stringplatform,Stringweapon,Stringtarget)throwsIOException{StringcmdString.format(FIRE|platform%s|weapon%s|target%s|qty1,platform,weapon,target);send(cmd);}有两个易错点值得提前说第一坐标单位与原点必须和插件端约定一致经纬度用十进制度或度分秒串取决于插件解析逻辑否则无人机会飞到一个莫名其妙的点第二target 填的是平台名字符串如 “Enemy_Ship”插件会去 WsfTrackList 里查这个名字对应的 track 再开火名字拼错就会找不到目标。在真实项目里我们通常会先发 GET_STATUS / LIST_PLATFORMS 确认目标存在且在我方射程内再下发 FIRE避免盲目开火。四、与 Spring Boot 集成真实项目里客户端不会裸跑而是作为 Spring Boot 的一个服务 bean 管理连接生命周期并通过 Controller 暴露给前端。仿真适配器项目架构如下图所示核心类就是 ExternalControlServicejavaServicepublicclassExternalControlService{privateAFSIMClientclient;PostConstructpublicvoidinit()throwsIOException{clientnewAFSIMClient();client.connect();// 应用启动即连 127.0.0.1:31000startReceiveLoop();// 后台线程持续拉取 track}privatevoidstartReceiveLoop(){newThread(()-{try{while(true){Stringlineclient.receive();// 插件推送的 track/状态if(linenull)break;handleTrack(line);// 更新态势、触发决策}}catch(IOExceptione){/* 重连逻辑 */}}).start();}publicvoidorderStrike()throwsIOException{client.flyTo(UAV_01,120000,85000,5000);client.fireWeapon(UAV_01,Enemy_Ship);}}再用一个 Controller 把能力暴露出去javaRestControllerRequestMapping(/afsim)publicclassExternalControlController{AutowiredprivateExternalControlServicesvc;PostMapping(/strike)publicStringstrike()throwsIOException{svc.orderStrike();return指令已下发;}}这样前端点一下按钮后端就通过 TCP 把指令送进仿真——一个完整的感知-决策-行动闭环就搭好了。五、Python 等价客户端如果你更习惯 Python比如做算法验证等价实现非常短pythonimportsocketdefmain():ssocket.create_connection((127.0.0.1,31000))# 真实协议管道分隔纯文本以 \n 结尾s.sendall(bMOVE_TO|platformUAV_01|lat32.85|lon120.50|alt8000|speed220\n)print(s.recv(4096).decode(utf-8))# 形如 OK|... 或 DATA|...s.close()if__name____main__:main()可见 Python 与 Java 的差异只在语法通信契约完全一致——同一套 COMMAND|keyvalue 管道文本协议谁都能连。在真实项目里我们的客户端遵循一个简单但稳健的先读后写模式启动后先持续 receive() 插件推送的 track 快照把它解析成内存里的态势对象业务线程如 Controller 收到前端请求再基于这份最新态势决定要不要下发 MOVE_TO / FIRE。也就是说读是常驻后台线程写是按需触发两者通过同一个 Socket 协作。多线程共用一个输出流时要加锁避免两条指令黏在一起被插件当一条解析而报错。这个小细节是多数初学者第一次联调时最容易被绊倒的地方。六、常见坑清单连接被拒Connection refused99% 是 wsf_external_control 插件没启动或仿真还没跑到监听那一步。确认 AFSIM 场景已加载该插件、仿真正在运行再确认端口确实是 31000 而非被改过。别急着改代码先看 Wizard 运行日志有没有external control listening字样。编码乱码务必客户端与插件两端统一 UTF-8Java 不要依赖平台默认编码。Windows 上 new OutputStreamWriter(socket.getOutputStream()) 不指明字符集时会用系统默认GBK与插件的 UTF-8 一碰面中文就乱码——始终显式传 StandardCharsets.UTF_8。心跳/超时长时间无交互某些环境会断连。可在空闲时周期性发一个轻量 ping 消息保活断连后做指数退避重连尽量不要用死循环无间隔重连把 CPU 打满。消息边界用 \n 行分隔读取端要用 readLine 或按行切分别一次性读半条命令。若一次 recv 拿到两条消息要按 \n 拆开逐条解析——每条都是形如 COMMAND|keyvalue|… 的纯文本黏在一起会被插件当成一条错指令。指令未生效确认平台名拼写与仿真内一致UAV_01 不是 uav_01且目标在射程/航程内。插件不会替你校验能不能打到发错只会被静默忽略或报错。多线程写竞争如上一节所说后台读线程与业务写线程共用 Socket 输出流务必加锁串行化写操作否则两条指令黏连会导致解析失败。小结外部控制是 TCP 行协议 管道文本客户端连 127.0.0.1:31000按 \n 分隔收发形如 COMMAND|keyvalue|… 的纯文本消息不是 JSON。Java 客户端核心是 Socket BufferedReader/Writer统一 UTF-8指令以 MOVE_TO / FIRE 等 COMMAND|… 文本行下发响应以 OK| / ERROR| / DATA| 文本行回传。Spring Boot 中由 ExternalControlService 管理连接与接收循环经 Controller 暴露给业务/前端。Python 客户端与 Java 同契约几行即可连上适合算法快速验证。踩坑重点连接被拒插件未启动、编码统一、心跳保活、行边界、平台名大小写。想扩展协议或自己写插件见 第 14 篇《自定义 C 插件开发》。下期预告代码闭环已经打通但我到底有没有连对、指令有没有生效、态势长啥样光看日志不够直观。下一篇 《13 可视化利器 Wizard快速调试与态势呈现》 带你用 AFSIM 自带的 Wizard 把场景树、track、外部控制连接状态一目了然地呈现出来调试效率直接拉满。点赞收藏关注咱们下期见