RedisUtils 接口文档

简介

简述：该文件提供了基于Redis的通信工具类，用于无人机仿真场景下的数据订阅回调处理，为RflySimSDK的通信模块提供Redis数据交互支撑。

在RflySim无人机仿真系统中，多个模块需要进行高效的跨进程数据交互，Redis作为高性能内存数据存储，常被用于无人机仿真中实时飞行数据、状态信息、传感器数据的中转分发。本模块封装了Redis通信的常用操作，并且提供了订阅回调的处理能力，适用于仿真环境下不同组件之间获取实时飞行数据、感知其他模块状态、响应数据更新的场景，可以帮助开发者快速搭建基于Redis的仿真数据通信链路，无需自行处理Redis连接、订阅回调的底层逻辑。

快速开始

最简可用示例，复制后修改最少配置即可运行。需要确保本地Redis服务已启动，默认端口6379即可运行

from RflySimSDK.comm.RedisUtils import RedisUtils

# 初始化Redis连接工具，默认连接本地6379端口的Redis服务
redis_util = RedisUtils()

# 定义测试键名
test_key = "test_rfly_key"
# 准备要存储的测试数据
test_data = {"vehicle_id": 1, "position": [120.1, 30.2, 100.5]}

# 写入数据到Redis
redis_util.set_data(test_key, test_data)
print(f"写入数据成功: {test_key} -> {test_data}")

# 从Redis读取数据
read_data = redis_util.get_data(test_key)
print(f"读取到数据: {read_data}")

# 写入单个简单数据测试
simple_key = "test_simple_key"
simple_data = "hello rflysim"
redis_util.set_singledata(simple_key, simple_data)
print(f"写入简单数据成功: {simple_key} -> {simple_data}")
read_simple = redis_util.get_data(simple_key)
print(f"读取简单数据: {read_simple}")

环境与依赖

• Python 环境：>= 3.8.10
• 依赖库：json、redis、threading、time
• 前置准备：调用此接口前，必须确保Redis服务正常运行并完成相关连接配置。

核心接口说明

该模块 RedisUtils.py 包含了配置变量、辅助函数及核心业务类。

全局常量与枚举定义

本节列出模块中所有可直接引用的全局常量和枚举定义。

独立常量

无

---

全局/独立函数

sub_callback(channel, data)

功能说明：消息订阅回调函数，用于处理对应通道接收到的消息数据，通常作为订阅接口的回调参数使用。 参数列表：

• channel: 接收到消息的通道标识，指定该数据来源的通道
• data: 对应通道接收到的消息数据，为通道传输的实际内容

返回值：

• 无

异常： 无

---

RedisUtils 类

Redis工具类，用于提供Redis连接与数据操作相关的工具能力，隶属于RflySimSDK通信模块。

__init__()

功能说明：初始化Redis工具类实例。 参数列表 (Args)： 无 返回值 (Returns)：无 异常 (Raises)：无

set_data(key, data)

功能说明：向Redis存储指定键的序列化数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
key	任意	是	无	Redis存储数据的键名
data	任意	是	无	需要存储的数据，会自动序列化

返回值 (Returns)：无返回值 异常 (Raises)：无

---

set_singledata(key, data)

功能说明：向Redis存储指定键的原始字符串数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
key	任意	是	无	Redis存储数据的键名
data	str	是	无	需要存储的原始字符串数据

返回值 (Returns)：无返回值 异常 (Raises)：无

---

get_data(key)

功能说明：从Redis获取指定键的反序列化数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
key	任意	是	无	Redis存储数据的键名

返回值 (Returns)：反序列化后的原始数据，键不存在时返回None 异常 (Raises)：无

---

get_singledata(key)

功能说明：从Redis获取指定键的原始字符串数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
key	任意	是	无	Redis存储数据的键名

返回值 (Returns)：原始字符串数据，键不存在时返回None 异常 (Raises)：无

---

get_data_list()

功能说明：获取当前Redis数据库中所有键名列表 参数列表 (Args)：无参数 返回值 (Returns)：包含所有键名的列表 异常 (Raises)：无

---

del_data(key)

功能说明：删除Redis中指定键的数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
key	任意	是	无	需要删除的Redis数据键名

返回值 (Returns)：无返回值 异常 (Raises)：无

---

key_count()

功能说明：统计当前Redis数据库中的键总数 参数列表 (Args)：无参数 返回值 (Returns)：当前数据库中键的数量 异常 (Raises)：无

---

clear_db()

功能说明：清空当前Redis数据库中的所有数据 参数列表 (Args)：无参数 返回值 (Returns)：无返回值 异常 (Raises)：无

---

insert_data(db, data)

功能说明：向指定Redis列表队列尾部插入数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
db	str	是	无	Redis列表队列的键名
data	任意	是	无	需要插入队列的数据

返回值 (Returns)：插入操作后队列的长度 异常 (Raises)：无

---

get_one_data(db)

功能说明：从指定Redis列表队列头部取出一条数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
db	str	是	无	Redis列表队列的键名

返回值 (Returns)：取出的数据，队列为空时返回None 异常 (Raises)：无

---

get_all_data(db)

功能说明：获取指定Redis列表队列中的所有数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
db	str	是	无	Redis列表队列的键名

返回值 (Returns)：包含队列所有数据的列表 异常 (Raises)：无

---

queue_count(db)

