1. 项目背景与核心价值
ScreenBridge 是我最近开源的一个 Java 桌面工具项目，它的核心功能是将 Android 设备投屏工具 scrcpy 的命令行操作封装成可视化界面。作为一个长期从事 Java 开发的工程师，我发现在实际工作中，很多非技术背景的同事虽然需要频繁使用手机投屏功能，但对 adb 命令行操作望而生畏。这正是 ScreenBridge 要解决的问题。
这个项目的独特之处在于，它不是一个简单的 UI 包装器，而是一个完整的工程实践案例。从技术选型到架构设计，从国际化支持到打包发布，我尝试将企业级开发的最佳实践应用到这个"小工具"中。特别值得一提的是，我选择了 Java 21 和 Swing 这套看似"过时"的技术组合，事实证明对于 Windows 桌面工具这类场景，轻量、稳定、部署简单的技术栈往往是最优解。
提示：选择 Swing 而非 JavaFX 或其他现代 UI 框架的考虑是，Swing 作为 JDK 内置组件，无需额外依赖，特别适合需要分发给非技术用户的小工具。
2. 技术架构与实现细节
2.1 技术栈选型解析
项目采用的技术栈组合经过深思熟虑：
- Java 21：使用最新LTS版本确保长期支持，同时享受记录类型、字符串模板等现代语法特性
- Swing：虽然界面略显陈旧，但胜在零依赖、启动快、内存占用低
- Maven：标准的项目管理和构建工具，便于依赖管理和持续集成
- jpackage：Java 14+ 引入的打包工具，可将JAR转换为原生安装包
特别要说明的是 adb 和 scrcpy 的集成方式。这两个关键组件都是通过 ProcessBuilder 调用外部进程实现的，这种设计既保持了工具的独立性，又避免了重复造轮子。
2.2 项目分层架构
为了避免常见的"大泥球"式Swing应用，我采用了清晰的分层架构：
code复制src/
├── main/
│ ├── java/
│ │ ├── application/ # 应用入口和主控制器
│ │ ├── domain/ # 设备信息、配置等领域对象
│ │ ├── infrastructure/ # adb/scrcpy进程调用等基础设施
│ │ ├── ui/ # Swing界面组件
│ │ ├── settings/ # 配置持久化
│ │ └── i18n/ # 国际化资源管理
│ └── resources/
│ ├── packaging/ # 打包所需的第三方二进制文件
│ └── i18n/ # 多语言资源文件
这种结构确保了关注点分离，例如当需要修改设备发现逻辑时，只需调整 infrastructure 层的代码，而不会影响UI展示。
3. 核心功能实现
3.1 设备发现与连接
设备管理是项目的第一个技术难点。实现流程如下：
- 通过
adb devices命令获取已连接设备列表 - 解析输出内容，提取设备ID和状态
- 封装为 DeviceInfo 对象列表返回给UI
- 支持USB和无线两种连接方式
关键代码片段：
java复制public List<DeviceInfo> listDevices() throws IOException {
Process process = new ProcessBuilder(adbPath, "devices").start();
try (BufferedReader reader = new BufferedReader(
new InputStreamReader(process.getInputStream()))) {
return reader.lines()
.skip(1) // 跳过"List of devices"标题行
.filter(line -> !line.trim().isEmpty())
.map(this::parseDeviceLine)
.collect(Collectors.toList());
}
}
private DeviceInfo parseDeviceLine(String line) {
String[] parts = line.split("\\s+");
return new DeviceInfo(parts[0], parts.length > 1 ? parts[1] : "");
}
3.2 投屏参数配置
scrcpy 支持丰富的命令行参数，我在UI中封装了最常用的几项：
| 参数名 | 对应配置项 | 默认值 | 说明 |
|---|---|---|---|
| --bit-rate | 码率 | 8M | 视频比特率 |
| --max-size | 最大分辨率 | 0 | 0表示原始分辨率 |
| --max-fps | 帧率 | 60 | 最大帧率限制 |
| --turn-screen-off | 关闭屏幕 | false | 投屏时关闭设备屏幕 |
| --stay-awake | 保持唤醒 | true | 防止设备休眠 |
这些参数通过 MirrorConfig 对象进行管理，并支持保存到本地配置文件，避免用户每次都需要重新设置。
4. 工程实践与经验分享
4.1 外部二进制文件管理
处理第三方可执行文件是桌面工具的常见挑战。我的解决方案是：
- 不在源码仓库中直接包含 scrcpy/adb 等二进制文件
- 构建时要求用户自行下载官方scrcpy包并放入指定目录
- 运行时优先使用用户指定的路径，其次尝试自动发现
- 在THIRD_PARTY_NOTICES.md中明确记录所有第三方组件
这样既遵守了开源协议，又保持了仓库的整洁。实际打包时，通过jpackage将这些文件包含在最终安装包中。
4.2 国际化实现技巧
虽然项目规模不大，但我还是实现了中英文双语支持。关键点包括：
- 使用Java标准的ResourceBundle机制
- 将所有UI文本提取到properties文件
- 通过Locale.getDefault()自动识别系统语言
- 设计文本键名时采用"组件.属性"的命名规范
示例资源文件：
properties复制# messages_en.properties
mainWindow.title=ScreenBridge - Android Mirror Tool
devicePanel.refreshButton=Refresh
settingsPanel.saveButton=Save
# messages_zh_CN.properties
mainWindow.title=ScreenBridge - 安卓投屏工具
devicePanel.refreshButton=刷新
settingsPanel.saveButton=保存
5. 常见问题与解决方案
5.1 设备无法识别
现象：点击刷新按钮后设备列表为空
排查步骤：
- 检查USB调试是否已开启
- 确认adb版本与设备兼容
- 尝试
adb kill-server && adb start-server - 查看日志输出中是否有权限错误
5.2 投屏启动失败
常见原因：
- scrcpy路径配置错误
- 防火墙阻止了adb连接
- 设备分辨率不支持
- 编码器不兼容
解决方案模板：
java复制try {
MirrorProcess process = new MirrorProcess(config);
process.start();
} catch (IOException e) {
LOGGER.error("启动投屏失败", e);
showErrorDialog(resources.getString("error.mirrorStartFailed"));
}
6. 打包与分发实践
使用jpackage生成Windows安装包的配置示例：
xml复制<plugin>
<groupId>org.panteleyev</groupId>
<artifactId>jpackage-maven-plugin</artifactId>
<version>1.6.0</version>
<configuration>
<name>ScreenBridge</name>
<vendor>YourName</vendor>
<appVersion>1.0.0</appVersion>
<mainClass>com.yourname.screenbridge.Application</mainClass>
<winConsole>false</winConsole>
<icon>${project.basedir}/src/main/resources/icons/app.ico</icon>
</configuration>
</plugin>
打包时需要特别注意：
- 将scrcpy/adb等二进制文件放入resources/packaging目录
- 配置jpackage的
<runtimeImage>指向正确的JRE - 测试安装包在纯净系统上的运行情况
7. 项目优化方向
基于目前版本的用户反馈，计划中的改进包括：
-
性能优化：
- 增加投屏状态实时监控
- 优化进程启动速度
- 减少内存占用
-
功能增强：
- 支持多设备同时投屏
- 添加截图和录屏功能
- 实现设备文件传输
-
用户体验：
- 更直观的错误提示
- 操作引导动画
- 主题切换支持
这个项目给我的最大启示是：一个好的工具不在于技术有多复杂，而在于它能否真正解决用户的痛点。通过将命令行工具可视化，我帮助了许多非技术同事提升了工作效率，这种成就感远超过实现某个复杂算法。