# VS Code 调试指南

## 前置要求

确保已安装以下 VS Code 扩展：

1. **Extension Pack for Java** (Microsoft)
   - 包含：Language Support for Java, Debugger for Java, Maven for Java 等
2. **Spring Boot Extension Pack** (VMware)
   - 包含：Spring Boot Tools, Spring Initializr 等

安装方式：
- 按 `Ctrl+Shift+X` 打开扩展面板
- 搜索 "Extension Pack for Java" 并安装
- 搜索 "Spring Boot Extension Pack" 并安装

## 一、Debug 运行（推荐）

### 方法 1：使用侧边栏（最简单）

1. **打开运行和调试面板**：
   - 快捷键：`Ctrl+Shift+D` (Windows/Linux) 或 `Cmd+Shift+D` (Mac)
   - 或点击左侧活动栏的「运行和调试」图标

2. **选择配置**：
   - 在顶部下拉框选择：`Debug Spring Boot App (Dev)`

3. **开始调试**：
   - 点击绿色的「启动调试」按钮（三角形）
   - 或按 `F5`

4. **设置断点**：
   - 在代码行号左侧点击，出现红点即为断点
   - 例如在 Controller 方法中打断点

5. **调试操作**：
   - `F5` - 继续执行
   - `F10` - 单步跳过
   - `F11` - 单步进入
   - `Shift+F11` - 单步跳出
   - `Shift+F5` - 停止调试

### 方法 2：右键快速启动

1. **打开主类**：
   - 打开 `src/main/java/org/springblade/Application.java`

2. **右键运行**：
   - 在编辑器中右键
   - 选择 `Run Java` 或 `Debug Java`

### 方法 3：使用命令面板

1. 按 `Ctrl+Shift+P` (或 `Cmd+Shift+P`)
2. 输入 `Java: Run`
3. 选择 `Debug Spring Boot App (Dev)`

## 二、普通运行（无调试）

### 使用终端运行

```bash
# 在 VS Code 集成终端中（Ctrl+`）
cd /remote_dev/martial/martial-master

# 加载 Java 环境
source ~/.sdkman/bin/sdkman-init.sh

# 运行应用
mvn spring-boot:run
```

### 使用 Maven 侧边栏

1. 点击左侧 Maven 图标（M）
2. 展开 `blade-api` → `Plugins` → `spring-boot`
3. 右键 `spring-boot:run` → `Run Maven Goal`

## 三、构建任务

按 `Ctrl+Shift+B` 可以快速访问构建任务：

- **Maven: Clean** - 清理 target 目录
- **Maven: Compile** - 编译项目
- **Maven: Package (Skip Tests)** - 打包（默认任务）
- **Maven: Install BladeX Framework** - 编译 BladeX 框架依赖
- **Spring Boot: Run Dev** - 后台运行开发环境
- **Kill Java Process on Port 8123** - 停止占用 8123 端口的进程

## 四、端口转发设置

### 自动转发（推荐）

VS Code Remote SSH 会自动检测端口 8123，只需：

1. 应用启动后，底部会出现提示
2. 点击「在浏览器中打开」即可

### 手动添加端口

1. **打开端口面板**：
   - 按 `Ctrl+Shift+P`
   - 输入 `Forward a Port`
   - 输入 `8123`

2. **或使用端口视图**：
   - 点击底部状态栏的「端口」标签
   - 点击「+」添加端口
   - 输入 `8123`

3. **访问应用**：
   - 浏览器访问：`http://localhost:8123/doc.html`
   - Knife4j API 文档自动打开

### 批量转发（开发常用端口）

在端口面板添加：
- `8123` - Spring Boot 应用
- `33066` - MySQL
- `63379` - Redis

## 五、调试配置说明

已配置的调试选项：

### 1. Debug Spring Boot App (Dev)
- **用途**：开发环境调试
- **配置文件**：application-dev.yml
- **快捷键**：F5 启动

### 2. Debug Spring Boot App (Test)
- **用途**：测试环境调试
- **配置文件**：application-test.yml

### 3. Debug Current Java File
- **用途**：调试单个 Java 文件（有 main 方法）
- **使用**：打开文件后按 F5

### 4. Attach to Remote JVM
- **用途**：连接到远程 JVM 进程
- **端口**：5005
- **使用场景**：当应用已在运行时附加调试器

