SpringBoot + Vue 构建 Python 在线调试器方案

架构设计

整体架构

┌─────────────────────────────────────────────────────────┐
│ 浏览器 (Browser)                                         │
│ ┌──────────────────────────────────────────────────┐    │
│ │ Vue 3 前端应用                                     │    │
│ │ ┌──────────────┐ ┌──────────────────┐            │    │
│ │ │ CodeMirror 6 │ │ Axios HTTP       │            │    │
│ │ │ 编辑器       │ │ 客户端           │            │    │
│ │ └──────────────┘ └──────────────────┘            │    │
│ └──────────────────────────────────────────────────┘    │
└─────────────────┬───────────────────────────────────────┘
                  │ HTTP/REST API
┌─────────────────┴───────────────────────────────────────┐
│ Spring Boot 后端 (Port: 8080)                           │
│ ┌──────────────────────────────────────────────────┐    │
│ │ PythonController                                 │    │
│ │ (REST API 端点)                                  │    │
│ └────────────────┬─────────────────────────────────┘    │
│                  │                                      │
│ ┌────────────────┴─────────────────────────────────┐    │
│ │ PythonExecutionService                           │    │
│ │ (代码执行和调试逻辑)                             │    │
│ └────────────────┬─────────────────────────────────┘    │
│                  │                                      │
│ ┌────────────────┴─────────────────────────────────┐    │
│ │ ProcessBuilder + Python Process                  │    │
│ │ (执行 Python 代码)                                │    │
│ └────────────────┬─────────────────────────────────┘    │
│                  │                                      │
│ ┌────────────────┴─────────────────────────────────┐    │
│ │ Python 3.x (系统安装)                            │    │
│ │ - pdb (Python 调试器)                            │    │
│ │ - 代码执行                                       │    │
│ └──────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────┘

分层架构

后端分层

Controller 层 (PythonController)
↓
Service 层 (PythonExecutionService)
↓
Process 层 (Java ProcessBuilder)
↓
Python 运行时环境

前端分层

视图层 (App.vue Template)
↓
逻辑层 (App.vue Script - Composition API)
↓
编辑器层 (CodeMirror 6)
↓
HTTP 层 (Axios)

核心实现方法

1. 代码执行实现

1.1 后端实现 (PythonExecutionService.executeCode)

核心步骤：

清理资源

Files.deleteIfExists(pythonFile);
runningProcesses.remove(sessionId);

读取输出

BufferedReader reader = new BufferedReader(
    new InputStreamReader(process.getInputStream(), "UTF-8"));
// 设置 30 秒超时
boolean finished = process.waitFor(30, TimeUnit.SECONDS);

启动 Python 进程

ProcessBuilder processBuilder = new ProcessBuilder(pythonCmd, pythonFile.toString());
processBuilder.environment().put("PYTHONIOENCODING", "utf-8");
Process process = processBuilder.start();

创建临时文件

Path pythonFile = Paths.get(tempDir, "python_" + sessionId + ".py");
Files.write(pythonFile, code.getBytes("UTF-8"));

关键技术点：

• 使用 ProcessBuilder 创建独立的 Python 进程
• 设置 PYTHONIOENCODING=utf-8 确保中文输出正确
• 使用临时文件存储用户代码
• 设置执行超时防止死循环
• UTF-8 编码处理确保字符正确传输

2. 调试功能实现

2.1 断点插入机制

实现方法：

1. 行号映射记录
   • 为所有插入的代码行建立映射
   • 包括 import pdb、空行、pdb.set_trace() 等
   • 确保能准确还原原始行号

断点代码注入

// 在断点行之前插入 pdb.set_trace()
result.append(indentStr).append("pdb.set_trace() # Breakpoint at line ")
      .append(originalLineNumber).append("\n");

行号映射表构建

Map<Integer, Integer> lineMapping = new HashMap<>(); // 实际行号 -> 原始行号

2.2 交互式调试会话管理

DebugSession 类：

private static class DebugSession {
    Process process;              // Python 进程
    BufferedWriter stdin;         // 标准输入流（发送 pdb 命令）
    Path pythonFile;              // 临时 Python 文件
    boolean isActive;             // 会话是否激活
    int currentLine;              // 当前执行行号
    StringBuilder outputBuffer;   // 输出缓冲区
    StringBuilder errorBuffer;    // 错误缓冲区
    Map<Integer, Integer> lineMapping; // 行号映射表
}

