鴻蒙開源第三方組件—日志工具組件Timber_ohos
前言
基于安卓平臺的日志工具組件Timber ( https://github.com/JakeWharton/timber)， 實現鴻蒙的功能化遷移和重構。代碼已經開源到(https://gitee.com/isrc_ohos/timber_ohos)，歡迎各位開發者提出寶貴意見。
背景
Timber_ohos是一個帶有小型可擴展API的日志工具組件，它可以給開發者提供統一的API接口，來記錄不同類型的日志，幫助開發者管理不同類型的log。同時，Timber_ohos是項目開發時的log開關，通過此開關控制log的打印與關閉，從而形成不同的軟件版本。該組件功能豐富且使用簡單高效，可以被廣泛應用于軟件項目開發中。
組件效果展示
1、測試界面。
如圖1所示，這是一個為了測試Timber_ohos功能而簡單構建的UI頁面。點擊“測試”按鈕即可輸出相應的log。
圖1 測試界面UI圖
2、Log打印
Timber類的靜態方法調用如圖2中的(a)圖所示。運行項目后查看HiLog顯示，可以看到實時打印出來的日志，如圖2中的(b)圖所示。
圖2 HiLog日志打印
Sample解析
1、Tree的使用
Timber_ohos將不同的日志操作以樹(Tree)的概念進行表示，種植一種樹就擁有一種日志記錄功能，種植多種樹就擁有多種日志記錄的功能，樹的種類有很多，常見的樹有：DebugTree、RealeseTree、FileTree、CrashReportingTree等，這些樹都是繼承自Tree類。
- DebugTree：對所有的日志進行記錄。
- RealeseTree：只對 warn,error,wtf 信息進行記錄。
- FileTree：在運行時將日志記錄到文件中。
- CrashReportingTree：對應用崩潰時的信息進行記錄。
Timber_ohos中默認已經種植了DebugTree，由于Timber_ohos本身是一個可擴展的框架，因此開發者想得到其他類型的Log日志時，就需要自己實現一個日志記錄類 ，然后種植到Timber_ohos中即可。
2、Sample的實現
Sample部分需要添加日志記錄種類，并負責整體顯示布局的搭建。首先為Timber_ohos組件添加想要的任何Tree子類實例(這里使用的是DebugTree)，然后設置簡單的按鈕監聽器，當按動按鈕時在鴻蒙常規HiLog中出現調試日志。下面將詳細介紹組件的使用方法。
步驟1. 種樹(添加Tree子類實例)。
步驟2. 創建整體的顯示布局。
步驟3. 導入相關類并設置按鈕監聽。
步驟4. 使用Tree實例。
(1)種樹(添加Tree子類實例)
本步驟是在ExampleApp類的onInitialize()方法中實現的。首先需要創建Tree子類實例，然后調用Timber的plant()方法，同時將實例作為plant()方法的參數，這個過程叫做“種樹”。
- Timber.plant(new Timber.DebugTree(0x001f00));
復制(2)創建整體的顯示布局 在XML文件中創建一個DirectionalLayout作為整體顯示布局，寬度和高度都跟隨父控件變化而調整。創建兩個組件，分別是Text組件和Button組件，用于控制組件效果顯示。整體顯示布局如圖1所示。
- <DirectionalLayout
- xmlns:ohos="http://schemas.huawei.com/res/ohos"
- ohos:height="match_parent"
- ohos:width="match_parent"
- ohos:orientation="vertical"
- ohos:padding="32vp"
- ohos:background_element="#ffffff"
- ohos:alignment="horizontal_center">
- <Text //“測試”提示
- ohos:height="match_content"
- ohos:width="match_content"
- ohos:layout_alignment="horizontal_center"
- ohos:text="Timber測試"
- ohos:text_size="35fp"/>
- <Button //控制按鈕
- ohos:id="$+id:btn1"
- ohos:height="match_content"
- ohos:width="match_content"
- ohos:top_margin="35vp"
- ohos:text_size="25fp"
- ohos:background_element="#FF51A8DD"
- ohos:padding="10vp"
- ohos:text="測試"/>
- </DirectionalLayout>
(3)導入顯示布局并設置按鈕監聽
在MainAbilitySlice中，整體顯示布局也需要通過super.setUIContent()方法進行設置，才能生效并成功顯示。然后給按鈕設置點擊事件，當用戶需要使用Tree子類實例時，可通過手指進行點擊。
- super.setUIContent(ResourceTable.Layout_ability_main);//設置整體顯示布局
- findComponentById(ResourceTable.Id_btn1).setClickedListener(new Component.ClickedListener() {
- ...//按鈕的點擊事件
- }
(4)使用Tree實例
當用戶需要打印調試日志的時候，調用Timber的靜態方法，就會在鴻蒙常規HiLog上出現調試日志。調試日志如組件效果展示部分的圖2所示。
- Timber.e ("Timber.e 測試成功！！！");
- Timber.d ("Timber.d 測試成功！！！");
- Timber.i ("Timber.i 測試成功！！！");
- Timber.w ("Timber.w 測試成功！！！");
- Timber.wtf ("Timber.wtf測試成功！！！");
Library解析
Library主要為Timber_ohos組件提供日志輸出的統一接口。以Sample中種植的調試樹(DebugTree)為例，當使用Timber的靜態方法Timber.e時，從MainAbilitySlice到Timber.e打印log的地方可以分為5個步驟，整體調用的流程如圖3所示。
圖3 調用順序圖
下面我們著重介紹樹(Tree類)在Library中的實現，核心算法prepareLog()內部的邏輯結構這兩個方面的內容。
1.樹(Tree)的實現
Tree類是一種概念形式的日志操作，具體可分為(DebugTree、ReleaseTree、FileTree等)。而在Library內部，Tree類也實現了一系列方法，以便于對森林中的各類樹進行增加、刪除、修改等操作。
(1)在Timber_ohos組件中維護一個森林對象(FOREST)。
森林對象由不同類型的日志樹組合而成，并提供對外的接口進行日志的打印。每種類型的樹都可以通過種植操作來把自己添加到森林對象中，或者通過移除操作從森林對象中刪除，從而實現該類型日志記錄的開啟和關閉。
- private static final List<Tree> FOREST = new ArrayList<>();
(2)種樹。
調用plant()方法，把Tree實例添加進FOREST里面 可以種植一棵樹，也可以種植多棵樹。這里以種一棵樹為例。可以看到，樹的種植是在plant()靜態方法的synchronized 同步代碼塊中進行的。具體流程是先將樹對象添加到 FOREST 列表中，然后將日志樹保存到 forestAsArray 數組中(將樹種植到森林中)。
需要注意的是，如果樹為空，則拋出空指針異常的錯誤;如果開發者手動種植靈魂之樹(TREE_OF_SOULS)，Timber_ohos將會拋出非法數據異常。
- public static void plant(@NotNull Tree tree) {
- if (tree == null) {
- throw new NullPointerException("tree == null");
- }
- if (tree == TREE_OF_SOULS) {
- throw new IllegalArgumentException("Cannot plant Timber into itself.");
- }
- synchronized (FOREST) {
- FOREST.add(tree);
- forestAsArray = FOREST.toArray(new Tree[FOREST.size()]);
- }
- }
(3)移除Tree實例
同樣的，樹的移除也是在靜態方法uproot()中的synchronized 同步代碼塊中進行的。如果沒有該樹可以移除，則Timber_ohos組件將拋出一個非法數據異常;反之，Timber_ohos組件將根據移除該樹后的 FOREST列表生成 新的forestAsArray 數組。
- public static void uproot(@NotNull Tree tree) {
- synchronized (FOREST) {
- if (!FOREST.remove(tree)) {
- throw new IllegalArgumentException("Cannot uproot tree which is not planted: " + tree);
- }
- forestAsArray = FOREST.toArray(new Tree[FOREST.size()]);
- }
- }
(4)清除森林里面全部的Tree實例
移除森林里所有的Tree實例，首先使用FOREST的clear()方法清除所有的Tree實例，將會自動生成一個對應的新的Tree數組，而forestAsArray就是這個數組的引用。因此forestAsArray 數組被設置為空數組。
- public static void uprootAll() {
- synchronized (FOREST) {
- FOREST.clear();
- forestAsArray = TREE_ARRAY_EMPTY;
- }
- }
(5) 靈魂之樹(TREE_OF_SOULS)
估計很多同學好奇上述TREE_OF_SOULS。代碼實現中，在這里運用的是經典設計模式中的代理模式，TREE_OF_SOULS 本質上是一個代理對象，森林中所有其他普通的樹對象都是被代理對象，代理對象通過 for 循環來依次調用被代理對象的同名方法，從而實現不同類型的日志記錄，如下所示。
- private static final Tree TREE_OF_SOULS = new Tree() {
- @Override public void v(String message, Object... args) {
- Tree[] forest = forestAsArray;
- for (Tree tree : forest) {
- tree.v(message, args);
- }
- }
2.核心算法( prepareLog)
Timber_ohos組件的日志記錄功能的核心算法在抽象類 Tree 的私有化 prepareLog()方法中，該方法接收四個參數，如圖4所示：
圖4 參數表
prepareLog()中首先判斷了打log的條件，然后將要打印的message信息進行了處理，最后調用了抽象方法log進行日志輸出。總體而言 prepareLog()算法流程如下：
(1)獲取當前線程的 tag。
(2)當正常信息message不為null且信息長度為0時，這時正常信息message為null。
(3)當正常信息message和異常信息t都是 null 時，說明沒有信息可以記錄，方法直接返回。
(4)異常信息t通過getStackTraceString方法轉換為字符串。
(5)正常信息message和可選格式化參數 args 通過formatMessage方法拼裝成一個字符串。
(6)調用抽象方法 log 進行日志記錄，這個方法由Tree的子類來實現。
- private void prepareLog(int priority, Throwable t, String message, Object... args) {
- //獲取當前線程的 tag
- String tag = getTag();
- //當正常信息message不為null且信息長度為0時，這時正常信息message為null
- if (message != null && message.length() == 0) {
- message = null;
- }
- //當正常信息 message 和異常信息 t 都是 null 時，說明沒有信息可以記錄，方法直接返回
- if (message == null) {
- if (t == null) {
- return; // Swallow message if it's null and there's no throwable.
- }
- //異常信息 t 通過 getStackTraceString 方法轉換為字符串
- message = getStackTraceString(t);
- } else {
- if (args != null && args.length > 0) {
- //正常信息 message 和可選格式化參數 args 通過 formatMessage 方法拼裝成一個字符串
- message = formatMessage(message, args);
- }
- if (t != null) {
- message += "\n" + getStackTraceString(t);
- }
- }
- //調用抽象方法 log 進行日志記錄，這個方法由 Tree 的子類來實現
- log(priority, tag, message, t);
- }