## 六、常见问题

### 问题 1：找不到主类

**解决方案**：
```bash
# 清理并重新编译
mvn clean compile

# 或在 VS Code 中
Ctrl+Shift+P -> Java: Clean Java Language Server Workspace
```

### 问题 2：端口 8123 已被占用

**解决方案**：
```bash
# 查找占用端口的进程
lsof -i:8123

# 或使用配置的任务
Ctrl+Shift+P -> Tasks: Run Task -> Kill Java Process on Port 8123
```

### 问题 3：Maven 依赖未找到

**解决方案**：
```bash
# 先编译 BladeX 框架
cd /remote_dev/martial/martial-tool
mvn clean install -DskipTests

# 或使用任务
Ctrl+Shift+P -> Tasks: Run Task -> Maven: Install BladeX Framework
```

### 问题 4：断点不生效

**原因**：代码未重新编译

**解决方案**：
- 停止调试 (Shift+F5)
- 重新编译 (Ctrl+Shift+B)
- 再次启动调试 (F5)

### 问题 5：MySQL/Redis 连接失败

**检查服务**：
```bash
# MySQL
docker ps --filter "name=dev-mysql"

# Redis
docker ps --filter "name=dev-redis"

# 如未运行，启动它们
docker start dev-mysql dev-redis
```

## 七、调试技巧

### 1. 条件断点
- 在断点上右键 → `Edit Breakpoint`
- 输入条件，例如：`userId == 1`

### 2. 日志断点
- 右键断点 → `Edit Breakpoint`
- 勾选 `Log Message`
- 输入消息，例如：`User ID: {userId}`

### 3. 异常断点
- 调试面板 → `BREAKPOINTS` → 点击 `+`
- 选择 `Java Exception Breakpoints`
- 输入异常类名，如：`NullPointerException`

### 4. 查看变量
- 鼠标悬停在变量上查看值
- 或在左侧 `VARIABLES` 面板查看所有变量
- 右键变量 → `Copy Value` 复制值

### 5. 表达式求值
- 调试时，点击 `DEBUG CONSOLE`
- 输入表达式并执行，例如：
  ```java
  user.getName()
  list.size()
  ```

### 6. 热重载（Spring Boot DevTools）
- 修改代码后自动重启应用
- 已在 `pom.xml` 中配置（如果需要）

## 八、快捷键速查表

| 操作 | Windows/Linux | Mac |
|------|---------------|-----|
| 开始调试 | F5 | F5 |
| 停止调试 | Shift+F5 | Shift+F5 |
| 单步跳过 | F10 | F10 |
| 单步进入 | F11 | F11 |
| 单步跳出 | Shift+F11 | Shift+F11 |
| 继续执行 | F5 | F5 |
| 切换断点 | F9 | F9 |
| 打开调试面板 | Ctrl+Shift+D | Cmd+Shift+D |
| 打开终端 | Ctrl+` | Ctrl+` |
| 命令面板 | Ctrl+Shift+P | Cmd+Shift+P |
| 构建任务 | Ctrl+Shift+B | Cmd+Shift+B |

## 九、开发工作流

### 典型开发流程：

1. **启动服务**：
   ```bash
   # 确保 MySQL 和 Redis 运行
   docker ps
   ```

2. **开始调试**：
   - 按 `F5` 启动应用
   - 等待应用启动（看底部终端日志）

3. **转发端口**：
   - VS Code 自动转发 8123
   - 或手动添加

4. **访问应用**：
   - 浏览器：`http://localhost:8123/doc.html`

5. **设置断点**：
   - 在 Controller 或 Service 方法中打断点

6. **测试 API**：
   - 在 Knife4j 界面发起请求
   - VS Code 会在断点处暂停

7. **修改代码**：
   - 停止调试 (Shift+F5)
   - 修改代码
   - 重新启动调试 (F5)

8. **查看日志**：
   - 集成终端显示应用日志
   - 或查看 `application.log` 文件

## 十、推荐扩展

除了必需的扩展，还推荐：

- **REST Client** - 直接在 VS Code 测试 API
- **Database Client** - 连接 MySQL 查看数据
- **GitLens** - Git 增强工具
- **Error Lens** - 内联显示错误
- **Better Comments** - 增强注释高亮
- **Material Icon Theme** - 美化文件图标

---

**快速开始：按 F5 即可开始调试！**