try-catch

KO | EN

gitlite — search

#typescript #golang #go #rust #linux #docker #macos #windows #awesome #vue #awesome-list #pytorch #ios #openai

(★ 9)

A Kotlin extension that brings the elegance of `try-catch` to functional error handling—while **safely avoiding accidental capture of `CancellationException` in coroutines**. Use typed, chainable handlers with `runCatching` and never break structured concurrency again.

try-catch 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# try-catch

A Kotlin extension that brings the elegance of `try-catch` to functional error handling—while **safely avoiding accidental capture of `CancellationException` in coroutines**. Use typed, chainable handlers with `runCatching` and never break structured concurrency again.

[![Maven Central](https://img.shields.io/maven-central/v/io.github.scarlet-pan/try-catch?label=Maven%20Central)](https://central.sonatype.com/artifact/io.github.scarlet-pan/try-catch)
[![Kotlin 1.6+](https://img.shields.io/badge/Kotlin-1.6%2B-blue?logo=kotlin&logoColor=white)](https://kotlinlang.org/)
[![Test Status](https://github.com/Scarlet-Pan/try-catch/actions/workflows/test.yml/badge.svg)](https://github.com/Scarlet-Pan/try-catch/actions/workflows/test.yml)
[![License](https://img.shields.io/github/license/Scarlet-Pan/try-catch)](https://raw.githubusercontent.com/Scarlet-Pan/try-catch/main/LICENSE)

---

## 🤔 Why Use It?

In coroutine-based code, **handling exceptions without breaking structured concurrency is essential**. Consider these three approaches:

### ❌ Traditional `try-catch` — Swallows cancellation!

```kotlin
suspend fun fetchConfig(): Config = try {
    remoteConfigService.getConfig() // Suspending call that may throw IllegalStateException
} catch (e: Exception) { // ⚠️ Catches CancellationException — breaks structured concurrency!
    Log.w(TAG, "Failed to fetch config.", e)
    defaultConfig
}
```

### ⚠️ Using `catch` — Delicate API in coroutines

```kotlin
suspend fun fetchConfig(): Config = runCatching {
    remoteConfigService.getConfig() // Suspending call that may throw IllegalStateException
} catch { e -> // ❌ Avoid in coroutines: handles CancellationException (delicate API)
    Log.w(TAG, "Failed to fetch config.", e)
    defaultConfig
}
```

### ✅ Using `catchNonCancel` — Coroutine-safe recovery (recommended)

```kotlin
suspend fun fetchConfig(): Config = runCatching {
    remoteConfigService.getConfig() // Suspending call that may throw IllegalStateException
} catchNonCancel { e: IllegalStateException ->
    Log.w(TAG, "Invalid remote config state.", e)
    defaultConfig
} catchNonCancel { e ->
    Log.w(TAG, "Failed to fetch config.", e)
    defaultConfig
}
```

> 💡 **Best Practice**: Always prefer `catchNonCancel` over `catch` in `suspend` functions or any coroutine context.

---

## 📦 Install

Add the dependency to your `build.gradle.kts`:

```kotlin
dependencies {
    implementation("io.github.scarlet-pan:try-catch:1.0.0")
}
```

> ✅ Compatible with Kotlin 1.6+ and JVM 8+.  
> ✅ Requires `org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4` or higher.

---

## 🚀 Usage

### Basic Usage

```kotlin
runCatching {
    // do something
} catch { e: IOException ->
    handleIOException(e)
} catch { e ->
    handle(e)
}
```

Supports chaining multiple typed exception handlers. Crucially, it allows you to distinguish whether `kotlinx.coroutines.CancellationException` should be handled or left to propagate.

In coroutine contexts, **it is strongly recommended to use `catchNonCancel`** instead of `catch`, to avoid accidentally swallowing cancellation signals and breaking structured concurrency.

### Coroutine-Safe Handling with `catchNonCancel`

```kotlin
suspend fun fetchConfig(): Config = runCatching {
    remoteConfigService.getConfig() // Suspending call that may throw IllegalStateException
} catchNonCancel { e: IllegalStateException ->
    Log.w(TAG, "Invalid remote config state.", e)
    defaultConfig
} catchNonCancel { e ->
    Log.w(TAG, "Failed to fetch config.", e)
    defaultConfig
}
```

- If the exception is a `CancellationException`, it is rethrown immediately.
- Otherwise, the handler recovers with a fallback value.

---

## 📄 License

This project is licensed under the **MIT License** – see the [LICENSE](LICENSE) file for details.

<div align="center">
  <hr width="80%" />
  <p><em>—— 中文文档 Chinese Documentation ——</em></p>
  <hr width="80%" />
</div>
<br><br>

# try-catch（中文）

一种能像传统 `try-catch` 一样优雅处理异常的 Kotlin 扩展，在协程中**自动规避误捕获 `CancellationException` 的风险**，让你在使用 `runCatching` 时既能享受类型安全的链式异常处理，又不会意外中断协程取消流程。

[![Maven Central](https://img.shields.io/maven-central/v/io.github.scarlet-pan/try-catch?label=Maven%20Central)](https://central.sonatype.com/artifact/io.github.scarlet-pan/try-catch)
[![Kotlin 1.6+](https://img.shields.io/badge/Kotlin-1.6%2B-blue?logo=kotlin&logoColor=white)](https://kotlinlang.org/)
[![测试状态](https://github.com/Scarlet-Pan/try-catch/actions/workflows/test.yml/badge.svg)](https://github.com/Scarlet-Pan/try-catch/actions/workflows/test.yml)
[![许可证](https://img.shields.io/github/license/Scarlet-Pan/try-catch)](https://raw.githubusercontent.com/Scarlet-Pan/try-catch/main/LICENSE)

---

## 🤔 为什么使用它？

在协程代码中，**处理异常的同时不破坏结构化并发至关重要**。请看以下三种方式：

### ❌ 传统 `try-catch` — 会吞掉取消信号！

```kotlin
suspend fun fetchConfig(): Config = try {
    remoteConfigService.getConfig() // 可能抛出 IllegalStateException 的挂起调用
} catch (e: Exception) { // ⚠️ 会捕获 CancellationException — 破坏结构化并发！
    Log.w(TAG, "Failed to fetch config.", e)
    defaultConfig
}
```

### ⚠️ 使用 `catch` — 在协程中属于 delicate API

```kotlin
suspend fun fetchConfig(): Config = runCatching {
    remoteConfigService.getConfig() // 可能抛出 IllegalStateException 的挂起调用
} catch { e -> // ❌ 协程中应避免：会处理 CancellationException（delicate API）
    Log.w(TAG, "Failed to fetch config.", e)
    defaultConfig
}
```

### ✅ 使用 `catchNonCancel` — 协程安全的恢复方式（推荐）

```kotlin
suspend fun fetchConfig(): Config = runCatching {
    remoteConfigService.getConfig() // 可能抛出 IllegalStateException 的挂起调用
} catchNonCancel { e: IllegalStateException ->
    Log.w(TAG, "Invalid remote config state.", e)
    defaultConfig
} catchNonCancel { e ->
    Log.w(TAG, "Failed to fetch config.", e)
    defaultConfig
}
```

> 💡 **最佳实践**：在 `suspend` 函数或任何协程上下文中，始终优先使用 `catchNonCancel` 而非 `catch`。

---

## 📦 安装

在 `build.gradle.kts` 中添加依赖：

```kotlin
dependencies {
    implementation("io.github.scarlet-pan:try-catch:1.0.0")
}
```

> ✅ 兼容 Kotlin 1.6+ 和 JVM 8+。  
> ✅ 需要 `org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4` 或更高版本。

---

## 🚀 用法

### 基础用法

```kotlin
runCatching {
    // 执行某些操作
} catch { e: IOException ->
    handleIOException(e)
} catch { e ->
    handle(e)
}
```

支持链式调用多个类型化的异常处理器。关键在于：你可以明确区分是否应处理 `kotlinx.coroutines.CancellationException`。

在协程上下文中，**强烈建议使用 `catchNonCancel` 而非 `catch`**，以避免意外吞掉取消信号，破坏结构化并发。

### 使用 `catchNonCancel` 实现协程安全的异常处理

```kotlin
suspend fun fetchConfig(): Config = runCatching {
    remoteConfigService.getConfig() // 可能抛出 IllegalStateException 的挂起调用
} catchNonCancel { e: IllegalStateException ->
    Log.w(TAG, "Invalid remote config state.", e)
    defaultConfig
} catchNonCancel { e ->
    Log.w(TAG, "Failed to fetch config.", e)
    defaultConfig
}
```

- 若异常为 `CancellationException`，会立即重新抛出；
- 否则，通过处理器返回兜底值进行恢复。

---

## 📄 许可证

本项目采用 **MIT 许可证**，详情请参见 [LICENSE](LICENSE) 文件。

也欢迎随时告诉我！

try-catch

try-catch 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

try-catch

try-catch 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README