Skip to content

development.md

Latest commit

 

History

History
176 lines (129 loc) · 4.12 KB

development.md

File metadata and controls

176 lines (129 loc) · 4.12 KB
Raw

開發者指南

環境需求

項目 版本 說明
Go >= 1.22 編譯和開發所需
ADB 最新版 僅 Agent 端需要（Android Platform Tools）
golangci-lint >= 1.55 程式碼品質檢查（可選）
Git >= 2.0 版本控制

快速開始

取得原始碼

git clone https://github.com/chris1004tw/remote-adb.git
cd remote-adb

建置全部元件

# 建置所有執行檔
go build ./cmd/...

# 所有元件已合併至 cmd/radb，單一執行檔
go build -o radb ./cmd/radb

Windows 使用 Go 1.26+ 時，建議改用專案內建腳本自動加入 GOEXPERIMENT=nogreenteagc：

powershell -ExecutionPolicy Bypass -File .\scripts\build-windows.ps1

若目標 radb.exe 正在執行，可加上 -ForceKillRunning 先自動終止同一路徑的執行中 process 再覆寫：

powershell -ExecutionPolicy Bypass -File .\scripts\build-windows.ps1 -ForceKillRunning

交叉編譯

# Windows
GOOS=windows GOARCH=amd64 GOEXPERIMENT=nogreenteagc go build -o radb.exe ./cmd/radb

# Linux
GOOS=linux GOARCH=amd64 go build -o radb ./cmd/radb

# macOS (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o radb ./cmd/radb

# macOS (Intel)
GOOS=darwin GOARCH=amd64 go build -o radb ./cmd/radb

執行測試

# 執行所有測試
go test ./...

# 含 race detector
go test -race ./...

# 顯示詳細輸出
go test -v ./...

# 執行特定 package 的測試
go test -v ./internal/adb/...
go test -v ./pkg/protocol/...

程式碼品質

Lint

# 安裝 golangci-lint
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# 執行 lint
golangci-lint run

格式化

# 格式化程式碼
gofmt -w .

# 或使用
go fmt ./...

專案結構

remote-adb/
├── cmd/
│   └── radb/                   # 統一入口（server / agent / daemon / CLI）
│       └── main.go
│
├── internal/                   # 私有 package（不可被外部 import）
│   ├── adb/                    # ADB 協定通訊與設備鎖定狀態表
│   ├── cli/                    # 終端機互動式選單（bubbletea）
│   ├── daemon/                 # 本機背景服務、Port 路由表、IPC
│   ├── proxy/                  # 透明 TCP 代理與 16KB 切片轉發
│   ├── signal/                 # WebSocket 信令交換與動態主機管理
│   └── webrtc/                 # pion/webrtc PeerConnection 與通道管理
│
├── pkg/                        # 公開 package（可被外部 import）
│   └── protocol/               # 共用的 Signaling JSON 與 IPC 格式定義
│
├── configs/                    # 設定檔範例 (.env)
├── docs/                       # 詳細文件
├── go.mod
├── go.sum
├── Makefile
├── LICENSE
└── README.md

開發原則

BDD (Behavior-Driven Development)

  • 每項功能先寫測試，再撰寫實作
  • 測試命名使用 Test<功能>_<場景> 格式
  • 範例：TestDeviceTable_ConcurrentLock、TestTracker_Reconnect

DRY (Don't Repeat Yourself)

  • 共用型別定義集中在 pkg/protocol/
  • 避免跨 package 複製程式碼

YAGNI (You Aren't Gonna Need It)

  • 不引入不需要的框架（如 viper、cobra）
  • 設定優先使用環境變數，夠用就好

KISS (Keep It Simple, Stupid)

  • 優先選擇最簡單的解法
  • 避免過度設計和不必要的抽象層

型別安全

  • 所有函式與方法加上 type hints
  • 使用明確的介面定義模組邊界

提交規範

  • Commit message 使用繁體中文
  • 依模組分別提交（如 feat(adb): 新增設備追蹤器）
  • 提交前確保 go test -race ./... 和 golangci-lint run 通過

Makefile 常用指令

.PHONY: build test lint clean

build:
	go build ./cmd/...

test:
	go test -race ./...

lint:
	golangci-lint run

clean:
	rm -f radb
	rm -f radb.exe

all: lint test build

若要在 Windows 本機建置，優先使用 scripts/build-windows.ps1，避免 Go 1.26+ 預設 Green Tea GC 在 Windows 上帶來額外風險。