会话管理：

• 使用 ConcurrentHashMap 存储多个调试会话
• 支持并发调试多个用户
• 自动清理会话资源

2.3 PDB 命令映射

支持的调试操作：

实现方式：

String pdbCommand;
switch (action) {
    case "continue": pdbCommand = "c\n"; break;
    case "step": pdbCommand = "s\n"; break;
    case "stepOver": pdbCommand = "n\n"; break;
    case "stepOut": pdbCommand = "u\n"; break;
}
session.stdin.write(pdbCommand);
session.stdin.flush();

2.4 行号解析和映射

PDB 输出格式解析：

// PDB 输出格式：> /path/to/file.py(行号)function_name()
Pattern pattern = Pattern.compile(">\\s+[^\\(]*\\(\\s*(\\d+)\\s*\\)[^\n]*");

行号转换：

1. 从 PDB 输出中提取实际行号
2. 通过映射表转换为原始行号
3. 如果没有精确匹配，向上查找最接近的行号
4. 返回给前端显示

3. 前端编辑器实现

3.1 CodeMirror 6 集成

编辑器初始化：

editorView.value = new EditorView({
    doc: codeContent,
    extensions: [
        basicSetup,     // 基础功能
        python(),       // Python 语言支持
        oneDark,        // 深色主题
        breakpointGutter, // 断点 gutter
        currentLineHighlight // 当前行高亮
    ],
    parent: editorContainer.value
});

3.2 断点可视化

实现原理：

• 使用 GutterMarker 创建断点标记
• 使用 StateField 管理断点状态
• 使用 RangeSet 存储断点位置
• 支持点击 gutter 区域切换断点

关键代码：

// 断点标记类
class BreakpointMarker extends GutterMarker {
    toDOM() {
        const span = document.createElement('span');
        span.className = 'breakpoint-marker';
        span.textContent = '●';
        return span;
    }
}

// 断点状态字段
const breakpointState = StateField.define({
    create() { return RangeSet.empty; },
    update(breakpoints, tr) { /* 处理断点变更 */ }
});

3.3 当前行高亮

实现方法：

// 当前行装饰器
const currentLineDecoration = Decoration.line({ class: 'cm-current-line' });

// 当前行状态字段
const currentLineState = StateField.define({
    create() { return RangeSet.empty; },
    update(currentLine, tr) { /* 更新当前行位置 */ },
    provide: f => EditorView.decorations.from(f)
});

样式定义：

.cm-current-line {
    background-color: rgba(78, 148, 255, 0.15);
    outline: 1px solid rgba(78, 148, 255, 0.3);
}

关键技术点

1. 进程管理

进程启动：

• 使用 ProcessBuilder 创建独立进程
• 分离标准输出和错误输出
• 设置环境变量确保编码正确

进程控制：

• 使用 Process.waitFor(timeout) 实现超时控制
• 使用 Process.destroyForcibly() 强制终止
• 使用 ConcurrentHashMap 管理多个进程

2. 异步 I/O 处理

输出读取：

Thread outputThread = new Thread(() -> {
    try (BufferedReader reader = ...) {
        String line;
        while ((line = reader.readLine()) != null && session.isActive) {
            synchronized (session.outputBuffer) {
                session.outputBuffer.append(line).append("\n");
            }
        }
    }
});
outputThread.start();

关键点：

• 使用独立线程读取进程输出
• 使用同步块保证线程安全
• 实时解析行号并更新状态

3. 行号映射算法

问题：

• 插入 import pdb 和 pdb.set_trace() 后行号会偏移
• PDB 显示的是插入后的行号，需要转换为原始行号

解决方案：

1. 构建完整的行号映射表
2. 精确匹配优先
3. 向上查找最接近的行号（最多 10 行）
4. 如果找不到，使用估算方法

4. 编码处理

UTF-8 编码设置：

// 后端
processBuilder.environment().put("PYTHONIOENCODING", "utf-8");
Files.write(pythonFile, code.getBytes("UTF-8"));
new InputStreamReader(process.getInputStream(), "UTF-8")

