suwoodblender/使用说明.md

Socket JSON 传输系统使用说明

📋 系统概述

这是一个基于 Python Socket 的 JSON 文件传输系统，包含完整的服务器端和客户端实现。系统支持：

• ✅ JSON 格式文件的双向传输
• ✅ 多客户端并发连接
• ✅ 完整的命令系统（获取文件、保存文件、列出文件、心跳测试）
• ✅ 实时状态监控和错误处理
• ✅ 自动化测试工具

📁 文件结构

blender/
├── server.py          # 服务器端程序
├── client.py          # 客户端程序
├── test_data.json     # 测试用 JSON 文件
├── test_socket.py     # 自动测试脚本
├── test.bat          # Windows 快速测试工具
└── 使用说明.md        # 本说明文档

🚀 快速开始

方法一：自动测试（推荐）

在 Windows 系统下：

# 双击运行
test.bat

# 或在命令行运行
python test_socket.py

方法二：手动测试

1. 启动服务器

   python server.py
   

   服务器启动后会显示：

   🚀 服务器启动成功！
   📍 监听地址: localhost:8888
   ⏰ 启动时间: 2024-xx-xx xx:xx:xx
   ✅ 等待客户端连接...
   

2. 在另一个终端窗口启动客户端

   # 交互模式
   python client.py
   
   # 或运行测试模式
   python client.py test
   

🎮 客户端交互命令

进入客户端交互模式后，可以使用以下命令：

命令	说明	示例
get <filename>	从服务器获取文件	get test_data.json
save <filename>	保存文件到服务器	save my_data.json
list	列出服务器上的 JSON 文件	list
ping	测试服务器连接	ping
msg <message>	发送普通文本消息	msg Hello Server!
quit	退出客户端	quit

保存文件示例

当使用 save 命令时，系统会提示输入 JSON 内容：

👉 请输入命令: save my_test.json
请输入要保存的 JSON 内容（输入空行结束）:
{
  "name": "测试用户",
  "age": 25,
  "message": "这是测试数据"
}

# 输入空行结束

🧪 测试方法详解

1. 自动化测试

运行 python test_socket.py 会执行以下测试：

• ✅ 文件检查：验证所有必需文件是否存在
• ✅ 服务器启动：自动启动服务器并检查状态
• ✅ 客户端功能：测试所有客户端命令
• ✅ 文件传输：验证 JSON 文件的正确传输

2. 手动功能测试

测试步骤：

1. 基础连接测试

   # 终端1：启动服务器
   python server.py
   
   # 终端2：连接客户端
   python client.py
   

2. 心跳测试

   👉 请输入命令: ping
   

   预期响应：

   {
     "status": "success",
     "command": "ping",
     "message": "pong",
     "server_time": "2024-xx-xxTxx:xx:xx",
     "client_address": "127.0.0.1:xxxxx"
   }
   

3. 文件列表测试

   👉 请输入命令: list
   

   预期响应：

   {
     "status": "success",
     "command": "list_files",
     "files": ["test_data.json"],
     "count": 1
   }
   

4. 文件获取测试

   👉 请输入命令: get test_data.json
   

   预期响应：

   {
     "status": "success",
     "command": "get_file",
     "filename": "test_data.json",
     "content": { ... },
     "size": 1234
   }
   

5. 文件保存测试

   👉 请输入命令: save new_file.json
   请输入要保存的 JSON 内容（输入空行结束）:
   {"test": "data"}
   
   # 输入空行
   

6. 普通消息测试

   👉 请输入命令: msg 你好服务器！
   

3. 多客户端并发测试

服务器支持多个客户端同时连接：

# 终端1：服务器
python server.py

# 终端2：客户端1
python client.py

# 终端3：客户端2
python client.py

# 终端4：客户端3
python client.py

📊 测试结果验证

成功指标

1. 服务器端日志：

   🚀 服务器启动成功！
   🔗 客户端连接: ('127.0.0.1', 端口号)
   📨 收到来自 ('127.0.0.1', 端口号) 的消息: {...}
   

2. 客户端端日志：

   ✅ 已连接到服务器 localhost:8888
   📤 发送请求: {...}
   📥 收到响应: {...}
   

3. 生成的文件：

   • client_test.json - 客户端测试时创建的文件
   • test_report.json - 自动测试生成的详细报告

常见问题排查

1. 连接失败

   ❌ 连接失败: [Errno 10061] No connection could be made
   

   解决方案：确保服务器已启动，检查端口 8888 是否被占用

2. 文件不存在

   {
     "status": "error",
     "message": "文件 xxx.json 不存在"
   }
   

   解决方案：检查文件名是否正确，确保文件在服务器目录中

3. JSON 格式错误

   ❌ JSON 格式错误: Expecting ',' delimiter
   

   解决方案：检查 JSON 语法，使用在线 JSON 验证工具

🔧 高级配置

修改服务器配置

在 server.py 中修改：

# 修改监听地址和端口
server = JSONSocketServer(host='0.0.0.0', port=9999)

修改客户端配置

在 client.py 中修改：

# 连接到不同的服务器
client = JSONSocketClient(host='192.168.1.100', port=9999)

解决 Windows 编码问题

如果在 Windows 控制台遇到 Unicode 编码错误：

1. 使用编码安全版本：

   # 使用编码安全的服务器
   python server_safe.py
   

2. 设置控制台编码：

   # 在 CMD 中运行
   chcp 65001
   set PYTHONIOENCODING=utf-8
   python server.py
   

3. 使用现代终端：

   • Windows Terminal（推荐）
   • VS Code 集成终端
   • PowerShell 7

4. 文件包含：

   • encoding_fix.py - 编码修复模块
   • server_safe.py - 编码安全的服务器版本
   • requirements.txt - 依赖说明（无需额外包）

🛡️ 安全注意事项

• 此系统仅用于学习和测试，不适用于生产环境
• 服务器默认只监听 localhost，如需远程访问请谨慎配置
• 传输的数据未加密，敏感信息请使用 HTTPS 或其他加密方案

📚 扩展功能

系统支持轻松扩展：

1. 添加新命令：在 server.py 的 process_request 方法中添加新的命令处理
2. 文件验证：添加文件类型检查、大小限制等
3. 用户认证：实现简单的用户名密码验证
4. 数据压缩：对大文件进行压缩传输
5. 传输加密：使用 SSL/TLS 加密连接

🎯 总结

这个 Socket JSON 传输系统提供了：

• 🔧 完整功能：文件传输、列表查看、心跳检测
• 🚀 易于使用：一键测试，交互式命令行
• 🛠️ 可扩展性：清晰的代码结构，便于功能扩展
• 📊 完善测试：自动化测试工具，详细的测试报告

通过运行 test.bat（Windows）或 python test_socket.py 开始您的测试之旅！