大疆云API项目实战入门：用Spring Boot搭建无人机云端控制平台的完整指南

【免费下载链接】DJI-Cloud-API-Demo 项目地址: https://gitcode.com/gh_mirrors/dj/DJI-Cloud-API-Demo

"想让自家无人机机场在千里之外乖乖听话，把航线、拍照、录像、返航全部交给云端调度，到底要写多少代码？"——这是很多初次接触大疆云API的开发者心里最大的疑问。

答案可能比你想的简单得多。DJI-Cloud-API-Demo 是大疆官方开源的云API参考实现，定位非常纯粹：让你"不再重复造轮子"。它基于 Spring Boot 构建，把 MQTT 双向通信、WebSocket 实时推送、OSS 文件存储等硬骨头全部啃好，开发者只需聚焦业务接口的编写，就能让 DJI Pilot2 直接和自家云平台对接。

项目采用 MIT 协议，代码可以放心学习参考。不过请注意：官方已于 2025 年 4 月宣布终止维护，本文所有内容仅用于学习用途，请勿直接部署到生产环境。

---

一、先聊聊痛点：为什么云API能帮你少写几千行代码

在没有云API之前，想控制一架无人机，通常要面对三座大山：

1. 协议不通：飞机、遥控器、机场之间通过私有链路通信，云端根本"插不上话"；
2. 链路复杂：从设备发现、连接管理到心跳保活，每一步都要自己从零实现；
3. 多设备适配：机场、遥控器、飞机型号千差万别，每个型号的消息格式都不一样。

云API做的事情，就是把这三座大山直接"铲平"。它定义了一套标准的物模型（Thing Model）和消息主题（Topic），云端只需要订阅固定的 MQTT 主题，就能收到设备上报的状态、事件和进度；向固定的主题发布指令，就能控制设备执行任务。

用一句话概括：你负责业务，DJI 负责通信。

二、先认识项目结构：一个SDK，一个Demo，分工明确

克隆仓库后，你会发现代码被清晰地分成两个 Maven 模块：

模块	目录	职责
cloud-sdk	cloud-sdk/	核心SDK，封装了MQTT收发、消息路由、物模型、设备注册等通用能力
sample	sample/	可直接运行的示例应用，展示如何落地一个完整的业务系统

git clone https://gitcode.com/gh_mirrors/dj/DJI-Cloud-API-Demo
cd DJI-Cloud-API-Demo

SDK 内部按业务域组织得非常清晰，打开 cloud-sdk/src/main/java/com/dji/sdk/cloudapi/ 就能看到一个个能力包：

• device：设备信息与状态物模型，几十个枚举和状态类把电池、云台、避障、信号等数据全部"翻译"成Java对象；
• wayline：航线任务的全套模型，从创建任务到执行、取消、断点续传一应俱全；
• control：实时控制能力，包括飞行指令、相机操作、指点飞行等；
• livestream：直播推流管理，支持 RTMP、RTSP、GB28181 等多种协议；
• media、firmware、hms、flightarea 等：分别负责媒体文件、固件升级、告警信息、飞行区域。

想快速预览接口长什么样？api/ 目录下还附带了 Postman 的 collection 和环境配置文件，导入即可调试。

三、最快上手方式：5分钟跑通最小示例

整个启动流程分三步，比想象中顺滑：

第一步：构建项目

项目要求 Java 11+ 和 Maven，执行：

mvn clean install

根目录的 pom.xml 采用父子模块管理，依赖版本统一锁定（Spring Boot 2.7.12、spring-integration-mqtt 5.5.5），一条命令即可完成两个模块的构建。

第二步：初始化数据库

示例应用依赖 MySQL 存储设备、用户、航线等业务数据，sql/cloud_sample.sql 里已经备好了全套建表语句，导入即可。

第三步：启动应用

cd sample
mvn spring-boot:run

启动类 CloudApiSampleApplication 通过 @ComponentScan("com.dji") 同时扫描 SDK 和示例代码，@MapperScan("com.dji.sample.*.dao") 自动注册 MyBatis 的 Mapper 接口。启动成功后访问 Swagger 文档页，就能看到当前开放的全部 REST 接口。

如果不想折腾本地环境，官方还提供了 Docker 镜像包，解压后按说明启动即可，省去装 Java 和 MySQL 的麻烦。

四、核心机制拆解：MQTT消息如何完成"邮差"工作

无人机和云端之间所有实时通信都建立在 MQTT 之上。SDK 在 cloud-sdk/src/main/java/com/dji/sdk/mqtt/ 下搭了一套非常优雅的消息管线，核心思路可以理解为一条自动分拣流水线：

1. 收件：MqttConfiguration 配置了一个 MQTT 客户端，订阅所有入站主题（inboundTopic），消息到达后统一进入 inbound 通道；
2. 分拣：InboundMessageRouter 根据消息的 Topic 找到对应的处理通道——CloudApiTopicEnum 维护了主题与通道的一一映射；
3. 投递：每条通道都对应一个业务处理器，比如 OSD 状态、航线进度、告警事件各走各的通道。

看一下 MQTT 连接的配置代码（见下图），其中 keepAliveInterval=10 表示每 10 秒一次心跳，自动重连选项也一并内置，这些细节在实际生产中非常关键：