// 前端
// Axios 自动处理 UTF-8 编码

配置文件：

server.servlet.encoding.charset=UTF-8
server.servlet.encoding.enabled=true
server.servlet.encoding.force=true
spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true
spring.http.encoding.force=true

5. 会话管理

会话存储：

ConcurrentHashMap<String, DebugSession> debugSessions
ConcurrentHashMap<String, Process> runningProcesses

会话生命周期：

1. 开始调试时创建会话
2. 执行调试命令时更新会话
3. 调试完成或停止时清理会话
4. 自动清理临时文件

API 接口设计

1. 代码执行接口

接口： POST /api/python/execute

请求体：

{
    "code": "print('Hello, World!')",
    "sessionId": "session_123"
}

响应：

{
    "output": "Hello, World!\n",
    "error": "",
    "success": true,
    "sessionId": "session_123"
}

2. 调试接口

接口： POST /api/python/debug

请求体：

{
    "code": "def func():\n x = 10\n return x",
    "sessionId": "session_123",
    "breakpoints": [2, 3],
    "action": "start" | "continue" | "step" | "stepOver" | "stepOut"
}

响应：

{
    "output": "> file.py(2)func()\n-> x = 10",
    "error": "",
    "success": true,
    "currentLine": 2,
    "sessionId": "session_123"
}

3. 停止执行接口

接口： POST /api/python/stop/{sessionId}

响应：

执行已停止

调试功能实现原理

1. 断点插入流程

原始代码          插入后代码
───────────────── ─────────────────
1 def func():     1 import pdb
2 x = 10          3 def func():
3 return x        4 pdb.set_trace() # Breakpoint at line 2
                  5 x = 10
                  6 return x
行号映射：实际行号 -> 原始行号
4 -> 2
5 -> 2

2. PDB 交互流程

前端 后端 Python 进程
│ │ │
│-- startDebug ---->│ │
│-- 创建临时文件 ----->│ │
│-- 启动进程 --------->│ │
│<-- PDB 暂停在第 N 行 ---│ │
│<-- 返回行号N -----│ │
│ │ │
│ │ │
│-- step ---------->│ │
│-- 发送 's\n' ------->│ │
│-- 步入函数 │ │
│<-- PDB 暂停在第 M 行 ---│ │
│<-- 返回行号M -----│ │

3. 行号解析流程

PDB 输出："> file.py(15)func()\n-> x = 10"
↓
正则匹配：Pattern.compile(">\s+[^\(]*\(\s*(\d+)\s*\)")
↓
提取行号：15
↓
查找映射：lineMapping.get(15) = 12
↓
返回前端：currentLine = 12

前端交互实现

1. Vue 3 Composition API

响应式状态：

const breakpoints = ref([]);
const currentDebugLine = ref(null);
const isInDebugMode = ref(false);

生命周期管理：

onMounted(() => {
    initEditor();
    sessionId.value = generateSessionId();
    window.addEventListener('keydown', handleKeyPress);
})
onUnmounted(() => {
    window.removeEventListener('keydown', handleKeyPress);
})

2. 断点管理

添加断点：

const addBreakpoint = () => {
    if (newBreakpoint.value && newBreakpoint.value > 0) {
        if (!breakpoints.value.includes(lineNum)) {
            breakpoints.value.push(lineNum);
            breakpoints.value.sort((a, b) => a - b);
            syncBreakpointsToEditor();
        }
    }
};

断点同步：

watch(breakpoints, () => {
    nextTick(() => {
        syncBreakpointsToEditor();
    });
}, { deep: true });

3. 调试控制

调试命令执行：

const executeDebugCommand = async (action) => {
    const response = await axios.post(`${API_BASE}/debug`, {
        code: '',
        sessionId: sessionId.value,
        breakpoints: [],
        action: action // 'continue', 'step', 'stepOver', 'stepOut'
    });
    // 更新当前行号并高亮
    if (result.currentLine) {
        currentDebugLine.value = result.currentLine;
        highlightCurrentLine(result.currentLine);
    }
};

键盘快捷键：

• F5: 继续执行
• F7: 步入
• F8: 单步执行
• Shift+F8: 步出

4. 实时更新机制

当前行高亮更新：

