Web Boot Runner

Run, stop, and debug Spring Boot applications in multi-module Maven workspaces — with reactor-aware commands, profile-aware ports, and port-conflict checks.

English · 简体中文

English

Why this extension

Multi-module Spring Boot repositories usually have two recurring problems:

• Modules outside the Maven reactor. A module can be commented out in the parent POM, or never declared at all. mvn -pl :module then fails with Could not find the selected project in the reactor.
• Ports hidden behind profiles. A single module may have many application-*.yml files that override server.port, while several web modules default to the same port (commonly 8080).

Web Boot Runner detects both cases and handles them automatically.

Features

• Application tree in the activity bar, showing live status, profile, port, and context path.
• Manual groups — create groups in the tree, drag apps in or out, and start/debug/stop an entire group; group nodes summarize port conflicts among their members.
• One-click run and restart via mvn spring-boot:run, with an optional pre-build step (compile by default).
• Reactor-aware commands — uses -pl :artifact (-am optional via webBoot.buildDependencies) inside the reactor and falls back to -f <module>/pom.xml outside it.
• Profile-aware ports — merges the base config with each application-<profile>.* file to compute the effective port and context path.
• Port-conflict detection — scans all apps before launch and offers to pick a free port, use the occupied one, or cancel.
• Debug with auto-attach — starts the app with JDWP and attaches after Spring Boot reports ready.
• launch.json generation — writes type: java configurations for developers who prefer pressing F5.
• Readiness detection — parses the run log for Started ... in ... seconds, the actual port, context path, and common failure messages.
• Runtime monitoring — after startup, refreshes JVM heap/GC (via jstat) and Tomcat HTTP status every 5 seconds in the tree and tooltip; shows Tomcat thread-pool metrics when Actuator is available.
• Runtime coverage (JaCoCo) — optionally attaches a JaCoCo agent to spring-boot:run (tcpserver mode); dumps execution data before the process is killed, merges it across runs, and generates HTML + XML reports with line/branch/class rates shown in the tree and tooltip.
• Process-tree stop — uses taskkill /T /F on Windows, so no orphan Java process keeps the port.
• Copy launch command — copies the exact Maven command for use in any terminal.
• Multi-language UI — English, Simplified Chinese, and Japanese; follows the VS Code display language by default and can be pinned with webBoot.language.

Requirements

• VS Code 1.75 or newer (Cursor works as well).
• Java and Maven available to the extension (mvn on PATH, or configure webBoot.mavenCommand).
• A workspace whose root contains the Maven pom.xml.
• The extension UI is currently in Chinese.

Getting started

1. Install Web Boot Runner from the Marketplace, or sideload the VSIX:

   code --install-extension web-boot-runner-0.1.5.vsix
   cursor --install-extension web-boot-runner-0.1.5.vsix
   

2. Open the root of your multi-module project.

3. Click the Web Boot icon in the activity bar.

Example application list:

order-web              dev    :8080   /order
report-web             dev    :8080   /report
monitor-server         dev    :9999   /monitor

• Click a stopped app to run it; click a running app to open it in the browser.
• Hover a node for inline Run / Debug / Edit or Open / Stop / Restart / Edit buttons.
• Right-click for profile selection, port override, profile/port/main-class/-am/coverage editing, moving apps between groups, command copy, Reload Resources on a running app (mvn process-resources), and Sample Coverage / Open Coverage Report when coverage is enabled.
• Drag apps onto a group (or onto the virtual "Ungrouped" bucket) to organize them; group nodes expose start/debug/stop for the whole group.
• Toolbar buttons: refresh, check port conflicts, generate launch.json, show output, create group.

Commands

Settings

Per-app preferences (profile, port, main class, buildDependencies, coverage) and manual groups are stored in .vscode/web-boot.json inside the workspace. A per-app buildDependencies or coverage value overrides the global setting for that app only.

How it works

• Scans **/src/main/java/**/*Application.java for classes annotated with @SpringBootApplication.
• Parses POMs with XML comments stripped to build the reactor model; modules outside the reactor use the -f form.
• Deep-merges the base application.* file with each application-<profile>.* file to resolve the effective server.port and server.servlet.context-path.
• Launches mvn spring-boot:run and watches the output for Started ... in ... seconds; the actual port reported by Tomcat or Netty takes precedence over configuration.
• While running, locates the Java process via jps -l (the Maven pid is a shell, not the JVM), reads heap and GC with jstat -gc, probes the app with HTTP HEAD, and optionally reads Tomcat thread-pool metrics from Actuator.
• With coverage enabled, appends a JaCoCo -javaagent (tcpserver mode) to spring-boot:run; on stop or manual sampling it first runs jacococli dump against the agent port, merges the exec with previous runs, and generates HTML + XML reports with jacococli report.
• Stops the entire process tree, preventing orphan Java processes from holding the port.

Notes and limitations

