鸿蒙公交出行应用模板实战笔记：ArkTS 模块组织与云端实践记录

今天在鸿蒙开发实践中心读了“公交出行应用模板”案例，到 GitCode 给它的代码仓 HarmonyOS-APPTMPL-bustravel 点了 Star；随后从成长中心出发，经 AI Agent 实践中心进入 AI DevSpace 体验版，在 AI Shell 里问了一次运行中 ECS 实例突然无法远程连接的排查方法。把两件事的要点合在一起记下来。本文是当日的阅读与提问记录，案例部分以案例详情页与仓库 README 为依据，未声称已完成真机联调。

一、案例是什么：公交出行应用模板

这是一个基于 HarmonyOS 生态的公交出行应用模板，目标是让开发者基于它快速定制公交类应用，也可以只挑其中的组件复用。模板覆盖四个模块：首页、出行、乘车码、我的。

• 首页：可查看公交资讯与公告、最近新闻热点、开卡与乘车码演示入口，以及禁携物品、寻找遗失物品等入口。
• 出行：站点和线路页面位于 feature/RouteDesign，可查看附近站点、车辆距离和时间，点击线路打开地图页面；路径规划支持按起点和终点查询推荐路线。
• 乘车码：展示开卡与乘车码演示页面，未开通时可见电子卡开通入口和使用说明。
• 我的：登录后可管理钱包和订单记录，还可以设置个人信息、联系客服。

适合人群是已具备 ArkTS/ArkUI 基础、希望基于公交出行模板定制业务的开发者，难度标注为进阶，阅读与体验预计 120 分钟。

二、工程长什么样：先看三份清单再动手

读模板最容易犯的错误是直接翻页面代码。我今天的做法是先看工程清单，再看业务代码，顺序是：

1. build-profile.json5：构建清单声明 8 个模块，其中 HAR 7 个、HSP 0 个。先确认默认产品、构建目标与 SDK 要求，本工程兼容 5.0.0(12)、目标 5.0.0(12)。
2. AppScope/app.json5：应用身份与 bundleName 所在，工程示例为 gjyy.1.xxxxxx，照抄到自己工程里会撞身份，改包名要从这里改。
3. entry/src/main/module.json5：入口模块 entry、Ability 为 EntryAbility，权限声明也在模块里：ohos.permission.INTERNET、ohos.permission.LOCATION、ohos.permission.APPROXIMATELY_LOCATION。

目录上，entry 是入口，feature 承载业务特性，common 放网络请求封装 AxiosHttpRequest、细化业务组件与常量。模板把路线相关的能力拆成两个可复用组件，放在工程根目录的 components 下：

• route_detail：公交路线详情组件，展示公交线路详情。
• route_search：公交路线搜索组件，展示公交路线搜索结果。

只想用组件、不想整包抄模板时，参考这两个组件的指导链接即可。模板还保留华为账号、地图等服务的端侧接入示例，真实服务的配置条件与验证步骤见案例的“运行案例”一节，不应把演示页面的本地数据当成已接通的服务。

三、两条跑起来的路：云端和本地

案例给出云端与本地两条路，按自己手头条件选一条，不要两条混着配。

云端路线：从在线开发工作区或案例中心进入，创建工作区并导入案例；先核对平台当前可选 ROM 的 API、ABI 与费用配额，再让 AI 按 build-profile.json5 编译默认产品的 entry HAP；产物无误后创建并连接云手机，安装并启动 EntryAbility，依次浏览首页资讯、路线与乘车码入口。结束后保存工程，停止云手机与不再使用的工作区。云手机的 ROM 滚动提供最新 5 至 6 个版本，不能把它当成 ARM64 真机。

本地路线：安装 DevEco Studio 5.1.0 Release 及以上、准备 HarmonyOS 5.1.0 Release SDK 及以上；把仓库 main 分支交给 AI 核对工程，执行 ohpm install --all，确认模块与依赖；再编译 entry HAP，在兼容模拟器或自己的鸿蒙真机上安装运行。真机需要自己的有效调试签名，模拟器按其调试安装机制安装。遇到构建失败，先看首个有效错误与 SDK、构建命令和依赖日志，不要盲目升级依赖。

四、一个值得动手的小改造：新增一条公交演示资讯

案例自带一个可选二次开发任务：新增一条公交演示资讯。读完之后，我认为这个任务最值得写下来的不是“加一行数据”，而是一个容易踩的坑：

• 入口在 feature/frontpage/src/main/ets/mock/MockData.ets，newsData 的 id 必须唯一。
• 当前 NewsDetail 固定读取 newsDetailPiece[0]，也就是说，只在列表里加一条资讯是不够的，必须同时设计列表 id 到详情的映射，以及无匹配数据时的回退。
• 改完要回归三件事：新增资讯能打开对应详情；缺失时有可理解的回退；原路线搜索、返回与空结果不受影响。

这个坑的通用教训是：做演示数据改造时，先找到“详情取数据”的那行代码，再决定列表要怎么改；只改列表、不改详情读取逻辑，改完大概率是点开详情却看到别人的内容。

五、同一天在 AI Shell 里问的另一件事：运行中 ECS 无法远程连接

今天在 AI DevSpace 体验版的 AI Shell 里，我问的是：“我有一台运行中的 ECS 实例，突然无法远程连接了，请帮我一步步排查。”AI Shell 给出的排查顺序很值得直接拿来当检查清单：

1. 先在控制台确认底座：实例是否处于运行中，有无欠费或到期；安全组入方向是否放行远程端口，Linux 是 22，Windows 是 3389，来源地址是否被限定；有问题时直接在安全组放行入方向测试。
2. 用 VNC 登录兜底：控制台的远程登录（VNC）不依赖公网网络与安全组，先确认系统本身是否正常，登录进去再查 sshd、RDP 服务与本地防火墙规则；检查时不要反复重启实例。
3. 进系统分层定位：确认 sshd 或服务状态，如 systemctl status sshd、ss -tlnp；查系统资源，free -h 看内存、df -h 看磁盘占用，内存或磁盘满了同样会连不上；看日志 journalctl -u sshd、dmesg；再按需排查公网带宽、自建 DNS 与自建防火墙。
4. 用命令复验：Windows 用 ping、telnet、Test-NetConnection -ComputerName <IP> -Port <3389>；Linux 用 ping、nc -vz <IP> 22；关键端口放行要在安全组规则和操作系统防火墙两侧一致。

我个人的体会是：连不上先分层——控制台、安全组、VNC、系统服务、资源、网络——按顺序排除，不要一上来就重启或重装；提问时把现象、已做步骤和期望输出写清楚，AI 给出的步骤才够具体。

六、今天的三点收获

1. 读模板先读清单：build-profile.json5、AppScope/app.json5、entry 模块声明三份文件，决定了工程能不能跑、身份对不对、权限够不够，比先读页面代码重要。
2. 改造前先找到详情的取数方式：演示数据、列表 id、详情映射、缺失回退要一起设计，验收时把“回归原功能”写进检查项。
3. 云上排障讲究顺序：ECS 连不上时，控制台、安全组、VNC、系统服务、资源、网络逐层收窄；AI Shell 的价值在于把这套顺序一次讲全，照着走不容易漏项。

后续我打算按案例的云端路线实际编译一次公交模板，并把新增资讯的改造真正跑通，到时再写一篇对照记录。