Оволодіння логуванням в Kotlin: Гнучкий підхід із делегацією та інверсією керування (IoC) - javascript.org.ua

Логування є важливим елементом розробки програмного забезпечення. Воно допомагає нам відлагоджувати проблеми, контролювати поведінку застосунку і розуміти, що відбувається "під капотом". Однак логування може швидко стати обтяжливим — воно може бути розкидане по всьому коду, тісно пов’язане з конкретними платформами або негнучким, коли змінюються вимоги. У цій статті ми розглянемо складну, але елегантну систему логування в Kotlin, яка використовує делегування та Інверсію Контролю (IoC), щоб зробити логування простішим, гнучкішим і адаптованим до різних середовищ.

Ми детально розглянемо потужну реалізацію логування, вивчимо її основні концепції, зважимо її переваги та недоліки, а також подивимося, як вона підтримує кілька бекендів логування, таких як Timber або навіть власні файлові логери. Незалежно від того, чи ви будуєте для Android, iOS чи мультиплатформенний проект на Kotlin, цей підхід має що запропонувати. Почнемо!

Основи: Чому нам потрібно логування?

У своїй основі логування допомагає нам:

Відлагоджувати проблеми: Відстежувати, що відбувається в додатку.
Контролювати поведінку: Збирати дані про продуктивність додатку.
Обробляти помилки: Логувати аварії та неочікувані збої.

Але ось у чому проблема: просте використання println() або Log.d() чудово підходить для швидкого відлагодження, але не витримує випробування більшими системами. Нам потрібно щось більш структуроване, налаштовуване та тестоване.

Визначення вимог до логування

Перед тим як переходити до коду, давайте окреслимо, що саме нам потрібно:

Незалежність від платформи — Працює на Android, iOS і JVM.
Кілька бекендів — Підтримка різних механізмів логування (Logcat, Timber, файлове логування тощо).
Налаштовувані рівні логів — Динамічне фільтрування логів (DEBUG, INFO, WARNING, ERROR).
Підтримка тегування — Легко категоризувати логи.
Мінімум шаблонного коду — Простий, зрозумілий виклик логування.

Маючи ці цілі на увазі, давайте розробимо систему, яка їх задовольнить.

Крок 1: Визначення інтерфейсу Logger

Перший крок — визначити загальний контракт для логування:

interface Logger {  
 val tag: String  
 fun log(message: String, level: LogLevel)  
 fun log(message: String, level: LogLevel, throwable: Throwable?)  
 fun withTag(tag: String): Logger  
}

Це робить нашу систему логування абстрактною та розширюваною. Ми не прив’язуємось до конкретної бібліотеки для логування — ми просто визначаємо поведінку, яку очікуємо.

Далі визначаємо рівні логів:

enum class LogLevel { DEBUG, INFO, WARNING, ERROR }

Крок 2: Спрощення логування за допомогою розширень функцій

Ми хочемо, щоб логування було легким. Замість того, щоб вручну передавати логер у кожен метод, додамо кілька зручних розширень функцій:

fun  T.log(  
 logger: Logger,  
 level: LogLevel,  
 message: String,  
 throwable: Throwable? = null,  
): T = apply {  
 if (throwable != null) {  
 logger.log(message, level, throwable)  
 } else {  
 logger.log(message, level)  
 }  
}  

inline fun  T.logDebug(logger: Logger, message: String): T =  
 log(logger, LogLevel.DEBUG, message)  

inline fun  T.logDebug(logger: Logger, message: (T) -> String): T =  
 log(logger, LogLevel.DEBUG, message(this))

Тепер ми можемо логувати так:

val result = userService  
 .logDebug(systemLogger) { "Kicking off user creation for: $it" }  
 .logDebug(timberLogger) { "User creation underway: $it" }  
 .createUser("Alice")  
 .logInfo(systemLogger) { "Success! User 'Alice' created with ID: $it" }  
 .logInfo(timberLogger) { "Completed: User 'Alice' added to system" }

Найбільша перевага, яку я бачу, це те, що можна легко ланцюжити записи логів і визначити, як саме їх обробляти, що робить відлагодження більш зручним і потужним.

Крок 3: Розуміння делегування та IoC

На даному етапі ми налаштували інтерфейс Logger та зручні розширення функцій. Але те, що робить цю систему справді блискучою, це те, як вона використовує делегування і Інверсію Контролю (IoC), щоб залишатися гнучкою.

Делегування — це як передача відповідальності. Уявіть собі офіціанта в ресторані: він не готує їжу — він передає ваше замовлення кухарю.

У нашій системі DefaultLogger не займається безпосередньо записом логів у файл чи консоль. Натомість ця задача делегується компоненту LogOutput. Це робить логер легким і дозволяє нам змінювати "шефа" (бекенд логування), не змінюючи "офіціанта" (логер).

Інверсія контролю (IoC) змінює традиційний підхід до кодування. Зазвичай логер може жорстко визначати, як він записує логи (наприклад, Log.d() для Android). З IoC ми впроваджуємо механізм логування ззовні. Уявіть, що це як підключення різних приладів до однієї розетки — наш DefaultLogger не турбується, чи надсилає логи до Timber, файлу чи системної консолі, головне, щоб він отримав LogOutput для роботи. Це робить нашу систему гнучкою та тестованою.