功能说明：获取指定Redis列表队列的数据长度 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
db	str	是	无	Redis列表队列的键名

返回值 (Returns)：队列中数据的数量 异常 (Raises)：无

---

clear_queue(db)

功能说明：清空指定Redis列表队列的所有数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
db	str	是	无	Redis列表队列的键名

返回值 (Returns)：无返回值 异常 (Raises)：无

---

pub_data(key, data)

功能说明：向指定Redis频道发布序列化后的消息 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
key	任意	是	无	Redis发布订阅的频道名
data	任意	是	无	需要发布的消息数据，会自动序列化

返回值 (Returns)：无返回值 异常 (Raises)：无

---

pub_singledata(key, data)

功能说明：向指定Redis频道发布原始字符串消息 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
key	任意	是	无	Redis发布订阅的频道名
data	str	是	无	需要发布的原始字符串消息

返回值 (Returns)：无返回值 异常 (Raises)：无

sub_data(message_type, channel, callback)

功能说明：订阅指定Redis通道的多数据消息，消息到达时触发指定回调函数处理 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
message_type	-	是	无	订阅消息的数据类型，用于解析接收到的消息
channel	-	是	无	要订阅的Redis通道名称
callback	-	是	无	消息到达时触发的回调函数，参数为解析后的消息

返回值 (Returns)：无返回值 异常 (Raises)：无

---

sub_singledata(message_type, channel, callback)

功能说明：订阅指定Redis通道的单数据消息，消息到达时触发指定回调函数处理 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
message_type	-	是	无	订阅消息的数据类型，用于解析接收到的消息
channel	-	是	无	要订阅的Redis通道名称
callback	-	是	无	消息到达时触发的回调函数，参数为解析后的消息

返回值 (Returns)：无返回值 异常 (Raises)：无

---

sub_data_multiple_channels(message_type, channels, callback)

功能说明：同时订阅多个Redis通道的多数据消息，任意通道有消息到达时触发指定回调函数处理 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
message_type	-	是	无	订阅消息的数据类型，用于解析接收到的消息
channels	-	是	无	要订阅的Redis通道名称列表，包含多个待订阅通道
callback	-	是	无	消息到达时触发的回调函数，参数为解析后的消息、来源通道信息

返回值 (Returns)：无返回值 异常 (Raises)：无

---

sub_singledata_multiple_channels(message_type, channels, callback)

功能说明：同时订阅多个Redis通道的单数据消息，任意通道有消息到达时触发指定回调函数处理 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
message_type	-	是	无	订阅消息的数据类型，用于解析接收到的消息
channels	-	是	无	要订阅的Redis通道名称列表，包含多个待订阅通道
callback	-	是	无	消息到达时触发的回调函数，参数为解析后的消息、来源通道信息

返回值 (Returns)：无返回值 异常 (Raises)：无

进阶用法示例

展示复杂组合场景（如多类协作、异步控制、批量操作）

本示例展示基于RedisUtils实现多无人机异构任务集群的异步状态同步与批量数据处理，结合异步IO框架实现多任务并发读写，适配大规模仿真中多机状态实时更新的需求：

import asyncio
from RflySimSDK.comm import RedisUtils

async def process_uav_status(uav_id, redis_utils):
    # 异步获取单无人机当前飞行状态
    current_status = redis_utils.get_singledata(f"uav:{uav_id}:status")
    if current_status is None:
        return
    # 根据任务需求更新状态后写回
    current_status["mode"] = "formation_keep"
    redis_utils.set_singledata(f"uav:{uav_id}:status", current_status)

async def batch_update_uavs(uav_count, redis_utils):
    # 批量生成任务，并发处理多无人机状态更新
    tasks = [process_uav_status(uav_id, redis_utils) for uav_id in range(1, uav_count+1)]
    await asyncio.gather(*tasks)

def main():
    # 初始化连接
    redis_utils = RedisUtils(host='localhost', port=6379, db=0)
    # 预存批量任务航路点数据
    waypoint_list = [[(10,10,100), (20,20,100)], [(15,15,100), (25,25,100)]]
    for idx, waypoints in enumerate(waypoint_list):
        redis_utils.insert_data(f"uav:{idx+1}:waypoints", waypoints)
    # 执行异步批量更新
    asyncio.run(batch_update_uavs(2, redis_utils))
    # 统计当前存储的无人机数据键数量
    print(f"当前存储的无人机数据条目: {redis_utils.key_count()}")

if __name__ == "__main__":
    main()

注意事项与避坑指南

• 区分批量与单键操作方法：set_singledata/get_singledata针对单个独立键值对操作，set_data/get_data针对列表类集合数据操作，混用会导致数据结构异常，无法正常读取结果。
• 清空数据库风险提示：调用clear_db会直接清空当前所选Redis库的所有键值，包含RflySim仿真核心存储的飞行器状态、配置信息，仅在自定义数据任务完全结束后调用，仿真运行过程中禁止使用该方法。
• 空值返回处理：当查询的键不存在时，get_singledata和get_one_data会返回None，直接对返回结果做属性或索引访问会引发空指针异常，使用前必须增加非空判断逻辑。
• 批量插入的键重复问题：insert_data是向已有列表中追加数据，若需要覆盖原有列表内容，应先调用del_data删除旧键，再执行插入，否则会出现新旧数据混合的错误。

更新日志

• 2025-05-29: fix：更新平台协议汇总页面