chakcy_code_repository/pyside_queue_sqlite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

modify: 说明文档

Browse Source
This commit is contained in:
chakcy 2025-09-13 19:08:20 +08:00
parent 295bb05c6a
commit 7abb876100
1 changed files with 281 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

297
README.md
View File

@ -1,23 +1,286 @@
# PySide6 桌面应用实践项目
```bat
python -m nuitka --onefile --windows-console-mode=disable --enable-plugin=pyside6 --lto=no --windows-icon-from-ico=.\resources\ico\logo.ico --output-dir=output --remove-output --jobs=4 main.py
这是一个基于 PySide6 和 QFluentWidgets 开发的桌面应用程序，重点展示了 `queue_sqlite` 在桌面应用中的实践应用，实现了高效的异步任务处理和消息队列机制。
## 项目特点
- 🖥️ **现代化界面**：采用 Fluent Design 设计风格
- 🧩 **模块化架构**：功能模块清晰分离，便于扩展和维护
- 🔄 **异步任务处理**：基于 queue_sqlite 的高效任务队列系统
- 📡 **消息队列机制**：可靠的消息传递和处理框架
- 🌐 **前后端通信**：通过队列系统实现前后端解耦
## 核心技术：queue_sqlite 的应用
### 队列调度器初始化
在 `app/scheduler_manager/__init__.py` 中初始化队列调度器：
```python
from queue_sqlite.scheduler import QueueScheduler
scheduler = QueueScheduler()
```
```bat
python -m nuitka ^
--onefile ^
--windows-console-mode=disable ^
--enable-plugin=pyside6 ^
--lto=no ^
--windows-icon-from-ico=.\resources\ico\logo.ico ^
--output-dir=output ^
--remove-output ^
--jobs=4 ^
--include-qt-plugins=mediaservice ^
--include-data-dir=.venv/Lib/site-packages/PySide6/plugins=PySide6/plugins ^
main.py
### 任务定义与挂载
在 `app/scheduler_manager/students/add_student.py` 中定义任务：
```python
from queue_sqlite.mounter.task_mounter import TaskMounter
from queue_sqlite.model import MessageItem
@TaskMounter.task(meta={"task_name": "add_student"})
def add_student(message_item: MessageItem):
# 模拟耗时操作
time.sleep(3)
print("点击了添加按钮")
return {"message": "学生添加成功"}
```
```bat
ffmpeg -re -stream_loop -1 -i test.mp4 -vcodec libx264 -tune zerolatency -f mpegts tcp://127.0.0.1:5000?listen
### 监听器定义
在 `app/scheduler_manager/students/students_listen.py` 中定义监听器：
```python
from queue_sqlite.mounter.listen_mounter import ListenMounter
@ListenMounter.listener()
def students(str_students_list: str):
print("students signal received")
listen_signals.listening_students_signal.emit(json.loads(str_students_list))
```
### 消息发送与处理
在 `app/view/students/student_interface.py` 中发送消息：
```python
def add_student(self):
self.addButton.setEnabled(False)
scheduler.send_message(
MessageItem(content={}, destination="add_student"),
self.add_student_callback,
)
```
### 前端与队列系统的交互
在 `app/view/web_view/entrance.py` 中通过 WebChannel 暴露队列操作给前端：
```python
class WebViewQueueSqliteOperations(QObject):
@Slot(str, str, result=str)
def send_message(self, message: str, store_key: str):
def callback(result: MessageItem):
global_signals.update_queue_state.emit(result.to_dict(), store_key)
scheduler.send_message(MessageItem.from_dict(json.loads(message)), callback)
```
### 项目结构
```text
项目根目录/
├── main.py # 应用入口点，启动队列调度器
├── app/ # 应用主要代码
│ ├── config/ # 配置管理
│ ├── scheduler_manager/ # 任务调度管理（queue_sqlite核心）
│ │ ├── __init__.py # 初始化队列调度器
│ │ └── students/ # 学生相关任务和监听器
│ ├── signal/ # 信号与事件处理
│ ├── style/ # 样式定义
│ └── view/ # 界面视图
│ ├── camera/ # 摄像头界面
│ ├── students/ # 学生管理界面（使用队列）
│ ├── video/ # 视频播放界面
│ └── web_view/ # Web视图界面（与队列交互）
└── resources/ # 资源文件
└── webview/ # Web前端资源
├── entrance/ # 主门户界面（调用队列接口）
└── new_plugin/ # 插件模板
```
## queue_sqlite 实践详解
### 1. 任务调度器管理
在应用启动时初始化队列调度器，并在应用退出时正确关闭：
```python
# main.py
def main():
# 启动队列调度器
scheduler.start_queue_scheduler()
# ... 应用逻辑 ...
# 停止队列调度器
scheduler.stop_queue_scheduler()
```
### 2. 异步任务处理
通过队列系统处理耗时操作，保持UI响应：
```python
# 发送消息到队列
scheduler.send_message(
MessageItem(content={}, destination="add_student"),
self.add_student_callback, # 回调函数
)
# 处理回调
def add_student_callback(self, message: MessageItem):
global_signals.show_add_dialog_signal.emit(message.to_dict())
```
### 3. 前后端解耦
通过消息队列实现前后端解耦，前端发送消息，后端异步处理：
```javascript
// 前端发送消息到队列
queueSqlite.send_message(
JSON.stringify({
"content": {"num": 1},
"destination": "test"
}),
"taskStatus"
)
```
### 4. 状态管理
通过队列系统的回调机制更新前端状态：
```python
def update_queue_state(self, result: dict, store_key: str):
json_str = json.dumps(result)
js_code = f"""
try {{
if (typeof window.queueStore.updateQueueData === 'function') {{
window.queueStore.updateQueueData('{store_key}', {json_str});
}}
}} catch (error) {{
console.error('Error in updateQueueData:', error);
}}
"""
self.page.runJavaScript(js_code)
```
### 5. 错误处理与重试
队列系统内置错误处理和重试机制，提高系统可靠性。
## 快速开始
### 环境要求
- Python 3.8+
- PySide6
- queue-sqlite
### 安装依赖
```bash
# 初始化项目
mkdir sqlite_queue_demo
cd sqlite_queue_demo
uv init
# 安装依赖
uv add PySide6 qfluentwidgets opencv-python
# 克隆 queue_sqlite 项目
mkdir lib
cd lib
git clone https://gitee.com/cai-xinpenge/pyside_queue_sqlite.git
或
git clone http://124.71.68.6:3000/chakcy_code_repository/queue_sqlite.git
# 安装 queue_sqlite 依赖
cd queue_sqlite
uv sync
# 激活环境
.venv/Scripts/activate
# 构建 Rust 核心模块
cd src/core
maturin develop --release
# 将会在 src/core/target/release 目录下生成 core.dll 或 core.so 文件。 将该文件复制到 queue_sqlite/core 目录下（dll文件需改名为pyd后缀）。
mv target/release/core.dll ../queue_sqlite/core/core.pyd
deactivate
# 安装 queue_sqlite 项目
cd ../../../../
uv add lib/queue_sqlite
```
### 运行应用
```bash
python main.py
```
## queue_sqlite 最佳实践
### 1. 任务定义
- 使用装饰器标记任务函数
- 明确任务名称便于管理和调试
- 合理设计任务参数和返回值
### 2. 消息设计
- 使用 MessageItem 封装消息内容
- 明确消息目的地（destination）
- 包含必要的元数据
### 3. 回调处理
- 为每个消息指定回调函数
- 在回调中更新UI状态
- 处理可能的错误情况
### 4. 监听器使用
- 使用监听器响应数据变化
- 通过信号机制通知UI更新
- 保持监听器简洁高效
## 扩展开发
### 添加新任务
1. 在 `scheduler_manager` 下创建新模块
2. 使用 `@TaskMounter.task` 装饰器定义任务
3. 在界面中发送消息到该任务
## 前端集成
1. 通过 WebChannel 暴露队列操作接口
2. 在前端调用队列接口发送消息
3. 通过回调更新前端状态
## 性能优化建议
1. **合理设置并发数**：根据任务类型调整队列并发数量
2. **任务优先级**：为重要任务设置更高优先级
3. **结果缓存**：对频繁请求的任务结果进行缓存
4. **批量处理**：对相似任务进行批量处理提高效率
## 学习价值
本项目重点展示了：
- queue_sqlite 在桌面应用中的集成方式
- 异步任务处理的最佳实践
- 前后端通过消息队列解耦的方案
- 基于回调的状态管理机制
- 错误处理和重试策略
### 后续计划
- 增加队列监控界面
- 实现任务优先级管理
- 添加任务持久化存储
- 优化队列性能指标
- 增加分布式队列支持
## 贡献指南
欢迎提交 Issue 和 Pull Request 来帮助改进这个项目，特别是与 queue_sqlite 相关的优化和实践。
## 许可证
MIT License