HarmonyOS 应用开发之日志体系与调试：Logger 工具类与 hilog 实践详解

日志体系与调试Logger 工具类与 hilog 实践一、引言短视频应用是典型的问题潜伏型工程播放器状态机流转、窗口断点变化、沉浸式切换、多设备差异化分支任何一个环节出错现场往往一闪而过。如果没有一套统一、分级、可过滤的日志体系排查问题只能靠加打印 → 复现 → 删打印的原始循环效率极低。multi-short-video 工程在公共模块中封装了统一的 Logger 工具类所有特性模块与产品模块复用同一套日志出口配合 hilog 的级别与隐私过滤能力形成从打日志到看日志的完整闭环。本文先讲 hilog 的能力底座再拆解工程Logger.ets的封装设计随后以窗口管理、播放器、入口 Ability 的真实调用为例最后给出日志查看、过滤与调试的实战技巧。二、hilog 基础与日志级别HarmonyOS 的日志系统由kit.PerformanceAnalysisKit提供 hilog 接口。其核心概念有三个domain业务域0~0xFFFF 的十六进制整数用于按域过滤、tag标签字符串标识日志来源、format格式化模板与参数列表。hilog 提供五个级别自低到高为级别接口语义典型场景DEBUGhilog.debug调试细节数据源内容、断点值INFOhilog.info关键流程窗口创建、全屏设置成功WARNhilog.warn可恢复异常缓冲不足、重试前提示ERRORhilog.error功能失败播放失败、窗口接口报错FATALhilog.fatal致命错误数据损坏、不可恢复级别不仅是语义约定还决定输出与过滤行为系统日志缓冲区按级别分层DevEco Studio 与命令行均可按级别过滤。工程中大部分业务日志使用 INFO 与 ERROR 两级调试过程数据用 DEBUG避免刷屏。三、Logger 工具类封装直接在业务代码中调用hilog.debug(domain, tag, format, args)存在三个问题domain/tag 到处重复、格式串不统一、后续想加时间戳或脱敏要改动所有调用点。工程在common/multishortvideobase/src/main/ets/utils/Logger.ets中做了统一封装完整实现如下// d:\HarmonyOS\WorkSpace\multi-short-video\common\multishortvideobase\src\main\ets\utils\Logger.ets import { hilog } from kit.PerformanceAnalysisKit; /** * Common logger utility class. */ class Logger { private domain: number; private prefix: string; private format: string %{public}s, %{public}s; public constructor(prefix: string) { this.prefix prefix; this.domain 0x0000; } public debug(...args: Object[]): void { hilog.debug(this.domain, this.prefix, this.format, args); } public info(...args: Object[]): void { hilog.info(this.domain, this.prefix, this.format, args); } public warn(...args: Object[]): void { hilog.warn(this.domain, this.prefix, this.format, args); } public error(...args: Object[]): void { hilog.error(this.domain, this.prefix, this.format, args); } } export default new Logger([multishortvideo]);这段封装的设计要点统一 TAG单例以[multishortvideo]为前缀导出全工程日志共享同一标签Log 面板中一条过滤条件即可看全应用日志统一 domain0x0000集中在构造器内避免散落各处统一格式模板%{public}s, %{public}s把两个参数都标记为 public详见第五节脱敏说明调用方只需传内容API 简洁debug/info/warn/error与 hilog 同名学习成本为零。调用方通常再叠加一层模块 TAG前缀例如窗口工具中const TAG WindowUtil然后Logger.error(TAG, ...)这样既能按应用过滤又能按模块定位。四、Logger 在工程中的真实使用工程中 Logger 覆盖了三个典型场景。窗口管理common/multishortvideobase/.../utils/WindowUtil.ets在获取主窗口、注册监听、设置沉浸式的关键节点打日志并统一捕获异步异常setFullScreen(isFullScreen: boolean): void { try { this.mainWindow!.setWindowLayoutFullScreen(isFullScreen) .then(() { Logger.info(TAG, Succeeded in setting full-screen mode.); this.mainWindowInfo.isFullScreen isFullScreen; }) .catch((err: BusinessError) { Logger.error(TAG, Failed to set full-screen mode. Code: ${err.code}, message: ${err.message}); }); } catch (error) { let err error as BusinessError; Logger.error(TAG, setWindowLayoutFullScreen sync error. Code: ${err.code}, message: ${err.message}); } }播放器features/multishortvideoadaptivevideo/.../view/AdaptiveAVPlayer.ets在创建、prepare、play、pause、seek、release 全生命周期打日志异常分支一律带err.code与err.messageavPlayer.on(error, (err: BusinessError) { Logger.error(TAG, Invoke prepare failed, code is ${err.code}, message is ${err.message}); }); Logger.info(TAG, changePortraitVideo immersionInfo ${JSON.stringify(immersionInfo)});入口 Abilityproducts/default/.../defaultability/MultiShortVideoDefaultAbility.ets则暴露了两类用法的对比——工程模板自带的裸hiloghilog.info(DOMAIN, testTag, %{public}s, Ability onCreate)与业务代码采用的LoggerLogger.info(Succeeded in setting the system bar properties.)。裸 hilog 的 tagtestTag与工程的[multishortvideo]不统一过滤时容易遗漏这也是封装 Logger 的初衷之一入口层也应收口到统一日志出口。五、日志脱敏与分级日志中常包含设备信息、业务数据甚至用户输入直接打印存在隐私风险。hilog 的格式化参数支持两种隐私标识%{public}s表示该参数明文输出%{private}s表示脱敏输出真机上显示为{private}。工程 Logger 的默认模板%{public}s, %{public}s把参数统一标记为 public适用于 tag 类内部标识一旦需要记录用户评论、账号等敏感字段应改用显式%{private}s模板或只记录长度、哈希等非敏感派生值。分级方面建议遵循INFO 记流程、ERROR 记失败、DEBUG 记细节正常路径的进入/成功用 INFO异常分支用 ERROR 并携带错误码与消息需要追踪的具体数值如窗口尺寸、断点枚举用 DEBUG。避免用 ERROR 打印可预期的分支如用户取消操作否则 ERROR 级别会失去信噪比真正的问题反被淹没。日志的性能开销同样值得关注。hilog 在调试态会全量输出但发布版应裁剪日志级别建议把Logger.debug级别的输出在 release 包中关闭仅保留 INFO 及以上避免高频日志如播放进度、窗口尺寸回调在线上产生额外 IO 与功耗。工程可在 Logger 封装中增加一个编译期开关如isDebug常量在 hvigor 的 release 构建中注入 false让 debug 调用在构建期被裁剪而不是在运行期做判断——这与 ArkTS 强类型约束下编译期解决的理念一脉相承。另外打印大对象如整个数据源数组会显著放大日志体积建议打印摘要字段长度、首元素、关键状态需要全量时再临时放开。六、日志查看与过滤日志输出后两种主流查看方式DevEco Studio Log 面板真机或模拟器运行后Log 面板按级别 关键字实时过滤可直接按 tag 输入multishortvideo过滤全工程日志再叠加WindowUtil、AdaptiveAVPlayer等模块关键字缩小范围日志默认按时间排序可配合按进程/按域分组。命令行 hilog连接设备后执行hdc shell hilog可用管道与 grep 组合过滤例如hdc shell hilog | findstr multishortvideo适合在自动化脚本或设备端抓取长时日志hilog 还支持按 domain 范围hilog -D 0x0000、按级别-L等参数精确裁剪。排查技巧上工程经验是复现一次、抓全三样完整日志确定错误码与堆栈、现场状态窗口尺寸、断点、播放器 state、操作序列用户路径。三者交叉比对通常能把问题收敛到某个Logger.error附近。七、调试技巧断点、ArkTS 调试器与状态面板日志之外DevEco Studio 的调试能力与日志互补断点调试在 ArkTS 源码行号左侧打点运行到断点后查看变量、表达式与调用栈配合条件断点如curIndex 2可在循环或列表场景精准命中。ArkTS 调试器支持单步、步入/步出、求值表达式适合追踪Monitor触发链路与状态变化顺序。状态面板UI Inspector运行中通过 ArkUI Inspector 查看组件树与属性、State/Trace实时值定位状态已变但 UI 未刷新类问题——这类问题日志往往无迹可寻状态面板一锤定音。V2 状态观察对Trace字段在Monitor回调中临时加Logger.debug可确认状态变化是否被监听、监听是否晚于预期。工程中最常见的两类日志看了白看的坑也值得记录其一异步回调里打印的变量在打印前被后续代码修改模板字符串在参数求值时就已展开不受影响但对象引用需注意其二真机日志缓冲被刷掉导致看不到早先日志可适当调高Logger.debug的采样或缩短抓取窗口。八、常见日志问题排查案例把前文理论落到真实问题三个案例最具代表性。案例一播放器反复起播失败。现象是视频页面偶发黑屏AdaptiveAVPlayer的Logger.error记录Invoke prepare failed, code is ...。排查过程先在 Log 面板按multishortvideoAdaptiveAVPlayer过滤确认错误集中在avPlayer.prepare()被调用时播放器仍未进入initialized状态——根源是快速滑动列表时同一个播放器实例被并发控制修复方式是保证状态机流转严格串行先 reset 再 prepare并在每次状态变更处补Logger.info记录当前 state让状态顺序有日志可查。案例二窗口断点不刷新。现象是折叠屏展开后布局未切换。日志中onWindowSizeChange与断点获取均无异常输出但widthBp没有变化——进一步在WindowUtil.updateWindowInfo的监听注册处补打日志后确认监听注册发生在setUIContext之前uiContext为 undefined 导致断点取不到。修复调用顺序后问题消失。这个案例说明日志要打在能力调用的边界而不是只打在成功/失败的结果上否则中间态丢失问题无法定位。案例三日志看着像没走。现象是某分支明明执行了Log 面板却搜不到。原因通常是过滤条件过窄domain/tag/级别任一不匹配或真机日志缓冲被新日志刷掉。排查时先放开过滤条件确认日志确实存在再逐步收紧必要时在onWindowStageCreate这类早期入口打Logger.info确认进程生命周期正常。三个案例的共同经验是日志点位的设计比日志量更重要——在状态机的每一次迁移、窗口注册的每一个边界、异常抛出的每一个位置打点才能让问题看见即定位。九、总结与最佳实践日志体系与调试沉淀为五条最佳实践统一出口所有模块复用common/.../utils/Logger.ets的单例统一 domain、tag[multishortvideo]与格式模板Log 面板一条过滤条件看全应用。分级克制INFO 记流程、ERROR 记失败必带err.code/err.message、DEBUG 记细节可用预期的分支不要用 ERROR。敏感字段脱敏默认模板%{public}s用于内部标识用户数据等敏感字段改用%{private}s或只记派生值。模块 TAG 前缀在调用方叠加const TAG WindowUtil之类模块标识实现应用级过滤 模块级定位两级收敛。日志与调试器互补问题不明时优先看日志收敛范围再上断点与状态面板定位状态/UI 不一致问题。