1. 项目概述1.1 核心需求解析先说结论这是一个用 HarmonyOS 6HarmonyOS NEXT 的后续版本开发新闻类客户端通过网络请求调用第三方新闻数据接口把数据解析后渲染到界面上的完整项目。这里的关键词是第三方接口——不是自己写后端而是直接对接外部现成的数据源。做新闻 APP 最核心的两件事一是数据从哪来二是数据怎么展示。很多人一开始会纠结要不要自己搭后端、自己爬数据实际上对于学习项目、个人作品、或者中小型应用来说接第三方接口是最快的路子。你只需要关注客户端侧的请求封装、数据解析、页面渲染不需要维护服务器、不需要处理反爬、不需要考虑数据清洗相当于把最重的活外包出去自己专心做用户体验。这个项目适合谁两类人一类是刚接触 HarmonyOS 开发想练手网络请求和数据绑定的新手另一类是已经会用 ArkTS 写基础页面但没完整跑通过请求-解析-渲染全流程的开发者。通过这个项目你能把网络层、数据层、UI层彻底打通后面再做任何需要联网的应用天气、股票、资讯、电商套路都是一样的。1.2 为什么选第三方接口而不是自建后端我在实际开发中反复比较过这两条路直接说结论学习阶段和中小型项目第三方接口是绝对的最优解。自然后端意味着你要处理一系列和客户端无关的问题服务器部署、数据库设计、接口鉴权、日志监控、域名备案、带宽成本。这些内容单独拎出来每一个都是一门课会把你的精力从如何用 HarmonyOS 做新闻 APP拉扯到如何维护一个后端服务最后两头都学不精。第三方接口的数据是现成的格式通常是标准 JSON你只需要发一个 GET 请求拿到 JSON 字符串解析成 TypeScript 对象绑定到列表组件四个步骤没有中间商赚差价。而且大部分新闻接口都免费开放、无需鉴权或只需要简单的 Key非常适合快速验证想法。当然第三方接口也有坑数据格式可能不是你想要的字段命名不规范接口偶尔不稳定还有访问频率限制。这些我在后面第 4 章会专门讲怎么应对。2. 前置准备与技术选型2.1 HarmonyOS 6 开发环境搭建HarmonyOS 6 的开发工具是 DevEco Studio目前已经迭代到比较稳定的版本。安装过程注意几点从华为开发者官网下载最新版 DevEco Studio不要用第三方渠道的破解版或旧版本坑太多。安装时勾选 HarmonyOS SDK 组件默认会装好配套的 SDK、模拟器镜像和命令行工具。首次启动需要登录华为开发者账号这个是免费的用于签名和后续真机调试。如果电脑配置一般建议关闭模拟器直接用真机调试——HarmonyOS 的模拟器对内存和 GPU 要求不低开起来风扇能起飞。创建工程时选择Empty Ability模板语言选ArkTS这就是目前 HarmonyOS 应用开发的主流方式。项目结构里重点关心两个目录entry/src/main/ets/——放你的业务代码页面、逻辑、组件都在这里entry/src/main/resources/——放字符串、颜色、媒体等资源文件2.2 网络请求库的选择ohos.net.http 还是 axiosHarmonyOS 原生提供了网络请求模块ohos.net.http它封装了底层的 HTTP 能力不需要额外安装依赖开箱即用。我在项目里最后选了它原因很直接原生模块对 HarmonyOS 的 API 版本适配最好不需要引入第三方依赖减少版本冲突问题。你可能在其他项目里用过 axios它在 HarmonyOS 上也有对应移植版本比如ohos/axios封装得确实更好用支持拦截器、请求取消、并发控制。但它的本质也是对原生模块的二次封装多一层封装就多一分维护成本。对当前这个新闻 APP 的场景——单次 GET 请求、没有并发、没有复杂的认证——原生ohos.net.http完全够用。下面是我封装网络请求的代码直接抄作业// services/HttpService.ets import http from ohos.net.http; export class HttpService { static get(url: string): Promisestring { return new Promise((resolve, reject) { const httpRequest http.createHttp(); const request httpRequest.request(url, { method: http.RequestMethod.GET, connectTimeout: 10000, readTimeout: 10000 }); request.then((response) { if (response.responseCode 200) { const result typeof response.result string ? response.result : JSON.stringify(response.result); resolve(result); } else { reject(new Error(HTTP error: ${response.responseCode})); } httpRequest.destroy(); }).catch((err) { reject(err); httpRequest.destroy(); }); }); } }这段代码做了几件基础但重要的事设置了 10 秒的连接超时和读取超时避免接口假死导致应用卡住请求结束后调用destroy()释放资源防止内存泄漏将响应统一转为字符串返回方便上层做 JSON.parse。2.3 新闻接口推荐与选型对比调用第三方接口前先得选一个靠谱的数据源。市面上常见的免费新闻接口有好几个风格差异挺大的。我把主流方案整理成对比表格接口来源请求方式数据格式是否需要Key稳定性适合场景聚合数据-新闻头条GETJSON需要高正式项目、多分类场景天行数据-新闻GETJSON需要高分类丰富、更新及时GitHub 开源接口GETJSON通常不需要一般学习练手、本地调试自建 Mock 服务GETJSON不需要最高离线开发、UI 先行我实际用的是天行数据tianapi.com的新闻接口注册后每个接口有赠送的免费调用次数通常每天 100 次对开发调试足够。它的返回格式很典型{ code: 200, msg: success, data: [ { title: 标题内容, content: 正文内容, source: 来源媒体, ctime: 发布时间, picUrl: 图片地址, url: 详情链接 } ] }字段不多不少正好覆盖新闻列表需要的所有信息。特别是picUrl很多免费接口不提供图片字段导致列表页只能干巴巴地显示文字。如果你是新手我强烈建议先用 Mock 数据把整个流程打通再换真实接口。这样能减少变量快速定位问题是出在网络层、解析层还是 UI 层。3. 核心实现请求、解析与渲染全流程3.1 项目结构设计写代码之前先想清楚目录结构。好的结构能让你后期加功能时不用大改我是一个目了然的分层方案entry/src/main/ets/ ├── pages/ │ └── Index.ets // 首页新闻列表 ├── services/ │ └── HttpService.ets // 网络请求封装 ├── models/ │ └── NewsModel.ets // 新闻实体类 └── utils/ └── CacheUtil.ets // 缓存工具可选核心思路是分层页面只负责 UI 展示不关心数据怎么来的服务层只负责网络请求不关心数据怎么用模型层只定义数据结构不掺任何逻辑。这种划分在工程里叫单一职责原则规模小的时候看不出价值但当你需要换接口、加分类、做缓存时就会发现少改了很多代码。3.2 定义新闻数据模型拿到接口返回的 JSON 后第一步是定义对应的 TypeScript 类。ArkTS 的类定义和标准 TypeScript 略有不同建议用可选的普通类型避免遇到空值直接崩溃// models/NewsModel.ets export class NewsModel { title: string; content: string; source: string; ctime: string; picUrl: string; url: string; constructor() { this.title ; this.content ; this.source ; this.ctime ; this.picUrl ; this.url ; } static fromJson(json: object): NewsModel { const model new NewsModel(); const data json as Recordstring, Object; model.title (data[title] as string) ?? ; model.content (data[content] as string) ?? ; model.source (data[source] as string) ?? ; model.ctime (data[ctime] as string) ?? ; model.picUrl (data[picUrl] as string) ?? ; model.url (data[url] as string) ?? ; return model; } }注意我用了?? 兜底而不是直接强制转换。第三方接口的字段偶尔会有null或者缺失如果不做兜底处理页面强解绑时可能非法值导致渲染异常。这个小习惯能帮你省掉后面不少崩溃排查。3.3 新闻列表页面实现页面层用 ArkUI 的声明式语法搭建核心组件是ListForEach。List是滚动列表容器ForEach遍历数据生成子项。下面是首页的完整实现// pages/Index.ets import { HttpService } from ../services/HttpService; import { NewsModel } from ../models/NewsModel; Entry Component struct Index { State newsList: NewsModel[] []; State isLoading: boolean true; State errorMessage: string ; aboutToAppear() { this.fetchNews(); } async fetchNews() { try { const url https://api.tianapi.com/txapi/guonei/?key你的KEY; const result await HttpService.get(url); const json JSON.parse(result) as Recordstring, Object; const dataArray json[data] as ArrayObject; this.newsList dataArray.map((item) NewsModel.fromJson(item)); this.isLoading false; } catch (err) { this.errorMessage (err as Error).message; this.isLoading false; } } build() { Column() { if (this.isLoading) { LoadingProgress() .width(80) .height(80) .color(#1E90FF) } else if (this.errorMessage.length 0) { Text(加载失败 this.errorMessage) .fontSize(16) .textAlign(TextAlign.Center) .margin(20) Button(重试) .onClick(() { this.isLoading true; this.errorMessage ; this.fetchNews(); }) } else { List({ space: 12 }) { ForEach(this.newsList, (item: NewsModel) { ListItem() { this.NewsCard(item) } }, (item: NewsModel) item.url) } .layoutWeight(1) .width(100%) } } .width(100%) .height(100%) .padding(12) } Builder NewsCard(item: NewsModel) { Row({ space: 12 }) { Image(item.picUrl) .width(100) .height(75) .borderRadius(8) .objectFit(ImageFit.Cover) .backgroundColor(#EEEEEE) Column({ space: 6 }) { Text(item.title) .fontSize(17) .fontWeight(FontWeight.Medium) .maxLines(2) .textOverflow({ overflow: TextOverflow.Ellipsis }) Row({ space: 8 }) { Text(item.source) .fontSize(12) .fontColor(#999999) Text(item.ctime) .fontSize(12) .fontColor(#CCCCCC) } } .layoutWeight(1) .alignItems(HorizontalAlign.Start) } .width(100%) .padding(12) .backgroundColor(Color.White) .borderRadius(12) } }这段代码把加载中-加载失败-加载成功三种状态都处理了。很多新手只写成功状态一旦接口超时或者 Key 过期页面就白屏体验极差。加一个失败重试的按钮在调试阶段尤其好用能省掉反复重启应用的时间。State装饰器是 ArkUI 数据响应式系统的核心它会让变量变化时自动刷新绑定的 UI。newsList一旦被赋值页面上的列表就会自动重新渲染不需要手动调用setState()之类的方法这就是声明式 UI 的便利之处。3.4 网络配置与权限申请容易踩坑HarmonyOS 的网络请求不是开箱就能用的还有一个关键步骤在配置文件里声明网络权限。打开entry/src/main/module.json5在module节点下添加{ module: { // ...其他配置 requestPermissions: [ { name: ohos.permission.INTERNET } ] } }很多新手在这个地方坑一整天代码明明没问题但请求一直报错日志显示 permission denied。原因就是忘了加权限声明。另外如果你要访问的是 HTTP 明文地址不是 HTTPS还需要在entry/src/main/resources/base/profile/network_config.json里配置网络安全策略{ network-security-config: { base-config: { cleartext-traffic-permitted: true } } }这是 HarmonyOS 的网络安全机制默认禁止明文流量和 Android 的cleartextTrafficPermitted类似。我建议尽量选 HTTPS 接口一是更安全二是省去这个配置。4. 常见问题与排查技巧4.1 跨域问题不只是浏览器才有一听到跨域很多人的第一反应是这不是网页才有的东西吗实际上 HarmonyOS 应用同样存在类似的限制。如果你请求的第三方接口配置了白名单只允许特定来源访问你在模拟器或真机上访问时就会收到 403 或者 CORS 相关错误。这个问题的排查路径是先用浏览器直接访问接口地址看是否正常返回 JSON。再用命令行工具 curl 请求添加和 App 相同的请求头。如果浏览器和 curl 都正常只有 App 报错优先怀疑接口的防盗链配置。解决方式主要有两种加请求头内的Referer和User-Agent伪装请求来源或者换一个不限制来源的接口。我在项目里就在HttpService里加了通用请求头const request httpRequest.request(url, { method: http.RequestMethod.GET, header: { Content-Type: application/json, User-Agent: Mozilla/5.0 (Linux; Android 10) AppleWebKit/537.36, }, connectTimeout: 10000, readTimeout: 10000 });实测下来大部分免费接口加上这两条请求头后都能正常通行。4.2 数据解析类型不匹配第三方接口的字段类型经常变今天返回的是字符串明天就变成数字甚至直接缺字段。ArkTS 对类型比较严格我遇到过一个问题新闻接口的ctime字段在某个时间段返回了null我的代码里直接用as string转换结果页面渲染时报Cannot read property length of undefined。这种问题防不胜防最好的策略是全面使用我在 3.2 节里的兜底写法。每个字段都判空再赋值可能有人觉得啰嗦但调试一次类型异常的时间成本远高于多写几行守卫代码。记住一句话从第三方接口拿到的数据永远不值得信任。如果 JSON 结构变化太大还可以用一个技巧快速定位用JSON.stringify把原始返回打印到控制台先肉眼看一眼再写解析逻辑不要对着文档猜结构。4.3 页面滚动卡顿与图片内存占用新闻列表通常有大量图片如果用Image组件直接加载高清图滚动时会出现明显的卡顿严重时直接 OOM 崩溃。HarmonyOS 官方推荐配合Image的onLoad回调做图片裁剪或者使用占位图渐进式加载。我采取的策略有两条接口返回的picUrl在拼 URL 时加上裁剪参数比如?imageView2/0/w/200请求小图而不是原图。列表加载时先用LoadingProgress占位图片加载完再替换。ArkUI 的Image组件自带内存缓存对同一 URL 重复加载时会命中缓存所以不用担心多次滑动反复请求的问题。4.4 接口频率限制触发 429免费接口都会限制调用频率天行数据是每天 100 次调试的时候一不小心就刷完了。遇到 429 响应时界面会显示加载失败如果你没有错误状态处理用户看到的就是一个空白页。我的建议是加一层简单缓存首次加载成功后把 JSON 字符串存到本地首选项Preferences后续如果接口调用失败直接读取缓存展示。这样即使频率超限应用也不至于完全不可用。代码大致如下// utils/CacheUtil.ets import preferences from ohos.data.preferences; export class CacheUtil { static async put(context: Context, key: string, value: string) { const store await preferences.getPreferences(context, news_cache); await store.put(key, value); await store.flush(); } static async get(context: Context, key: string): Promisestring | null { const store await preferences.getPreferences(context, news_cache); const value await store.get(key, ); return value ? null : value as string; } }在fetchNews里加入逻辑接口失败时尝试读缓存读不到再抛异常。这一步对用户体感的提升非常明显。5. 进阶优化从能跑到好用5.1 下拉刷新与分页加载新闻 APP 最基本的手势操作就是下拉刷新和上拉加载更多。HarmonyOS 的List组件为刷新提供了兼容方案在List外层包一个Refresh容器。Refresh({ refreshing: this.isRefreshing, onRefresh: () this.loadMore() }) { List({ space: 12 }) { // 列表内容 } }分页加载的核心是控制当前页码每页返回固定条数。天行接口支持num和page参数你可以在接口 URL 上拼接页码。当用户滚动到底部时触发onReachEnd回调加载下一页并追加到newsList尾部。注意要防止重复请求加一个isLoadingMore布尔值做并发锁。5.2 新闻详情页跳转列表页只是个入口真正的体验在详情页。点击一条新闻用路由跳转到 WebView 页面加载全文链接Button() { // 卡片内容 } .onClick(() { router.pushUrl({ url: pages/DetailPage, params: { newsUrl: item.url, newsTitle: item.title } }); })详情页可以简单直接嵌套一个Web组件加载 URLWeb({ src: this.newsUrl, controller: this.controller })需要注意第三方接口返回的url有些是站外链接页面质量参差不齐。如果你想做更完整的新闻 APP可以在详情页自己渲染content字段而不是跳转网页。但那样要处理富文本排版工作量会翻倍看你的最终目标取舍。5.3 关于Spring Boot 对外提供接口应该放在哪里最近很多人在讨论Spring Boot 服务给第三方/客户端提供的接口到底是放在单独服务里还是放在对应业务模块里这个话题和本文项目虽然不是直接关系但它背后的问题很相似——接口提供方和消费方如何解耦。如果你的后端是单体 Spring Boot 应用对外接口完全可以和内部接口放在同一个服务通过独立的Controller和统一的/api/open/前缀区分。只有并发压力极大、或者需要独立部署弹性扩容时才值得拆成独立微服务。做新闻数据接口这种场景自己写一个 Spring Boot 的RestController返回固定 JSON其实就是自建 Mock 服务的加强版——数据可控、格式可控、不受第三方限制只要你的服务器能撑住流量。对齐到 HarmonyOS 客户端选择第三方接口还是自建后端本质上就是权衡开发成本和可控性。我个人的经验是先用第三方验证产品量起来了再自建后端不要一上来就搞大架构。5.4 性能与包体积优化实测下来HarmonyOS 应用的基础模板包体积已经不小如果再引入大体积依赖编译和安装都会变慢。优化方向图片直接加载缩略图减少运行时内存。HttpService使用单例模式避免重复创建连接。首页数据预加载第一屏图片懒加载。按需引入组件不要全量加载 SDK 模块。这些都是老生常谈但在实际项目里见效最直接的还是第一点控制图片体积。6. 实操过程与避坑速查表6.1 完整落地流程回顾给你梳理一遍从零到一的完整步骤照着做就能跑通注册天行数据账号申请新闻接口的 Key。用浏览器测试接口确认返回 JSON 结构。DevEco Studio 创建 Empty Ability 工程语言选 ArkTS。添加ohos.permission.INTERNET权限。新建models/NewsModel.ets按接口字段定义模型和fromJson。新建services/HttpService.ets封装 GET 请求。改造pages/Index.ets实现列表渲染、加载状态、失败重试。真机运行抓日志调试。加分项加入下拉刷新、缓存和详情页跳转。这个流程在 HarmonyOS 5、6 上完全通用API 版本兼容性很好核心模块的 API 没有大改动。6.2 常见问题速查表现象原因解决办法请求报 permission denied未声明网络权限在 module.json5 加 requestPermissions请求 HTTP 地址失败默认禁止明文流量配置 network_config 允许明文返回 403接口有防盗链添加 User-Agent / Referer 请求头JSON 解析报错字段缺失或类型变化fromJson 里做兜底赋值列表白屏未做错误状态处理加 loading / error / retry 三态滚动卡顿图片原图过大请求缩略图 占位图频繁加载失败接口频率超限加本地缓存兜底模拟器请求正常、真机失败代理或证书问题真机连同一网络关闭代理6.3 真机调试经验分享模拟器毕竟是模拟器很多网络问题和它无关但你也能遇到。我的习惯是网络相关的功能一律真机调试UI 布局再用模拟器看效果。HarmonyOS 真机调试的步骤手机开启开发者模式连接电脑DevEco 自动识别设备点击 Run 即可部署。签名方面自动签名已经帮你处理了不需要额外配置。真机调试时注意代理问题如果你的电脑开了全局代理手机会因为同一个 Wi-Fi 网络也走了代理导致请求超时。这时候症状很明显——电脑上浏览器一切正常模拟器正常唯独真机请求卡住。关掉代理、或者让手机走蜂窝流量测试几秒钟就能定位问题。再分享一个日志技巧HarmonyOS 的console.info输出在 DevEco 的 Log 面板里你可以用HiLog的 tag 区分模块。我在HttpService里加了响应日志console.info([HttpService] URL: ${url}); console.info([HttpService] Response: ${result});调试完后建议删掉或者用if (process.env.NODE_ENV development)包一层避免把敏感信息打到生产日志里。7. 项目扩展思路做完基础版之后这个项目的天花板还很高。给你几个我实验中觉得有意思的方向多分类频道天行数据有国内、国际、社会、娱乐、体育等多个新闻分类每一项对应不同的接口 URL。你可以用Tab组件做顶部标签栏每切换一个分类就请求对应接口一个新闻 APP 的核心框架就完整了。搜索功能用搜索框 搜索接口实现关键词检索新闻。注意做防抖用户停止输入 500ms 后再发起请求。个性化推送基于用户阅读历史做简单推荐这一步只会用到本地数据不需要服务端介入。用 Preferences 记录已读新闻的 URL再次加载时标记已读状态。WebSocket 实时推送进阶如果你自建后端可以引入 WebSocket在服务端推送突发新闻客户端即时弹窗提醒。这一步能显著提升 App 的活着的感觉但复杂度也上升一个台阶。我个人体会是学习 HarmonyOS 开发最忌讳只看文档不写代码。新闻 APP 这个项目麻雀虽小五脏俱全网络层、数据层、UI 层、异常处理全都有涉及而且成果可见——每次打开 App 都能看到实时新闻正反馈很强。把这个跑通之后你再看 HarmonyOS 的文档很多概念就融会贯通了。动手写别犹豫。