SDK 内部定义了几十个通道（ChannelName 类里一目了然）：inboundStatus 管设备上下线、inboundOsd 管实时飞行状态、inboundEvents 管各类事件推送……消息处理完全基于 Spring Integration 的注解驱动，业务代码里只需要一个 @ServiceActivator 就能"接住"某类消息，几乎不用关心底层协议细节。

五、深入看一个功能：航线任务是如何"云端一键下发"的

航线任务是最能体现云API价值的能力之一。在示例应用的 sample/src/main/java/com/dji/sample/wayline/service/impl/WaylineJobServiceImpl.java 中，可以看到一个完整的航线作业服务实现（见下图），它注入了一堆协作组件：任务 Mapper、设备服务、文件服务、Redis 服务等：

航线任务的标准流程可以拆成四步，对应 SDK 中 AbstractWaylineService 提供的四个方法：

步骤	方法	说明
① 创建	flighttaskCreate	云端先生成任务，拿到任务ID
② 准备	flighttaskPrepare	把航线文件推给设备，等待设备确认就绪
③ 执行	flighttaskExecute	设备开始按航线飞行
④ 取消	flighttaskUndo	随时可以终止任务

执行过程中，设备会持续通过事件通道上报 flighttaskProgress（任务进度）和 flighttaskReady（就绪通知），SDK 把这些都封装成了带类型的请求对象，你只需要重写抽象方法处理业务逻辑即可，比如更新数据库里的任务状态、向前端推送实时进度。

设计亮点：SDK 还支持断点续传（FlighttaskBreakPoint）和任务暂停/恢复，这在机场场景（如突遇大风中断任务）下非常实用。

六、再看设备接入：从注册到状态同步的完整链路

在云端真正"管"住一台设备，需要三步：

第一步：注册设备。 设备接入前，先用 SDKManager.registerDevice() 把网关序列号（gatewaySn）登记到内存中，SDK 内部用 ConcurrentHashMap 维护设备与版本信息的映射。注意，未注册的设备在收发消息时会直接抛出 CloudSDKException 提醒你。

第二步：接收状态。 设备上线后，状态服务会持续收到 OSD（实时状态）和上下线通知。示例代码中重写了 updateTopoOnline 方法（见下图），从 MQTT 消息里取出子设备序列号，再通过 Redis 查询并刷新设备在线状态：

第三步：对外提供REST接口。 示例应用通过实现 SDK 定义的 HTTP 接口（如 IHttpTsaService），把云端能力暴露成标准 RESTful API。TopologyController 就是一个很好的范例（见下图）：一行核心逻辑，就能返回当前工作区所有设备的拓扑列表，供前端控制台渲染设备关系图：

这套"MQTT 收状态 + REST 出接口"的组合拳，就是整个云端控制平台的骨架。

七、模块速查：一次看清整个项目的地图

除了上面重点讲的几个模块，示例应用 sample 里还有很多值得翻看的业务模块：

模块	路径	负责什么
设备管理	sample/manage/	设备、用户、固件、日志、直播流的统一管理
地图能力	sample/map/	飞行区域、工作区元素、离线地图管理
媒体服务	sample/media/	媒体文件上传回调、指纹秒传、存储配置
实时控制	sample/control/	指点飞行、相机控制、DRC 模式等实时指令
存储对接	sample/storage/	OSS 的 STS 凭证获取与上传流程

配合 sample/src/main/java/com/dji/sample/component/ 下的 MQTT 客户端、Redis、WebSocket、OSS 等组件配置，你能看到一套完整的企业级应用是怎么把各个基础设施串起来的。

八、避坑指南与扩展方向

结合大量开发者的实践反馈，几个高频"坑"值得提前知晓：

1. 设备必须先在平台上完成绑定和注册，否则所有 MQTT 消息都会被 SDK 拦下并抛异常；
2. 心跳和主题订阅必须匹配：订阅主题、QoS 等级（示例中入站 QoS=1）要与官方物模型文档保持一致，否则会出现"设备在线但收不到数据"的诡异问题；
3. 不要在生产环境直接跑 Demo：官方终止维护公告中明确提示，示例代码可能存在未修复的安全隐患（如未授权访问），直接暴露公网风险很高。学习架构可以，上线请务必做安全自查或二次开发；
4. 数据库与配置先行：先导入 sql/cloud_sample.sql、配好 MySQL 和 Redis，再启动应用，否则启动时会因缺表报错。

如果你想让这套架构在真实业务中发光发热，可以沿着这几个方向扩展：

• 多租户支持：基于工作区（workspace）体系扩展组织级权限；
• 告警联动：把 HMS 告警接入企业微信/钉钉机器人，实现异常秒级通知；
• 媒体流水线：对接自建对象存储或 CDN，改造上传回调实现直播与回放联动；
• 航线智能化：结合气象数据与飞行区域，给航线任务加一层"自动决策"。

---

从"一头雾水"到"云端下发航线"，DJI-Cloud-API-Demo 给出一条非常平滑的学习曲线。建议你按本文的顺序动手走一遍：先看 SDK 的物模型和消息通道，再跑通示例应用，最后挑一个业务模块（比如航线任务）深入阅读源码。

纸上得来终觉浅，打开终端 clone 下来，亲手发一条航线指令，看着飞机按指令起飞的瞬间，你会真正理解这套云API的设计之美。🚁

【免费下载链接】DJI-Cloud-API-Demo 项目地址: https://gitcode.com/gh_mirrors/dj/DJI-Cloud-API-Demo