200 lines
3.8 KiB
Markdown
200 lines
3.8 KiB
Markdown
# 最小功能测试框架
|
||
|
||
## 概述
|
||
|
||
这是一个最小功能测试框架，用于验证 Flask + SocketIO + threading 技术栈在打包成 exe 后的可用性。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ Flask HTTP 服务
|
||
- ✅ SocketIO WebSocket 服务
|
||
- ✅ 强制使用 threading 异步模式
|
||
- ✅ 完整的前端测试界面
|
||
- ✅ HTTP API 测试
|
||
- ✅ WebSocket 连接测试
|
||
- ✅ 实时消息收发测试
|
||
- ✅ 系统信息显示
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
install/
|
||
├── minimal_test_app.py # 主应用文件
|
||
├── build_minimal.py # 打包脚本
|
||
├── requirements_minimal.txt # 最小依赖列表
|
||
└── README.md # 说明文档
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements_minimal.txt
|
||
```
|
||
|
||
### 2. 测试运行
|
||
|
||
```bash
|
||
python minimal_test_app.py
|
||
```
|
||
|
||
然后在浏览器中访问 http://localhost:5000 进行测试。
|
||
|
||
### 3. 打包成 exe
|
||
|
||
```bash
|
||
python build_minimal.py
|
||
```
|
||
|
||
### 4. 测试 exe
|
||
|
||
打包完成后，运行：
|
||
|
||
```bash
|
||
# 方式1：直接运行
|
||
dist/MinimalTestApp.exe
|
||
|
||
# 方式2：使用脚本
|
||
dist/start_test.bat
|
||
```
|
||
|
||
## 测试步骤
|
||
|
||
### HTTP API 测试
|
||
|
||
1. 点击「测试 HTTP API」按钮
|
||
2. 确认返回成功响应
|
||
3. 检查响应数据包含服务器信息
|
||
|
||
### WebSocket 测试
|
||
|
||
1. 页面加载时会自动连接 WebSocket
|
||
2. 确认连接状态显示为「已连接」
|
||
3. 点击「发送测试消息」
|
||
4. 确认能收到服务器响应
|
||
5. 测试断开和重连功能
|
||
|
||
### 系统信息检查
|
||
|
||
- 服务器时间：确认时间正确
|
||
- SocketIO模式：确认显示为 "threading"
|
||
- Flask版本：确认版本信息
|
||
|
||
## 技术要点
|
||
|
||
### 异步模式选择
|
||
|
||
```python
|
||
# 强制使用 threading 模式，避免 eventlet/gevent 依赖问题
|
||
socketio = SocketIO(
|
||
app,
|
||
cors_allowed_origins='*',
|
||
async_mode='threading', # 关键配置
|
||
logger=False,
|
||
engineio_logger=False
|
||
)
|
||
```
|
||
|
||
### 打包配置
|
||
|
||
```python
|
||
# PyInstaller 隐藏导入配置
|
||
hiddenimports=[
|
||
'flask',
|
||
'flask_socketio',
|
||
'socketio',
|
||
'engineio',
|
||
'engineio.async_drivers.threading', # 关键：threading 驱动
|
||
'socketio.namespace',
|
||
'dns',
|
||
'dns.resolver',
|
||
'dns.asyncresolver'
|
||
],
|
||
# 排除不需要的异步模式
|
||
excludes=[
|
||
'eventlet',
|
||
'gevent',
|
||
'gevent_uwsgi'
|
||
]
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **"Invalid async_mode specified" 错误**
|
||
- 确认已安装所有依赖
|
||
- 检查 PyInstaller 隐藏导入配置
|
||
- 确认排除了不需要的异步模式
|
||
|
||
2. **WebSocket 连接失败**
|
||
- 检查防火墙设置
|
||
- 确认端口 5000 未被占用
|
||
- 查看控制台错误信息
|
||
|
||
3. **打包失败**
|
||
- 确认 PyInstaller 版本兼容
|
||
- 检查依赖版本冲突
|
||
- 查看详细错误输出
|
||
|
||
### 调试模式
|
||
|
||
如需调试，可以修改 `minimal_test_app.py`：
|
||
|
||
```python
|
||
# 启用调试模式
|
||
socketio.run(
|
||
app,
|
||
host='0.0.0.0',
|
||
port=5000,
|
||
debug=True, # 启用调试
|
||
allow_unsafe_werkzeug=True
|
||
)
|
||
```
|
||
|
||
## 扩展指南
|
||
|
||
### 添加新功能
|
||
|
||
1. **新增 HTTP 路由**
|
||
```python
|
||
@app.route('/api/new-endpoint')
|
||
def new_endpoint():
|
||
return jsonify({'message': 'New endpoint'})
|
||
```
|
||
|
||
2. **新增 SocketIO 事件**
|
||
```python
|
||
@socketio.on('new_event')
|
||
def handle_new_event(data):
|
||
emit('response', {'status': 'received'})
|
||
```
|
||
|
||
3. **添加依赖**
|
||
- 更新 `requirements_minimal.txt`
|
||
- 更新 `build_minimal.py` 中的 `hiddenimports`
|
||
- 重新测试打包
|
||
|
||
### 渐进式集成
|
||
|
||
按照以下顺序逐步添加业务功能：
|
||
|
||
1. ✅ 基础 Flask + SocketIO（当前阶段）
|
||
2. 🔄 添加数据库支持
|
||
3. 🔄 添加文件操作
|
||
4. 🔄 添加外部库依赖
|
||
5. 🔄 添加硬件设备支持
|
||
|
||
每个阶段都要确保打包和运行正常，出现问题时更容易定位。
|
||
|
||
## 版本信息
|
||
|
||
- Flask: 2.3.3
|
||
- Flask-SocketIO: 5.3.6
|
||
- PyInstaller: 6.1.0
|
||
- Python: 3.8+
|
||
|
||
## 许可证
|
||
|
||
MIT License |