Разом делегування та IoC означають, що ми можемо змінювати, як працює логування, не торкаючись основної логіки. Хочете записувати логи в базу даних замість Logcat? Просто підключіть новий LogOutput. Це так просто.

Крок 4: Реалізація DefaultLogger

Давайте подивимося, як побудувати DefaultLogger, який використовує делегування. Ось код:

interface LogOutput {  
 fun output(tag: String, level: LogLevel, message: String, throwable: Throwable?)  
}  

class DefaultLogger(  
 override val tag: String,  
 private val enabledLogLevels: Set = LogLevel.values().toSet(),  
 private val messageFormatter: (String) -> String = { it },  
 private val logOutput: LogOutput  
) : Logger {  

 @Synchronized  
 override fun log(message: String, level: LogLevel, throwable: Throwable?) {  
 if (level !in enabledLogLevels) return  
 val formattedMessage = messageFormatter(message)  
 logOutput.output(tag, level, formattedMessage, throwable)  
 }  

 override fun log(message: String, level: LogLevel) {  
 log(message, level, null)  
 }  

 override fun withTag(tag: String): Logger {  
 return DefaultLogger(tag, enabledLogLevels, messageFormatter, logOutput)  
 }  
}

Ось що відбувається:

tag: Ідентифікує джерело логу (наприклад, "UserService").
enabledLogLevels: Динамічно фільтрує логи — пропускати DEBUG у продакшн-середовищі.
messageFormatter: Налаштовує повідомлення логів (наприклад, додає часові мітки).
logOutput: Делегований компонент, який здійснює фактичне логування.

Анотація @Synchronized гарантує безпеку потоків, що важливо для багатопотокових додатків, таких як Android. Зверніть увагу, як logOutput обробляє виведення — DefaultLogger не турбується, як це робиться, головне, щоб це було зроблено. Ось так працює делегування!

Крок 5: Реалізація специфічних для платформ компонентів з KMP

Оскільки ви згадали підтримку мультиплатформ, давайте подивимося, як це працює з Kotlin Multiplatform (KMP):

Що, якщо ви розробляєте для Android, iOS та JVM? Kotlin Multiplatform (KMP) має рішення для цього. KMP дозволяє нам ділитися основною логікою (такою як наш Logger і DefaultLogger) і одночасно налаштовувати компоненти, специфічні для платформи.

Ми використовуємо механізм expect/actual для визначення контракту LogOutput в загальному коді і реалізації його на кожній платформі.

Ось як це працює:

expect class PlatformLogOutput() : LogOutput {  
 override fun output(tag: String, level: LogLevel, message: String, throwable: Throwable?)  
}

Реалізація для Android (androidMain):

actual class PlatformLogOutput actual constructor() : LogOutput {  
 override fun output(tag: String, level: LogLevel, message: String, throwable: Throwable?) {  
 when (level) {  
 LogLevel.DEBUG -> android.util.Log.d(tag, message, throwable)  
 LogLevel.INFO -> android.util.Log.i(tag, message, throwable)  
 LogLevel.WARNING -> android.util.Log.w(tag, message, throwable)  
 LogLevel.ERROR -> android.util.Log.e(tag, message, throwable)  
 }  
 }  
}

Реалізація для iOS (iosMain):

actual class PlatformLogOutput actual constructor() : LogOutput {  
 override fun output(tag: String, level: LogLevel, message: String, throwable: Throwable?) {  
 val nsLog = NSLog() // Спрощено; використовуйте рідну систему логування для iOS  
 nsLog.log("$tag [${level.name}] $message")  
 }  
}

З таким налаштуванням ваш DefaultLogger працює скрізь, делегуючи правильному PlatformLogOutput залежно від платформи. Додайте версію для JVM або JS, і у вас буде справжня мультиплатформна система логування!

Переваги цього підходу

Ця система логування не просто гарна — вона практична. Ось чому вона крута:

Гнучкість: Заміна реалізацій LogOutput без зміни жодного рядка в коді DefaultLogger.
Тестованість: Можливість мокати LogOutput в юніт-тестах для перевірки поведінки логування.
Незалежність від платформи: Використовуйте один і той самий Logger для Android, iOS, JVM і більше з KMP.
Конфігурованість: Динамічно змінюйте рівні логування або формат повідомлень.
Зручність: Логування з ланцюгом, як logDebug().createUser().logInfo(), виглядає чисто і інтуїтивно.

Ваш приклад чудово це демонструє — логування вписується в код природно, що робить дебагінг простим.

Потенційні недоліки

Немає ідеальних систем. Ось де цей підхід може зазнати труднощів:

Складність: Налаштування інтерфейсів, делегування та KMP вимагає більше зусиль, ніж базовий println().
Продуктивність: Додаткове абстрагування додає невелике навантаження — це не суттєво для більшості додатків, але варто зауважити.
Крива навчання: Новим членам команди може знадобитися час, щоб зрозуміти делегування та IoC.

