Kotlin guide done. (20.10.26)

2026-10-20 12:54:25 +03:00
parent da3ad9dd1a
commit 6853ada348
81 changed files with 30112 additions and 0 deletions
@@ -0,0 +1,336 @@
+---
+title: Result и runCatching
+description: Ошибка как значение: Result, runCatching, свои sealed-типы и когда что выбирать
+tags:
+  - kotlin
+  - exceptions
+---
+
+Исключение - не единственный способ сообщить об ошибке. Ошибку можно вернуть как значение, и тогда компилятор заставит её обработать.
+
+Три уровня, от простого к гибкому:
+
+| Способ | Что несёт ошибка | Когда |
+|---|---|---|
+| `T?` | ничего, только «не получилось» | причина не важна |
+| `Result<T>` | `Throwable` | причина нужна, но типизировать её незачем |
+| свой `sealed`-тип | что угодно | причин несколько и они разные |
+
+## Nullable как простейший Result
+Для одной очевидной причины сбоя `null` достаточно:
+```kotlin
+fun main() {
+    println("42".toIntOrNull())        // 42
+    println("abc".toIntOrNull())       // null
+    println("abc".toIntOrNull() ?: 0)  // 0
+}
+```
+Стандартная библиотека придерживается соглашения: `toInt()` бросает, `toIntOrNull()` возвращает `null`; `first()` бросает, `firstOrNull()` - нет.
+```kotlin
+fun main() {
+    val items = listOf(1, 2, 3)
+    println(items.getOrNull(10))                 // null
+    println(items.firstOrNull { it > 5 })        // null
+    println(mapOf("a" to 1)["b"])                // null
+}
+```
+Подробнее: [Null-безопасность](../Синтаксис%20и%20типы/Null-безопасность/Null-безопасность.md)
+
+## Result
+`Result<T>` хранит либо значение, либо `Throwable`.
+```kotlin
+fun main() {
+    val ok: Result<Int> = Result.success(42)
+    val fail: Result<Int> = Result.failure(IllegalStateException("сбой"))
+
+    println(ok.isSuccess)                 // true
+    println(fail.isFailure)               // true
+    println(ok.getOrNull())               // 42
+    println(fail.getOrNull())             // null
+    println(fail.exceptionOrNull()?.message)   // сбой
+}
+```
+
+### runCatching
+Оборачивает блок: результат - `Result`, исключение - `failure`.
+```kotlin
+fun parse(s: String): Result<Int> = runCatching { s.toInt() }
+
+fun main() {
+    println(parse("42"))        // Success(42)
+    println(parse("abc").exceptionOrNull()?.javaClass?.simpleName)  // NumberFormatException
+}
+```
+Есть вариант-расширение с получателем:
+```kotlin
+fun main() {
+    val length = "привет".runCatching { length }
+    println(length.getOrNull())      // 6
+}
+```
+
+### Извлечение значения
+```kotlin
+fun main() {
+    val ok = runCatching { 42 }
+    val fail = runCatching<Int> { error("сбой") }
+
+    println(ok.getOrNull())                           // 42
+    println(fail.getOrDefault(0))                     // 0
+    println(fail.getOrElse { e -> e.message!!.length }) // 4
+    println(ok.getOrThrow())                          // 42
+
+    try {
+        fail.getOrThrow()
+    } catch (e: IllegalStateException) {
+        println("пробросилось: ${e.message}")         // пробросилось: сбой
+    }
+}
+```
+
+### Преобразования
+```kotlin
+fun main() {
+    val r = runCatching { "42" }
+        .map { it.toInt() }            // только при успехе
+        .map { it * 2 }
+    println(r.getOrNull())             // 84
+
+    // mapCatching перехватывает исключение внутри преобразования
+    val bad = runCatching { "abc" }.mapCatching { it.toInt() }
+    println(bad.isFailure)             // true
+
+    // map не перехватывает — исключение улетит наружу
+    val thrown = runCatching { runCatching { "abc" }.map { it.toInt() } }
+    println(thrown.isFailure)          // true
+}
+```
+Разница существенная: `map` предполагает, что преобразование не падает, `mapCatching` - что может.
+
+```kotlin
+fun main() {
+    val r = runCatching<Int> { error("сбой") }
+        .recover { 0 }                 // заменяем ошибку значением
+    println(r.getOrNull())             // 0
+
+    val folded = runCatching { "42".toInt() }
+        .fold(
+            onSuccess = { "значение $it" },
+            onFailure = { "ошибка ${it.message}" },
+        )
+    println(folded)                    // значение 42
+}
+```
+
+### onSuccess и onFailure
+Побочные эффекты без изменения значения - они возвращают сам `Result`:
+```kotlin
+fun main() {
+    runCatching { "abc".toInt() }
+        .onSuccess { println("получили $it") }
+        .onFailure { println("не вышло: ${it.message}") }
+        .getOrDefault(0)
+        .let { println("итог: $it") }
+    // не вышло: For input string: "abc"
+    // итог: 0
+}
+```
+
+## Свой sealed-тип
+Когда причин несколько и клиент должен их различать, `Result` слишком беден - в нём любая ошибка это `Throwable`.
+```kotlin
+sealed interface LoadResult {
+    data class Success(val user: String) : LoadResult
+    data object NotFound : LoadResult
+    data class Forbidden(val reason: String) : LoadResult
+    data class NetworkError(val retryAfter: Int) : LoadResult
+}
+
+fun load(id: Int): LoadResult = when {
+    id == 1 -> LoadResult.Success("Иван")
+    id == 2 -> LoadResult.Forbidden("нет прав")
+    id < 0 -> LoadResult.NetworkError(retryAfter = 5)
+    else -> LoadResult.NotFound
+}
+
+fun describe(r: LoadResult) = when (r) {      // else не нужен
+    is LoadResult.Success -> "загружен ${r.user}"
+    LoadResult.NotFound -> "не найден"
+    is LoadResult.Forbidden -> "запрещено: ${r.reason}"
+    is LoadResult.NetworkError -> "повтор через ${r.retryAfter} с"
+}
+
+fun main() {
+    listOf(1, 2, 3, -1).forEach { println(describe(load(it))) }
+    // загружен Иван
+    // запрещено: нет прав
+    // не найден
+    // повтор через 5 с
+}
+```
+Главное преимущество - компилятор проверяет, что обработаны все варианты. Добавили новый - все `when` перестанут компилироваться, пока его не учтут. С `Result` такой гарантии нет.
+
+Подробнее: [Sealed class и interface](../Синтаксис%20и%20типы/Базовые%20типы%20ООП/Sealed%20class%20и%20interface.md)
+
+### Свой Result с типизированной ошибкой
+```kotlin
+sealed interface Outcome<out T, out E> {
+    data class Ok<T>(val value: T) : Outcome<T, Nothing>
+    data class Err<E>(val error: E) : Outcome<Nothing, E>
+}
+
+enum class ParseError { EMPTY, NOT_A_NUMBER, NEGATIVE }
+
+fun parsePositive(s: String): Outcome<Int, ParseError> = when {
+    s.isBlank() -> Outcome.Err(ParseError.EMPTY)
+    s.toIntOrNull() == null -> Outcome.Err(ParseError.NOT_A_NUMBER)
+    s.toInt() < 0 -> Outcome.Err(ParseError.NEGATIVE)
+    else -> Outcome.Ok(s.toInt())
+}
+
+fun main() {
+    listOf("42", "", "abc", "-1").forEach { input ->
+        when (val r = parsePositive(input)) {
+            is Outcome.Ok -> println("'$input' -> ${r.value}")
+            is Outcome.Err -> println("'$input' -> ошибка ${r.error}")
+        }
+    }
+    // '42' -> 42
+    // '' -> ошибка EMPTY
+    // 'abc' -> ошибка NOT_A_NUMBER
+    // '-1' -> ошибка NEGATIVE
+}
+```
+`Nothing` в позиции второго параметра позволяет `Ok` подходить под любой тип ошибки. Подробнее: [Any, Unit, Nothing](../Синтаксис%20и%20типы/Базовые%20типы%20ООП/Any,%20Unit,%20Nothing.md), [Вариантность](../Дженерики/Вариантность.md)
+
+## Что выбрать
+```mermaid
+graph TD
+    A["Ошибка возможна"] --> B{"Вызывающий может<br/>что-то сделать?"}
+    B -->|"нет, это баг"| C["исключение:<br/>require, check, error"]
+    B -->|"да"| D{"Причину нужно<br/>различать?"}
+    D -->|"нет"| E["T?"]
+    D -->|"да, но обработка общая"| F["Result&lt;T&gt;"]
+    D -->|"да, по-разному"| G["свой sealed-тип"]
+```
+
+Практическое разделение:
+- **исключение** - для нарушенных предпосылок: неверный аргумент, недопустимое состояние. Это ошибка программиста, её исправляют в коде, а не обрабатывают. Подробнее: [Проверки и контракты](Проверки%20и%20контракты.md)
+- **`T?`, `Result`, sealed** - для ожидаемых ситуаций: нет записи в БД, сеть недоступна, ввод пользователя некорректен
+
+## Граница с исключениями
+`runCatching` удобен на границе: внешний код бросает, ваш возвращает значение.
+```kotlin
+class User7(val id: Int, val name: String)
+
+fun fetchFromDb(id: Int): User7 =
+    if (id == 1) User7(1, "Иван") else throw NoSuchElementException("нет пользователя $id")
+
+fun findUser(id: Int): User7? = runCatching { fetchFromDb(id) }.getOrNull()
+
+fun main() {
+    println(findUser(1)?.name)      // Иван
+    println(findUser(99))           // null
+}
+```
+Обратное направление - когда API требует исключений, а внутри `Result`:
+```kotlin
+fun loadOrThrow(id: Int): String = runCatching {
+    require(id > 0) { "id должен быть положительным" }
+    "данные $id"
+}.getOrThrow()
+
+fun main() {
+    println(loadOrThrow(1))      // данные 1
+    try {
+        loadOrThrow(-1)
+    } catch (e: IllegalArgumentException) {
+        println(e.message)        // id должен быть положительным
+    }
+}
+```
+
+> [!info] Отличия от Java
+> | Java | Kotlin |
+> |---|---|
+> | checked exceptions в сигнатуре | `Result<T>` или sealed-тип |
+> | `Optional<T>` | `T?` - часть системы типов |
+> | `Optional.map`/`orElse` | `?.let`/`?:` |
+> | нет аналога `Result` в JDK | `Result<T>` в stdlib |
+> | `try`/`catch` для управления | `runCatching` как выражение |
+>
+> **`Result` частично возвращает то, что отняло отсутствие checked exceptions.** Сигнатура `fun load(): Result<User>` сообщает, что функция может не справиться, и компилятор не даст использовать значение без разбора. Разница с checked exceptions в том, что это выбор автора функции, а не навязанное правило, и такие значения свободно проходят через `map`, `filter` и другие обобщённые функции.
+>
+> **`T?` вместо `Optional<T>`.** `Optional` - обёртка-объект: аллокация, два уровня значений (`null` и пустой `Optional`), неудобство в полях. Nullable-тип в Kotlin существует только при компиляции, а в байт-коде это обычная ссылка - накладных расходов нет:
+> ```kotlin
+> fun main() {
+>     val name: String? = null
+>     println(name?.uppercase() ?: "<нет>")      // <нет>
+> }
+> ```
+> ```java
+> Optional<String> name = Optional.empty();
+> System.out.println(name.map(String::toUpperCase).orElse("<нет>"));
+> ```
+>
+> **Sealed-типы вместо иерархии исключений.** В Java разные причины сбоя обычно выражают классами исключений и ловят их по типу. Sealed-тип даёт то же различение, но с проверкой полноты при компиляции и без стоимости стектрейса.
+>
+> Сравнить: [Система исключений в Java](../../Программирование%20на%20Java/Исключения/Система%20исключений.md)
+
+> [!warning] Подводные камни
+> **`runCatching` перехватывает всё, включая то, что перехватывать нельзя.** Он ловит `Throwable`, то есть `OutOfMemoryError`, `StackOverflowError` и - самое опасное - `CancellationException` в корутинах:
+> ```kotlin
+> // Требует kotlinx-coroutines-core.
+> // suspend fun broken() {
+> //     runCatching { delay(1000) }      // проглотит отмену корутины
+> // }
+> //
+> // suspend fun fixed() = runCatching { delay(1000) }
+> //     .onFailure { if (it is CancellationException) throw it }
+> ```
+> В корутинах либо проверяйте тип вручную, либо используйте обычный `try`/`catch` с перехватом конкретных типов. Подробнее: [Исключения в корутинах](../Корутины/Исключения%20в%20корутинах.md)
+>
+> **`Result` нельзя вернуть из функции в публичном API без оговорок.** До Kotlin 1.5 это было запрещено совсем; сейчас разрешено, но тип по-прежнему `value class`, поэтому из Java он виден странно и его нельзя использовать как тип свойства:
+> ```kotlin
+> class Holder {
+>     // val r: Result<Int> = Result.success(1)    // компилируется, но Result как поле боксируется
+>     private val value: Int = 1
+>     fun get(): Result<Int> = Result.success(value)
+> }
+>
+> fun main() { println(Holder().get().getOrNull()) }    // 1
+> ```
+>
+> **`Result` стирает тип ошибки.** Все причины сбоя - `Throwable`, поэтому различать их приходится через `is`, и компилятор полноту не проверяет:
+> ```kotlin
+> fun main() {
+>     val r = runCatching<Int> { error("сбой") }
+>     val msg = when (val e = r.exceptionOrNull()) {
+>         null -> "успех"
+>         is IllegalStateException -> "состояние: ${e.message}"
+>         else -> "прочее"              // else обязателен
+>     }
+>     println(msg)      // состояние: сбой
+> }
+> ```
+>
+> **Создание `failure` всё равно создаёт исключение со стектрейсом** - то есть `Result` не даёт экономии на производительности, если ошибку формирует `runCatching`. Дешёвый вариант - sealed-тип без `Throwable` внутри.
+>
+> **Проигнорированный `Result` не вызывает предупреждения:**
+> ```kotlin
+> fun save(): Result<Unit> = runCatching { error("не записалось") }
+>
+> fun main() {
+>     save()                     // ошибка потеряна молча
+>     println(save().isFailure)  // true — так правильно
+> }
+> ```
+> В отличие от исключения, которое всплывёт само, забытый `Result` ничего не делает. Это основной риск подхода.
+>
+> **Цепочка `map` на `Result` может бросить.** `map` не перехватывает исключения из своей лямбды - для этого есть `mapCatching`.
+>
+> **`getOrThrow` на чужом `Result` бросает исходное исключение,** а не обёртку, поэтому стектрейс указывает на место первоначального сбоя, а не на `getOrThrow`. Для диагностики это хорошо, для чтения логов - неожиданно.
+>
+> **Смешение подходов в одном слое запутывает.** Если часть функций репозитория возвращает `null`, часть `Result`, а часть бросает, клиентский код обрастает тремя видами обработки. Выберите одно соглашение на слой.
+
+Далее: [Проверки и контракты](Проверки%20и%20контракты.md)