SpringBoot + Vue 实现 Python 在线调试器 - 技术方案文档
📋 目录
项目概述
Python 在线调试器是一个基于 Web 的 Python 代码执行和调试工具，支持在线编写、运行和交互式调试 Python 代码。项目采用前后端分离架构，前端负责用户界面和交互，后端负责代码执行和调试逻辑。
技术栈
后端技术栈
| 技术/框架 | 版本 | 用途 |
|---|---|---|
| Java | 17 | 编程语言 |
| Spring Boot | 3.1.5 | Web框架 |
| Spring Web | - | RESTful API支持 |
| Spring Validation | - | 参数验证 |
| Jackson | - | JSON序列化/反序列化 |
| Maven | 3.6+ | 项目构建和依赖管理 |
| Python | 3.x | 代码执行环境 |
核心依赖：
spring-boot-starter-web: Web开发支持spring-boot-starter-websocket: WebSocket支持（预留扩展）spring-boot-starter-validation: 参数验证jackson-databind: JSON处理
前端技术栈
| 技术/框架 | 版本 | 用途 |
|---|---|---|
| Vue.js | 3.3.4 | 前端框架 |
| Vite | 5.0.0 | 构建工具和开发服务器 |
| CodeMirror 6 | 6.x | 代码编辑器 |
| Axios | 1.6.0 | HTTP客户端 |
| Node.js | 16+ | 运行环境 |
| npm | - | 包管理器 |
核心依赖：
@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)
核心步骤：
-
创建临时文件
javaPath pythonFile = Paths.get(tempDir, "python_" + sessionId + ".py"); Files.write(pythonFile, code.getBytes("UTF-8")); -
启动Python进程
javaProcessBuilder processBuilder = new ProcessBuilder(pythonCmd, pythonFile.toString()); processBuilder.environment().put("PYTHONIOENCODING", "utf-8"); Process process = processBuilder.start(); -
读取输出
javaBufferedReader reader = new BufferedReader( new InputStreamReader(process.getInputStream(), "UTF-8")); // 设置30秒超时 boolean finished = process.waitFor(30, TimeUnit.SECONDS); -
清理资源
javaFiles.deleteIfExists(pythonFile); runningProcesses.remove(sessionId);
关键技术点：
- 使用
ProcessBuilder创建独立的Python进程 - 设置
PYTHONIOENCODING=utf-8确保中文输出正确 - 使用临时文件存储用户代码
- 设置执行超时防止死循环
- UTF-8编码处理确保字符正确传输
2. 调试功能实现
2.1 断点插入机制
实现方法：
-
行号映射表构建
javaMap<Integer, Integer> lineMapping = new HashMap<>(); // 实际行号 -> 原始行号 -
断点代码注入
java// 在断点行之前插入 pdb.set_trace() result.append(indentStr).append("pdb.set_trace() # Breakpoint at line ") .append(originalLineNumber).append("\n"); -
行号映射记录
- 为所有插入的代码行建立映射
- 包括
import pdb、空行、pdb.set_trace()等 - 确保能准确还原原始行号
2.2 交互式调试会话管理
DebugSession 类：
java
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命令映射
支持的调试操作：
| 操作 | PDB命令 | 说明 |
|---|---|---|
| 继续执行 | c\n |
continue - 继续到下一个断点 |
| 单步执行 | n\n |
next - 执行下一行（不进入函数） |
| 步入 | s\n |
step - 进入函数内部 |
| 步出 | u\n |
up - 返回到调用者 |
实现方式：
java
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输出格式解析：
java
// PDB输出格式: > /path/to/file.py(行号)function_name()
Pattern pattern = Pattern.compile(">\\s+[^\\(]*\\(\\s*(\\d+)\\s*\\)[^\n]*");行号转换：
- 从PDB输出中提取实际行号
- 通过映射表转换为原始行号
- 如果没有精确匹配，向上查找最接近的行号
- 返回给前端显示
3. 前端编辑器实现
3.1 CodeMirror 6 集成
编辑器初始化：
javascript
editorView.value = new EditorView({
doc: codeContent,
extensions: [
basicSetup, // 基础功能
python(), // Python语言支持
oneDark, // 深色主题
breakpointGutter, // 断点gutter
currentLineHighlight // 当前行高亮
],
parent: editorContainer.value
})3.2 断点可视化
实现原理：
- 使用
GutterMarker创建断点标记 - 使用
StateField管理断点状态 - 使用
RangeSet存储断点位置 - 支持点击gutter区域切换断点
关键代码：
javascript
// 断点标记类
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 当前行高亮
实现方法：
javascript
// 当前行装饰器
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)
})样式定义：
css
.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处理
输出读取：
java
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显示的是插入后的行号，需要转换为原始行号
解决方案：
- 构建完整的行号映射表
- 精确匹配优先
- 向上查找最接近的行号（最多10行）
- 如果找不到，使用估算方法
4. 编码处理
UTF-8编码设置：
java
// 后端
processBuilder.environment().put("PYTHONIOENCODING", "utf-8");
Files.write(pythonFile, code.getBytes("UTF-8"));
new InputStreamReader(process.getInputStream(), "UTF-8")
// 前端
// Axios自动处理UTF-8编码配置文件：
properties
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=true5. 会话管理
会话存储：
java
ConcurrentHashMap<String, DebugSession> debugSessions
ConcurrentHashMap<String, Process> runningProcesses会话生命周期：
- 开始调试时创建会话
- 执行调试命令时更新会话
- 调试完成或停止时清理会话
- 自动清理临时文件
API接口设计
1. 代码执行接口
接口： POST /api/python/execute
请求体：
json
{
"code": "print('Hello, World!')",
"sessionId": "session_123"
}响应：
json
{
"output": "Hello, World!\n",
"error": "",
"success": true,
"sessionId": "session_123"
}2. 调试接口
接口： POST /api/python/debug
请求体：
json
{
"code": "def func():\n x = 10\n return x",
"sessionId": "session_123",
"breakpoints": [2, 3],
"action": "start" | "continue" | "step" | "stepOver" | "stepOut"
}响应：
json
{
"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 -> 22. 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
响应式状态：
javascript
const breakpoints = ref([])
const currentDebugLine = ref(null)
const isInDebugMode = ref(false)生命周期管理：
javascript
onMounted(() => {
initEditor()
sessionId.value = generateSessionId()
window.addEventListener('keydown', handleKeyPress)
})
onUnmounted(() => {
window.removeEventListener('keydown', handleKeyPress)
})2. 断点管理
添加断点：
javascript
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()
}
}
}断点同步：
javascript
watch(breakpoints, () => {
nextTick(() => {
syncBreakpointsToEditor()
})
}, { deep: true })3. 调试控制
调试命令执行：
javascript
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. 实时更新机制
当前行高亮更新：
javascript
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
- 或集成到后端静态资源
安全建议
- 代码执行限制
- 添加沙箱机制
- 限制系统调用
- 限制资源使用（CPU、内存）
- 网络安全
- 配置具体的CORS允许域名
- 使用HTTPS
- 添加身份验证
- 输入验证
- 验证代码长度
- 过滤危险操作
- 设置执行超时
性能优化
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实现交互式调试。核心特点：
- 技术选型合理：现代化的技术栈，易于维护和扩展
- 实现方案可行：使用成熟的ProcessBuilder和pdb，稳定性好
- 用户体验良好：可视化断点、当前行高亮、快捷键支持
- 扩展性强：预留WebSocket接口，可升级到更专业的调试方案
改进方向：
- 使用debugpy实现更专业的调试
- 添加WebSocket实现实时交互
- 增强安全性和性能优化
- 支持更多调试功能（变量查看、表达式求值等）
文档版本： 1.0
最后更新： 2026年