PTT Android 開發求生指南
- Android App Repo: https://github.com/Ptt-official-app/Ptt-Android
- Api Repo: https://github.com/Ptt-official-app/go-openbbsmiddleware
- Api 文件: https://doc.devptt.dev/
- Zeplin 設計稿文件(Mockup): https://app.zeplin.io/project/5d7346333838ff497428d1c5
由於此專案為自願性,且仍在開發初期,需要你主動加入,可由以下方式加入:
- 在 Telegram 找 @kenhuang1120,會協助你加入 Ptt Android 的 Telegram 群組與取得相關資訊
- 直接在 Android App Repo 發 PR or Issue
此專案參考 Android Architecture,分為 UI layer
, Domain layer
, Data Layer
,以 module 形式切分,使用 Kolin 開發並使用 Koin 實作 DI。
以下將逐一介紹各 module、職責與所使用的技術
對應 Android Architecture
的 UI layer
Component:
Activity
、Fragment
、etc... : 由於本專案採用 MVVM 架構,所有 data 與 ui 之間的交換都要透過ViewModel
交換,View 與 ViewModel 之間的 data 交換推薦使用 StateFlow 和 SharedFlow。- Navigation: 頁面轉換使用 Navigation component,相關的程式碼統一放在 Navigation.kt 管理
對應 Android Architecture
的 Domain layer
Component:
- UseCase: Data layer 與 ViewModel 間的 data 轉換與商業邏輯
對應 Android Architecture
的 Data layer
Components﹔
- ApiServices : 本專案採用 OKHttp 作為 Http client,並使用 Retrofit 原始資料轉換成 App 內定義的資料結構,並使用 Flow 傳遞
Repository
:將資料公開到Domain layer
,Repository
可以根據需要將資料 merge 、 filter 、transform 等等資料操作,這些處理目的是為了提供給外部需要且可靠的資料結構,而不會執行任何商業邏輯。DataSource
:分為remote(network)
及local(database)
,用以區隔網路來的資料或是 local 端資料。
擺放其他共用元件(Ex: Logger、extensions、etc...)
專案使用 Git hooks 在 commit 前進行 coding style 檢查。
到專案 root folder 執行:
chmod +x ./script/pre_commit_format.sh && ./script/pre_commit_format.sh
之後確認 .git/hooks
下已新增 pre-commit ,如果找不到 .git/hooks
請自行新增 git hook 。
參考 Google Java Style Guide, Android Kotlin Style Guide。
遵循 Git workflow。
請盡量使用英文描述 commit message。
目前有使用 spotless 做程式碼的檢查及整理。
使用 spotless 來為專案 reformat,專案在 build 之前會自動進行一次 reformat ,除此之外執行上面的 Getting Start 後在 commit 前 spotless 也會做一次 coding style 的檢查。
spotless 外掛 ktlint 及 google-java-format 當作他的檢查工具。
平常 coding 時可使用 gradlew spotlessCheck
及 gradlew spotlessApply
檢查程式碼格式。
由於 Google 及 Jetbrains 都沒有對外釋出 kotlin 的官方版 lint 工具,目前我們是使用第三方的 ktlint 來做 lint 檢查。
ktlint 的 code style 參考自 kotlinlang.org 及 Android Kotlin Style Guide,另外 lint 的 rule 規則可參考 ktlint 的 Standard rules (例外:專案內依然允許 wildcard import
s)。
Google 的 format 工具,專案裡把縮排的規則改成 4 格。
- 開發前請確認
build variant
設定為stagingDebug
再行開發 - (optional)自行在專案
local.properties
裡面加入:
HOST=https://<api_host_domain>
ACCOUNT=<unit_test_account>
PASSWORD=<unit_test_account_password>
目前僅支援 go-openbbsmiddleware 版本API