sansenhoshi/ts-mobile-go

Fork 0

Files

T

sansen ef1bf61f9f 首次推送

2026-07-20 19:01:03 +08:00

7.4 KiB

Raw Permalink Blame History

步骤 01：项目基础设施

搭建项目骨架、构建系统、依赖配置，确保能编译运行空白应用。

一、目标

建立 Android 项目基本结构
配置 Go + gomobile 构建流程
集成 teamspeak-go SDK
确保能编译生成空白 APK

二、任务清单

2.1 Android 项目结构

根目录：android/（在 IDE 中打开此目录，非仓库根目录）

android/
├── build.gradle.kts              # 根构建脚本（插件声明）
├── settings.gradle.kts           # 项目设置（仓库、模块）
├── gradle.properties             # Gradle 属性
├── gradlew / gradlew.bat         # Gradle Wrapper
└── app/
    ├── build.gradle.kts          # 应用构建脚本（依赖、SDK 版本）
    ├── libs/                     # gomobile AAR 产物存放处
    │   └── teamspeak.aar         # Go 编译产物（git ignore）
    └── src/main/
        ├── AndroidManifest.xml   # 清单文件
        └── java/com/tsmobile/app/
            ├── MainActivity.kt   # 入口 Activity
            ├── TSBridge.kt       # Go 桥接封装
            └── voice/            # 语音模块（后续步骤扩展）
                ├── OpusEncoder.kt
                ├── OpusDecoder.kt
                └── VoiceService.kt

关键配置项：

配置	值	说明
`namespace`	`com.tsmobile.app`	包名
`compileSdk`	35	Android 15
`minSdk`	26	Android 8.0（gomobile 要求最低 API 26）
`targetSdk`	35	目标 Android 15
`jvmTarget`	17	Java 17
`compose`	true	启用 Jetpack Compose

AndroidManifest.xml 权限声明：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />

INTERNET / ACCESS_NETWORK_STATE：连接 TeamSpeak 服务器
RECORD_AUDIO：语音功能（运行时动态申请）

2.2 Go 模块配置

目录：go/

go/
├── go.mod                        # Go 模块定义
├── go.sum                        # 依赖校验
├── teamspeak/                    # gomobile 导出包（bridge.go 所在）
└── _patches/                     # 上游补丁（不可删除）
    └── github.com/honeybbq/teamspeak-go/

go.mod 关键内容：

module tsmobile

go 1.26.0

require github.com/honeybbq/teamspeak-go v0.2.0

// 本地补丁替换（必须保留）
replace github.com/honeybbq/teamspeak-go => ./_patches/github.com/honeybbq/teamspeak-go

gomobile 工具声明（go.mod 中）：

tool golang.org/x/mobile/cmd/gobind

关键依赖：

依赖	用途
`github.com/honeybbq/teamspeak-go`	TeamSpeak 协议实现
`golang.org/x/mobile`	gomobile 工具链
`golang.org/x/crypto`	加密支持

本地补丁说明：

go/_patches/github.com/honeybbq/teamspeak-go/ 包含修改后的上游代码：

修复 32 位整数溢出问题（math.MaxUint32 → 平台相关限制）
通过 go.mod 的 replace 指令应用

⚠️ 不可删除此目录或移除 replace 指令，否则编译或运行时会出错。

2.3 构建脚本

项目提供两个构建脚本，位于仓库根目录：

脚本	平台	说明
`build.bat`	Windows	批处理脚本
`build.sh`	Linux/macOS	Shell 脚本

构建流程分 4 步：

[1/4] 检查依赖 → [2/4] 下载 Go 依赖 → [3/4] Go → AAR → [4/4] Android → APK

Step 1：检查依赖

检查 go 命令是否可用
检查 gomobile 是否安装（不存在则自动安装并 init）
检查 ANDROID_HOME 环境变量

Step 2：下载 Go 依赖

cd go && go mod tidy

Step 3：Go → AAR（核心步骤）

# Windows 需先设置编码
set JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8

gomobile bind \
  -target=android \
  -androidapi=26 \
  -ldflags="-linkmode=external -extldflags=-Wl,--hash-style=both" \
  -o android/app/libs/teamspeak.aar \
  ./teamspeak

必须的 ldflags：

-linkmode=external：使用 NDK 外部链接器，防止 Go 运行时与 Android 信号处理冲突导致 SIGSEGV
-extldflags=-Wl,--hash-style=both：生成兼容的 ELF 哈希表，防止 dlopen failed: empty/missing DT_HASH

Step 4：Android → APK

cd android && ./gradlew assembleDebug

输出：android/app/build/outputs/apk/debug/app-debug.apk

2.4 依赖管理

Kotlin/Android 依赖（app/build.gradle.kts）

Compose 相关：

依赖	版本	用途
`compose-bom`	2024.12.01	Compose 版本目录
`material3`	BOM 管理	Material Design 3
`material-icons-extended`	BOM 管理	扩展图标库
`ui-tooling`	BOM 管理	调试工具

架构组件：

依赖	版本	用途
`activity-compose`	1.9.3	Compose Activity 集成
`navigation-compose`	2.8.5	导航框架
`lifecycle-runtime-compose`	2.8.7	生命周期感知
`lifecycle-viewmodel-compose`	2.8.7	ViewModel 集成

工具库：

依赖	版本	用途
`datastore-preferences`	1.1.1	持久化键值存储（替代 SharedPreferences）
`kotlinx-coroutines-android`	1.9.0	协程支持
`kotlinx-serialization-json`	1.7.3	JSON 序列化

gomobile AAR 引入方式：

implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.aar"))))

将 teamspeak.aar 放入 app/libs/ 目录即可自动引入。

Gradle 插件（根 build.gradle.kts）

插件	版本	用途
`com.android.application`	8.7.3	Android 构建
`org.jetbrains.kotlin.android`	2.1.0	Kotlin Android 支持
`org.jetbrains.kotlin.plugin.compose`	2.1.0	Compose 编译器插件
`org.jetbrains.kotlin.plugin.serialization`	2.1.0	序列化插件

三、验收标准

#	验证项	验证方法
1	Go 模块可正常编译	`cd go && go build ./teamspeak` 无报错
2	gomobile 生成 AAR	运行 `build.bat` / `build.sh` 第 3 步，`app/libs/teamspeak.aar` 存在且大小 > 0
3	Android 项目可编译	`cd android && gradlew.bat assembleDebug` 成功
4	空白 APK 可安装	安装 `app-debug.apk` 到设备/模拟器，启动无崩溃
5	TSBridge 可调用	在 MainActivity 中添加 `TSBridge.isConnected()` 调用，编译通过

四、已完成清单

项目	状态	文件
Android 项目结构	✅	`android/` 目录
Gradle 构建配置	✅	`android/build.gradle.kts`, `android/app/build.gradle.kts`
AndroidManifest	✅	`android/app/src/main/AndroidManifest.xml`
Go 模块配置	✅	`go/go.mod`
本地补丁	✅	`go/_patches/`
构建脚本	✅	`build.bat`, `build.sh`
TSBridge 封装	✅	`android/app/src/main/java/com/tsmobile/app/TSBridge.kt`
VoiceService 骨架	✅	`android/app/src/main/java/com/tsmobile/app/voice/`

五、参考文档

CLAUDE.md — 构建命令、关键 flags 说明
docs/sdk文档-go.md — SDK 依赖与 API
docs/UI架构设计.md — 整体架构设计

7.4 KiB Raw Permalink Blame History Unescape Escape