Разработка
SOLID-обработка ошибок в Android: создаём базовый модуль ошибок с нуля
Как применение принципов SOLID к стратегии обработки ошибок может превратить Android-кодовую базу из хрупкой в устойчивую.
Каждый Android-разработчик с этим сталкивался. Открываешь файл и находишь блок try-catch на 200 строк, оборачивающий половину бизнес-логики. Сообщения об ошибках жёстко прописаны в коде. Одна и та же логика повторных попыток скопирована в 15 разных репозиториях. А ViewModel знает о кодах состояния HTTP, исключениях базы данных и каким-то образом даже о JSONException.
Но так быть не должно.
После нескольких лет разработки Android-приложений для реального использования автор пришёл к выводу, что те же принципы SOLID, которые применяются при разработке функций приложения, способны радикально улучшить и обработку ошибок. В статье с нуля создаётся полноценный модуль core-error, который можно подключить практически к любому проекту, и показывается, как каждый принцип SOLID влияет на его архитектуру.
Проблема: обработка ошибок как второстепенная задача
Большинство Android-проектов начинается с довольно простого подхода: сетевой вызов выполняется во ViewModel, а разные исключения ловятся непосредственно там. В зависимости от кода HTTP или типа исключения интерфейсу передаётся нужное сообщение.
class UserViewModel(private val api: ApiService) : ViewModel() {
fun loadUser(id: String) {
viewModelScope.launch {
try {
val user = api.getUser(id)
_state.value = UserState.Success(user)
} catch (e: HttpException) {
if (e.code() == 401) {
_state.value = UserState.Error("Session expired. Please login again.")
} else if (e.code() == 404) {
_state.value = UserState.Error("User not found.")
} else {
_state.value = UserState.Error("Something went wrong.")
}
} catch (e: IOException) {
_state.value = UserState.Error("No internet connection.")
} catch (e: Exception) {
_state.value = UserState.Error("An unexpected error occurred.")
}
}
}
}
Это работает до тех пор, пока в приложении не появляется 30 экранов, делающих одно и то же. Затем возникает необходимость локализовать сообщения об ошибках. Потом продуктовая команда просит добавить кнопку повторной попытки для сетевых ошибок, но не показывать её при ошибках авторизации. После этого требуется ещё и аналитика для каждого типа ошибки.
В результате изначально «простая» обработка ошибок превращается в кошмар с точки зрения сопровождения.
Нужен отдельный модуль core-error — самостоятельная переиспользуемая библиотека, которая централизует описание ошибок, их преобразование и обработку.
Архитектура: где находится core-error
Перед реализацией важно понять граф зависимостей.
Presentation → Domain → core-error
Data → core-error
Слой представления зависит от доменного слоя, доменный и слой данных используют core-error. Сам core-error является конечным модулем графа зависимостей: он не зависит ни от каких частей приложения.
Доменный слой использует его модели, например AppError и AppResult, примерно так же, как использовал бы встроенный Result из Kotlin. Это обычные закрытые интерфейсы и классы данных. Слой данных использует средства преобразования ошибок, а слой представления — типы действий, связанных с ними.
Такое решение сделано намеренно. Моделирование ошибок затрагивает всё приложение, поэтому логично вынести его в отдельный модуль.
S — Single Responsibility: отделяем саму ошибку от её отображения
Первое и наиболее важное архитектурное решение заключается в том, что доменный слой должен описывать что произошло, а слой представления — что показать пользователю.
Это две разные ответственности, и они не должны находиться в одном классе.
Модель ошибок
Вместо строк и кодов состояния создаётся закрытая иерархия, представляющая все виды сбоев, которые могут происходить в приложении.
sealed interface AppError { sealed interface Network : AppError { data object NoConnection : Network data object Timeout : Network data class Server(val code: Int, val serverMessage: String? = null) : Network } sealed interface Auth : AppError { data object SessionExpired : Auth data object Unauthorized : Auth } sealed interface Data : AppError { data class NotFound(val resource: String) : Data data class Validation(val fields: Map<String, String>) : Data } data class Unknown(val throwable: Throwable) : AppError }
Например, ошибки можно разделить на сетевые, ошибки авторизации, ошибки данных и неизвестные ошибки. При этом в модели нет строк интерфейса, решений о том, показывать ли Toast, Snackbar или диалог, а также нет логики повторной попытки. Модель описывает исключительно саму ошибку.
Например, отсутствие сетевого подключения означает одно и то же независимо от того, будет ли информация показана в диалоге, баннере или просто записана в журнал.
Обёртка результата
Вместо передачи исключений между слоями результат операции предлагается описывать явно: либо успех с данными, либо ошибка с соответствующим AppError.
sealed interface AppResult<out T> {
data class Success<T>(val data: T) : AppResult<T>
data class Failure(val error: AppError) : AppResult<Nothing>
}
Такой подход заставляет каждого потребителя явно учитывать путь ошибки. Исчезают ситуации, когда разработчик просто забыл обернуть очередной вызов в try-catch.
Текст, готовый к локализации
Чтобы слой представления мог корректно выполнять свою работу, нужен тип, способный хранить либо обычную строку, либо ссылку на строковый ресурс Android.
sealed interface UiText {
data class Raw(val value: String) : UiText
data class Resource(@StringRes val resId: Int, val args: List<Any> = emptyList()) : UiText
fun resolve(context: Context): String = when (this) {
is Raw -> value
is Resource -> context.getString(resId, *args.toTypedArray())
}
}
Это позволяет отделить представление текста от модели самой ошибки и поддерживать локализацию без проникновения ресурсов Android в доменный слой.
Отдельный тип описывает, что именно должен сделать интерфейс: показать сообщение, выполнить переход, предложить повторить операцию или вообще ничего не показывать.
sealed interface ErrorAction {
data class ShowMessage(val message: UiText) : ErrorAction
data class Navigate(val route: String) : ErrorAction
data class Retry(val message: UiText, val retryAction: suspend () -> Unit) : ErrorAction
data object Silent : ErrorAction
}
В итоге каждый тип отвечает только за одну задачу:
AppErrorописывает, что произошло;UiTextзанимается текстом и локализацией;ErrorActionсообщает интерфейсу, что нужно сделать.
Ни один класс не выполняет сразу несколько обязанностей.
O — Open/Closed: расширяем без изменения существующего кода
Представим реальный сценарий. Сегодня приложение использует Retrofit. В следующем квартале одна команда переходит на Ktor. Затем кто-то добавляет GraphQL.
Каждый из этих инструментов выбрасывает собственные исключения. Если каждый раз добавлять очередной блок обработки в центральный преобразователь, код будет постоянно меняться.
Вместо этого архитектура должна позволять расширять поведение без изменения уже существующей реализации.
Система плагинов
Для этого вводится простой интерфейс плагина преобразования исключений.
interface ExceptionMapperPlugin {
fun map(throwable: Throwable): AppError?
}
Если плагин умеет обработать конкретное исключение, он возвращает соответствующий AppError. Если нет — возвращает null, и исключение передаётся следующему плагину.
Это классическая цепочка ответственности.
Центральный преобразователь
Центральный ExceptionMapper получает набор плагинов, последовательно спрашивает каждый из них и, если ни один не смог обработать исключение, использует встроенные правила по умолчанию.
@Singleton
class ExceptionMapper @Inject constructor(
private val customMappers: Set<@JvmSuppressWildcards ExceptionMapperPlugin>
) {
fun map(throwable: Throwable): AppError {
for (plugin in customMappers) {
plugin.map(throwable)?.let { return it }
}
return mapDefault(throwable)
}
private fun mapDefault(throwable: Throwable): AppError = when (throwable) {
is SocketTimeoutException -> AppError.Network.Timeout
is IOException -> AppError.Network.NoConnection
else -> AppError.Unknown(throwable)
}
}
Например, тайм-аут может преобразовываться в сетевую ошибку времени ожидания, а IOException — в отсутствие подключения. Всё остальное становится неизвестной ошибкой.
Плагин Retrofit
Встроенный плагин Retrofit в предлагаемой архитектуре использует рефлексию. Благодаря этому Retrofit может оставаться необязательной зависимостью: сам модуль core-error продолжит работать даже в приложении, где Retrofit вообще не используется.
class RetrofitExceptionMapperPlugin @Inject constructor() : ExceptionMapperPlugin {
override fun map(throwable: Throwable): AppError? {
val httpExceptionClass = try {
Class.forName("retrofit2.HttpException")
} catch (_: ClassNotFoundException) {
return null
}
if (!httpExceptionClass.isInstance(throwable)) return null
val code = httpExceptionClass.getMethod("code").invoke(throwable) as Int
val message = httpExceptionClass.getMethod("message").invoke(throwable) as? String
return mapHttpCode(code, message)
}
private fun mapHttpCode(code: Int, message: String?): AppError = when (code) {
401 -> AppError.Auth.SessionExpired
403 -> AppError.Auth.Unauthorized
404 -> AppError.Data.NotFound("resource")
in 500..599 -> AppError.Network.Server(code, message)
else -> AppError.Network.Server(code, message)
}
}
Плагин проверяет, является ли исключение HttpException, получает код ответа и преобразует его в соответствующую доменную ошибку: истёкшую сессию, отсутствие прав, отсутствие ресурса или ошибку сервера.
Добавление нового плагина
Когда появляется GraphQL, команде не приходится менять core-error.
class GraphQLExceptionMapperPlugin @Inject constructor() : ExceptionMapperPlugin {
override fun map(throwable: Throwable): AppError? {
if (throwable !is GraphQLException) return null
return when (throwable.errorType) {
"UNAUTHENTICATED" -> AppError.Auth.SessionExpired
"NOT_FOUND" -> AppError.Data.NotFound(throwable.path)
else -> AppError.Unknown(throwable)
}
}
}
Она создаёт собственный плагин в своём модуле, описывает преобразование ошибок GraphQL и регистрирует его через Hilt.
@Module
@InstallIn(SingletonComponent::class)
abstract class GraphQLErrorModule {
@Binds @IntoSet
abstract fun bindGraphQLMapper(impl: GraphQLExceptionMapperPlugin): ExceptionMapperPlugin
}
В результате в core-error не меняется ни одной строки. Модуль закрыт для модификации, но открыт для расширения.
Расширения для результата
Тот же принцип применяется и к AppResult. Дополнительное поведение добавляется через функции-расширения, а не путём изменения самого закрытого интерфейса. Можно добавлять обработчики успеха и ошибки, преобразование результата, восстановление после ошибки, получение значения или значения по умолчанию.
inline fun <T> AppResult<T>.onSuccess(action: (T) -> Unit): AppResult<T> {
if (this is AppResult.Success) action(data)
return this
}
inline fun <T> AppResult<T>.onFailure(action: (AppError) -> Unit): AppResult<T> {
if (this is AppResult.Failure) action(error)
return this
}
inline fun <T, R> AppResult<T>.map(transform: (T) -> R): AppResult<R> = when (this) {
is AppResult.Success -> AppResult.Success(transform(data))
is AppResult.Failure -> this
}
inline fun <T, R> AppResult<T>.flatMap(transform: (T) -> AppResult<R>): AppResult<R> = when (this) {
is AppResult.Success -> transform(data)
is AppResult.Failure -> this
}
inline fun <T> AppResult<T>.recover(transform: (AppError) -> AppResult<T>): AppResult<T> = when (this) {
is AppResult.Success -> this
is AppResult.Failure -> transform(error)
}
fun <T> AppResult<T>.getOrNull(): T? = when (this) {
is AppResult.Success -> data
is AppResult.Failure -> null
}
fun <T> AppResult<T>.getOrDefault(default: T): T = when (this) {
is AppResult.Success -> data
is AppResult.Failure -> default
}
Любая команда способна создавать собственные расширения, например для аналитики, не меняя базовый модуль.
// Analytics team adds this in their own module
fun <T> AppResult<T>.trackFailure(analytics: Analytics): AppResult<T> =
onFailure { error ->
analytics.track("error", mapOf("type" to error::class.simpleName))
}
L — Liskov Substitution: каждый обработчик должен соблюдать контракт
Принцип подстановки Лисков говорит, что подтипы должны иметь возможность заменять базовые типы, не нарушая ожидаемое поведение.
В контексте обработки ошибок это означает следующее: если определён интерфейс ErrorHandler, любая его реализация должна полностью обработать ошибку. Она не должна молча её проглатывать или выполнять только часть работы.
Контракт
Обработчик принимает AppError и обязан вернуть ErrorAction.
interface ErrorHandler {
fun handle(error: AppError): ErrorAction
}
Возвращаемое значение не является необязательным. Нельзя вернуть null, нельзя выбросить исключение и нельзя обработать ошибку только частично. Каждая реализация обязана предоставить осмысленное действие.
Реализация по умолчанию
Стандартный обработчик сопоставляет каждый тип ошибки с подходящим действием.
class DefaultErrorHandler @Inject constructor(
private val globalErrorHandler: GlobalErrorHandler
) : ErrorHandler {
override fun handle(error: AppError): ErrorAction = when (error) {
is AppError.Network.NoConnection -> ErrorAction.ShowMessage(
UiText.Raw("No internet connection. Please check your network.")
)
is AppError.Network.Timeout -> ErrorAction.ShowMessage(
UiText.Raw("Request timed out. Please try again.")
)
is AppError.Network.Server -> ErrorAction.ShowMessage(
UiText.Raw("Server error (${error.code}). Please try again later.")
)
is AppError.Auth.SessionExpired -> ErrorAction.Navigate("login")
is AppError.Auth.Unauthorized -> ErrorAction.ShowMessage(
UiText.Raw("You don't have permission to perform this action.")
)
is AppError.Data.NotFound -> ErrorAction.ShowMessage(
UiText.Raw("Requested ${error.resource} was not found.")
)
is AppError.Data.Validation -> ErrorAction.ShowMessage(
UiText.Raw(formatValidationErrors(error.fields))
)
is AppError.Unknown -> ErrorAction.ShowMessage(
UiText.Raw("An unexpected error occurred.")
)
}
private fun formatValidationErrors(fields: Map<String, String>): String =
fields.entries.joinToString("\n") { (field, message) -> "$field: $message" }
}
Отсутствие интернета приводит к сообщению о проблемах с сетью, тайм-аут — к предложению повторить попытку, серверная ошибка — к соответствующему уведомлению, истёкшая сессия — к переходу на экран входа, а ошибки данных — к сообщениям о проблеме с конкретным ресурсом или валидацией.
Поскольку AppError представляет собой закрытую иерархию, компилятор Kotlin заставляет обработать все варианты. Если через месяц появится новый подтип AppError, все неполные выражения when перестанут компилироваться.
Это исключает тихие сбои и забытые сценарии.
При этом любой экран может предоставить собственную реализацию ErrorHandler. Пока она возвращает корректный ErrorAction для каждого AppError, она остаётся полноценной заменой стандартной реализации.
I — Interface Segregation: не заставляйте всех обрабатывать всё
Не каждому слою приложения нужно знать обо всех типах ошибок. Например, ViewModel, показывающая кэшированные статьи, не должна заниматься истёкшей сессией пользователя. Это ответственность глобального уровня приложения. Если заставлять каждого потребителя учитывать каждую возможную ошибку, будет нарушен принцип разделения интерфейсов.
Глобальная и экранная обработка
Обработка ошибок делится на два уровня.
@Singleton
class GlobalErrorHandler @Inject constructor() {
private val _errors = Channel<ErrorAction>(Channel.BUFFERED)
val errors: Flow<ErrorAction> = _errors.receiveAsFlow()
suspend fun dispatch(action: ErrorAction) {
_errors.send(action)
}
suspend fun dispatchAuth(error: AppError.Auth) {
val action = when (error) {
is AppError.Auth.SessionExpired -> ErrorAction.Navigate("login")
is AppError.Auth.Unauthorized -> ErrorAction.Navigate("unauthorized")
}
dispatch(action)
}
}
Глобальный обработчик занимается событиями, относящимися ко всему приложению, например авторизацией и сессией пользователя. Он может отправлять действия, которые затем перехватываются на уровне Activity.
В результате логика глобальных переходов или уведомлений подключается один раз.
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
@Inject lateinit var globalErrorHandler: GlobalErrorHandler
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
lifecycleScope.launch {
globalErrorHandler.errors.collect { action ->
when (action) {
is ErrorAction.Navigate -> navigateTo(action.route)
is ErrorAction.ShowMessage -> showSnackbar(action.message)
else -> Unit
}
}
}
}
}
Отдельные ViewModel обрабатывают только то, что относится непосредственно к их экрану. Ошибки авторизации передаются глобальному обработчику, а обычные экранные ошибки остаются локальными.
class ArticleListViewModel @Inject constructor(
private val getArticles: GetArticlesUseCase,
private val errorHandler: ErrorHandler,
private val globalErrorHandler: GlobalErrorHandler
) : ViewModel() {
fun load() {
viewModelScope.launch {
getArticles()
.onFailure { error ->
when (error) {
is AppError.Auth -> globalErrorHandler.dispatchAuth(error)
else -> _state.value = ArticleState.Error(errorHandler.handle(error))
}
}
.onSuccess { articles ->
_state.value = ArticleState.Loaded(articles)
}
}
}
}
Каждый слой занимается только своей зоной ответственности.
D — Dependency Inversion: зависим от абстракций, а не от Retrofit
Именно этот принцип позволяет превратить весь модуль в самостоятельную библиотеку.
Бизнес-логика не должна зависеть от HttpException из Retrofit, SQLiteException из Room или исключений любого другого конкретного фреймворка.
Граница safeCall
Репозиторий становится границей, на которой исключения конкретных фреймворков преобразуются в доменные ошибки.
suspend fun <T> safeCall(
mapper: ExceptionMapper,
block: suspend () -> T
): AppResult<T> = try {
AppResult.Success(block())
} catch (e: CancellationException) {
throw e
} catch (e: Exception) {
AppResult.Failure(mapper.map(e))
}
Операция выполняется в безопасной обёртке. Успешный результат превращается в AppResult.Success, обычные исключения проходят через ExceptionMapper, а CancellationException обязательно выбрасывается дальше.
Последний момент особенно важен: проглатывание CancellationException ломает структурированную конкурентность и является одной из наиболее распространённых ошибок обработки исключений в Android.
Репозиторий
Интерфейс репозитория работает только с абстракциями AppResult и AppError, принадлежащими доменному уровню.
interface UserRepository {
suspend fun getUser(id: String): AppResult<User>
suspend fun updateUser(user: User): AppResult<Unit>
}
В нём нет @Throws и нет упоминаний HttpException. Реализация скрывает конкретные детали используемых фреймворков.
class UserRepositoryImpl @Inject constructor(
private val api: UserApi,
private val dao: UserDao,
private val mapper: ExceptionMapper
) : UserRepository {
override suspend fun getUser(id: String): AppResult<User> =
safeCall(mapper) { api.getUser(id).toDomain() }
override suspend fun updateUser(user: User): AppResult<Unit> =
safeCall(mapper) { dao.update(user.toEntity()) }
}
Поэтому при переходе с Retrofit на Ktor или с Room на SQLDelight ViewModel, сценарии использования и общая логика обработки ошибок не меняются вообще. Достаточно написать новый ExceptionMapperPlugin и обновить реализацию репозитория.
Подключение через Hilt
Модуль предоставляет две конфигурации Hilt. Первая создаёт пустой набор плагинов, чтобы библиотека могла работать даже без каких-либо дополнительных преобразователей.
@Module
@InstallIn(SingletonComponent::class)
abstract class ErrorEmptyModule {
@Multibinds
abstract fun bindExceptionMapperPlugins(): Set<ExceptionMapperPlugin>
}
Вторая связывает стандартные реализации обработчиков и встроенный преобразователь Retrofit.
@Module
@InstallIn(SingletonComponent::class)
abstract class ErrorModule {
@Binds
abstract fun bindErrorHandler(impl: DefaultErrorHandler): ErrorHandler
@Binds
@IntoSet
abstract fun bindRetrofitMapper(impl: RetrofitExceptionMapperPlugin): ExceptionMapperPlugin
}
При этом модули приложения могут добавлять собственные плагины через многосвязывание Hilt, не изменяя core-error.
Как всё выглядит вместе
После интеграции модуля ViewModel становится значительно проще.
class UserProfileViewModel @Inject constructor(
private val getUser: GetUserUseCase,
private val errorHandler: ErrorHandler,
private val globalErrorHandler: GlobalErrorHandler
) : ViewModel() {
fun load(userId: String) {
viewModelScope.launch {
_state.value = UserProfileState.Loading
getUser(userId)
.onSuccess { user ->
_state.value = UserProfileState.Loaded(user)
}
.onFailure { error ->
when (error) {
is AppError.Auth -> globalErrorHandler.dispatchAuth(error)
else -> _state.value = UserProfileState.Error(
errorHandler.handle(error)
)
}
}
}
}
}
Она запускает сценарий использования, обновляет состояние при успехе, а при ошибке определяет только одно: относится ли ошибка к глобальному уровню приложения или должна быть обработана локально.
В результате код получается декларативным, а каждая ответственность находится в правильном слое. Блоков try-catch в ViewModel больше нет.
Структура модуля
Полный core-error разбит на несколько логических частей:
core-error/
├── build.gradle.kts
└── src/main/java/com/core/error/
├── model/
│ ├── AppError.kt — Sealed error hierarchy
│ ├── AppResult.kt — Success/Failure wrapper
│ ├── ErrorAction.kt — What the UI should do
│ └── UiText.kt — Localization-ready text
├── mapper/
│ ├── ExceptionMapper.kt — Central mapping engine
│ ├── ExceptionMapperPlugin.kt — Plugin interface (Open/Closed)
│ └── RetrofitExceptionMapperPlugin.kt — Built-in HTTP mapping
├── handler/
│ ├── ErrorHandler.kt — Screen-level handler interface
│ ├── DefaultErrorHandler.kt — Default implementation
│ └── GlobalErrorHandler.kt — App-wide auth/session handler
├── extension/
│ └── ResultExtensions.kt — map, flatMap, recover, getOrNull, etc.
├── util/
│ └── SafeCall.kt — safeCall with CancellationException safety
└── di/
├── ErrorModule.kt — Hilt bindings
└── ErrorEmptyModule.kt — Empty multibinding set
Такая структура делает обработку ошибок самостоятельной частью архитектуры, а не набором случайных try-catch по всему проекту.
Интеграция за три шага
Для подключения модуля нужно добавить его в проект, подключить как зависимость и затем использовать безопасную обёртку в репозиториях.
После этого все ошибки на границе слоя данных преобразуются в унифицированный AppResult, с которым уже работают остальные уровни приложения.
Что это даёт
После применения SOLID к обработке ошибок в нескольких реальных приложениях автор регулярно наблюдал одни и те же преимущества.
- Новые типы ошибок. Достаточно добавить новый подтип закрытой иерархии, и компилятор сам покажет все места, где он ещё не обработан.
- Новые фреймворки. Нужно написать один
ExceptionMapperPluginи зарегистрировать его. Существующий код менять не приходится. - Изменения интерфейса. Например,
Snackbarможно заменить на нижний лист исключительно в слое представления, не затрагивая бизнес-логику. - Миграции фреймворков. При переходе с Retrofit на Ktor изменяется только граница слоя данных.
- Тестирование. Преобразование ошибок, их обработку и отображение можно тестировать независимо друг от друга.
Обработка ошибок — не самая эффектная часть разработки. Но именно с этим кодом пользователь взаимодействует чаще всего, когда что-то идёт не так, а такие ситуации происходят регулярно.
Применение SOLID здесь — не избыточная архитектура. Это признание того, что негативные сценарии заслуживают такой же архитектурной проработки, как и успешные.
