## File: README.md

[](https://github.com/CarGuo/gsy_github_app_flutter/actions)
[](https://github.com/CarGuo/gsy_github_app_flutter/stargazers)
[](https://github.com/CarGuo/gsy_github_app_flutter/network)
[](https://github.com/CarGuo/gsy_github_app_flutter/issues)
[](https://github.com/CarGuo/gsy_github_app_flutter/blob/master/LICENSE)
[](https://gitcode.com/ZuoYueLiang/gsy_github_app_flutter)


### [English Readme](https://github.com/CarGuo/gsy_github_app_flutter/blob/master/README_EN.md)


## 一款跨平台的开源Github客户端App，提供更丰富的功能，更好体验，旨在更好的日常管理和维护个人Github，提供更好更方便的驾车体验～～Σ(￣。￣ﾉ)ﾉ。项目涉及各种常用控件、网络、数据库、设计模式、主题切换、多语言、状态管理（Redux、Riverpod、Provider）等。在开发学习过程中，提供丰富的同款对比：


* ### 同款Weex版 （ https://github.com/CarGuo/GSYGithubAppWeex ）
* ### 同款ReactNative版 （ https://github.com/CarGuo/GSYGithubApp ）
* ### 同款Android Kotlin View版本（ https://github.com/CarGuo/GSYGithubAppKotlin ）
* ### 同款Android Compose版本（ https://github.com/CarGuo/GSYGithubAppCompose ）
* ### 同款Compose Multiplatform版本（ https://github.com/CarGuo/GSYGithubAppCMP ）
* ### 同款HarmonyOS ArkUI版本（ https://github.com/CarGuo/GSYGithubAppOH ）

* ### 简单 Flutter 独立学习项目 ( https://github.com/CarGuo/gsy_flutter_demo )



## 相关文章

| 公众号   | 掘金     |  知乎    |  CSDN   |   简书   
|---------|---------|--------- |---------|---------|
| GSYTech  |  [点我](https://juejin.cn/user/582aca2ba22b9d006b59ae68/posts)    |   [点我](https://www.zhihu.com/people/carguo)       |   [点我](https://blog.csdn.net/ZuoYueLiang)  |   [点我](https://www.jianshu.com/u/6e613846e1ea)  

- ### [Flutter系列文章专栏](https://juejin.cn/column/6960546078202527774)

----
- ### [Flutter 独立简单学习演示项目](https://github.com/CarGuo/gsy_flutter_demo)
- ### [Flutter 完整开发实战详解 Gitbook 预览下载](https://github.com/CarGuo/gsy_flutter_book)
- ### [所有运行问题请点击这里](https://github.com/CarGuo/gsy_github_app_flutter/issues/13)

* ### GSY老书：[《Flutter开发实战详解》](https://item.jd.com/12883054.html)上架啦：[京东](https://item.jd.com/12883054.html) / [当当](http://product.dangdang.com/28558519.html) / 电子版[京东读书](https://e.jd.com/30624414.html)和[Kindle](https://www.amazon.cn/dp/B08BHQ4TKK/ref=sr_1_5?__mk_zh_CN=亚马逊网站&keywords=flutter&qid=1593498531&s=digital-text&sr=1-5)

- ### [如果克隆太慢或者图片看不到，可尝试从码云地址下载](https://gitee.com/CarGuo/gsy_github_app_flutter)



-----

## 须知

> **因为是偏学习展示项目，所以项目里会有各式各样的模式、库、UI等，请不要介意**
> 
> 0、 全局状态管理目前有多种模式，包括 Provider、Redux、Riverpod 等
> 
> 1、 TrendPage ： 目前采用纯  riverpod  状态管理，演示
>
> 2、 Provider：目前在 RepositoryDetailPage 出使用
>
> 3、 Redux：目前展示了全局登陆和用户信息等上面使用。
> 
> 4、 riverpod：目前用于管理全局灰度，多语言。
>
> 5、 Repos 等请求展示了 graphQL
> 
> 6、 Redux：目前展示了全局登陆和用户信息等上面使用。
> 
> 7、 Signals：目前用于 NotifyPage、RepositoryDetailFileListPage 页面内状态管理
> 
> **列表显示有多个，其中：**
> 
> 1、**gsy_pull_load_widget.dart.dart**
> `common_list_page.dart 等使用，搭配 gsy_list_state.dart 使用`
>
> 2、**gsy_pull_new_load_widget.dart.dart**
> `dynamic_page.dart 等使用，搭配 gsy_bloc_list_state.dart 使用`
> `有 iOS 和 Android 两种风格下拉风格支持`
> 
> 3、**gsy_nested_pull_load_widget.dart**
> `trend_page.dart 等使用，配置sliver 效果`


## 编译运行流程

1、配置好Flutter开发环境(目前Flutter SDK 版本 **3.44.1**，仓库已在 `.fvmrc` 里锁定该版本，推荐使用 [FVM](https://fvm.app/) 一键切换：`fvm install 3.44.1 && fvm use 3.44.1`)，可参阅 [【搭建环境】](https://flutterchina.club)。

2、clone代码，执行`Packages get`安装第三方包。(因为某些不可抗力原因，国内可能需要设置代理: [代理环境变量](https://flutterchina.club/setup-windows/))

>### 3、重点：你需要自己在lib/common/config/目录下 创建一个`ignoreConfig.dart`文件，然后输入你申请的Github client_id 和 client_secret。

     class NetConfig {
       static const CLIENT_ID = "xxxx";
     
       static const CLIENT_SECRET = "xxxxxxxxxxx";
     }


   [      注册 Github APP 传送门](https://github.com/settings/applications/new)，当然，前提是你现有一个github账号(～￣▽￣)～ 。
 
### 4、如果使用安全登录（授权登录），那么在上述注册 Github App 的 Authorization callback URL 一栏必须填入 `gsygithubapp://authed`






### 5、运行之前请注意下

>### 1、本地 Flutter SDK 版本 3.44.1（`.fvmrc` 已锁定，可用 `fvm use` 切换）； 2、是否执行过 `flutter pub get`；3、 网络等问题参考: [如果出现登陆失败或者请求失败 ](https://github.com/CarGuo/gsy_github_app_flutter/issues/643)


### 下载

#### Apk下载链接： [Apk下载链接1 ](https://github.com/CarGuo/gsy_github_app_flutter/releases)
#### Apk下载链接： [Apk下载链接2 ](https://www.openapk.net/gsygithubappflutter/com.shuyu.gsygithub.gsygithubappflutter/)


| 类型          | 二维码                                      |
| ----------- | ---------------------------------------- |
| **Apk二维码**  |  |
| **iOS暂无下载** | |



## 项目结构图






### 常见问题

* 如果包同步失败，一般都是因为没设置包代理，可以参考：[环境变量问题](https://github.com/CarGuo/gsy_github_app_flutter/issues/13)

* [如果克隆太慢，可尝试码云地址下载](https://gitee.com/CarGuo/gsy_github_app_flutter)

### 示例图片
### 示例图片












### 框架

>当前 Flutter SDK 版本 3.38

```
用户交互 → UI层(Widget/Page) → 状态层(Redux/Provider/Riverpod) → 服务层(Repositories) 
       → 网络层(Net) → GitHub API → 数据模型(Model) → 本地存储(DB) → UI更新
```

```
┌─────────────────────────────────────────────────────────────────┐
│                         GSY GitHub App                          │
├─────────────┬───────────────┬────────────────┬─────────────────┤
│   UI Layer  │  State Layer  │  Service Layer │     Data Layer  │
├─────────────┼───────────────┼────────────────┼─────────────────┤
│             │               │                │                 │
│  ┌─────────┐│  ┌─────────┐  │  ┌─────────┐   │   ┌─────────┐   │
│  │ Pages   ││  │ Redux   │  │  │Repositories│  │   │ Models │   │
│  └─────────┘│  └─────────┘  │  └─────────┘   │   └─────────┘   │
│             │               │                │                 │
│  ┌─────────┐│  ┌─────────┐  │  ┌─────────┐   │   ┌─────────┐   │
│  │ Widgets ││  │ Provider│  │  │Network API│  │   │Database │   │
│  └─────────┘│  └─────────┘  │  └─────────┘   │   └─────────┘   │
│             │               │                │                 │
│  ┌─────────┐│  ┌─────────┐  │                │                 │
│  │Common UI││  │Riverpod │  │                │                 │
│  └─────────┘│  └─────────┘  │                │                 │
│             │               │                │                 │
│             │  ┌─────────┐  │                │                 │
│             │  │ Signals │  │                │                 │
│             │  └─────────┘  │                │                 │
│             │               │                │                 │
└─────────────┴───────────────┴────────────────┴─────────────────┘
```

```
lib/
├── main.dart              # 应用入口点
├── main_prod.dart         # 生产环境入口点
├── app.dart               # 应用配置与路由
├── common/                # 公共功能模块
│   ├── config/            # 应用配置
│   ├── event/             # 事件总线
│   ├── local/             # 本地化
│   ├── localization/      # 多语言支持
│   ├── net/               # 网络请求
│   ├── repositories/      # 数据仓库
│   ├── router/            # 路由配置
│   ├── style/             # 样式配置
│   └── utils/             # 工具类
├── db/                    # 数据库相关
│   ├── provider/          # 数据库提供者
│   ├── sql_manager.dart   # SQL管理器
│   └── sql_provider.dart  # SQL提供者
├── env/                   # 环境配置
├── model/                 # 数据模型
├── page/                  # 页面
│   ├── debug/             # 调试页面
│   ├── dynamic/           # 动态页面
│   ├── home/              # 主页
│   ├── issue/             # Issue相关页面
│   ├── login/             # 登录页面
│   ├── push/              # 推送相关页面
│   ├── release/           # 发布相关页面
│   ├── repos/             # 仓库相关页面
│   ├── search/            # 搜索页面
│   ├── trend/             # 趋势页面
│   └── user/              # 用户相关页面
├── provider/              # Provider状态管理
├── redux/                 # Redux状态管理
│   ├── middleware/        # Redux中间件
│   ├── gsy_state.dart     # Redux状态定义
│   ├── login_redux.dart   # 登录状态管理
│   └── user_redux.dart    # 用户状态管理
├── test/                  # 测试相关
└── widget/                # 自定义组件
    ├── anima/             # 动画组件
    ├── markdown/          # Markdown渲染组件
    ├── menu/              # 菜单组件
    ├── particle/          # 粒子效果组件
    ├── pull/              # 下拉刷新组件
    └── state/             # 状态相关组件
```

riverpod 页面内状态管理：

```
/* Detailed source-code truncated for AI context efficiency. */
```

provider 页面内状态管理：

```
/* Detailed source-code truncated for AI context efficiency. */
```





> 更多可见：https://codewiki.google/github.com/carguo/gsy_github_app_flutter

## Star History Chart










### LICENSE
```
CarGuo/gsy_github_app_flutter is licensed under the
Apache License 2.0

A permissive license whose main conditions require preservation of copyright and license notices. 
Contributors provide an express grant of patent rights. 
Licensed works, modifications, and larger works may be distributed under different terms and without source code.
```

---

## File: docs/06-decisions/README.md

# 决策记录

这个目录用于保存 ADR 风格的长期决策。
凡是"以后还会反复被问到"的架构选择，不要只留在代码评审历史里。

## 现有记录

- [ADR-0001 状态管理收敛策略](ADR-0001-状态管理收敛策略.md)
- [ADR-0002 新增功能默认状态方案](ADR-0002-新增功能默认状态方案.md)
- [ADR-0003 Markdown 相对路径图片处理边界](ADR-0003-markdown-相对路径图片处理边界.md)
- [ADR-0004 Markdown 内嵌 HTML 前置转换策略](ADR-0004-markdown-内嵌HTML前置转换策略.md)

后续适合记录的主题包括：

- 状态管理收敛策略
- CI 最小验证基线
- 生成代码工作流
- 功能目录约定

---

## File: docs/05-ai/feature-playbooks/debug-change.md

# 功能模板：修改调试页相关功能

## 开始前先读

1. `docs/02-features/debug.md`
2. `lib/common/net/AGENTS.md`

## 优先定位

- 调试页 UI：`lib/page/debug/debug_data_page.dart`
- 日志数据结构：`log_interceptor.dart`、`common/logger.dart`

## 修改策略

- 调试页只服务开发和诊断，不要引入业务依赖
- 改日志字段时同步检查调试页展示
- 复制和 JSON 弹窗链路都要能工作

## 最低验证

1. 调试页可打开
2. 四个 tab 可切换
3. 列表项可点击查看 JSON
4. 长按和双击复制正常

## 收尾步骤

调试页改动完成后，仍需先经过新的 reviewer subagent 审查，再对外汇报结果。

---

## File: docs/05-ai/feature-playbooks/dynamic-change.md

# 功能模板：修改动态页相关功能

## 开始前先读

1. `docs/02-features/dynamic.md`
2. `docs/04-quality/smoke-matrix.md`
3. `lib/page/AGENTS.md`

## 优先定位

- 页面刷新和滚动行为：`lib/page/dynamic/dynamic_page.dart`
- 列表数据与分页：`lib/page/dynamic/dynamic_bloc.dart`
- 事件跳转：`common/utils/event_utils.dart`

## 修改策略

- 首次加载、手动刷新、恢复前台刷新都要分开验证
- 动态页依赖当前登录用户，注意 Redux 用户态
- 不要只改 bloc 不测页面恢复刷新

## 最低验证

1. 首次进入动态页
2. 下拉刷新
3. 上拉加载更多
4. 退到后台再回来，验证自动刷新
5. 点击事件项跳转

## 收尾步骤

动态页改动完成后，先拉起新的 reviewer subagent 审查首次加载、恢复刷新和事件跳转，再对外汇报。

---

## File: docs/05-ai/feature-playbooks/home-change.md

# 功能模板：修改首页容器相关功能

## 开始前先读

1. `docs/02-features/home.md`
2. `docs/04-quality/smoke-matrix.md`
3. `lib/page/AGENTS.md`

## 优先定位

- tab 容器和搜索入口：`lib/page/home/home_page.dart`
- drawer：`lib/page/home/widget/home_drawer.dart`

## 修改策略

- 首页只负责容器和导航，不要承接具体业务逻辑
- 改 tab 结构时，同时验证 dynamic/trend/my 三个入口
- 改搜索入口时，要验证右上角位置计算与动画起点

## 最低验证

1. 首页可正常进入
2. 三个 tab 可切换
3. 双击 tab 可回到顶部
4. 搜索入口可打开搜索页
5. Android 返回键行为符合预期

## 收尾步骤

首页容器相关改动在完成验证后，必须先经过新的 reviewer subagent 审查。
这是容器层改动，不应由 author 自己直接宣布完成。

---

## File: docs/05-ai/feature-playbooks/issue-change.md

# 功能模板：修改 Issue 相关功能

## 开始前先读

1. `docs/02-features/issue.md`
2. `docs/04-quality/smoke-matrix.md`
3. `lib/page/AGENTS.md`

## 优先定位

- 展示和交互问题：`lib/page/issue/issue_detail_page.dart`
- 数据协议问题：`lib/common/repositories/issue_repository.dart`

## 修改策略

- 头部信息和评论列表分开看，不要混成一条链路
- 编辑、删除、回复逻辑都依赖刷新回流
- 不要只改按钮显示，不改实际提交链路

## 最低验证

1. 进入 issue 详情
2. 头部正常展示
3. 评论列表正常加载
4. 回复 issue
5. 编辑 issue 或评论
6. open/close issue 后头部状态更新

## 收尾步骤

Issue 相关改动完成后，先用新的 reviewer subagent 审查评论链路和头部状态回流，再对外汇报完成。

---

## File: docs/05-ai/feature-playbooks/notify-change.md

# 功能模板：修改通知页相关功能

## 适用场景

- 修改通知列表展示
- 调整未读/参与/全部筛选
- 修复刷新、分页或已读状态问题
- 扩展通知跳转行为

## 开始前先读

1. `docs/02-features/notify.md`
2. `docs/04-quality/smoke-matrix.md`
3. `lib/page/AGENTS.md`

## 先判断问题属于哪一层

### 页面与交互层

对应：

- `lib/page/notify/notify_page.dart`

适合处理：

- 列表渲染
- 滑动已读
- 顶部筛选
- 跳转行为

### 数据层

对应：

- `lib/common/repositories/user_repository.dart`
- `lib/model/notification.dart`

适合处理：

- 获取通知
- 标记已读
- 全部已读
- 通知字段解析

## 修改策略

- 优先维持 Signals 结构稳定
- 扩展通知类型跳转时，集中处理在 `_renderEventItem`
- 改分页或刷新逻辑时，必须一起验证筛选切换和返回强刷
- 未经明确允许，不得把本模块从 Signals 改成别的状态实现；这里保留 Signals 具有明确演示价值

## 常见误区

- 忽略 `signalPage = -1` 的强制刷新约定
- 只验证默认列表，不验证三个筛选 tab
- 标记已读后忘了检查列表移除或刷新逻辑

## 最低验证

1. 进入通知页
2. 默认列表加载
3. 切换 未读 / 参与 / 全部
4. 下拉刷新
5. 上拉加载更多
6. 单条标记已读
7. 全部标记已读
8. 点击 Issue 类型通知进入详情并返回

## 需要额外谨慎的情况

- 修改 Signals 触发链路
- 修改分页边界
- 修改通知详情跳转映射

## 收尾步骤

通知页改动完成后，必须先经过新的 reviewer subagent 审查。
author 不应在未做独立 review 的情况下直接宣布完成。

---

## File: docs/05-ai/feature-playbooks/push-change.md

# 功能模板：修改 Push 提交详情相关功能

## 开始前先读

1. `docs/02-features/push.md`
2. `docs/04-quality/smoke-matrix.md`
3. `lib/page/AGENTS.md`

## 优先定位

- 页面与 patch 展示：`lib/page/push/push_detail_page.dart`
- patch 转 HTML：`common/utils/html_utils.dart`
- commit 数据：`ReposRepository`

## 修改策略

- 头部和文件列表来自同一请求结果
- patch 展示问题不要忽略 HTML 转换逻辑
- 改导航时要验证返回仓库详情按钮

## 最低验证

1. 进入 push 提交详情
2. 头部信息正常
3. 文件变更列表正常
4. 点击文件项进入 patch 详情
5. 返回仓库详情链路正常

## 收尾步骤

Push 提交详情改动完成后，必须先经过新的 reviewer subagent 审查 patch 展示和返回链路。