接口文档生成了，却把内部方法也暴露：HarmonyOS 7 arktsdoc 怎么守住对外 API 边界

不才难以繁此生

121人浏览 · 2026-10-11 02:30:28

不才难以繁此生 · 2026-10-11 02:30:28 发布

接口文档生成了，却把内部方法也暴露：HarmonyOS 7 arktsdoc 怎么守住对外 API 边界

DevEco Studio 26.0 的命令行工具加入 arktsdoc，IDE 也支持按工程、模块、目录或文件生成 ArkTSDoc。真正危险的不是文档生成失败，而是生成得太成功：只要变量、方法、接口或类被 export，它就可能进入文档。内部实验接口一旦随文档交付，读者就会把它当成稳定契约。目录排除只能缩小扫描范围，不能代替符号级 API 设计。

源码导出、ArkTSDoc 生成与公开 API 门禁

先按这张现场排查表行动

1. 公共入口显式白名单导出。

2. demo、generated、ohosTest 目录单独排除。

3. 生成前清理输出目录。

4. 保存提交 SHA 与模块集合。

5. 新增删除签名变化都要评审。

复现与取证起点

准备 public、internal、experimental 三个目录，各放一个 exported class；再让 public/index.ets 误导出 experimental。分别按整个工程和指定模块生成文档，记录 sourcePath、exportName、module、since、stability、excludedByPath 和 rendered。修正导出后再次生成，将两次文档符号集合做差，确认删除项是否属于有意的破坏性变更。

复现记录至少包含设备形态、窗口尺寸、字体或显示配置、关键状态、操作路径和截图时间。只保存一张最终截图，无法解释问题是在布局、状态恢复还是输入阶段发生。

三个判断点

ArkTSDoc 以 export 为符号入口

未 export 的对象不生成；反过来，export 不只是编译可见性，也会影响对外文档。公共入口文件应明确列举允许暴露的符号。

这里必须同时保存输入条件、设备或窗口形态、触发动作和最终可观察状态。工具报告用于缩小范围，任务是否可完成仍由同一条用户路径的读回结果决定。

目录排除解决扫描范围，不解决错误 re-export

26.0 支持多模块和 Ant 风格排除路径。它适合排除 demo、generated、ohosTest，却拦不住 public/index.ets 主动 re-export 的内部类。

文档差异应成为 API 评审证据

每次生成后保存符号清单，与基线比较新增、删除和签名变化。仅比较 HTML 文件数量，会漏掉同文件内的接口变化。

方案对比

方式	优点	风险
靠开发者记住哪些不能 export	零工具成本	团队协作下容易失守
只排除 internal 目录	配置简单	挡不住错误 re-export
公开入口白名单 + ArkTSDoc 符号快照差异	可审计	需要维护基线

我的选择：采用第三种，让源码导出边界和文档交付边界使用同一份可检查清单。

案例一：实验接口被 public/index.ets 顺手导出

目录位于 experimental，但公共入口 re-export 后仍会出现。删除 re-export，或将实验契约放入单独模块并明确 stability；不能只在注释里写“内部使用”。

修复后用原始条件再次执行完整任务，并保留修改前后同一节点的可见性、可操作性和状态对照。

案例二：多模块生成时旧模块文档没有清理

输出目录残留导致已删除接口仍可搜索。生成前清理目标目录，保存模块清单与提交 SHA，再校验 HTML 索引和符号快照来自同一轮任务。

第二个案例选择不同形态或不同状态，用来证明方案不是对单一截图的局部修补。

工程侧模型

type ApiSymbol={module:string;name:string;stability:'stable'|'experimental'}
function publicSymbols(all:ApiSymbol[]){return all.filter(x=>x.stability==='stable').map(x=>x.module+'#'+x.name).sort()}

模型只表达稳定的决策边界，界面组件、窗口事件和工具结果通过适配器接入，避免把设备差异散落在每个页面。

可独立执行的状态断言

function diff(oldSet,newSet){const a=new Set(oldSet),b=new Set(newSet);return{added:newSet.filter(x=>!a.has(x)),removed:oldSet.filter(x=>!b.has(x))}}
const r=diff(['entry#RecipeApi'],['entry#RecipeApi','entry#DebugApi']);if(r.added[0]!=='entry#DebugApi'||r.removed.length)throw new Error('API 快照差异错误');

这些断言验证纯状态、几何或边界计算，不代表 API 26 工程已经编译，也不代表真机、模拟器特定镜像或应用市场审核已经通过。

封装与复用

封装 PublicApiManifest，从公共入口提取模块、符号、签名、since 和稳定性；生成文档后对比快照，未审批新增或删除直接阻断交付。

复用层输出决策和证据，不强行统一所有页面视觉。每个页面仍可保留自身信息层级，但必须满足相同的任务可达性与状态连续标准。

验证边界

本文依据当前华为官方文档整理能力与约束，纯状态模型已在本机执行。当前本机 HarmonyOS SDK 为 API 24，且没有连接 HDC 设备，因此 API 26 编译、目标模拟器镜像行为、折叠真机连续性和平台审核结果仍属于待验证项。完成目标环境验证后，应把版本、设备、构建身份和读回结果补入证据包。