diff --git a/README.md b/README.md index dc370a2..87d00d4 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ 計算版本號的 Gitea Action:依儲存庫現有的 release,推算下一個穩定版或 beta 版本號,並寫出為 Action output 供後續步驟取用。以 Docker 容器執行,容器內由 Node.js 主程式實作。 -> 更新時間:2026/06/30 17:38:51(Asia/Taipei) +> 更新時間:2026/06/30 18:18:13(Asia/Taipei) ## 專案列表 @@ -35,9 +35,9 @@ | [config.normalizeBetaFlag](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L38) | [將 beta 旗標正規化為布林值(僅字面 "true" 為真)。](#confignormalizebetaflag) | | [config.loadConfig](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L101) | [從環境變數載入並驗證執行所需的設定。](#configloadconfig) | | [index.main](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/index.js#L30) | [Action 進入點:依序執行參數檢查、取得舊版本、計算版本號並寫出 output。](#indexmain) | -| [logger.section](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L45) | [輸出帶分隔線的區塊標題,用於在 log 中分隔處理階段。](#loggersection) | -| [logger.info](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L60) | [輸出 `[INF][時間]` 格式的資訊訊息至標準輸出。](#loggerinfo) | -| [logger.error](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L77) | [輸出 `[ERR][時間]` 格式的錯誤訊息至標準錯誤輸出。](#loggererror) | +| [logger.info](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L58) | [輸出 `[階段][INF][時間]` 格式的資訊訊息至標準輸出(階段選填)。](#loggerinfo) | +| [logger.error](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L76) | [輸出 `[階段][ERR][時間]` 格式的錯誤訊息至標準錯誤輸出(階段選填)。](#loggererror) | +| [logger.forStage](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L89) | [建立綁定特定階段的子記錄器,自動為每則訊息帶入階段前綴。](#loggerforstage) | | [output.writeOutput](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/output.js#L16) | [將一行 `name=value` 附加寫入 Action 的輸出檔。](#outputwriteoutput) | | [releases.fetchReleases](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/releases.js#L24) | [以分頁方式取得指定 Gitea repo 的所有 release。](#releasesfetchreleases) | | [version.compareVersionArrays](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L15) | [逐區段比較兩個版本號數值陣列,較短者視為較小。](#versioncompareversionarrays) | @@ -121,34 +121,25 @@ await main({ // → 回傳 '1.2.4' ``` - -### logger.section - -輸出帶標題的區塊段落至標準輸出,標題前後以分隔線包夾,用於在 log 中分隔各處理階段(例如「參數檢查」「取得舊版本」)。此為結構性段落標題,不套用 `[等級][時間]` 前綴。 - -```js -const logger = require('./app/logger'); - -logger.section('參數檢查'); -// 輸出:換行 + 50 個 = + 標題 + 50 個 - -``` - ### logger.info -輸出一般資訊(INF)層級的 log 訊息至標準輸出,格式統一為 `[INF][{台灣時間}]: {訊息}`(時間為 Asia/Taipei,格式 `yyyy/MM/dd HH:mm:ss`),結尾換行。 +輸出一般資訊(INF)層級的 log 訊息至標準輸出,格式統一為 `[{階段}][INF][{台灣時間}]: {訊息}`(時間為 Asia/Taipei,格式 `yyyy/MM/dd HH:mm:ss`),結尾換行。階段(`stage`)為選填,省略時略過 `[{階段}]` 區塊。 ```js const logger = require('./app/logger'); logger.info('NEW_VERSION=1.2.4'); // 輸出:[INF][2026/06/30 17:38:51]: NEW_VERSION=1.2.4 + +logger.info('NEW_VERSION=1.2.4', '計算版本號'); +// 輸出:[計算版本號][INF][2026/06/30 17:38:51]: NEW_VERSION=1.2.4 ``` ### logger.error -輸出錯誤(ERR)層級的 log 訊息至標準錯誤輸出(stderr),格式統一為 `[ERR][{台灣時間}]: {訊息}`。僅負責輸出,不終止行程,是否結束由呼叫端決定。 +輸出錯誤(ERR)層級的 log 訊息至標準錯誤輸出(stderr),格式統一為 `[{階段}][ERR][{台灣時間}]: {訊息}`。階段為選填。僅負責輸出,不終止行程,是否結束由呼叫端決定。 ```js const logger = require('./app/logger'); @@ -157,6 +148,19 @@ logger.error('GITEA_SERVER_URL 未設定'); // stderr 輸出:[ERR][2026/06/30 17:38:51]: GITEA_SERVER_URL 未設定 ``` + +### logger.forStage + +建立綁定特定階段(stage)的子記錄器,回傳 `{ info, error }`;其方法只需傳入 `message`,即會自動在每則訊息開頭帶入 `[{階段}]` 前綴。進入點以此為每個處理階段建立子記錄器,使該階段(含其呼叫的 `fetchReleases` 等模組)輸出的訊息都帶一致的階段前綴。 + +```js +const logger = require('./app/logger'); + +const stageLog = logger.forStage('取得舊版本'); +stageLog.info('使用授權 token 取得 release'); +// 輸出:[取得舊版本][INF][2026/06/30 17:38:51]: 使用授權 token 取得 release +``` + ### output.writeOutput