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 系统下：
```bash
# 双击运行
test.bat

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

### 方法二：手动测试

1. **启动服务器**
   ```bash
   python server.py
   ```
   
   服务器启动后会显示：
   ```
   🚀 服务器启动成功！
   📍 监听地址: localhost:8888
   ⏰ 启动时间: 2024-xx-xx xx:xx:xx
   ✅ 等待客户端连接...
   ```

2. **在另一个终端窗口启动客户端**
   ```bash
   # 交互模式
   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. **基础连接测试**
   ```bash
   # 终端1：启动服务器
   python server.py
   
   # 终端2：连接客户端
   python client.py
   ```

2. **心跳测试**
   ```
   👉 请输入命令: ping
   ```
   
   预期响应：
   ```json
   {
     "status": "success",
     "command": "ping",
     "message": "pong",
     "server_time": "2024-xx-xxTxx:xx:xx",
     "client_address": "127.0.0.1:xxxxx"
   }
   ```

3. **文件列表测试**
   ```
   👉 请输入命令: list
   ```
   
   预期响应：
   ```json
   {
     "status": "success",
     "command": "list_files",
     "files": ["test_data.json"],
     "count": 1
   }
   ```

4. **文件获取测试**
   ```
   👉 请输入命令: get test_data.json
   ```
   
   预期响应：
   ```json
   {
     "status": "success",
     "command": "get_file",
     "filename": "test_data.json",
     "content": { ... },
     "size": 1234
   }
   ```

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

6. **普通消息测试**
   ```
   👉 请输入命令: msg 你好服务器！
   ```

### 3. 多客户端并发测试

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

```bash
# 终端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. **文件不存在**
   ```json
   {
     "status": "error",
     "message": "文件 xxx.json 不存在"
   }
   ```
   **解决方案**：检查文件名是否正确，确保文件在服务器目录中

3. **JSON 格式错误**
   ```
   ❌ JSON 格式错误: Expecting ',' delimiter
   ```
   **解决方案**：检查 JSON 语法，使用在线 JSON 验证工具

## 🔧 高级配置

### 修改服务器配置

在 `server.py` 中修改：

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

### 修改客户端配置

在 `client.py` 中修改：

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

### 解决 Windows 编码问题

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

1. **使用编码安全版本**：
   ```bash
   # 使用编码安全的服务器
   python server_safe.py
   ```

2. **设置控制台编码**：
   ```cmd
   # 在 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` 开始您的测试之旅！