• Terminal mode does not detect readiness. With webBoot.runner = terminal, the node is marked running immediately, auto-attach is unavailable, and Stop does not end the process in the terminal.
• Output encoding is detected per line. Each line's bytes are decoded as UTF-8 when valid and as GBK otherwise, so Chinese logs from JDK 8 apps on Windows (which default to file.encoding=GBK) display correctly without changing the system code page or switching to terminal mode. Only if the host lacks a GBK decoder (ICU missing) does it fall back to plain UTF-8, where Chinese text may still be garbled; readiness detection relies on ASCII log lines and is unaffected either way.
• Modules may need a different JDK or Maven. For example, a Boot 3.x module may require JDK 17 and Maven 3.6.3+ while the rest of the repository uses older versions. Point webBoot.javaHome at the required JDK and use a matching Maven.
• Generated launch.json entries are not guaranteed to work. For modules outside the reactor, the VS Code Java language server may not have imported the project. Use this extension's Maven path for those modules.
• Monitoring needs JDK tools. jps / jstat ship with the JDK; with a JRE only, JVM metrics show as unavailable while the Tomcat HTTP status still works.
• Actuator metrics use the default path. A custom management.server.port or management.endpoints.web.base-path disables the thread-pool display; HTTP probing is unaffected.
• Terminal mode has no monitoring. With webBoot.runner = terminal, the Java process is unknown and no JVM / Tomcat metrics are collected.
• Coverage needs compiled classes and is unavailable in terminal mode. The dump/report steps run java -jar jacococli; if target/classes is missing, coverage is skipped for that run. Only the module's own classes are measured (dependency modules are not included). Coverage preparation failures degrade gracefully: the app still starts without the agent.

Development

Building from source, the self-check scripts, and the implementation notes live in DEVELOPMENT.md (Chinese).

Support

If this extension saved you some time, you can optionally buy the author a coffee via WeChat Pay. Donations are entirely voluntary: they unlock nothing and imply no support commitment.

_{Ad slot — this page keeps one clearly-labelled sponsor slot, for tools and services a Spring Boot / VS Code developer would actually use. To take it, reach the author through the WeChat QR code above and mention AD. Ads are always marked as ads, carry a plain https link and a static PNG at most, contain no tracking pixels or affiliate links, and never change how this extension behaves.}

License

MIT © 2026 eppen

简体中文

为什么需要它

多模块 Spring Boot 仓库通常有两个反复出现的问题：

• 模块不在 Maven reactor 内。 模块可能在父 POM 中被注释掉，或从未声明。此时 mvn -pl :module 会报 Could not find the selected project in the reactor。
• 端口藏在 profile 里。 一个模块可能有很多 application-*.yml 覆盖 server.port，同时多个 Web 模块默认使用同一个端口（通常是 8080）。

Web Boot Runner 会自动识别并处理这两种情况。

功能

• 应用树：活动栏中的列表，直接显示运行状态、profile、端口与 context-path。
• 手动分组：在树中新建分组，拖拽应用归类，可整组启动 / 调试 / 停止；分组标题汇总组内端口冲突。
• 一键启动与重启：通过 mvn spring-boot:run 启动，可选预编译步骤（默认 compile）。
• reactor 感知：reactor 内使用 -pl :artifact（-am 由 webBoot.buildDependencies 控制），reactor 外自动降级为 -f <模块>/pom.xml。
• profile 端口计算：将基础配置与每个 application-<profile>.* 深合并，算出该 profile 的生效端口与 context-path。
• 端口冲突检测：启动前检查全部应用，可结束占用端口的进程、自动换端口、仍用该端口或取消；占用者是本扩展管理的应用时直接停止它。
• 调试自动 attach：以 JDWP 启动，Spring Boot 就绪后自动连接调试器。
• 生成 launch.json：为习惯按 F5 的开发者写入 type: java 配置。
• 就绪检测：解析启动日志中的 Started ... in ... seconds、实际端口、context-path 与常见失败信息。
• 运行期监控：启动后每 5 秒刷新 JVM 堆/GC（jstat）与 Tomcat HTTP 状态，显示在树节点与悬浮提示；应用暴露 Actuator 时还会显示 Tomcat 线程池。
• 运行时覆盖率（JaCoCo）：可选给 spring-boot:run 挂 JaCoCo agent（tcpserver 模式），停止 / 采样时先 dump 执行数据再结束进程，多次运行累积合并后生成 HTML + XML 报告，行 / 分支 / 类命中率显示在树节点与悬浮提示。
• 按进程树停止：Windows 下使用 taskkill /T /F，避免 Java 子进程残留占用端口。
• 复制启动命令：把实际执行的 Maven 命令复制到剪贴板，可贴进任意终端。
• 多语言界面：简体中文 / 英文 / 日文，默认跟随 VS Code 显示语言，可用 webBoot.language 固定。
• 中 / 日 / 英 三语界面：默认跟随 VS Code 显示语言，也可用 webBoot.language 固定为 zh-cn / en / ja。

环境要求

• VS Code 1.75 或更高版本（Cursor 同样可用）。
• 扩展可访问 Java 与 Maven（mvn 在 PATH 中，或配置 webBoot.mavenCommand）。
• 工作区根目录包含 Maven 的 pom.xml。
• 界面支持简体中文 / 英文 / 日文，默认跟随 VS Code 的显示语言。

