GitHub 源码管理工具介绍与实践——以“史迹·时空漫游 APP”为例
一、源码管理工具的作用
在团队软件开发过程中，源码管理工具不仅用于保存代码，更重要的是帮助团队记录代码变化、管理不同版本、分配开发任务，并降低多人协作时出现代码冲突和版本混乱的风险。
如果项目只依靠本地文件夹或压缩包传递代码，很容易出现“谁的版本最新”“某个功能是谁修改的”“代码出错后如何回退”等问题。尤其是在团队项目中，不同成员往往负责不同功能模块，如果没有统一的源码管理工具，后期整合代码会比较困难。
我们团队正在开发的项目是 “史迹·时空漫游 APP”。该项目包含 Android 客户端、Spring Boot 后端服务和项目文档，功能涉及内容浏览、历史地图探索、AI 生成攻略、AI 视频创作、管理员审核和个人中心等模块。因此，我们选择使用 GitHub 对项目进行源码管理和协作开发。
二、主流源码管理工具简介
目前常见的源码管理工具包括 GitHub、GitLab、Gitee、Azure DevOps / TFS 和 SVN 等。
| 工具 | 主要特点 | 适用场景 |
|---|---|---|
| GitHub | 使用广泛，支持 Git 版本管理、Issue、Pull Request、分支协作 | 学生项目、开源项目、团队协作开发 |
| GitLab | 功能完整，支持私有化部署和 DevOps 流程 | 企业内部项目、持续集成开发 |
| Gitee | 国内访问方便，中文界面友好 | 国内团队项目、课程作业 |
| Azure DevOps / TFS | 偏企业级项目管理与源码管理 | 大型企业软件开发 |
| SVN | 传统集中式版本管理工具 | 老项目维护、简单代码管理 |
综合考虑学习成本、使用普及度、团队协作便利性和项目展示效果，我们最终选择 GitHub 作为本项目的源码管理工具。
三、“史迹·时空漫游 APP”项目结构
我们的项目采用单仓库管理方式，也就是把前端、后端和文档统一放在一个 GitHub 仓库中。这样便于团队成员查看完整项目。
当前项目结构主要包括：
shiji-time-travel-app/
├─ app/ Android 客户端代码
├─ backend/ Spring Boot 后端服务代码
├─ docs/ API 文档、数据库文档
├─ gradle/ Gradle 配置文件
├─ build.gradle Android 项目构建文件
├─ settings.gradle 项目模块配置文件
└─ .gitignore Git 忽略规则文件
其中，app/ 目录主要存放 Android 前端代码，包括首页、历史探索、视频播放、AI 创作和个人中心等页面；backend/ 目录主要存放 Spring Boot 后端代码，包括历史探索接口、数据库实体类、服务层和控制层；docs/ 目录用于保存接口文档、数据库设计和项目说明文档。
这种结构比较适合课程团队项目，因为前端、后端和文档都集中在一个仓库中，既方便管理，也能体现项目的完整性。
四、GitHub 仓库创建与代码上传
在正式上传代码前，我们先在 GitHub 上创建了项目仓库，仓库名称为：
shiji-time-travel-app
由于本地项目已经开发了一部分，因此创建仓库时没有额外勾选 README、.gitignore 或 License，而是先创建一个空仓库，再通过 Git 命令上传已有代码。
上传前，我们先配置了 .gitignore 文件，用于排除不适合上传的本地文件和编译产物，例如：
.gradle/
.idea/
app/build/
backend/target/
local.properties
*.jar
*.apk
这样可以避免把本机缓存、编译结果或个人配置上传到 GitHub，使仓库更加干净规范。
项目上传时主要使用了以下命令：
git init
git add .
git commit -m "chore: initialize Shiji Time Travel App project"
git branch -M main
git remote add origin https://github.com/Luna-Breeze/shiji-time-travel-app.git
git push -u origin main
完成上传后，项目代码成功进入 GitHub 版本管理。后续团队成员就可以基于该仓库进行协作开发。
五、分支管理设计
为了避免所有成员直接修改同一个分支，我们采用了较简单但清晰的分支管理方式：
main 稳定展示版本
develop 日常开发整合版本
feature/* 功能开发分支
其中，main 分支用于保存稳定版本，也就是可以展示和运行的代码；develop 分支用于日常开发整合；feature/* 分支用于具体功能开发。
目前我们已经创建了 main 和 develop 两个基础分支。后续成员开发新功能时，需要从 develop 分支拉取自己的功能分支，开发完成后再通过 Pull Request 合并回 develop。
例如，后续可以根据项目模块创建以下分支：
feature/android-discover-video
feature/android-explore-profile
feature/backend-explore-api
feature/backend-ai-generation
feature/backend-admin-review
这种分支管理方式可以让每个功能模块相对独立，减少不同成员之间的代码冲突，也方便项目管理者检查和合并代码。
六、团队成员分工与协作方式
我们团队加上本人共 5 人，因此采用“项目管理者 + 模块负责人”的方式进行协作。
| 角色 | 主要负责内容 |
|---|---|
| 项目管理者 | GitHub 仓库管理、Issue 分配、Milestone 管理、文档整理 |
| 前端成员 A | 首页内容浏览、视频展示、搜索入口 |
| 前端成员 B | 历史地图探索、事件详情、个人中心 |
| 后端成员 C | 历史探索 API、数据库、收藏与足迹接口 |
| 后端 / AI 成员 D | AI 生成攻略、AI 解说文案、视频发布与审核 |
团队协作规则主要包括：
main分支只保存稳定版本，成员不直接提交到main。- 日常开发基于
develop分支进行。 - 每个成员根据自己的任务创建或使用对应的
feature分支。 - 功能完成后，通过 Pull Request 合并到
develop。 - 提交代码时使用清晰的提交说明。
常用提交信息示例如下：
git commit -m "feat: 完成历史地图探索页面"
git commit -m "fix: 修复收藏状态显示问题"
git commit -m "docs: 更新历史探索接口文档"
git commit -m "chore: 添加 .gitignore 配置"
通过这样的协作方式，团队成员可以明确知道自己负责什么、在哪个分支开发、开发完成后如何合并。
七、Issue 任务管理
除了保存代码，GitHub 还可以通过 Issues 进行任务管理。我们将项目任务拆分成多个 Issue，每个 Issue 对应一个具体任务，例如前端页面完善、后端接口开发、数据库调整或文档补充。
在 v0.2-explore-integration 阶段，我们创建了 4 个待完成 Issue：
feat: 完善后端历史探索 API 与数据库数据
feat: Android 前端接入历史探索后端 API
feat: 实现收藏与历史足迹真实数据联调
docs: 补充历史探索联调文档与接口说明
这些任务对应下一阶段的重点：让 Android 前端和 Spring Boot 后端真正完成历史探索模块的联调。
通过 Issues，项目管理者可以清楚看到哪些任务已经完成、哪些任务仍在进行；团队成员也可以根据分配的 Issue 明确自己的工作内容。
八、Labels 标签分类
为了让任务更清晰，我们创建了 5 个常用 Labels：
| Label | 作用 |
|---|---|
docs |
文档任务 |
database |
数据库任务 |
backend |
后端任务 |
frontend |
前端任务 |
bug |
问题修复 |
例如，后端接口任务会标记为 backend，数据库相关任务会标记为 database，Android 页面或前端联调任务会标记为 frontend。这样在 Issues 页面中可以快速区分任务类型，方便筛选和管理。
九、Milestones 阶段管理
为了体现项目开发进度，我们使用 Milestones 对项目进行阶段划分。当前设置了 3 个里程碑：
| Milestone | 阶段说明 |
|---|---|
v0.1-static-demo |
当前静态演示版 |
v0.2-explore-integration |
历史探索前后端联调版 |
v0.3-ai-review |
AI 创作与审核闭环版 |
其中，v0.1-static-demo 对应当前已经完成的基础版本，包括 Android 基础页面、Mock 数据、Spring Boot 后端历史探索基础接口和项目文档。我们为该阶段创建了 5 个已完成 Issue，并将它们关闭，因此 GitHub 显示该阶段进度为 100% complete。
v0.2-explore-integration 是下一阶段重点，目前已经创建了 4 个 open Issue，表示历史探索模块的前后端联调任务已经规划好，但还未完成。
v0.3-ai-review 则对应更后续的 AI 创作和管理员审核闭环，包括 AI 生成旅游攻略、AI 解说文案、视频发布、管理员审核、退回修改和个人中心审核状态展示等功能。
十、GitHub 在本项目中的实际意义
通过本次实践，我们不只是把代码上传到了 GitHub，而是初步建立了一个较规范的团队协作流程。
首先，仓库结构清晰，前端、后端和文档分别放在 app/、backend/ 和 docs/ 目录下，便于查看和维护。其次，main 和 develop 分支的设置让稳定版本和开发版本区分开来，避免多人直接修改主分支导致代码混乱。再次，通过 Issues、Labels 和 Milestones，我们能够把项目任务拆分、分类并按阶段推进，使项目进度更加可视化。
对于“史迹·时空漫游 APP”这种功能模块较多的团队项目来说，GitHub 的作用不仅是代码托管，更是团队协作管理工具。它帮助我们明确了当前完成度、下一阶段任务和团队成员分工，也为后续项目开发提供了更清晰的管理基础。
十一、总结
本次源码管理工具实践中，我们选择 GitHub 作为“史迹·时空漫游 APP”的源码管理平台，并完成了仓库创建、代码上传、分支设计、Issue 任务拆分、Label 分类和 Milestone 阶段管理。
通过这次实践，我认识到，源码管理工具并不是简单的代码存储工具，而是团队开发过程中的协作平台。合理使用 GitHub，可以让团队成员更清楚地了解项目结构、开发任务和阶段进度，也可以减少多人协作中的版本混乱和沟通成本。
目前，本项目已经完成 v0.1-static-demo 静态演示版，并进入 v0.2-explore-integration 历史探索前后端联调阶段。后续团队将继续按照 GitHub 的分支和任务管理流程推进开发，逐步完善 AI 创作、视频发布、管理员审核和个人中心审核状态等功能。
浙公网安备 33010602011771号