"TeachLink" 是一款基於 Single Activity MVI 架構並完全使用 Jetpack Compose UI 構建，模擬預約教師行事曆的多模組 Android 應用程式。
UI 設計採用 Material 3 Design ，並以 Jetpack Compose 實作 Collapsing Toolbar 帶有 Snap 動畫效果。
這款 APP 的目標是展示如何遵循 Modern Android Development (現代 Android 開發方法) 最佳實踐，同時提供完整的架構遷移指南和實用參考資訊給開發者。
Note
查看 TeachLink：MAD 遷移之旅 ，了解本專案遷移路徑。
- MVI Architecture (Model - View - Intent)
- Jetpack Compose
- Material 3
- Coroutines
- Kotlin Flow
- Retrofit2 & OkHttp3: Construct the REST APIs and paging network data.
- Hilt: for dependency injection.
- Navigation Compose: The Navigation component provides support for Jetpack Compose applications.
- Proto DataStore: A Jetpack solution for storing key-value pairs or typed objects using protocol buffers. It leverages Kotlin coroutines and Flow for asynchronous and transactional data storage.
- Coil: An image loading library for Android backed by Kotlin Coroutines.
- Turbine: A small testing library for kotlinx.coroutines Flow.
- Google Truth: Fluent assertions for Java and Android.
- Roborazzi: A screenshot testing library for JVM.
- Robolectric: Robolectric is the industry-standard unit testing framework for Android.
建構此 App 你可能需要以下工具：
- Android Studio Giraffe | 2022.3.1
- JDK JavaVersion.VERSION_17
在此應用程式中，我們對於 MVI 架構中常見的使用情境進行了以下封裝：
BaseViewModel：提供MutableStateFlow供 UI 訂閱 UI State，並提供dispatch()抽象方法供子類別實現。
Note: 通過
dispatch()統一處理事件分發，有助於 View 與 ViewModel 間的解耦，同時也更利於日誌分析與後續處理。
StateFlowStateExtensions.kt：封裝 UI StateFlow 流，提供更方便的操作方式。DataSourceResult.kt：封裝數據源結果的密封類別，封裝可能是成功 (Success)、錯誤 (Error) 或正在加載 (Loading) 的狀態。designsystem/ui/management/states/topappbar/*：封裝以 Jetpack Compose 實現 Collapsing Toolbar 相關類，並提供EnterAlwaysCollapsedState、EnterAlwaysState、ExitUntilCollapsedState或ScrollState的滾動行為 flags。
Note: 在
ScheduleScreen可以看到其搭配 Snap 動畫之使用範例。
該應用程序包含常用 debug 和 release build variants。
此外，該應用程序也使用了 Product Flavors 來控制應用內容的載入來源。
demoflavor 透過使用靜態本地數據，允許開發者立即建立應用並探索其使用者介面。prodflavor 則透過向後端伺服器發起真實網路請求，提供最新的內容。 目前，尚未公開後端服務。
對於正常開發，請使用該 demoDebug variant。對於 UI 性能測試，請使用該 demoRelease variant。
Note: 詳見 Google 官方網誌文章 Why should you always test Compose performance in release?
本專案採用 Material 3 Design ，使用自適應佈局來 Support different screen sizes。
並以 Jetpack Compose 實作 Collapsing Toolbar 帶有 Snap 動畫效果，並為其進行封裝。 遵循 Google 官方 API Guidelines for Jetpack Compose 。
Note: Material 3 尚未 release collapsing toolbar 相關 UI 元件 API，截止 2023/09/27
本專案遵循了 Android 官方應用架構指南。
以下圖表顯示尋找處理特定事件用途最佳方式時的決策樹。
不要使用 Channels, SharedFlow 或其他回應式串流向 UI 公開 ViewModel 事件。
- 立即處理一次性的 ViewModel 事件，並將其降為 UI 狀態。
- 使用可觀察的數據持有類型來公開狀態。
Note: 關於不應使用上述 API 的理由和示例，
請參閱 Google 官方網誌文章 ViewModel: One-off event antipatterns
Top tip：模組圖（如上所示）在模組化規劃期間有助於視覺化展示模組間的依賴性。
TeachLink 主要包含以下幾種模組:
-
app模組 - 此模組包含 app 級別的核心組件和 scaffolding 類，例如MainActivity、TlApp以及 app 級別控制的導航。app模組將會依賴所有的feature模組和必要的core模組。 -
feature:模組 - 這些模組各自專注於某個特定功能或用戶的互動流程。每個模組都只聚焦於一個特定的功能職責。如果某個類別只被一個feature模組所需要，那麼它應只存在於該模組中；若非如此，則應該將其移至適當的core模組。每個feature模組應避免依賴其他feature模組，並只應依賴其所需的core模組。 -
core:模組 - 這些模組是公共的函式庫模組，它們包含了眾多輔助功能的程式碼和那些需要在多個模組間共享的依賴項。這些模組可以依賴其他core模組，但絕不應依賴於feature模組或app模組。 -
其他各種模組：例如
test模組，主要用於進行軟體測試。
採用上述模組化策略，TeachLink 應用程序具有以下模組：
| Name | Responsibilities | Key classes and good examples |
|---|---|---|
app |
將所有必要元素整合在一起，確保應用程式的正確運作。 eg. UI scaffolding、navigation...等 |
TlApplication,TlNavHostTopLevelDestinationTlAppTlAppState |
feature:1,feature:2... |
負責實現某個特定功能或用戶的互動流程的部分。這通常包含 UI 組件、UseCase 和 ViewModel，並從其他模組讀取資料。例如： • feature:teacherschedule 專注於展示教師預約時段的行事曆資訊。• feature:login 提供歡迎畫面和登入畫面。當 Token 失效時，會跨模組導航，導向此模組。 |
ScheduleScreen,ScheduleListPreviewParameterProvider,domain/GetTeacherScheduleUseCase... |
core:data |
負責從多個來源獲取應用程式的資料，並供其他功能模組共享。 | TeacherScheduleRepository, utils/ConnectivityManagerNetworkMonitor |
core:common |
包含被多個模組共享的通用類別。 eg. 工具類、擴展方法...等 |
network/TlDispatchers,result/DataSourceResult,authentication/TokenManager,manager/SnackbarManager,extensions/StateFlowStateExtensions,utils/UiText... |
core:domain |
包含被多個模組共享的 UseCase。 | IntervalizeScheduleUseCase |
core:model |
提供整個應用程式所使用的模型類別。 | IntervalScheduleTimeSlot,ScheduleTimeSlot |
core:network |
負責發送網絡請求，並處理來自遠程數據源的回應。 | RetrofitTlNetworkApi |
core:designsystem |
UI 依賴項。 eg. app theme、Core UI 元件樣式...等 |
TlTheme,TlAppSnackbarmanagement/states/topappbar/*... |
core:testing |
測試依賴項、repositories 和 util 類。 | MainDispatcherRule,TlTestRunner,... |
core:datastore |
儲存持久性數據 | TlPreferencesDataSource,UserPreferencesSerializer,... |
本專案主要採用 Test double、Robot Testing Pattern 以及 Screenshot tests 作為測試策略，使測試更加健全且易於維護。
在 TeachLink 專案中，我們使用了 Hilt 來進行依賴注入。而在資料層，我們將元件定義成接口形式，並依照具體需求進行實現綁定。
- TeachLink 並未使用任何 mocking libraries，而選擇使用 Hilt 的測試 API，方便我們將正式版本輕鬆替換成測試版本。
- 測試版本與正式版本保持相同的接口，但是測試版本的實現更為簡單且真實，且有特定的測試掛鉤。
- 這種設計策略不僅降低了測試的脆弱性，還有效提高了代碼覆蓋率。
- 在測試過程中，我們為每個 repository 提供測試版本。在測試
ViewModel時，這些測試版的 repository 會被使用，進而透過測試掛鉤操控其狀態並確認測試結果。
對於 UI Testing，TeachLink 採用了 Robot Testing Pattern，其核心目的是建立一個抽象層，以聲明性的方式進行 UI 交互。
- 易於理解：測試內容直觀，使用者可以快速理解而不必深入了解其背後的實現。
- 代碼重用：通過將測試進行模組化，能夠重複使用測試步驟，從而提高測試效率。
- 隔離實現細節：透過策略分層，確保了代碼遵循單一責任原則，這不僅提高了代碼的維護性，還使得測試和優化過程更為簡便。
TeachLink 使用 Roborazzi 進行特定畫面和組件的截圖測試。要運行這些測試，請執行 verifyRoborazziDemoDebug 或 recordRoborazziDemoDebug 任務。
Important
截圖是在 CI 上使用 Linux 記錄的，其他平台可能產生略有不同的圖像，使得測試失敗。
See the original assignment specification at TeachLink: Android Assignment Option B.
TeachLink is distributed under the terms of the Apache License (Version 2.0). See the license for more information.
Special thanks to JetBrains for their support in this project.
