1. 开工前的思考为什么要先搞定项目管理平台Day 2 的学习内容正式从本地代码走向团队协作。昨天还在折腾 Flutter SDK 和 OpenHarmony 环境的时候我就意识到一个问题Flutter 工程结构复杂、依赖链长再加上 Flutter 对 OpenHarmony 的适配分支本身就处于快速迭代期如果没有一个顺手的管理平台代码很容易变成一团乱麻——改了什么不知道、哪里出了问题回溯不了、多人协作时更是灾难。所以 DAY 2 的核心任务很明确打通 AtomGit 这个项目管理平台把 Flutter for OpenHarmony 的工程接入进去顺便把项目管理的整套工作流搭建起来。为什么选 AtomGit一句话总结它是国内可以直接访问、体验接近 GitHub 的代码托管平台而且 Push 代码时不用操心网络问题。对于 OpenHarmony 开发这种动不动要拉大仓库、同步上游源码的场景平台的可访问性和稳定性是第一位的。先说说这天的学习目标了解 AtomGit 平台的核心能力代码托管、Issue 管理、Pull Request、WebIDE 等创建适配 OpenHarmony 的 Flutter 工程并成功推到远端配置项目基础信息建立分支管理和协作规范掌握本地 Git 工作流与平台功能的配合方式整个过程走下来有一个很深的体会项目管理平台不是装个软件、建个仓库就完事了。真正高效的项目管理是把工具的机制和团队的习惯融合在一起。这篇笔记会把 DAY 2 的实操过程和思考完整记录下来包括踩过的坑和最后稳定下来的工作流模式。适合谁来参考准备在 OpenHarmony 上跑 Flutter、需要团队协作或长期维护项目的开发者以及想知道 AtomGit 到底怎么用的同学。如果你是打算一个人单干、纯研究性质的项目平台也照样能用只是你可以跳过部分团队协作配置。2. AtomGit 核心能力与选型分析2.1 AtomGit 能做什么和 GitHub/Gitee 比有什么不一样AtomGit 是国内开源的代码托管平台由开放原子开源基金会牵头建设和 OpenHarmony 本身就是同一生态体系。实际操作下来它在以下几个方面和 GitHub / Gitee 的体验做了取舍首先速度真的快。无论是 HTTPS 克隆还是推送AtomGit 在国内网络环境下都很顺畅。我在这一天里反复 clone、push 了无数次没有一次因为网络中断而重试——这对于拉取 OpenHarmony 相关大仓库的场景来说体验提升是实打实的。GitHub 动辄连接超时Gitee 高峰期偶尔也会卡AtomGit 目前的表现非常稳定。其次功能完整度不输主流平台。AtomGit 提供了仓库管理、Issue 系统、Pull Request、里程碑、Wiki、WebIDE、CI/CD 等一套完整的项目管理能力。和 GitHub 的腾飞工作流相比AtomGit 的 MRMerge Request即合并请求机制完全够用。权限体系也做得比较细支持私有仓库、团队分组、分支保护规则这类功能。再者和 OpenHarmony 生态强相关。AtomGit 本身就是开源领域的基础设施项目之一国内不少开源项目都托管在上面。如果做 OpenHarmony 相关的开发把代码放在 AtomGit从生态归属感和社区协作角度看都比较自然。对比一下三个平台的场景差异对比维度AtomGitGitHubGitee国内访问速度非常流畅不稳定较好但高峰拥堵私有仓库免费免费(有限额)免费MR/PR 流程支持支持支持OpenHarmony 相关项目较多且集中分散部分CI 能力支持强大支持社区生态快速成长中全球最大国内成熟2.2 学习场景下的平台选择思路我们得想清楚一个问题DAY 2 选择 AtomGit到底是为了什么目的在学习场景下代码托管平台承担的角色不仅是“备份代码”更要作为学习和项目的记录载体。我在实际使用中发现AtomGit 很适合这种用途Issue 可以当作学习笔记的追踪工具比如我需要完成“Flutter 侧与 OpenHarmony 侧的双向通信 Demo”就建一个 Issue把需求、参考链接、截止时间全部放进去让学习任务化。PR/MR 流程可以帮助理解开源协作模式哪怕是个人项目我也建议走分支开发 MR 合并的流程提前养成专业习惯。里程碑功能可以做学习阶段规划把 Day 1 到 Day 30 的学习任务挂到里程碑下每周看一下进度。所以选择 AtomGit 不只是“用个平台存代码”而是要在上面长出一个比较规范的项目管理体系。这一天的学习后半段我明显感觉到代码还是那个代码但当项目有了结构化的管理方式后整个学习节奏和心理状态都变了——每天该做什么、做了什么、遇到什么问题一眼就能看清。2.3 平台账号准备与仓库规划动手操作之前先做简单准备AtomGit 支持通过手机号注册也支持扫码登录整体流程不到五分钟就能搞定。注册后建议顺手完善个人主页信息包括头像、个人简介、常用技能标签这在后续参与开源协作时会让对方更快了解你的背景。仓库规划很关键。我当时把仓库分成了三类学习仓库存放每天的练习代码、笔记、Demo对应 DAY 2 里创建的 Flutter for OpenHarmony 工程工具仓库存放自己封装的一些辅助脚本、环境配置模板团队/协作仓库多人参与的正式项目DAY 2 只需要建立第一个——学习仓库。仓库命名建议清晰但不要太长我用的名称是flutter_oh_day2_demo一眼能看出用途和阶段。如果未来要做成系列也可以考虑一个总仓库 子目录的方式。3. 创建仓库与本地 Flutter 工程初始化3.1 AtomGit 仓库创建的关键参数在 AtomGit 上新建仓库主要会遇到几个配置项仓库名称、描述、可见性公开/私有、初始化选项是否添加 README、.gitignore、License。我个人的建议是名称尽量用项目语义比如flutter_oh_sample不要用test、aaa这类无意义名字描述写清楚技术栈和用途比如 “Flutter application adapted for OpenHarmony, showcasing basic interaction”可见性学习阶段可以公开方便以后在简历里展示但如果涉及个人敏感配置或公司业务果断选私有初始化选项建议勾选 README 和 .gitignoreAtomGit 会根据仓库语言推荐对应的模板这里有一个点要注意如果勾选了初始化 README那么远端仓库会有一次初始提交。第一次 push 本地代码前需要先拉取合并否则会提示远端有更新。我在这次操作时就是先让 AtomGit 生成了 README 和 .gitignore然后本地执行git pull origin master --allow-unrelated-histories合并掉两段不相关的提交历史。3.2 本地 Flutter 工程初始化细节Flutter for OpenHarmony 工程的初始化方式和标准的 Flutter 工程略有不同。如果你是使用 OpenHarmony 的 Flutter SDK 分支例如从 Gitee 上 openharmony 相关组织拉取的 flutter 代码仓需要用对应的 flutter 命令来创建项目而不是直接用官方的 flutter。整个初始化流程如下把 OpenHarmony 适配版的 Flutter SDK 路径配置好确保命令flutter --version输出的是适配版本执行flutter create生成新工程例如flutter create --org com.example --platforms ohos flutter_oh_demo注意--platforms参数OpenHarmony 适配版的 Flutter SDK 通常支持ohos这个平台标识。如果你的 SDK 版本不支持该参数可以直接创建后用 DevEco Studio 打开再手动补充 ohos 目录的工程配置。创建出来的工程包含标准的 Flutter 目录结构lib、pubspec.yaml 等同时会有 OpenHarmony 侧的相关配置目录。这块和传统 Android/iOS 工程最大的区别是OpenHarmony 侧的工程文件主要供 DevEco Studio 使用。有一个经验值得在这里说出来创建工程时最好把包名和 org 想清楚后边改了很麻烦。OpenHarmony 的 HAP 包名和应用标识跟 Android 的 applicationId 还不是一回事一旦签了字、生了成再改会涉及签名配置和配置文件的联动修改特别浪费时间。初始化完成后先在本地跑一次flutter build hap --debug具体命令取决于你使用的 Flutter SDK 版本和插件确认工程能正常构建再初始化 Git 提交。好的做法是“本地全绿才推远端”避免把无法构建的半成品推到远端给协作者添乱。3.3 第一批提交应该包含什么第一次提交建议把以下内容纳入版本管理工程主体代码lib 目录下的 Dart 代码、ohos 目录下的 OpenHarmony 工程配置pubspec.yaml这是 Flutter 项目的依赖清单必须提交README.md写清楚项目的用途、环境要求、怎么构建、怎么跑.gitignore排除构建产物build 目录、.hvigor 缓存目录、.idea 目录等.gitignore这块容易踩坑标准 Dart/Flutter 的 gitignore 模板有时候不覆盖 OpenHarmony 构建产生的目录。我实际使用后发现至少需要额外加上这些# OpenHarmony build outputs **/ohos/.hvigor/ **/ohos/build/ **/ohos/.cxx/ **/ohos/.clangd/ **/ohos/oh_modules/如果不排除掉这些目录build 一次之后 Git 状态会搅成一团仓库大小也失真。这块在 Flutter 官方模板里是没有的属于 OpenHarmony 适配工程的实际经验自行补充即可。再有一点pubspec.lock要不要提交对于 Flutter 应用项目答案是提交。应用项目需要锁定依赖版本保证构建可复现只有库项目通常不提交pubspec.lock因为要允许下游灵活解析依赖版本。这个规则很多刚开始用 Flutter 的同学容易搞混。4. 本地 Git 初始化与首次推送实操4.1 完整的 Git 配置过程假设中央仓库已经建好本地工程也已经创建完毕接下来把两者连接起来。我在实际操作中按下面这个顺序执行以仓库地址示例为准实际操作时替换为你自己的地址cd flutter_oh_demo git init git add . git commit -m chore: initial commit for Flutter OpenHarmony demo git remote add origin https://atomgit.com/yourname/flutter_oh_demo.git git fetch origin git merge origin/master --allow-unrelated-histories --no-edit git push -u origin master这个顺序里fetch和merge两步的前提是你在创建仓库时勾选了“初始化 README”。如果你的仓库是空仓库没有做任何初始化那可以直接git push -u origin master不需要合并操作。说一下为什么我额外走了fetch merge而不是直接push --forceforce push 会把远端初始化的 README 覆盖掉虽然第二次 push 体验更顺滑但这种习惯不好——如果当时远端已经有协作者的提交一个--force就能把别人的代码全冲掉。宁可多敲两行命令也别养成强推的习惯。4.2 Push 后立刻要做的三件事首次推送成功后我建议不要急着去写功能代码先把仓库打磨好第一件完善 README。很多人的 README 就一行标题其实这是很亏的。一个合格的 README 至少要写清楚这个项目是干什么的一句话说清楚核心价值环境依赖Flutter SDK 版本、OpenHarmony 版本、DevEco Studio 版本如何构建和运行命令行 IDE 两种方式项目结构说明简单列一下目录含义已知问题或 Roadmap第二件设置分支保护。在 AtomGit 的仓库设置 → 分支设置里把 master 设成保护分支要求合并请求merge request必须经过审核才能合入。即使是个人项目这一步也能帮你养成规范习惯后面多人协作时直接受益。具体设置项看平台版本一般有“允许合并方式和保护分支”的选项。第三件建立项目和标签体系。创建好里程碑给计划中的功能建好 Issue把接下来要做的 Demo 任务全部可视化。这一天的计划我是这么拆的Issue 1完成 Flutter OpenHarmony 工程构建验证Issue 2实现 Dart 调用 OpenHarmony 系统能力获取设备信息Issue 3实现 OpenHarmony 侧通过事件通道向 Flutter 侧传递数据Issue 4整理项目 README 与开发文档每个 Issue 关联到一个里程碑“DAY 2 ~ DAY 5基础开发能力”这样整体节奏很清楚。4.3 开发分支策略的初步选择“分支策略”听起来很高级其实说白了就是确定几件事长期存在的分支有哪些、新功能从哪个分支出、合并到哪个分支、出问题怎么回滚。DAY 2 阶段的项目规模很小不需要上 Git Flow 那种重量级流程用最简单的主干开发 短分支模式就够了master主分支保持可发布状态受保护feature/*功能分支比如feature/basic-ui、feature/device-infofix/*修复分支比如fix/build-hvigor-cache操作上一般流程是这样git checkout master git pull origin master git checkout -b feature/device-info # ... 开发、提交 ... git push -u origin feature/device-info然后在 AtomGit 网页端发起 Merge RequestMerge 到 master。整个过程工具链比较自然不需要额外装插件。5. 使用 WebIDE 与平台集成功能提高效率5.1 WebIDE浏览和快速修改的利器AtomGit 提供了基于 Web 的 IDE在仓库页面就可以直接打开。这个功能特别适合以下场景你只是想快速浏览代码不想把整个仓库 clone 到本地你出差在外手头没有开发环境但想临时改一行注释或文档Code Review 时觉得某个文件有问题直接在线改完再提交我在 DAY 2 测试 WebIDE 时发现它支持语法高亮、文件树、Git 面板提交、推送、分支切换前端体验已经比较接近桌面编辑器了。对于 Dart 代码还有基本的语法提示。不过说实话WebIDE 对于大型 Flutter 工程还是不适合做完整开发——因为无法在本机跑模拟器、无法调试。5.2 Release 管理与下载中心实战提交代码之后可以把当前版本打一个 tag 发一个 Release。AtomGit 会生成下载链接这样团队成员不需要 clone 整个仓库也能在页面上下载对应版本的源码 zip 包。Release 也有助于回溯问题。比如某一天代码改崩了你只看 Git log 很难定位到底是哪个版本开始出问题但如果有 Release 体系每个版本对应一份归档配合提交记录就可以快速 diff 出问题所在。这个习惯建议从 Day 1 就开始养成不要等出了问题才想起打标签。5.3 Issues Pull Request 联动的日常复盘DAY 2 比较有收获的一个环节是把 AtomGit 的 Issue 和 MR 跑通了一条闭环流程。以“实现设备信息获取”为例在 Issues 里新建 Issue写清楚需求背景和验收标准本地新建feature/device-info分支开发调试提交代码并推送远端在 AtomGit 上创建 Merge Request并在描述里关联对应 Issue合并后平台上自动将 Issue 标记为已完成这套机制最大的价值是“上下文持续存在”。两周后回来看这个 MR能清楚知道当时为什么要这么写、解决了什么问题、和哪个 Issue 相关。对 OpenHarmony 这种还在快速演进的技术栈来说回溯能力尤其重要——有些问题现在能跑但升级 SDK 后可能就崩了那时候翻历史记录就知道该从哪里查起。6. 团队协作流程和权限管理的进阶配置6.1 添加成员与团队分组如果你不是单机开发趁项目还小就把团队结构建好。在 AtomGit 上有两种组织方式个人仓库直接邀请成员或者是创建组织再统一管理仓库。实际建议只要超过两个人就建组织Group。组织的好处是可以按项目分组管理仓库成员权限统一管控比如Owner完全权限管理成员、仓库设置、计费信息Admin管理项目配置但不能改组织设置Developer常规开发权限推分支、提 MRReporter只读权限浏览、下载代码按这个模型学习阶段你是 Owner如果导师或同学要参与给 Developer 权限就够了不用把仓库钥匙全交出去。6.2 分支保护规则和数据安全分支保护不是摆设尤其在共享仓库中。我建议至少对 master 分支开启以下规则禁止直接 Push必须走 MR 合并合并前要求流水线通过如果有 CI合并前要求至少一名成员评审有一个常被忽略的点保护分支也要考虑 MR 合入后的推送方式。AtomGit 支持“合并但不删除源分支”和“合并后自动删除源分支”。我建议勾选自动删除后将不再保留习惯养成后远端分支列表始终干干净净。再补充一个安全建议嵌入在代码里的敏感信息API Key、签名密码、内网地址不要以明文形式提交到仓库。一旦提交到历史里即便后面删除文件Git 历史里仍然可以翻到。如果已经失误提交除了清理历史还要考虑轮换相关密钥。AtomGit 的网页端设置有仓库 Secrets 之类功能的话尽量用平台提供的变量管理方式保存敏感值不要写在代码里。6.3 仓库规范文档化把约定变成准绳团队协作时除了代码本身还需要一套约定的文档把这个节奏稳定下来。我在 AtomGit 的项目 Wiki 里记录了以下内容Git 分支命名规范feature/功能名、fix/问题名、docs/文档名Commit Message 格式采用 Conventional Commits 风格比如feat: add device info channel、fix: resolve build error on OpenHarmony合并请求模板要求描述变更目的、测试方式、影响范围代码风格规范比如 Dart 统一使用 flutter_lints 默认规则这些“软”的东西早期建立比团队变大以后再推行要容易得多。等习惯了这套流程去参与开源项目也会无缝衔接——因为主流社区都是同一套玩法。7. 实际体验中的问题排查与心得7.1 首次合并历史冲突的处理第一次 push 就碰到远端 README 与本地提交历史不关联的问题。由于 AtomGit 初始化时生成了 README产生了一次提交本地 git init 后的仓库则是另一套毫无关联的提交历史直接git push会被拒。具体的处理命令前面已经写过了git fetch origin git merge origin/master --allow-unrelated-histories --no-edit git push -u origin master--allow-unrelated-histories这个参数允许合并两个没有共同祖先的提交历史。如果项目一直在同一仓库演进一般用不到但首次接入远端时很常见。7.2 误提交构建产物到仓库在把 OpenHarmony 构建产物ohos/build、.hvigor误提交之后的处理办法是先修改.gitignore然后从 Git 索引中移除这些文件git rm -r --cached ohos/build ohos/.hvigor git add . git commit -m chore: remove build outputs from version control git push origin master从缓存移除后再提交远端仓库就会彻底删掉这些文件。该命令影响面广操作前先git status确认一下文件列表不要出现把源码目录当构建产物删除的误操作。7.3 克隆远程仓库速度慢时的对策有些 OpenHarmony 相关依赖仓库体量不小克隆慢可能不只是网络问题。可以这样组合应对只克隆需要的分支git clone -b master --single-branch repo-url使用--depth 1做浅克隆只拉最新一次提交需要完整历史时再--unshallow如果仓库内包含子模块记得git submodule update --init --recursive但在 AtomGit 上操作起来整体速度是要好于 GitHub 的至少我测下来这一天的 pull/push 都非常快。如果你发现某个 repo 特别慢先看是不是仓库本身塞了大量二进制资产。7.4 协作时不规范提交记录的处理团队协作一段时间后commit 记录会变得五花八门。有的信息是 “fix”有的是 “update”根本看不出来干了什么。要规范化办法是让 MR 合入时使用 squash 合并把功能分支上的所有提交压缩成一个提交再合入 master。这样主干历史非常干净每个功能只有一个 commit。命令行的变基操作也很有用。在本地分支上把零零碎碎的提交整合好再推送git rebase -i HEAD~5或者只是修改最近一次 commit 信息git commit --amend不过 amend 和 rebase 都是在改动历史如果分支已经被别人拉取过不要随便改写否则会让协作者一头雾水。这条经验不只是 AtomGit 通用是所有 Git 协作的通用准则。7.5 我的几条实际操作心得第一项目初期就要写好 README 和规范文档。不要等代码写完了再补。早期的文档帮我们理清思路也方便后来加入的伙伴快速理解项目。第二推送代码前先在本地跑一次 build。Flutter 工程编译问题如果不提前发现推到 CI 上只会浪费更多时间。OpenHarmony 的构建比较吃资源我一般先跑 debug 编译快速验证再跑 release。第三每次 MR 关联 Issue。这个习惯后来帮我省了很多事。有一次开发中遇到 OpenHarmony 上 Flutter 页面偶现黑屏我直接通过关联的 Issue 追溯到前一天的代码改动半小时就锁定了疑似问题这种事在正式团队里可以让你少加很多班。第四多看平台更新。AtomGit 本身功能迭代也很快偶尔逛一下官方文档和更新日志会发现一些新特性可以提升效率。8. 后续学习中继续深入的方向DAY 2 的核心已经完成项目上了 AtomGit 平台本地和远端工作流打通基础的项目管理规范也开始运转起来了。后续还有几个比较明确的方向会在此基础上继续展开接入自动构建流水线利用平台 CI 能力在每次推送后自动跑 Flutter analyze 和 build并在 MR 页面直接看到检查结果。这块等 DAY 3 或 DAY 4 可以重点突破。单元测试与自动化测试的接入Flutter 侧的 unit test 和 widget test 相对成熟可以放进 CI 中为每次 MR 提供质量门槛。版本发布流程的固化结合 Release 功能把构建产物HAP 包和版本说明一并归档。多端工程结构的梳理Flutter for OpenHarmony 的工程里既有 Dart 代码又有 OpenHarmony 代码两者如何组织、目录如何隔离也需要在后续实践里持续打磨。最后分享一个 DAY 2 我特别深的感觉工具本身不会让项目变好但好的工具流会让每一次代码变更都变得可追溯、可讨论、可回滚。OpenHarmony 生态还在快速演进把项目放在一个稳定可控的管理平台上等于给学习过程加了一份保险——哪怕是深夜把代码改崩了也知道身后还有一份完整的历史记录等着你捞自己一把。