SpringBoot + Vue 实现 Python 在线调试器 - 技术方案文档

📋 目录

1. 项目概述
2. 技术栈
3. 架构设计
4. 核心实现方法
5. 关键技术点
6. API接口设计
7. 调试功能实现原理
8. 前端交互实现
9. 部署方案

项目概述

Python 在线调试器是一个基于 Web 的 Python 代码执行和调试工具，支持在线编写、运行和交互式调试 Python 代码。项目采用前后端分离架构，前端负责用户界面和交互，后端负责代码执行和调试逻辑。

技术栈

后端技术栈

核心依赖：

• spring-boot-starter-web: Web开发支持
• spring-boot-starter-websocket: WebSocket支持（预留扩展）
• spring-boot-starter-validation: 参数验证
• jackson-databind: JSON处理

前端技术栈

核心依赖：

• @codemirror/lang-python: Python语言支持
• @codemirror/view: 编辑器视图
• @codemirror/state: 编辑器状态管理
• @codemirror/theme-one-dark: 深色主题
• @vitejs/plugin-vue: Vite Vue插件

架构设计

整体架构

┌─────────────────────────────────────────────────────────┐ │ 浏览器 (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)

核心步骤：

1. 创建临时文件

   /* by yours.tools - online tools website : yours.tools/zh/menstrual.html */ Path pythonFile = Paths.get(tempDir, "python_" + sessionId + ".py"); Files.write(pythonFile, code.getBytes("UTF-8"));

2. 启动Python进程

   /* by yours.tools - online tools website : yours.tools/zh/menstrual.html */ ProcessBuilder processBuilder = new ProcessBuilder(pythonCmd, pythonFile.toString()); processBuilder.environment().put("PYTHONIOENCODING", "utf-8"); Process process = processBuilder.start();

3. 读取输出

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

4. 清理资源

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

关键技术点：

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

2. 调试功能实现

2.1 断点插入机制

实现方法：

1. 行号映射表构建

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

2. 断点代码注入

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

3. 行号映射记录

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

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 2 3 return x 3 def func(): 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
• 启动：![img](http://localhost:63342/markdownPreview/1811665444/commandRunner/run.png)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

生产环境建议

后端：

• 打包：![img](http://localhost:63342/markdownPreview/1811665444/commandRunner/run.png)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实现实时交互
• 增强安全性和性能优化
• 支持更多调试功能（变量查看、表达式求值等）

文档版本：1.0
最后更新：2026年