快速开始

1. 从插件市场安装 Web Boot Runner，或离线安装 VSIX：

   code --install-extension web-boot-runner-0.1.5.vsix
   

2. 打开多模块项目的根目录。

3. 点击活动栏中的 Web Boot 图标。

应用列表示意：

order-web              dev    :8080   /order
report-web             dev    :8080   /report
monitor-server         dev    :9999   /monitor

• 点击未运行的节点启动应用；点击运行中的节点在浏览器打开。
• 悬浮节点出现内联按钮：启动 / 调试 / 编辑，或打开 / 停止 / 重启 / 编辑。
• 右键菜单可选择 Profile、指定端口、编辑 Profile / 端口 / 主类 / -am、移动到分组、复制启动命令；运行中的应用还可「重新加载资源」（mvn process-resources）。
• 把应用拖到分组（或虚拟的「未分组」桶）即可归类；分组节点可启动 / 调试 / 停止整组。
• 标题栏按钮：刷新、检查端口冲突、生成 launch.json、显示输出、新建分组。

命令

配置

每个应用的 profile、端口、主类、buildDependencies、coverage 偏好与手动分组保存在工作区的 .vscode/web-boot.json。应用级 buildDependencies / coverage 只覆盖该应用，未设置时跟随全局设置。

实现方式

• 扫描 **/src/main/java/**/*Application.java 中带 @SpringBootApplication 的启动类。
• 剥离 POM 中的 XML 注释后构建 reactor 模型；reactor 外的模块使用 -f 形式。
• 将基础 application.* 与每个 application-<profile>.* 深合并，解析生效的 server.port 与 server.servlet.context-path。
• 通过 mvn spring-boot:run 启动，并监听日志中的 Started ... in ... seconds；Tomcat 或 Netty 报告的实际端口优先于配置值。
• 运行中通过 jps -l 定位 Java 进程（Maven 的 pid 是 shell，不是 JVM），用 jstat -gc 读取堆与 GC，向应用发 HTTP HEAD 探活，并在 Actuator 可用时读取 Tomcat 线程池。
• 启用覆盖率时，在 spring-boot.run.jvmArguments 追加 JaCoCo -javaagent（tcpserver 模式）；停止或手动采样时先用 jacococli dump 连 agent 端口拉取执行数据，与历史 exec 合并后由 jacococli report 生成 HTML + XML 报告。
• 停止时结束整棵进程树，避免 Java 子进程残留占用端口。

说明与限制

• 终端模式不检测就绪。 webBoot.runner = terminal 时节点会直接显示为运行中，无法自动 attach，且「停止」不会结束终端中的进程。
• 输出编码按行自动识别。 每行的字节在合法 UTF-8 时按 UTF-8 解码，否则按 GBK 解码，因此 Windows 上 JDK 8 应用（默认 file.encoding=GBK）的中文日志可以正常显示，无需改系统代码页或切到终端模式。仅当宿主缺少 GBK 解码器（ICU 不全）时退化为按 UTF-8 读取，此时中文仍可能乱码；就绪检测依赖 ASCII 日志，任何情况下都不受影响。
• 不同模块可能需要不同 JDK / Maven。 例如 Boot 3.x 模块可能需要 JDK 17 与 Maven 3.6.3+，而仓库其余部分使用旧版本。请用 webBoot.javaHome 指向所需 JDK，并搭配相应 Maven。
• 生成的 launch.json 不保证能运行。 reactor 外的模块可能未被 VS Code Java 语言服务器导入，type: java 直启会失败；这类模块请使用本扩展的 Maven 路径。
• 监控依赖 JDK 工具。 jps / jstat 随 JDK 提供；只有 JRE 时 JVM 指标显示不可用，Tomcat HTTP 状态仍可显示。
• Actuator 指标使用默认路径。 自定义 management.server.port 或 management.endpoints.web.base-path 时不会显示线程池；HTTP 探活不受影响。
• 终端模式不监控。 webBoot.runner = terminal 时拿不到 Java 进程，不采集 JVM / Tomcat 指标。
• 覆盖率需要已编译字节码，且终端模式不可用。 dump / 报告通过 java -jar jacococli 执行；模块未编译（target/classes 不存在）时本次不启用覆盖率，只统计本模块字节码（不含依赖模块）。覆盖率准备失败会降级为「本次不启用」，不影响应用启动。

开发

构建、自检脚本与实现细节见 DEVELOPMENT.md。

支持

如果这个扩展帮你省下了时间，可以自愿微信扫码请作者喝杯咖啡。赞助完全自愿，不影响任何功能，也不构成任何形式的服务承诺。

_{广告位 — 本页保留一个明确标注的赞助位，只接受 Spring Boot / VS Code 开发者真正用得上的工具或服务。有意投放请扫上方二维码联系作者，并注明 AD。广告一律标注为广告，只接受 https 链接与静态 PNG，不含追踪像素或返利链接，也不影响扩展的任何行为。}

许可

MIT © 2026 eppen