ManyCourse 项目架构详解：四层设计从 UI 到网络

前言#

看一个项目，最怕的就是”打开代码不知道该从哪看起”。本文的目标就是帮你建立 ManyCourse（课多多）项目的全局心智地图——看懂它分了几层、每层干什么、一次登录后数据怎么流。

读完这一篇，你打开代码就不会迷路。

1. 四层架构速览#

代码里所有 package 都在 com.tof.manycourse 下，按职责分成 4 大块，从「离用户最近」到「离网络最近」：

1
┌────────────────────────────────────────────────────────┐
2
│ ui/        Compose 界面（课表/日历/地图/我的/设置/玻璃组件）   │
3
│            —— 只负责「画出来 + 响应用户」                   │
4
├────────────────────────────────────────────────────────┤
5
│ data/      本地仓库与纯数据（Course/School/SchoolCourse…）  │
6
│            —— 只负责「存数据 + 算规则」，不碰网络、不碰 UI    │
7
├────────────────────────────────────────────────────────┤
8
│ gr_api/    学校接口层（一所学校一个文件）                    │
9
│            —— 负责「登录/拉课表/拉姓名」，把结果翻译成 data 层 │
10
├────────────────────────────────────────────────────────┤
11
│ api/       网络与密码学底座（OkHttp/Cookie/RSA/SM2/AES）   │
12
│            —— 与「具体学校」无关的可复用件                   │
13
└────────────────────────────────────────────────────────┘

依赖方向是单向的：ui → data，ui → gr_api，gr_api → api，gr_api → data。底层永远不认识上层。

一句话记忆：ui 负责画，data 负责存，gr_api 负责”和学校打交道”，api 负责”和网络/密码打交道”。

2. 它到底在解决什么问题#

大学生每学期都要对着教务系统网站看课表、截屏存手机。这个 App 做的事：

1. 登录：把各校教务系统的登录接口一个个接进来（现有 3 所：广软 gzus、金城学院 nhjcxy、广工 gdut）。
2. 同步：登录成功后，自动把「姓名 + 课表 + 教学周」拉到本地。
3. 展示：周视图课表 + 月历 + 校园地图，本地缓存还能离线看。

核心卖点是 SchoolApi 接口——加新学校 = 实现这个接口 + 注册一行，别的地方都不动。

3. 目录地图（源码位置对照）#

入口文件：

• MainActivity.kt —— 登录页（学校下拉 / 账号 / 密码 / 验证码）
• ManyCourseMain.kt —— 登录后的主界面，管 4 个 Tab 的挂载与切换
• 4 个 XxxFragment.kt —— 课表 / 日历 / 地图 / 我的，各自是 Compose 的容器

4. 一次「登录 → 同步」的完整数据流#

这是整个项目最重要的图，先看图再读代码：

1
用户在登录页填学号密码，点登录
2
        │
3
        ▼
4
SchoolRegistry.apiOf(schoolId).login(账号, 密码) { result -> }
5
        │   ① 按学校 id 分发到对应实现（gzus / nhjcxy / gdut）
6
        ▼
7
[gr_api 层] 某某 Api 发起 HTTP（api 层的 HttpMethod 帮它发）
8
        │   ② 可能多步：GET 登录页拿 token/公钥 → POST 表单 → 判定
9
        ▼
10
login 回调 LoginResult（sealed：Success / Failure / NeedCaptcha / Pending）
11
        │   ③ Success → SessionStore 存会话（Keystore 加密 Cookie），跳主界面
12
        ▼
13
ManyCourseMain.onCreate
14
        │   ④ CourseSync.sync(schoolId, account)
15
        ▼
16
api.fetchProfile(account) { profile ->      // 拉姓名
17
    api.fetchSchedule(account) { schedule -> // 拉课表
18
        CourseRepository.replaceAll(list)     // 写进本地仓库
19
        state = Ready(...)                    // 供课表页显示
20
    }
21
}
22
        │   ⑤ 两个回调都来自 OkHttp 工作线程 → main{} 切回主线程改数据
23
        ▼
24
Compose 自动重组 → 课表页/日历页显示出刚同步的数据

每个环节落在哪个文件：

5. 三个最核心的概念#

1
interface SchoolApi {
2
    val school: School                    // 学校本身（id/名称/地址/节次表）
3
    val configured: Boolean               // 接没接好（没接好=提示"未接入"）
4
    fun login(account, password, captcha?, callback)   // 登录
5
    fun fetchSchedule(account, callback)  // 拉课表（有默认实现）
6
    fun fetchProfile(account, callback)   // 拉姓名（有默认实现）
7
    fun exportSession() / importSession() / clearSession()  // 会话持久化
8
}

1
private val apis: List<SchoolApi> = listOf(
2
    GzusApi(),
3
    NhjcxyApi(),
4
    GdutApi(),
5
)

1
object CourseRepository {
2
    val courses = mutableStateListOf<Course>()   // Compose 可观察列表
3
    fun add(...): Course { ... }
4
    fun replaceAll(remote: List<SchoolCourse>) { ... }
5
    fun coursesOn(weekday: Int): List<Course> = ...
6
}

6. 页面是怎么组织的#

4 个 Tab = 4 个 Fragment，每个 Fragment 里装一个 ComposeView 渲染 Compose 界面：

1
ManyCourseMain (AppCompatActivity)
2
 ├─ ClassScheduleFragment   → 课表页（周视图）
3
 ├─ CalenderFragment        → 日历页（月历）
4
 ├─ MapFragment             → 地图页（校园平面图）
5
 └─ SelfFragment            → 我的页（资料/设置/统计）

底栏（玻璃底栏）在 ui/components/ 里，切换逻辑在 ManyCourseMain.kt 的 selectTab()。

为什么用 Fragment + Compose 混搭，而不是纯 Compose？这是历史演进的结果，读代码时知道”这 4 个是入口、具体界面在 ui/ 里”就够了。

7. 两条铁律（改代码前先背下来）#

项目 README 里强调过，零基础最容易踩：

1. 学校 id 是持久化主键，定了不许改——它存在本地 SharedPreferences 里，“上次选的学校”靠它恢复。改了就等于清空老用户的选择。全小写英文短名。
2. 加接口不要新建 HttpMethod——Cookie 会话挂在 SchoolApi 实例的 http 里，新建实例等于开了个空会话，接口必然被认为”没登录”。

8. 一句话总结每层边界#

• 要加一所学校 → 只动 gr_api/schools/（新文件）+ SchoolRegistry.kt（一行）。
• 要改课表怎么算/怎么存 → 动 data/。
• 要改界面长什么样 → 动 ui/。
• 要接入新的加密/网络能力 → 动 api/。

分层清晰的定义就是：改一层，别层几乎不用动。这就是好的架构。

后续阅读#

架构看完了，下一步建议阅读 核心代码导读，逐文件逐行理解最关键的源码实现。