充篇 9.1：Ktor Logging 深入：Header、Body 脫敏與自定義 Logger)
第九篇我們已經(jīng)知道Logging ↓ 負(fù)責(zé)記錄 HTTP Request / Response最基礎(chǔ)的配置可能只是install(Logging) { logger Logger.DEFAULT level LogLevel.ALL }但正式項目真正需要考慮的遠(yuǎn)不只是“把日志打印出來”而是哪些內(nèi)容應(yīng)該記錄 哪些 Header 絕對不能打印 Request Body 中的 password 怎么辦 Response Body 中的 token 怎么辦 文件上傳為什么不能打印 Body 10MB JSON 要全部打印嗎 Logger.DEFAULT 和 Custom Logger 到底是什么關(guān)系 已經(jīng)用了 Kermit / AppLogger Ktor 日志應(yīng)該怎么接進(jìn)去所以這一篇專門把 Ktor Logging 拆開。當(dāng)前 Ktor 3.5.x 的LoggingConfig提供logger、level、filter()、sanitizeHeader()、bodyFilter、format等配置其中bodyFilter默認(rèn)使用BinaryLogBodyFilter用于避免把二進(jìn)制 Body 當(dāng)普通文本輸出。一、先建立最重要的 Logging 心智模型Ktor Logging 可以拆成三層Logging Plugin ↓ LoggingConfig │ ┌────────────────┼────────────────┐ ↓ ↓ ↓ level sanitizeHeader bodyFilter │ │ Header處理 Body處理 └────────────────┼────────────────┘ ↓ 生成日志內(nèi)容 ↓ Logger / \ ↓ ↓ Logger.DEFAULT Custom Logger ↓ AppLogger / Kermit這里最重要的是LoggingConfig 決定“日志內(nèi)容怎么處理”Logger 決定“處理后的日志往哪里輸出”。不要把這兩件事混在一起。二、Logging Plugin 是什么安裝install(Logging)相當(dāng)于HttpClient ↓ 獲得 HTTP Logging 能力它負(fù)責(zé)觀察Request Response Method URL Headers Body Status它不是你的App 全局日志框架它只是HTTP 網(wǎng)絡(luò)日志的生產(chǎn)者。例如你的項目可能還有業(yè)務(wù)日志 數(shù)據(jù)庫日志 WebSocket 日志 機(jī)器人通信日志 異常日志Ktor Logging 只是其中一個來源。三、LoggingConfig 是什么當(dāng)我們寫install(Logging) { logger Logger.DEFAULT level LogLevel.ALL sanitizeHeader { it HttpHeaders.Authorization } }大括號里的接收者就是LoggingConfig當(dāng)前 3.5.x API 中它主要提供logger level format bodyFilter filter() sanitizeHeader()因此install(Logging) { ... }本質(zhì)就是配置 Logging Plugin 的工作規(guī)則。四、Logger 又是什么Ktor 的Logger非常簡單。核心就是interface Logger { fun log( message: String, ) }所以 Logger 根本不負(fù)責(zé)抓 Request 抓 Response 解析 Header 讀取 Body它主要負(fù)責(zé)Ktor 已經(jīng)生成了一段日志字符串我把它輸出到哪里所以Logging Plugin ↓ 生成 message ↓ Logger.log(message)五、方案 A直接使用 Logger.DEFAULT最簡單install(Logging) { logger Logger.DEFAULT level LogLevel.ALL }流程Request / Response ↓ Logging Plugin ↓ 生成日志 ↓ Logger.DEFAULT ↓ 平臺日志系統(tǒng)Ktor 官方當(dāng)前說明在 JVM 上Logger.DEFAULT使用 SLF4JAndroid 推薦提供slf4j-android。Multiplatform 項目則可以提供自己的 Logger。Android 例如androidMain.dependencies { implementation( org.slf4j:slf4j-android:$slf4jVersion ) }然后install(Logging) { logger Logger.DEFAULT level LogLevel.ALL }六、Ktor 3.5.x 還有 Logger.ANDROID當(dāng)前 API 里還有 JVM/Android 專用Logger.ANDROID它會面向 Android Logcat 輸出并處理 Android 單條日志長度限制如果存在 SLF4J Provider也會使用默認(rèn) Logger。所以 Android-only 項目里也可能看到install(Logging) { logger Logger.ANDROID level LogLevel.ALL }但是對于 KMP 項目如果已經(jīng)有統(tǒng)一Kermit AppLogger后面介紹的 Custom Logger 通常更適合。七、LogLevel 到底控制什么當(dāng)前 Ktor Logging 有NONE INFO HEADERS BODY ALL可以先這樣理解NONE ↓ 完全不記錄 INFO ↓ Request / Response 基礎(chǔ)信息 HEADERS ↓ 基礎(chǔ)信息 Header BODY ↓ 基礎(chǔ)信息 Body ALL ↓ Header Body 完整 HTTP 日志開發(fā)環(huán)境常見level LogLevel.ALL但是正式環(huán)境不建議簡單ALL 什么都不脫敏直接上線。八、為什么 Logging 會帶來安全問題假設(shè)POST /login Authorization: Bearer abc123 Cookie: session987654 { username: tom, password: 123456 }如果level LogLevel.ALL完全不做處理那么Token Cookie Password全部可能進(jìn)入Logcat 文件日志 日志上傳平臺 Crash 日志這就不是調(diào)試問題了而是數(shù)據(jù)安全問題所以 Logging 至少需要兩層考慮Header ↓ sanitizeHeader Body ↓ bodyFilter九、sanitizeHeader 到底是什么例如sanitizeHeader { it HttpHeaders.Authorization }這句話第一次看容易暈。完整展開sanitizeHeader { headerName - headerName HttpHeaders.Authorization }Ktor 相當(dāng)于不斷問“這個 Header Name 需要隱藏嗎”如果Content-Type ↓ false正常打印。如果Authorization ↓ true隱藏它的值。十、這里的 it 是 Header Name不是 Value例如真實 RequestAuthorization: Bearer abc123 Platform: Android Language: zh-CNKtor判斷headerName Authorization ↓ true ↓ 脫敏 headerName Platform ↓ false ↓ 正常輸出最終日志Authorization: *** Platform: Android Language: zh-CN當(dāng)前sanitizeHeader()的簽名本質(zhì)是fun sanitizeHeader( placeholder: String ***, predicate: (String) - Boolean, )所以默認(rèn)占位符就是***十一、sanitizeHeader 不修改真實 Request這個一定要分清楚。真實 RequestAuthorization: Bearer abc123經(jīng)過 Logging真實 HTTP Request ↓ 仍然是 Authorization: Bearer abc123 ↓ 發(fā)送給服務(wù)器同時Logging ↓ Authorization 命中 sanitizeHeader ↓ 日志 Authorization: ***所以sanitizeHeader 只修改“日志展示”不修改真正發(fā)送的 Header。十二、多個敏感 Header 怎么處理例如Authorization Cookie X-Api-Key X-Access-Token可以sanitizeHeader { headerName - headerName HttpHeaders.Authorization || headerName HttpHeaders.Cookie || headerName X-Api-Key || headerName X-Access-Token }我更推薦集中管理private val sensitiveHeaders setOf( HttpHeaders.Authorization, HttpHeaders.Cookie, X-Api-Key, X-Access-Token, )然后sanitizeHeader { headerName - headerName in sensitiveHeaders }這樣以后擴(kuò)展更方便。十三、還可以修改脫敏占位符默認(rèn)***也可以sanitizeHeader( placeholder redacted ) { headerName - headerName HttpHeaders.Authorization }日志Authorization: redacted十四、但 sanitizeHeader 有一個天然限制它只能處理Header不能處理Request Body Response Body例如{ username: tom, password: 123456, accessToken: abcdef }這里password accessToken根本不是 Header。所以sanitizeHeader { it HttpHeaders.Authorization }對它們完全沒有作用。這就是bodyFilter存在的意義。十五、bodyFilter 是什么當(dāng)前 Ktor 3.5.x 的LoggingConfig.bodyFilter類型是LogBodyFilter它可以決定 Body 日志正常記錄 修改以后記錄 只記錄一部分 直接跳過官方 API 明確把隱藏敏感數(shù)據(jù) 截斷過長 Body 修改日志格式列為其使用場景。十六、bodyFilter 不只可以處理 ResponseLogBodyFilter當(dāng)前提供filterRequest(...)和filterResponse(...)也就是說Request Body ↓ 可以處理 Response Body ↓ 也可以處理所以可以形成Request JSON ↓ password 脫敏 Response JSON ↓ token 脫敏十七、CommonLogBodyFilter 又是什么如果 Request 和 Response 使用同一套 Body 處理規(guī)則沒必要分別實現(xiàn)filterRequest filterResponseKtor 提供CommonLogBodyFilter它內(nèi)部的filterAll(...)會同時用于 Request 和 Response。所以Request Body ─┐ ↓ 同一過濾器 ↑ Response Body ┘特別適合JSON統(tǒng)一脫敏 文本統(tǒng)一截斷 二進(jìn)制統(tǒng)一跳過十八、bodyFilter 返回什么核心返回BodyFilterResult當(dāng)前 API 中主要有Content Empty Skip其中BufferContent可以返回修改后的可讀 BodySkip表示這段 Body 不應(yīng)該繼續(xù)打印例如JSON ↓ 處理后 ↓ BufferContent 圖片 ↓ Skip(binary body)十九、Ktor 默認(rèn)其實已經(jīng)幫你過濾二進(jìn)制 Body當(dāng)前bodyFilter默認(rèn)BinaryLogBodyFilter它負(fù)責(zé)過濾二進(jìn)制內(nèi)容。這非常合理。否則image/jpeg application/pdf video/mp4 zip如果直接LogLevel.ALLLogcat 可能看到一大堆JFIF.....沒有任何意義。二十、為什么 Multipart / 文件上傳通常應(yīng)該 Skip例如POST /upload Content-Type: multipart/form-dataBody 中可能包含20MB 圖片 100MB 視頻 PDF ZIP日志真正需要知道的是上傳哪個接口 文件名 Content-Type 文件大小 Status 耗時而不是把 100MB 文件內(nèi)容打印出來所以Multipart Binary ↓ Skip通常更合理。二十一、Body 脫敏的核心流程例如真實 Request{ username: tom, password: 123456, accessToken: abcdef }我們希望日志{ username: tom, password: ***, accessToken: *** }處理過程ByteReadChannel ↓ 讀取日志 Body ↓ String ↓ 解析 JSON ↓ 遍歷字段 ↓ 敏感 Key ↓ 替換 *** ↓ 重新生成 JSON ↓ BufferContent ↓ Logging 輸出二十二、為什么不推薦正則作為最終 JSON 脫敏學(xué)習(xí)階段可能寫json.replace( Regex( (password\s*:\s*)[^]*() ), $1***$2, )簡單 JSON 能工作。但是 JSON 還可能有嵌套對象 數(shù)組 轉(zhuǎn)義字符 字段順序變化 復(fù)雜字符串所以正式項目更推薦String ↓ JsonElement ↓ 遞歸遍歷 ↓ 按 Key 脫敏這正好可以使用前面已經(jīng)學(xué)過的kotlinx.serialization二十三、定義敏感 JSON Key例如private val sensitiveJsonKeys setOf( password, token, accessToken, refreshToken, secret, apiKey, )以后如果還需要phone idCard bankCard只需要繼續(xù)增加。不過哪些字段應(yīng)該完全隱藏、哪些應(yīng)該部分掩碼要根據(jù)實際業(yè)務(wù)和合規(guī)要求設(shè)計。二十四、遞歸脫敏 JsonElement例如private fun sanitizeJsonElement( element: JsonElement, ): JsonElement { return when (element) { is JsonObject - { JsonObject( element.mapValues { entry, - val key entry.key val value entry.value if ( key in sensitiveJsonKeys ) { JsonPrimitive( *** ) } else { sanitizeJsonElement( value ) } } ) } is JsonArray - { JsonArray( element.map( ::sanitizeJsonElement ) ) } else - { element } } }這樣{ user: { name: Tom, password: 123456 }, tokens: { accessToken: abc } }也可以處理成{ user: { name: Tom, password: *** }, tokens: { accessToken: *** } }這比簡單 Regex 穩(wěn)定很多。二十五、封裝 sanitizeJson()private val logJson Json { ignoreUnknownKeys true } private fun sanitizeJson( raw: String, ): String { return runCatching { val element logJson.parseToJsonElement( raw ) sanitizeJsonElement( element ).toString() }.getOrElse { // JSON 解析失敗時 // 不做復(fù)雜處理 raw } }不過這里還有一個安全問題如果JSON 解析失敗直接返回raw可能重新暴露敏感信息。所以正式項目更保守可以選擇getOrElse { [body omitted: invalid json] }我更推薦后者。二十六、大 Body 為什么也應(yīng)該限制假設(shè)GET /huge-data ↓ Response 15MB JSON即使沒有任何敏感字段15MB 全打印仍然很糟糕。會產(chǎn)生巨大 Logcat 日志文件膨脹 CPU 消耗 內(nèi)存壓力 日志平臺流量 真正重要日志被淹沒所以 Body Logging 通常還應(yīng)該有最大長度例如8KB 16KB 32KB根據(jù)項目決定。二十七、一個簡單截斷函數(shù)例如private fun truncateBody( value: String, maxChars: Int, ): String { if ( value.length maxChars ) { return value } return buildString { append( value.take(maxChars) ) append( \n...[truncated] ) } }注意這里控制的是字符數(shù)不是精確網(wǎng)絡(luò)字節(jié)數(shù)對于日志限制通常已經(jīng)夠用。二十八、但是“大 Body”最好在讀取之前就判斷例如Content-Length 100MB如果你的邏輯先全部讀取 100MB ↓ 再截斷成 8KB顯然還是浪費(fèi)資源。所以更好的contentLength 已知且特別大 ↓ 直接 Skip例如 1MB ↓ 不記錄 Body而不是讀取以后再處理。二十九、一個完整 Safe BodyFilter下面把JSON 脫敏 文本截斷 大 Body Skip Binary Skip組合起來。private fun createSafeBodyFilter( json: Json, maxBodyChars: Int 8 * 1024, maxReadableBytes: Long 1024 * 1024, ): LogBodyFilter { return CommonLogBodyFilter { contentLength, contentType, _, body, - // 1. 已知 Body 特別大 if ( contentLength ! null contentLength maxReadableBytes ) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason body too large, byteSize contentLength, ) } // 2. 不知道 Content-Type if (contentType null) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason unknown content type, byteSize contentLength, ) } val isJson contentType.contentSubtype .contains( json, ignoreCase true, ) val isText contentType.contentType .equals( text, ignoreCase true, ) // 3. Binary / Multipart 等直接跳過 if ( !isJson !isText ) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason non-text body, byteSize contentLength, ) } // 4. 讀取日志 Body val raw body .readBuffer() .readString() // 5. JSON 做字段級脫敏 val safe if (isJson) { sanitizeJson( json json, raw raw, ) } else { raw } // 6. 控制日志長度 val truncated truncateBody( value safe, maxChars maxBodyChars, ) // 7. 重新構(gòu)造日志內(nèi)容 val buffer Buffer().apply { writeString( truncated ) } BodyFilterResult .BufferContent( buffer buffer, charset Charsets.UTF_8, ) } }當(dāng)前BodyFilterResult.BufferContent就是接收Buffer Charset把處理后的 Body 提供給 LoggingSkip則表示跳過 Body并可以攜帶 reason 和 byteSize。Buffer.readString()和writeString()則來自當(dāng)前kotlinx-ioAPI。三十、sanitizeJson 完整版本private val sensitiveJsonKeys setOf( password, token, accessToken, refreshToken, secret, apiKey, ) private fun sanitizeJson( json: Json, raw: String, ): String { return runCatching { val element json.parseToJsonElement( raw ) sanitizeJsonElement( element ).toString() }.getOrElse { [body omitted: invalid json] } } private fun sanitizeJsonElement( element: JsonElement, ): JsonElement { return when (element) { is JsonObject - { JsonObject( element.mapValues { entry, - if ( entry.key in sensitiveJsonKeys ) { JsonPrimitive( *** ) } else { sanitizeJsonElement( entry.value ) } } ) } is JsonArray - { JsonArray( element.map { sanitizeJsonElement( it ) } ) } else - { element } } }三十一、為什么 BodyFilter 不應(yīng)該修改真正的業(yè)務(wù) Body這一點和sanitizeHeader一樣。這里我們做的是日志副本 ↓ 脫敏 ↓ Logger真正網(wǎng)絡(luò) Requestpassword 123456如果服務(wù)器確實需要這個字段那么真正發(fā)送仍然是 123456日志password ***所以網(wǎng)絡(luò) Body 和 日志 Body一定分開理解。三十二、不要把 BodyFilter 當(dāng) Request 加密器例如業(yè)務(wù)要求請求 Body ↓ AES 加密 ↓ 發(fā)送服務(wù)器這不能靠Logging bodyFilter來完成。因為 bodyFilter 的職責(zé)是Body ↓ 怎么記錄到日志而真正修改發(fā)送 BodyRequest Body ↓ 加密 ↓ 發(fā)送應(yīng)該進(jìn)入后面要講的Custom Client Plugin transformRequestBody SendingRequest這是完全不同的生命周期。三十三、現(xiàn)在理解 Custom Logger如果項目已經(jīng)有Kermit或者自己的AppLogger我們不希望業(yè)務(wù)日志 ↓ Kermit HTTP 日志 ↓ 另外一套 Logger而希望所有日志 ↓ 統(tǒng)一 AppLogger于是logger object : Logger { override fun log( message: String, ) { AppLogger.d( tag HTTP, message message, ) } }三十四、Custom Logger 的完整執(zhí)行順序例如真實Authorization: Bearer abc Body: { password: 123456 }流程Logging Plugin ↓ sanitizeHeader ↓ Authorization: *** ↓ bodyFilter ↓ password: *** ↓ 整理成 message ↓ Custom Logger.log(message) ↓ AppLogger所以Custom Logger 收到的已經(jīng)可以是經(jīng)過 Ktor 第一輪日志脫敏后的內(nèi)容。三十五、那 Custom Logger 還要不要脫敏可以再做。比如你的 AppLogger 有手機(jī)號脫敏 身份證脫敏 郵箱脫敏 通用 Token 脫敏那就logger object : Logger { override fun log( message: String, ) { val safeMessage globalLogSanitizer .sanitize( message ) AppLogger.d( tag HTTP, message safeMessage, ) } }于是形成第一層 Ktor HTTP 專用脫敏 ↓ Header / Body 第二層 項目級日志脫敏 ↓ 手機(jī)號 / 賬號 / 通用規(guī)則這屬于Defense in Depth多一道保護(hù)。三十六、但不要把所有脫敏都拖到 Custom Logger比如你完全不使用sanitizeHeader bodyFilter然后把未經(jīng)處理的整個 HTTP 日志Authorization Password Token全部交給Custom Logger再做字符串正則。雖然可以實現(xiàn)但職責(zé)不夠清楚。更合理HTTP 已知結(jié)構(gòu) ↓ 優(yōu)先 Ktor LoggingConfig 處理 整個 App 通用日志規(guī)則 ↓ AppLogger 再兜底所以推薦sanitizeHeader bodyFilter globalSanitize而不是everything ↓ global Regex三十七、方案 ALogger.DEFAULT 完整配置如果項目不需要自己的日志系統(tǒng)fun configureLogging( config: LoggingConfig, json: Json, ) { with(config) { logger Logger.DEFAULT level LogLevel.ALL sanitizeHeader { headerName - headerName in sensitiveHeaders } bodyFilter createSafeBodyFilter( json json, ) } }使用HttpClient { install(Logging) { logger Logger.DEFAULT level LogLevel.ALL sanitizeHeader { it in sensitiveHeaders } bodyFilter createSafeBodyFilter( json logJson, ) } }流程HTTP ↓ Ktor Logging ↓ Header 脫敏 ↓ Body 脫敏 / Skip / 截斷 ↓ Logger.DEFAULT這已經(jīng)可以是一套完整方案。三十八、方案 BCustom Logger 完整配置如果項目已經(jīng)有統(tǒng)一日志框架HttpClient { install(Logging) { logger object : Logger { override fun log( message: String, ) { AppLogger.d( tag HTTP, message globalLogSanitizer .sanitize( message ), ) } } level LogLevel.ALL sanitizeHeader { it in sensitiveHeaders } bodyFilter createSafeBodyFilter( json logJson, ) } }流程HTTP ↓ LoggingConfig │ ├ sanitizeHeader └ bodyFilter ↓ HTTP 專用第一輪脫敏 ↓ Custom Logger ↓ 項目級第二輪脫敏 ↓ AppLogger / Kermit ↓ Console / File / Upload三十九、如果使用 Kermit可以怎么接概念非常簡單install(Logging) { logger object : Logger { override fun log( message: String, ) { co.touchlab.kermit.Logger .withTag(HTTP) .d { message } } } level LogLevel.ALL sanitizeHeader { it in sensitiveHeaders } bodyFilter createSafeBodyFilter( json logJson, ) }也就是說Ktor Logger只是一個 AdapterKtor Logging ↓ Logger 接口 ↓ Kermit四十、filter() 又有什么用除了脫敏LoggingConfig 還能決定哪些 Request 根本不需要記錄例如filter { request - request.url.host .contains( api.example.com ) }只有匹配api.example.com的請求進(jìn)入日志。官方當(dāng)前文檔就是這樣使用filter()對請求進(jìn)行篩選。例如你還可以analytics 埋點 心跳如果請求頻率特別高可以考慮不打印完整日志。四十一、Logging 也應(yīng)該有環(huán)境策略推薦思想Debug ↓ 詳細(xì)日志 Release ↓ 降低 Level 嚴(yán)格脫敏 必要時只記錄錯誤元數(shù)據(jù)例如level if (isDebug) { LogLevel.ALL } else { LogLevel.INFO }不是說正式環(huán)境完全不能有網(wǎng)絡(luò)日志。而是正式環(huán)境的日志目標(biāo)應(yīng)該從“方便開發(fā)”變成“可以診斷但不泄露數(shù)據(jù)”。四十二、完整生產(chǎn)思路應(yīng)該是這樣HTTP ↓ Logging ↓ LoggingConfig │ ┌──────────────┼──────────────┐ ↓ ↓ ↓ level filter sanitizeHeader ↓ Header 脫敏 │ ↓ bodyFilter │ ┌──────────┼──────────┐ ↓ ↓ ↓ JSON脫敏 大Body截斷 Binary Skip └──────────┼──────────┘ ↓ 安全日志 message ↓ Custom Logger ↓ Global Sanitizer ↓ AppLogger/Kermit ↓ Console / File / Upload四十三、給一個最終完整示例下面把這一篇的核心組合起來。private val logJson Json { ignoreUnknownKeys true } private val sensitiveHeaders setOf( HttpHeaders.Authorization, HttpHeaders.Cookie, X-Api-Key, X-Access-Token, ) private val sensitiveJsonKeys setOf( password, token, accessToken, refreshToken, secret, apiKey, ) private fun sanitizeJsonElement( element: JsonElement, ): JsonElement { return when (element) { is JsonObject - { JsonObject( element.mapValues { entry, - if ( entry.key in sensitiveJsonKeys ) { JsonPrimitive( *** ) } else { sanitizeJsonElement( entry.value ) } } ) } is JsonArray - { JsonArray( element.map { sanitizeJsonElement( it ) } ) } else - { element } } } private fun sanitizeJson( json: Json, raw: String, ): String { return runCatching { val element json.parseToJsonElement( raw ) sanitizeJsonElement( element ).toString() }.getOrElse { [body omitted: invalid json] } } private fun truncateBody( value: String, maxChars: Int, ): String { if ( value.length maxChars ) { return value } return value.take( maxChars ) \n...[truncated] } private fun createSafeBodyFilter( json: Json, maxBodyChars: Int 8 * 1024, maxReadableBytes: Long 1024 * 1024, ): LogBodyFilter { return CommonLogBodyFilter { contentLength, contentType, _, body, - if ( contentLength ! null contentLength maxReadableBytes ) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason body too large, byteSize contentLength, ) } if (contentType null) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason unknown content type, byteSize contentLength, ) } val isJson contentType.contentSubtype .contains( json, ignoreCase true, ) val isText contentType.contentType .equals( text, ignoreCase true, ) if ( !isJson !isText ) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason binary/non-text body, byteSize contentLength, ) } val raw body .readBuffer() .readString() val safe if (isJson) { sanitizeJson( json json, raw raw, ) } else { raw } val truncated truncateBody( value safe, maxChars maxBodyChars, ) val buffer Buffer().apply { writeString( truncated ) } BodyFilterResult .BufferContent( buffer buffer, charset Charsets.UTF_8, ) } }最后 HttpClientfun createHttpClient(): HttpClient { return HttpClient { install(Logging) { logger object : Logger { override fun log( message: String, ) { AppLogger.d( tag HTTP, message message, ) } } level LogLevel.ALL sanitizeHeader { headerName, - headerName in sensitiveHeaders } bodyFilter createSafeBodyFilter( json logJson, ) } } }這個示例表達(dá)的并不是所有項目必須照抄而是完整展示 Logging 的職責(zé)鏈Request / Response ↓ Ktor Logging ↓ Header 脫敏 ↓ Body 分類 ↓ JSON 敏感字段脫敏 ↓ 大 Body 控制 ↓ Binary Skip ↓ Custom Logger ↓ AppLogger四十四、如果項目已經(jīng)有自己的全局脫敏怎么辦那就在AppLogger繼續(xù)加第二層override fun log( message: String, ) { val safeMessage globalSanitizer .sanitize( message ) AppLogger.d( tag HTTP, message safeMessage, ) }于是Ktor ↓ HTTP結(jié)構(gòu)級脫敏 AppLogger ↓ 項目級通用脫敏這是比較完整的正式項目思路。四十五、最容易踩的幾個坑坑一以為 Custom Logger 才能脫敏不對。sanitizeHeader bodyFilter屬于LoggingConfig所以Logger.DEFAULT同樣可以脫敏。坑二以為 sanitizeHeader 會修改 Request不對。它只是日志脫敏不會影響真實網(wǎng)絡(luò) Header?？尤詾?bodyFilter 是網(wǎng)絡(luò) Body 轉(zhuǎn)換不對。它處理的是Body 如何進(jìn)入日志不是Body 如何發(fā)送給服務(wù)器真正 Request/Response Body 轉(zhuǎn)換屬于后面的 Custom Plugin 生命周期。坑四只關(guān)注 Authorization不管 Body例如登錄接口Authorization 已經(jīng) ***但password仍然明文輸出。這仍然是不安全的?？游灏?Multipart / Binary 全打印通常沒有意義而且可能造成巨大性能和日志問題?？恿鵅ody 讀完以后再截斷巨大內(nèi)容如果已經(jīng)知道Content-Length 100MB應(yīng)該盡早Skip而不是先讀取 100MB 再take(8192)坑七把 Logging 當(dāng)業(yè)務(wù)日志系統(tǒng)Ktor LoggingHTTP 日志來源而AppLogger / Kermit才更適合作為整個 App 的統(tǒng)一日志基礎(chǔ)設(shè)施。四十六、本篇總結(jié)這一篇最重要的是搞清楚Logging Plugin LoggingConfig Logger三者不是一回事。完整關(guān)系HTTP Request / Response ↓ Logging Plugin ↓ LoggingConfig │ ├── level ├── filter ├── sanitizeHeader ├── bodyFilter └── format ↓ 安全日志內(nèi)容 ↓ Logger / \ ↓ ↓ DEFAULT Custom ↓ AppLogger/Kermit其中sanitizeHeader ↓ 負(fù)責(zé) Header 日志脫敏bodyFilter ↓ 負(fù)責(zé) Request / Response Body 如何進(jìn)入日志 ↓ 脫敏 / 截斷 / SkipLogger ↓ 負(fù)責(zé)最終日志輸出所以方案 ALogger.DEFAULT和方案 BCustom Logger 都可以使用 KtorLoggingConfig自帶的 Header/Body 處理能力。Custom Logger 的真正價值不是“才能脫敏”而是把已經(jīng)經(jīng)過 Ktor 處理的 HTTP 日志接入自己的統(tǒng)一日志系統(tǒng)并且可以再增加第二層項目級處理。另外還要特別記住Logging Body 的脫敏和真正 Request/Response Body 的修改完全不是一回事。Logging bodyFilter ↓ 改的是日志 Custom Plugin transformRequestBody / transformResponseBody ↓ 改的才是網(wǎng)絡(luò)生命周期里的 Body這也正好為下一篇最核心的內(nèi)容鋪路。下一篇第十篇《Ktor Custom Client Plugin從 OkHttp Interceptor 真正理解請求與響應(yīng)生命周期》下一篇不再停留在install(Logging) install(HttpTimeout) install(HttpRequestRetry)這種“調(diào)用官方 API”的層面。而是回到真正的底層擴(kuò)展模型OkHttp ↓ Application Interceptor RetryAndFollowUpInterceptor BridgeInterceptor CacheInterceptor ConnectInterceptor Network Interceptor CallServerInterceptor ↓ Custom Interceptor ↓ chain.proceed() VS Ktor ↓ HttpClient Pipeline ↓ createClientPlugin ↓ onRequest ↓ transformRequestBody ↓ SendingRequest ↓ Send ↓ Engine ↓ onResponse ↓ transformResponseBody真正解決一次 Ktor Request 到底經(jīng)過哪些生命周期Plugin 又是如何插入這些生命周期并修改 Request、Response 和 Body 的這會是整個系列從“會使用 Ktor”進(jìn)入“真正理解 Ktor”的關(guān)鍵一篇。 補(bǔ)充篇 9.1：Ktor Logging 深入：Header、Body 脫敏與自定義 Logger
第九篇我們已經(jīng)知道Logging ↓ 負(fù)責(zé)記錄 HTTP Request / Response最基礎(chǔ)的配置可能只是install(Logging) { logger Logger.DEFAULT level LogLevel.ALL }但正式項目真正需要考慮的遠(yuǎn)不只是“把日志打印出來”而是哪些內(nèi)容應(yīng)該記錄 哪些 Header 絕對不能打印 Request Body 中的 password 怎么辦 Response Body 中的 token 怎么辦 文件上傳為什么不能打印 Body 10MB JSON 要全部打印嗎 Logger.DEFAULT 和 Custom Logger 到底是什么關(guān)系 已經(jīng)用了 Kermit / AppLogger Ktor 日志應(yīng)該怎么接進(jìn)去所以這一篇專門把 Ktor Logging 拆開。當(dāng)前 Ktor 3.5.x 的LoggingConfig提供logger、level、filter()、sanitizeHeader()、bodyFilter、format等配置其中bodyFilter默認(rèn)使用BinaryLogBodyFilter用于避免把二進(jìn)制 Body 當(dāng)普通文本輸出。一、先建立最重要的 Logging 心智模型Ktor Logging 可以拆成三層Logging Plugin ↓ LoggingConfig │ ┌────────────────┼────────────────┐ ↓ ↓ ↓ level sanitizeHeader bodyFilter │ │ Header處理 Body處理 └────────────────┼────────────────┘ ↓ 生成日志內(nèi)容 ↓ Logger / \ ↓ ↓ Logger.DEFAULT Custom Logger ↓ AppLogger / Kermit這里最重要的是LoggingConfig 決定“日志內(nèi)容怎么處理”Logger 決定“處理后的日志往哪里輸出”。不要把這兩件事混在一起。二、Logging Plugin 是什么安裝install(Logging)相當(dāng)于HttpClient ↓ 獲得 HTTP Logging 能力它負(fù)責(zé)觀察Request Response Method URL Headers Body Status它不是你的App 全局日志框架它只是HTTP 網(wǎng)絡(luò)日志的生產(chǎn)者。例如你的項目可能還有業(yè)務(wù)日志 數(shù)據(jù)庫日志 WebSocket 日志 機(jī)器人通信日志 異常日志Ktor Logging 只是其中一個來源。三、LoggingConfig 是什么當(dāng)我們寫install(Logging) { logger Logger.DEFAULT level LogLevel.ALL sanitizeHeader { it HttpHeaders.Authorization } }大括號里的接收者就是LoggingConfig當(dāng)前 3.5.x API 中它主要提供logger level format bodyFilter filter() sanitizeHeader()因此install(Logging) { ... }本質(zhì)就是配置 Logging Plugin 的工作規(guī)則。四、Logger 又是什么Ktor 的Logger非常簡單。核心就是interface Logger { fun log( message: String, ) }所以 Logger 根本不負(fù)責(zé)抓 Request 抓 Response 解析 Header 讀取 Body它主要負(fù)責(zé)Ktor 已經(jīng)生成了一段日志字符串我把它輸出到哪里所以Logging Plugin ↓ 生成 message ↓ Logger.log(message)五、方案 A直接使用 Logger.DEFAULT最簡單install(Logging) { logger Logger.DEFAULT level LogLevel.ALL }流程Request / Response ↓ Logging Plugin ↓ 生成日志 ↓ Logger.DEFAULT ↓ 平臺日志系統(tǒng)Ktor 官方當(dāng)前說明在 JVM 上Logger.DEFAULT使用 SLF4JAndroid 推薦提供slf4j-android。Multiplatform 項目則可以提供自己的 Logger。Android 例如androidMain.dependencies { implementation( org.slf4j:slf4j-android:$slf4jVersion ) }然后install(Logging) { logger Logger.DEFAULT level LogLevel.ALL }六、Ktor 3.5.x 還有 Logger.ANDROID當(dāng)前 API 里還有 JVM/Android 專用Logger.ANDROID它會面向 Android Logcat 輸出并處理 Android 單條日志長度限制如果存在 SLF4J Provider也會使用默認(rèn) Logger。所以 Android-only 項目里也可能看到install(Logging) { logger Logger.ANDROID level LogLevel.ALL }但是對于 KMP 項目如果已經(jīng)有統(tǒng)一Kermit AppLogger后面介紹的 Custom Logger 通常更適合。七、LogLevel 到底控制什么當(dāng)前 Ktor Logging 有NONE INFO HEADERS BODY ALL可以先這樣理解NONE ↓ 完全不記錄 INFO ↓ Request / Response 基礎(chǔ)信息 HEADERS ↓ 基礎(chǔ)信息 Header BODY ↓ 基礎(chǔ)信息 Body ALL ↓ Header Body 完整 HTTP 日志開發(fā)環(huán)境常見level LogLevel.ALL但是正式環(huán)境不建議簡單ALL 什么都不脫敏直接上線。八、為什么 Logging 會帶來安全問題假設(shè)POST /login Authorization: Bearer abc123 Cookie: session987654 { username: tom, password: 123456 }如果level LogLevel.ALL完全不做處理那么Token Cookie Password全部可能進(jìn)入Logcat 文件日志 日志上傳平臺 Crash 日志這就不是調(diào)試問題了而是數(shù)據(jù)安全問題所以 Logging 至少需要兩層考慮Header ↓ sanitizeHeader Body ↓ bodyFilter九、sanitizeHeader 到底是什么例如sanitizeHeader { it HttpHeaders.Authorization }這句話第一次看容易暈。完整展開sanitizeHeader { headerName - headerName HttpHeaders.Authorization }Ktor 相當(dāng)于不斷問“這個 Header Name 需要隱藏嗎”如果Content-Type ↓ false正常打印。如果Authorization ↓ true隱藏它的值。十、這里的 it 是 Header Name不是 Value例如真實 RequestAuthorization: Bearer abc123 Platform: Android Language: zh-CNKtor判斷headerName Authorization ↓ true ↓ 脫敏 headerName Platform ↓ false ↓ 正常輸出最終日志Authorization: *** Platform: Android Language: zh-CN當(dāng)前sanitizeHeader()的簽名本質(zhì)是fun sanitizeHeader( placeholder: String ***, predicate: (String) - Boolean, )所以默認(rèn)占位符就是***十一、sanitizeHeader 不修改真實 Request這個一定要分清楚。真實 RequestAuthorization: Bearer abc123經(jīng)過 Logging真實 HTTP Request ↓ 仍然是 Authorization: Bearer abc123 ↓ 發(fā)送給服務(wù)器同時Logging ↓ Authorization 命中 sanitizeHeader ↓ 日志 Authorization: ***所以sanitizeHeader 只修改“日志展示”不修改真正發(fā)送的 Header。十二、多個敏感 Header 怎么處理例如Authorization Cookie X-Api-Key X-Access-Token可以sanitizeHeader { headerName - headerName HttpHeaders.Authorization || headerName HttpHeaders.Cookie || headerName X-Api-Key || headerName X-Access-Token }我更推薦集中管理private val sensitiveHeaders setOf( HttpHeaders.Authorization, HttpHeaders.Cookie, X-Api-Key, X-Access-Token, )然后sanitizeHeader { headerName - headerName in sensitiveHeaders }這樣以后擴(kuò)展更方便。十三、還可以修改脫敏占位符默認(rèn)***也可以sanitizeHeader( placeholder redacted ) { headerName - headerName HttpHeaders.Authorization }日志Authorization: redacted十四、但 sanitizeHeader 有一個天然限制它只能處理Header不能處理Request Body Response Body例如{ username: tom, password: 123456, accessToken: abcdef }這里password accessToken根本不是 Header。所以sanitizeHeader { it HttpHeaders.Authorization }對它們完全沒有作用。這就是bodyFilter存在的意義。十五、bodyFilter 是什么當(dāng)前 Ktor 3.5.x 的LoggingConfig.bodyFilter類型是LogBodyFilter它可以決定 Body 日志正常記錄 修改以后記錄 只記錄一部分 直接跳過官方 API 明確把隱藏敏感數(shù)據(jù) 截斷過長 Body 修改日志格式列為其使用場景。十六、bodyFilter 不只可以處理 ResponseLogBodyFilter當(dāng)前提供filterRequest(...)和filterResponse(...)也就是說Request Body ↓ 可以處理 Response Body ↓ 也可以處理所以可以形成Request JSON ↓ password 脫敏 Response JSON ↓ token 脫敏十七、CommonLogBodyFilter 又是什么如果 Request 和 Response 使用同一套 Body 處理規(guī)則沒必要分別實現(xiàn)filterRequest filterResponseKtor 提供CommonLogBodyFilter它內(nèi)部的filterAll(...)會同時用于 Request 和 Response。所以Request Body ─┐ ↓ 同一過濾器 ↑ Response Body ┘特別適合JSON統(tǒng)一脫敏 文本統(tǒng)一截斷 二進(jìn)制統(tǒng)一跳過十八、bodyFilter 返回什么核心返回BodyFilterResult當(dāng)前 API 中主要有Content Empty Skip其中BufferContent可以返回修改后的可讀 BodySkip表示這段 Body 不應(yīng)該繼續(xù)打印例如JSON ↓ 處理后 ↓ BufferContent 圖片 ↓ Skip(binary body)十九、Ktor 默認(rèn)其實已經(jīng)幫你過濾二進(jìn)制 Body當(dāng)前bodyFilter默認(rèn)BinaryLogBodyFilter它負(fù)責(zé)過濾二進(jìn)制內(nèi)容。這非常合理。否則image/jpeg application/pdf video/mp4 zip如果直接LogLevel.ALLLogcat 可能看到一大堆JFIF.....沒有任何意義。二十、為什么 Multipart / 文件上傳通常應(yīng)該 Skip例如POST /upload Content-Type: multipart/form-dataBody 中可能包含20MB 圖片 100MB 視頻 PDF ZIP日志真正需要知道的是上傳哪個接口 文件名 Content-Type 文件大小 Status 耗時而不是把 100MB 文件內(nèi)容打印出來所以Multipart Binary ↓ Skip通常更合理。二十一、Body 脫敏的核心流程例如真實 Request{ username: tom, password: 123456, accessToken: abcdef }我們希望日志{ username: tom, password: ***, accessToken: *** }處理過程ByteReadChannel ↓ 讀取日志 Body ↓ String ↓ 解析 JSON ↓ 遍歷字段 ↓ 敏感 Key ↓ 替換 *** ↓ 重新生成 JSON ↓ BufferContent ↓ Logging 輸出二十二、為什么不推薦正則作為最終 JSON 脫敏學(xué)習(xí)階段可能寫json.replace( Regex( (password\s*:\s*)[^]*() ), $1***$2, )簡單 JSON 能工作。但是 JSON 還可能有嵌套對象 數(shù)組 轉(zhuǎn)義字符 字段順序變化 復(fù)雜字符串所以正式項目更推薦String ↓ JsonElement ↓ 遞歸遍歷 ↓ 按 Key 脫敏這正好可以使用前面已經(jīng)學(xué)過的kotlinx.serialization二十三、定義敏感 JSON Key例如private val sensitiveJsonKeys setOf( password, token, accessToken, refreshToken, secret, apiKey, )以后如果還需要phone idCard bankCard只需要繼續(xù)增加。不過哪些字段應(yīng)該完全隱藏、哪些應(yīng)該部分掩碼要根據(jù)實際業(yè)務(wù)和合規(guī)要求設(shè)計。二十四、遞歸脫敏 JsonElement例如private fun sanitizeJsonElement( element: JsonElement, ): JsonElement { return when (element) { is JsonObject - { JsonObject( element.mapValues { entry, - val key entry.key val value entry.value if ( key in sensitiveJsonKeys ) { JsonPrimitive( *** ) } else { sanitizeJsonElement( value ) } } ) } is JsonArray - { JsonArray( element.map( ::sanitizeJsonElement ) ) } else - { element } } }這樣{ user: { name: Tom, password: 123456 }, tokens: { accessToken: abc } }也可以處理成{ user: { name: Tom, password: *** }, tokens: { accessToken: *** } }這比簡單 Regex 穩(wěn)定很多。二十五、封裝 sanitizeJson()private val logJson Json { ignoreUnknownKeys true } private fun sanitizeJson( raw: String, ): String { return runCatching { val element logJson.parseToJsonElement( raw ) sanitizeJsonElement( element ).toString() }.getOrElse { // JSON 解析失敗時 // 不做復(fù)雜處理 raw } }不過這里還有一個安全問題如果JSON 解析失敗直接返回raw可能重新暴露敏感信息。所以正式項目更保守可以選擇getOrElse { [body omitted: invalid json] }我更推薦后者。二十六、大 Body 為什么也應(yīng)該限制假設(shè)GET /huge-data ↓ Response 15MB JSON即使沒有任何敏感字段15MB 全打印仍然很糟糕。會產(chǎn)生巨大 Logcat 日志文件膨脹 CPU 消耗 內(nèi)存壓力 日志平臺流量 真正重要日志被淹沒所以 Body Logging 通常還應(yīng)該有最大長度例如8KB 16KB 32KB根據(jù)項目決定。二十七、一個簡單截斷函數(shù)例如private fun truncateBody( value: String, maxChars: Int, ): String { if ( value.length maxChars ) { return value } return buildString { append( value.take(maxChars) ) append( \n...[truncated] ) } }注意這里控制的是字符數(shù)不是精確網(wǎng)絡(luò)字節(jié)數(shù)對于日志限制通常已經(jīng)夠用。二十八、但是“大 Body”最好在讀取之前就判斷例如Content-Length 100MB如果你的邏輯先全部讀取 100MB ↓ 再截斷成 8KB顯然還是浪費(fèi)資源。所以更好的contentLength 已知且特別大 ↓ 直接 Skip例如 1MB ↓ 不記錄 Body而不是讀取以后再處理。二十九、一個完整 Safe BodyFilter下面把JSON 脫敏 文本截斷 大 Body Skip Binary Skip組合起來。private fun createSafeBodyFilter( json: Json, maxBodyChars: Int 8 * 1024, maxReadableBytes: Long 1024 * 1024, ): LogBodyFilter { return CommonLogBodyFilter { contentLength, contentType, _, body, - // 1. 已知 Body 特別大 if ( contentLength ! null contentLength maxReadableBytes ) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason body too large, byteSize contentLength, ) } // 2. 不知道 Content-Type if (contentType null) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason unknown content type, byteSize contentLength, ) } val isJson contentType.contentSubtype .contains( json, ignoreCase true, ) val isText contentType.contentType .equals( text, ignoreCase true, ) // 3. Binary / Multipart 等直接跳過 if ( !isJson !isText ) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason non-text body, byteSize contentLength, ) } // 4. 讀取日志 Body val raw body .readBuffer() .readString() // 5. JSON 做字段級脫敏 val safe if (isJson) { sanitizeJson( json json, raw raw, ) } else { raw } // 6. 控制日志長度 val truncated truncateBody( value safe, maxChars maxBodyChars, ) // 7. 重新構(gòu)造日志內(nèi)容 val buffer Buffer().apply { writeString( truncated ) } BodyFilterResult .BufferContent( buffer buffer, charset Charsets.UTF_8, ) } }當(dāng)前BodyFilterResult.BufferContent就是接收Buffer Charset把處理后的 Body 提供給 LoggingSkip則表示跳過 Body并可以攜帶 reason 和 byteSize。Buffer.readString()和writeString()則來自當(dāng)前kotlinx-ioAPI。三十、sanitizeJson 完整版本private val sensitiveJsonKeys setOf( password, token, accessToken, refreshToken, secret, apiKey, ) private fun sanitizeJson( json: Json, raw: String, ): String { return runCatching { val element json.parseToJsonElement( raw ) sanitizeJsonElement( element ).toString() }.getOrElse { [body omitted: invalid json] } } private fun sanitizeJsonElement( element: JsonElement, ): JsonElement { return when (element) { is JsonObject - { JsonObject( element.mapValues { entry, - if ( entry.key in sensitiveJsonKeys ) { JsonPrimitive( *** ) } else { sanitizeJsonElement( entry.value ) } } ) } is JsonArray - { JsonArray( element.map { sanitizeJsonElement( it ) } ) } else - { element } } }三十一、為什么 BodyFilter 不應(yīng)該修改真正的業(yè)務(wù) Body這一點和sanitizeHeader一樣。這里我們做的是日志副本 ↓ 脫敏 ↓ Logger真正網(wǎng)絡(luò) Requestpassword 123456如果服務(wù)器確實需要這個字段那么真正發(fā)送仍然是 123456日志password ***所以網(wǎng)絡(luò) Body 和 日志 Body一定分開理解。三十二、不要把 BodyFilter 當(dāng) Request 加密器例如業(yè)務(wù)要求請求 Body ↓ AES 加密 ↓ 發(fā)送服務(wù)器這不能靠Logging bodyFilter來完成。因為 bodyFilter 的職責(zé)是Body ↓ 怎么記錄到日志而真正修改發(fā)送 BodyRequest Body ↓ 加密 ↓ 發(fā)送應(yīng)該進(jìn)入后面要講的Custom Client Plugin transformRequestBody SendingRequest這是完全不同的生命周期。三十三、現(xiàn)在理解 Custom Logger如果項目已經(jīng)有Kermit或者自己的AppLogger我們不希望業(yè)務(wù)日志 ↓ Kermit HTTP 日志 ↓ 另外一套 Logger而希望所有日志 ↓ 統(tǒng)一 AppLogger于是logger object : Logger { override fun log( message: String, ) { AppLogger.d( tag HTTP, message message, ) } }三十四、Custom Logger 的完整執(zhí)行順序例如真實Authorization: Bearer abc Body: { password: 123456 }流程Logging Plugin ↓ sanitizeHeader ↓ Authorization: *** ↓ bodyFilter ↓ password: *** ↓ 整理成 message ↓ Custom Logger.log(message) ↓ AppLogger所以Custom Logger 收到的已經(jīng)可以是經(jīng)過 Ktor 第一輪日志脫敏后的內(nèi)容。三十五、那 Custom Logger 還要不要脫敏可以再做。比如你的 AppLogger 有手機(jī)號脫敏 身份證脫敏 郵箱脫敏 通用 Token 脫敏那就logger object : Logger { override fun log( message: String, ) { val safeMessage globalLogSanitizer .sanitize( message ) AppLogger.d( tag HTTP, message safeMessage, ) } }于是形成第一層 Ktor HTTP 專用脫敏 ↓ Header / Body 第二層 項目級日志脫敏 ↓ 手機(jī)號 / 賬號 / 通用規(guī)則這屬于Defense in Depth多一道保護(hù)。三十六、但不要把所有脫敏都拖到 Custom Logger比如你完全不使用sanitizeHeader bodyFilter然后把未經(jīng)處理的整個 HTTP 日志Authorization Password Token全部交給Custom Logger再做字符串正則。雖然可以實現(xiàn)但職責(zé)不夠清楚。更合理HTTP 已知結(jié)構(gòu) ↓ 優(yōu)先 Ktor LoggingConfig 處理 整個 App 通用日志規(guī)則 ↓ AppLogger 再兜底所以推薦sanitizeHeader bodyFilter globalSanitize而不是everything ↓ global Regex三十七、方案 ALogger.DEFAULT 完整配置如果項目不需要自己的日志系統(tǒng)fun configureLogging( config: LoggingConfig, json: Json, ) { with(config) { logger Logger.DEFAULT level LogLevel.ALL sanitizeHeader { headerName - headerName in sensitiveHeaders } bodyFilter createSafeBodyFilter( json json, ) } }使用HttpClient { install(Logging) { logger Logger.DEFAULT level LogLevel.ALL sanitizeHeader { it in sensitiveHeaders } bodyFilter createSafeBodyFilter( json logJson, ) } }流程HTTP ↓ Ktor Logging ↓ Header 脫敏 ↓ Body 脫敏 / Skip / 截斷 ↓ Logger.DEFAULT這已經(jīng)可以是一套完整方案。三十八、方案 BCustom Logger 完整配置如果項目已經(jīng)有統(tǒng)一日志框架HttpClient { install(Logging) { logger object : Logger { override fun log( message: String, ) { AppLogger.d( tag HTTP, message globalLogSanitizer .sanitize( message ), ) } } level LogLevel.ALL sanitizeHeader { it in sensitiveHeaders } bodyFilter createSafeBodyFilter( json logJson, ) } }流程HTTP ↓ LoggingConfig │ ├ sanitizeHeader └ bodyFilter ↓ HTTP 專用第一輪脫敏 ↓ Custom Logger ↓ 項目級第二輪脫敏 ↓ AppLogger / Kermit ↓ Console / File / Upload三十九、如果使用 Kermit可以怎么接概念非常簡單install(Logging) { logger object : Logger { override fun log( message: String, ) { co.touchlab.kermit.Logger .withTag(HTTP) .d { message } } } level LogLevel.ALL sanitizeHeader { it in sensitiveHeaders } bodyFilter createSafeBodyFilter( json logJson, ) }也就是說Ktor Logger只是一個 AdapterKtor Logging ↓ Logger 接口 ↓ Kermit四十、filter() 又有什么用除了脫敏LoggingConfig 還能決定哪些 Request 根本不需要記錄例如filter { request - request.url.host .contains( api.example.com ) }只有匹配api.example.com的請求進(jìn)入日志。官方當(dāng)前文檔就是這樣使用filter()對請求進(jìn)行篩選。例如你還可以analytics 埋點 心跳如果請求頻率特別高可以考慮不打印完整日志。四十一、Logging 也應(yīng)該有環(huán)境策略推薦思想Debug ↓ 詳細(xì)日志 Release ↓ 降低 Level 嚴(yán)格脫敏 必要時只記錄錯誤元數(shù)據(jù)例如level if (isDebug) { LogLevel.ALL } else { LogLevel.INFO }不是說正式環(huán)境完全不能有網(wǎng)絡(luò)日志。而是正式環(huán)境的日志目標(biāo)應(yīng)該從“方便開發(fā)”變成“可以診斷但不泄露數(shù)據(jù)”。四十二、完整生產(chǎn)思路應(yīng)該是這樣HTTP ↓ Logging ↓ LoggingConfig │ ┌──────────────┼──────────────┐ ↓ ↓ ↓ level filter sanitizeHeader ↓ Header 脫敏 │ ↓ bodyFilter │ ┌──────────┼──────────┐ ↓ ↓ ↓ JSON脫敏 大Body截斷 Binary Skip └──────────┼──────────┘ ↓ 安全日志 message ↓ Custom Logger ↓ Global Sanitizer ↓ AppLogger/Kermit ↓ Console / File / Upload四十三、給一個最終完整示例下面把這一篇的核心組合起來。private val logJson Json { ignoreUnknownKeys true } private val sensitiveHeaders setOf( HttpHeaders.Authorization, HttpHeaders.Cookie, X-Api-Key, X-Access-Token, ) private val sensitiveJsonKeys setOf( password, token, accessToken, refreshToken, secret, apiKey, ) private fun sanitizeJsonElement( element: JsonElement, ): JsonElement { return when (element) { is JsonObject - { JsonObject( element.mapValues { entry, - if ( entry.key in sensitiveJsonKeys ) { JsonPrimitive( *** ) } else { sanitizeJsonElement( entry.value ) } } ) } is JsonArray - { JsonArray( element.map { sanitizeJsonElement( it ) } ) } else - { element } } } private fun sanitizeJson( json: Json, raw: String, ): String { return runCatching { val element json.parseToJsonElement( raw ) sanitizeJsonElement( element ).toString() }.getOrElse { [body omitted: invalid json] } } private fun truncateBody( value: String, maxChars: Int, ): String { if ( value.length maxChars ) { return value } return value.take( maxChars ) \n...[truncated] } private fun createSafeBodyFilter( json: Json, maxBodyChars: Int 8 * 1024, maxReadableBytes: Long 1024 * 1024, ): LogBodyFilter { return CommonLogBodyFilter { contentLength, contentType, _, body, - if ( contentLength ! null contentLength maxReadableBytes ) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason body too large, byteSize contentLength, ) } if (contentType null) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason unknown content type, byteSize contentLength, ) } val isJson contentType.contentSubtype .contains( json, ignoreCase true, ) val isText contentType.contentType .equals( text, ignoreCase true, ) if ( !isJson !isText ) { returnCommonLogBodyFilter BodyFilterResult.Skip( reason binary/non-text body, byteSize contentLength, ) } val raw body .readBuffer() .readString() val safe if (isJson) { sanitizeJson( json json, raw raw, ) } else { raw } val truncated truncateBody( value safe, maxChars maxBodyChars, ) val buffer Buffer().apply { writeString( truncated ) } BodyFilterResult .BufferContent( buffer buffer, charset Charsets.UTF_8, ) } }最后 HttpClientfun createHttpClient(): HttpClient { return HttpClient { install(Logging) { logger object : Logger { override fun log( message: String, ) { AppLogger.d( tag HTTP, message message, ) } } level LogLevel.ALL sanitizeHeader { headerName, - headerName in sensitiveHeaders } bodyFilter createSafeBodyFilter( json logJson, ) } } }這個示例表達(dá)的并不是所有項目必須照抄而是完整展示 Logging 的職責(zé)鏈Request / Response ↓ Ktor Logging ↓ Header 脫敏 ↓ Body 分類 ↓ JSON 敏感字段脫敏 ↓ 大 Body 控制 ↓ Binary Skip ↓ Custom Logger ↓ AppLogger四十四、如果項目已經(jīng)有自己的全局脫敏怎么辦那就在AppLogger繼續(xù)加第二層override fun log( message: String, ) { val safeMessage globalSanitizer .sanitize( message ) AppLogger.d( tag HTTP, message safeMessage, ) }于是Ktor ↓ HTTP結(jié)構(gòu)級脫敏 AppLogger ↓ 項目級通用脫敏這是比較完整的正式項目思路。四十五、最容易踩的幾個坑坑一以為 Custom Logger 才能脫敏不對。sanitizeHeader bodyFilter屬于LoggingConfig所以Logger.DEFAULT同樣可以脫敏。坑二以為 sanitizeHeader 會修改 Request不對。它只是日志脫敏不會影響真實網(wǎng)絡(luò) Header?？尤詾?bodyFilter 是網(wǎng)絡(luò) Body 轉(zhuǎn)換不對。它處理的是Body 如何進(jìn)入日志不是Body 如何發(fā)送給服務(wù)器真正 Request/Response Body 轉(zhuǎn)換屬于后面的 Custom Plugin 生命周期。坑四只關(guān)注 Authorization不管 Body例如登錄接口Authorization 已經(jīng) ***但password仍然明文輸出。這仍然是不安全的?？游灏?Multipart / Binary 全打印通常沒有意義而且可能造成巨大性能和日志問題?？恿鵅ody 讀完以后再截斷巨大內(nèi)容如果已經(jīng)知道Content-Length 100MB應(yīng)該盡早Skip而不是先讀取 100MB 再take(8192)坑七把 Logging 當(dāng)業(yè)務(wù)日志系統(tǒng)Ktor LoggingHTTP 日志來源而AppLogger / Kermit才更適合作為整個 App 的統(tǒng)一日志基礎(chǔ)設(shè)施。四十六、本篇總結(jié)這一篇最重要的是搞清楚Logging Plugin LoggingConfig Logger三者不是一回事。完整關(guān)系HTTP Request / Response ↓ Logging Plugin ↓ LoggingConfig │ ├── level ├── filter ├── sanitizeHeader ├── bodyFilter └── format ↓ 安全日志內(nèi)容 ↓ Logger / \ ↓ ↓ DEFAULT Custom ↓ AppLogger/Kermit其中sanitizeHeader ↓ 負(fù)責(zé) Header 日志脫敏bodyFilter ↓ 負(fù)責(zé) Request / Response Body 如何進(jìn)入日志 ↓ 脫敏 / 截斷 / SkipLogger ↓ 負(fù)責(zé)最終日志輸出所以方案 ALogger.DEFAULT和方案 BCustom Logger 都可以使用 KtorLoggingConfig自帶的 Header/Body 處理能力。Custom Logger 的真正價值不是“才能脫敏”而是把已經(jīng)經(jīng)過 Ktor 處理的 HTTP 日志接入自己的統(tǒng)一日志系統(tǒng)并且可以再增加第二層項目級處理。另外還要特別記住Logging Body 的脫敏和真正 Request/Response Body 的修改完全不是一回事。Logging bodyFilter ↓ 改的是日志 Custom Plugin transformRequestBody / transformResponseBody ↓ 改的才是網(wǎng)絡(luò)生命周期里的 Body這也正好為下一篇最核心的內(nèi)容鋪路。下一篇第十篇《Ktor Custom Client Plugin從 OkHttp Interceptor 真正理解請求與響應(yīng)生命周期》下一篇不再停留在install(Logging) install(HttpTimeout) install(HttpRequestRetry)這種“調(diào)用官方 API”的層面。而是回到真正的底層擴(kuò)展模型OkHttp ↓ Application Interceptor RetryAndFollowUpInterceptor BridgeInterceptor CacheInterceptor ConnectInterceptor Network Interceptor CallServerInterceptor ↓ Custom Interceptor ↓ chain.proceed() VS Ktor ↓ HttpClient Pipeline ↓ createClientPlugin ↓ onRequest ↓ transformRequestBody ↓ SendingRequest ↓ Send ↓ Engine ↓ onResponse ↓ transformResponseBody真正解決一次 Ktor Request 到底經(jīng)過哪些生命周期Plugin 又是如何插入這些生命周期并修改 Request、Response 和 Body 的這會是整個系列從“會使用 Ktor”進(jìn)入“真正理解 Ktor”的關(guān)鍵一篇。