const highlightCurrentLine = (lineNum) => {
    const view = editorView.value;
    const line = view.state.doc.line(lineNum);
    view.dispatch({
        effects: [
            EditorView.scrollIntoView(line.from, { y: 'center' }),
            setCurrentLineEffect.of(line.from)
        ]
    });
};

部署方案

开发环境

后端：

• 端口：8080
• 启动：mvn spring-boot:run
• 或使用：start-backend.bat / start-backend.sh

前端：

• 端口：3000
• 启动：npm run dev
• 或使用：start-frontend.bat / start-frontend.sh
• Vite 代理：/api → http://localhost:8080

生产环境建议

后端：

• 打包：mvn clean package
• 运行：java -jar target/python-debug-backend-1.0.0.jar
• 配置：修改 application.properties
• 反向代理：Nginx

前端：

• 构建：npm run build
• 输出目录：dist/
• 静态资源服务器：Nginx / Apache
• 或集成到后端静态资源

安全建议

1. 代码执行限制
   • 添加沙箱机制
   • 限制系统调用
   • 限制资源使用（CPU、内存）
2. 网络安全
   • 配置具体的 CORS 允许域名
   • 使用 HTTPS
   • 添加身份验证
3. 输入验证
   • 验证代码长度
   • 过滤危险操作
   • 设置执行超时

性能优化

1. 进程管理优化

• 限制并发执行的进程数
• 及时清理已完成的进程
• 使用线程池管理 I/O 操作

2. 前端优化

• 代码编辑器懒加载
• 输出内容虚拟滚动（大量输出时）
• 防抖处理频繁的断点操作

3. 缓存策略

• 缓存 Python 命令检测结果
• 复用调试会话（如果可能）

扩展方案

1. WebSocket 实时交互

优势：

• 实时双向通信
• 更好的调试体验
• 支持断点处的变量查看

实现方向：

• 使用 Spring WebSocket
• 前端使用 WebSocket API
• 实时推送调试状态

2. 使用 debugpy 替代 pdb

优势：

• 更专业的调试协议（DAP）
• 更好的性能
• 支持更多调试功能

实现方向：

• 集成 debugpy 库
• 实现 DAP 协议客户端
• 支持变量查看、表达式求值等

3. 多文件支持

实现方向：

• 文件管理器组件
• 多标签编辑器
• 文件间依赖管理

4. 代码补全

实现方向：

• 集成 Python 语言服务器（如 Pyright）
• CodeMirror 自动补全扩展
• 提供代码提示和错误检查

技术难点与解决方案

难点 1: 行号映射准确性

问题： 插入调试代码后，行号偏移，需要准确映射回原始行号。

解决方案：

• 建立完整的行号映射表
• 使用向上查找算法作为备选
• 智能匹配最接近的行号

难点 2: PDB 输出解析

问题： PDB 输出格式多样，需要准确提取当前行号。

解决方案：

• 使用正则表达式匹配多种格式
• 从后往前查找最新的 PDB 提示符
• 容错处理，支持多种输出格式

难点 3: 异步 I/O 同步

问题： 异步读取输出与同步操作之间的时序问题。

解决方案：

• 使用同步块保护共享资源
• 合理的等待时间
• 状态标志控制异步读取

难点 4: 编码问题

问题： Windows 系统默认 GBK 编码，导致中文乱码。

解决方案：

• 设置 PYTHONIOENCODING=utf-8 环境变量
• 统一使用 UTF-8 编码
• Spring Boot 配置 UTF-8 响应编码

总结

本项目采用前后端分离架构，使用 Spring Boot 3.x 和 Vue 3 构建，通过 ProcessBuilder 执行 Python 代码，使用 pdb 实现交互式调试。核心特点：

1. 技术选型合理：现代化的技术栈，易于维护和扩展
2. 实现方案可行：使用成熟的 ProcessBuilder 和 pdb，稳定性好
3. 用户体验良好：可视化断点、当前行高亮、快捷键支持
4. 扩展性强：预留 WebSocket 接口，可升级到更专业的调试方案

改进方向：

• 使用 debugpy 实现更专业的调试
• 添加 WebSocket 实现实时交互
• 增强安全性和性能优化
• 支持更多调试功能（变量查看、表达式求值等）