Для малих проєктів це може бути надмірно. Але для більших або мультиплатформних додатків переваги значно перевищують витрати.

Практичний приклад

Давайте використаємо це на прикладі UserService:

class UserService(private val logger: Logger) {  
 fun createUser(name: String): String {  
 return "123"  
 .logDebug(logger) { "Початок створення користувача для: $name" }  
 .let { id ->  
 // Симулюємо роботу  
 id.logInfo(logger) { "Користувач '$name' створений з ID: $it" }  
 }  
 .logError(logger.takeIf { name.isEmpty() }) { "Помилка: Ім'я не може бути порожнім" }  
 }  
}  

val systemLogger = DefaultLogger("UserService", logOutput = PlatformLogOutput())  
val timberLogger = DefaultLogger("Timber", logOutput = TimberLogOutput()) // Користувацька реалізація для Timber  

val userService = UserService(systemLogger)  
userService  
 .logDebug(timberLogger) { "Ініціалізація сервісу користувачів" }  
 .createUser("Alice")  
 .logInfo(timberLogger) { "Завершено з ID: $it" }

Це демонструє ланцюгове логування, обробку помилок і використання кількох логерів в дії. Ви могли б замінити systemLogger на файл логер в продакшн-середовищі або мокати LogOutput для тестування — повна гнучкість!

Для лінивих програмістів

Для тих, хто любить хороші рішення для копіювання та вставки, функції розширення цієї системи — це мрія.
Вони зменшили кількість шаблонного коду до мінімуму — ось як:

 // Зручні функції для конкретних рівнів логування  
 inline fun  T.logDebug(logger: Logger, message: (T) -> String): T =  
 log(logger, LogLevel.DEBUG, message = message(this))  

 inline fun  T.logInfo(logger: Logger, message: (T) -> String): T =  
 log(logger, LogLevel.INFO, message = message(this))  

 inline fun  T.logWarning(logger: Logger, message: (T) -> String): T =  
 log(logger, LogLevel.WARNING, message = message(this))  

 inline fun  T.logError(logger: Logger, message: (T) -> String, throwable: Throwable? = null): T =  
 log(logger, LogLevel.ERROR, message(this), throwable)  

 // Простіші версії з безпосереднім рядковим повідомленням  
 fun  T.logDebug(logger: Logger, message: String): T = log(logger, LogLevel.DEBUG, message = message)  
 fun  T.logInfo(logger: Logger, message: String): T = log(logger, LogLevel.INFO, message = message)  
 fun  T.logWarning(logger: Logger, message: String): T = log(logger, LogLevel.WARNING, message = message)  
 fun  T.logError(logger: Logger, message: String, throwable: Throwable? = null): T =  
 log(logger, LogLevel.ERROR, message = message, throwable)  

 // Для розширень рядків  
 fun String.logDebug(logger: Logger): String = log(logger, LogLevel.DEBUG, message = this)  
 fun String.logInfo(logger: Logger): String = log(logger, LogLevel.INFO, message = this)  
 fun String.logWarning(logger: Logger): String = log(logger, LogLevel.WARNING, message = this)  
 fun String.logError(logger: Logger, throwable: Throwable? = null): String =  
 log(logger, LogLevel.ERROR, message = this, throwable)

Висновок

Ця система логування на Kotlin пропонує потужний, але простий підхід до відстеження поведінки вашого додатка. Побудована з урахуванням гнучкості та практичності, вона надає набір функцій, які роблять логування як надійним, так і зручним у використанні.

Однією з видатних рис є включені рівні логування. Налаштовуючи, які рівні — такі як DEBUG, INFO, WARNING або ERROR — активні, ви можете точно налаштувати, що записується в логах, не змінюючи код. Під час розробки ви можете активувати всі рівні для максимального огляду, а в продакшн-версії обмежити лише ERROR, зберігаючи логи мінімальними та зосередженими. Цей динамічний контроль заощаджує час, дозволяючи уникнути зайвих даних, і забезпечує актуальність ваших логів.

Ще однією перевагою є форматувальник повідомлень. Хоча основна логіка логування залишається простою, форматувальник дозволяє налаштувати, як виглядатимуть повідомлення — додаючи мітки часу, ідентифікатори потоків чи будь-які інші елементи оформлення. Це відокремлення форматування від логування дозволяє адаптувати виведення для різних контекстів (наприклад, консоль проти файлу), не торкаючись самих лог-записів. Це маленький штрих, що додає великої вартості.

Крім того, система вирізняється:

Інтуїтивно зрозумілими функціями розширення, що зменшують логування до однорядкових викликів, знижуючи повторюваний код.
Типобезпечними генераками, що дозволяють легко і послідовно логувати будь-який об'єкт.
Підтримкою Throwable, що робить логування помилок таким же простим, як і все інше.

Разом ці функції роблять логування простим — адаптивним, упорядкованим і чистим. Спробуйте це у вашому наступному проєкті та подивіться, як це змінить ваш процес дебагінгу!

Перекладено з: Mastering Logging in Kotlin: A Flexible Approach with Delegation and IoC