🔥个人主页：杨利杰YJlio
❄️个人专栏：《Windows 疑难杂症与工单复盘案例库》 《Sysinternals实战教程》
《WINDOWS教程》 《Windows PowerShell 实战》 《IOS插件分析测试》
《超简单：用Python让Excel飞起来》
🌟让复杂的事情更简单，让重复的工作自动化
HarmonyOS 7.0学习笔记58：AI能力接入前的接口与隐私边界
文章目录
- HarmonyOS 7.0学习笔记58：AI能力接入前的接口与隐私边界
- 一、接入前先把问题拆清楚
- 二、先画出数据边界，再决定传什么
- 三、接口契约要写清输入、输出和失败
- 四、用最小本地例子验证输入和输出
- 五、把成功、失败和取消分成不同结果
- 六、按工程版本核验能力和配置
- 七、用可复现记录替代模糊结论
- 八、接入前检查清单
- 参考资料
大家好，我是杨利杰 YJlio。
这篇学习笔记讨论一个容易被“先把接口调通”掩盖的问题：当应用准备接入 AI 文本处理能力时，哪些数据会离开设备，调用失败或用户取消时页面如何反馈，以及怎样证明功能确实按预期工作。
我会先把边界和接口约定清楚，再从一个不依赖外部服务的最小例子开始。**本文没有提供真实 AI 服务地址、密钥配置或设备运行记录，因此不会把概念示例写成已接入、已编译或已验证的功能。**具体 SDK/API 和服务调用方式需要按自己的工程版本与服务文档核对。
一、接入前先把问题拆清楚
面对“接入 AI”这个目标，我会先拆成四个可检查步骤：准备输入、决定页面如何呈现、处理用户操作、观察结果。这样做的好处是，即使暂时没有服务端接口，也能先把界面状态、输入边界和验证方法约定好。
在这个阶段，我会先回答几个具体问题：
- 用户输入的是什么，是否可能包含个人信息或工作数据？
- 页面准备把哪些内容交给外部服务，哪些只在本地处理？
- 正常返回、请求失败和用户取消时，界面分别呈现什么状态？
- 我要观察什么，才能区分“按钮被点击”和“结果真的返回”？
这些问题看起来不如直接写调用代码快，却能避免把隐私、网络、界面状态和服务结果混成一个难以排查的步骤。
二、先画出数据边界，再决定传什么
我会把输入数据分成三类：用户原始输入、应用在本地进行的必要处理、确实需要发送到外部服务的最小内容。每一项都要有用途，不能因为“接口字段可以放”就默认上传。
实践时，可以按下面的顺序检查：
- 必要性：完成当前功能是否必须使用这段数据？
- 最小化：是否能删去姓名、账号、联系方式、工单编号等无关信息？
- 可见性：用户是否清楚哪些内容会发送到服务端？
- 留存与日志：调试日志、错误截图和示例数据是否会意外保存原文？
- 失败路径：网络不可用、服务拒绝或用户取消时，是否能停止后续处理？
如果一个输入只用于展示格式或验证页面，我会先用本地示例完成练习，不把真实个人信息或企业内容塞进测试请求。真实数据是否可以外发，应由项目的数据规则和服务约定决定，不能凭“只是做学习”自行推断。
三、接口契约要写清输入、输出和失败
接口不一定一开始就要连接真实服务，但字段的职责可以先写清楚。对于文本处理场景，我至少会约定输入文本、用户可见的结果、失败反馈，以及取消后页面如何收尾。需要发送的字段应和功能目标对应，不需要的内容就不进入请求。
这里的“请求卡片”和“响应卡片”只是概念示意，并非某个真实云服务的协议。**原稿没有给出服务商、接口地址、鉴权方式或 JSON 字段，因此本文不虚构这些细节。**准备接入时，我会先从服务文档确认字段、认证、超时、错误码、数据保存政策，再映射到自己的业务模型。
可以先用表格记录接口约定：
| 项目 | 需要确认的内容 | 当前练习边界 |
|---|---|---|
| 输入 | 哪些文本会被处理，是否需要裁剪或脱敏 | 使用非敏感示例 |
| 输出 | 页面如何呈现处理结果 | 先定义展示位置和空结果状态 |
| 失败 | 网络、鉴权、服务端错误如何区分 | 暂不假设具体错误码 |
| 取消 | 用户离开或主动取消时如何停止后续更新 | 记录取消后的预期状态 |
| 留存 | 请求与结果是否会进入日志或历史记录 | 以实际项目规则核验 |
四、用最小本地例子验证输入和输出
在外部依赖尚未确定时，我会先验证页面输入、函数处理和结果展示之间的数据流。原稿提供的示例只做字符串空值判断和展示，不发起网络请求：
functiondescribeResult(input:string):string{returninput.trim().length===0?'暂无内容':`已读取：${input}`}// 在页面事件中调用，并显示返回结果；观察输入与页面输出是否一致。这个函数只适合说明本地输入与输出的关系。它没有调用 AI，也没有证明网络、权限或持久化流程已经完成。放到实际 ArkUI 页面前，还要根据当前页面状态和工程所用 SDK 检查类型、导入和调用位置。
我会先只保留输入、触发操作和结果展示三个部分；等它们的状态关系清楚后，再加入异步过程或外部服务。最小例子的价值是缩小问题范围，不是代替服务集成测试。
五、把成功、失败和取消分成不同结果
接入外部能力后，一次操作不只有“成功”与“失败”。至少还要分清用户取消、网络中断、服务响应异常和重复触发等情况。不同结果应该回到明确的页面状态，而不是都显示成同一句“处理失败”。
我会把检查顺序分成两层：先观察请求操作有没有被触发，再核对返回结果如何更新页面。失败后是否允许重试、取消后是否还会收到旧结果、重复点击是否会并发触发，都要结合实际实现逐项验证。原稿没有提供具体网络 API，所以这里仅列出检查思路，不给出未经核实的调用代码。
六、按工程版本核验能力和配置
HarmonyOS 工具链、SDK/API 版本、工程模板和模块依赖都会影响具体代码写法。遇到类型或 API 不存在时，我会先记录 DevEco Studio 版本、工程实际选择的 SDK/API、模块依赖与导入路径，再查看当前官方文档和工程模板中的可用形式。
图片中的版本块没有标注具体版本，表示这是核验流程图，不代表本文已经验证某一个 SDK/API 组合。没有实测的兼容性结论就保留为空，不用“支持”“可运行”等词替代验证。
七、用可复现记录替代模糊结论
如果后续在自己的工程中运行，我会记录环境、输入类型、操作步骤和实际观察结果。涉及用户数据的截图应先脱敏；日志只保留定位问题需要的信息，不附带完整敏感文本。
推荐记录这些字段：
| 记录项 | 示例说明 |
|---|---|
| 工具链与 SDK/API | 填写本机实际版本，不使用猜测值 |
| 运行目标 | 记录模拟器或真机型号、系统版本和窗口尺寸 |
| 输入类型 | 使用脱敏类别描述，不抄录真实敏感内容 |
| 操作步骤 | 按顺序写清输入、点击、等待或取消动作 |
| 预期与实际 | 分开记录看到的结果和原先预期 |
| 错误信息 | 保留完整诊断文本，同时去除密钥和隐私内容 |
如果页面没有变化，我会从事件触发、状态更新、界面绑定和结果展示逐层检查；如果编译失败，则先看完整诊断和当前工程配置。这样留下的记录才便于自己复现，也方便别人判断问题来自代码还是环境。
八、接入前检查清单
在真正调用 AI 服务之前，我会逐项确认：
- 输入字段是否必要，是否做了最小化和脱敏；
- 用户是否知道数据会发往哪里，并符合项目的数据规则；
- 请求、响应、失败、取消和重复触发是否有清楚的处理约定；
- 服务端接口与当前工程 SDK/API 是否已按正式文档核验；
- 日志和截图是否避免暴露原始个人信息、令牌或密钥；
- 测试结论是否来自真实运行记录，而不是概念图或预期结果。
这篇笔记的重点不是“怎样快速接上一个 AI 接口”，而是先把数据要去哪里、失败后如何收尾、怎样判断结果说清楚。只有服务约定、隐私规则和工程版本都核验后，示例才适合进入真实集成。
参考资料
- 《HarmonyOS 7.0学习笔记：AI能力接入前的接口与隐私边界》原始学习笔记。本文保留其练习性质，未把计划阶段内容写成真实运行结果。
- HarmonyOS 官方开发文档：华为开发者联盟文档中心。涉及具体 SDK/API 时，以工程当前版本对应文档为准。
说明：本文中的图片为流程示意图，不是 DevEco Studio、模拟器或真机实测截图。示例代码仅展示本地字符串处理思路；真实 AI 服务、版本适配和运行结果尚未提供，发布前请以自己的工程核验记录补充。
返回顶部
