[Server-side Kotlin] Using Kotlin’s Built-in Result Type for Error Management

<h1 id="introduction" data-line="1" class="code-line"><a class="header-anchor-link" href="#introduction" aria-hidden="true"></a> Introduction</h1>
Hello. My name is Shiode, and I do payment-related backend development in the Toyota Woven City Payment Solution Development Group. As mentioned in <a href="https://blog.kinto-technologies.com/posts/2022-09-27-kotlin-moshi/" target="_blank" rel="nofollow noopener noreferrer">my previous article</a>, our group uses Kotlin for development, with Ktor as our web framework and Exposed as the ORM. We also adopt Clean Architecture in our code architecture.
Initially, we used Kotlin's <a href="https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-result" target="_blank" rel="nofollow noopener noreferrer">Result type</a> for error handling, but as the number of developers increased, we started seeing a mix of Result and throw used in code. Mixing throw into code that uses Result defeats the purpose of expressing error handling through types, as it still requires try-catch blocks.
Since Kotlin doesn't have Java's checked exceptions, it's easy to forget to call a try-catch block, which can lead to unhandled errors. To improve this situation, we discussed within the team and decided to standardize our error handling using Kotlin's Result type.
In this article, I'll walk you through how our group writes error handling in practice.
This article does not include the following.
<ul data-line="13" class="code-line">
<li data-line="13" class="code-line">Explanation of Clean Architecture</li>
<li data-line="14" class="code-line">Explanation of Ktor and Exposed</li>
<li data-line="15" class="code-line">Comparison between <code>kotlin-result</code> and Kotlin's official Result type</li>
</ul>
<h2 id="application-directory-structure" data-line="17" class="code-line"><a class="header-anchor-link" href="#application-directory-structure" aria-hidden="true"></a> Application Directory Structure</h2>
Before getting into the main topic, I will explain the directory structure of the application in this group. Below is the well-known diagram of Clean Architecture along with our group's directory structure. As we've adopted Clean Architecture, our application's directory structure is generally organized in line with its principles.
<img src="/assets/blog/authors/reona-shiode/error-handling/CleanArchitecture.jpg" alt="Clean Architecture" /> (Source: <a href="https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html" target="_blank" rel="nofollow noopener noreferrer">The Clean Code Blog</a>)
<div class="code-block-container"><pre class="language-text"><code class="language-text code-line" data-line="23">App Route/
├── domain
├── usecase/
│ ├── inputport
│ └── interactor
└── adapter/
├── web/
│ └── controller
└── gateway/
├── db
└── etc
</code></pre></div>The correspondence between our directory structure and the Clean Architecture diagram is as follows:
<ul data-line="39" class="code-line">
<li data-line="39" class="code-line"><code>domain</code> directory: <code>entities</code></li>
<li data-line="40" class="code-line"><code>usecase</code> directory: <code>Use Cases</code></li>
<li data-line="41" class="code-line"><code>adapter/web/controller</code> directory: <code>Controllers</code></li>
<li data-line="42" class="code-line"><code>adapter/gateway</code> directory: <code>Gateways</code></li>
</ul>
The terminology doesn't match exactly, but basically the <code>domain</code> directory sits at the core, the <code>usecase</code> directory surrounds it, and everything under <code>adapter</code> forms the outermost layer.
Therefore, the allowed direction of dependency is as follows:
<ul data-line="48" class="code-line">
<li data-line="48" class="code-line"><code>usecase</code> -> <code>domain</code></li>
<li data-line="49" class="code-line">Everything under <code>adapter</code> -> <code>usecase</code> or <code>domain</code></li>
</ul>
This direction of dependency makes it possible to develop business logic without being affected by factors such as web frameworks or database types.
<h1 id="error-handling-policy" data-line="53" class="code-line"><a class="header-anchor-link" href="#error-handling-policy" aria-hidden="true"></a> Error Handling Policy</h1>
Basically, our error handling is based on the following policies:
<ul data-line="57" class="code-line">
<li data-line="57" class="code-line">Use Result type instead of throw in case of processing failure</li>
<li data-line="58" class="code-line">When a function returns a Result type, do not use throw</li>
<li data-line="59" class="code-line">When returning an exception, use a custom-defined exception type</li>
</ul>
In the next section, I'll go over each of these policies in more detail, with code examples.
<h2 id="use-the-result-type-when-a-function-may-fail" data-line="63" class="code-line"><a class="header-anchor-link" href="#use-the-result-type-when-a-function-may-fail" aria-hidden="true"></a> Use the Result type When a Function May Fail</h2>
Since Kotlin doesn't have checked exceptions like Java, there's no mechanism to force the caller to handle errors. By using the Result type, you can explicitly indicate that an error may be returned to the caller, reducing the chances of error handling being missed. However, in cases like <code>Result<Unit></code>, where the return value isn't used, error handling cannot be enforced unless a custom lint rule is defined. But as of now, we haven't defined one yet.
<h3 id="code-examples" data-line="67" class="code-line"><a class="header-anchor-link" href="#code-examples" aria-hidden="true"></a> Code Examples</h3>
Below is a simple code example. When defining a function that performs division, it typically results in an error if the denominator is zero. If a function might fail, specify Result as its return type. In this example, <code>Result<Int></code> is specified.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="70">fun divide(numerator: Int, denominator: Int) : Result<Int> {
if (denominator == 0) {
return Result.failure(ZeroDenominatorException())
}
return Result.success(numerator/denominator)
}
</code></pre></div><h2 id="when-returning-an-exception-as-a-result-type%2C-wrap-the-exception-in-a-custom-defined-exception" data-line="79" class="code-line"><a class="header-anchor-link" href="#when-returning-an-exception-as-a-result-type%2C-wrap-the-exception-in-a-custom-defined-exception" aria-hidden="true"></a> When Returning an Exception as a Result Type, Wrap the Exception in a Custom-defined Exception</h2>
Repositories are defined as interfaces in the domain layer, with their implementations residing in the adapter layer. If a use case layer calls a repository function and handles errors, and the adapter layer returns a third-party library exception as is, then the use case layer must be aware of that third-party exception. In that case, the use case layer becomes dependent on the adapter layer. Here's what that looks like in a diagram:
<img src="/assets/blog/authors/reona-shiode/error-handling/dependency.png" alt="依存関係" width="400" /> Interface-based Dependency and Exception-based Dependency (bad example)
To avoid this, we always make sure to wrap any exception returned via Result in a custom-defined exception.
One tricky point when applying Clean Architecture is deciding which layer exceptions belong to, but I personally think it should be in the domain layer. Our group uses a shared set of custom exceptions across multiple services, so we've extracted them into a separate domain library.
Another tricky point with Kotlin's official Result type is that it doesn't allow you to specify the exception type, which means you can't enforce returning only custom exceptions. In cases like this, it may be worth considering the use of <a href="https://github.com/michaelbull/kotlin-result" target="_blank" rel="nofollow noopener noreferrer"><code>kotlin-result</code></a>. However, we chose not to adopt it in order to avoid introducing third-party types into the domain code.
<h3 id="code-examples-1" data-line="91" class="code-line"><a class="header-anchor-link" href="#code-examples-1" aria-hidden="true"></a> Code Examples</h3>
Let's say the following interface is defined in the domain layer.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="95">data class Entity(val id: String)
interface EntityRepository {
fun getEntityById(id: String): Result<Entity>
}
</code></pre></div>Now, consider a case where a third-party library exposes a method like the one shown below, and it's used as-is.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="105">fun thirdPartyMethod(id: String): Entity {
throw ThirdPartyException()
}
</code></pre></div><h4 id="bad-example" data-line="111" class="code-line"><a class="header-anchor-link" href="#bad-example" aria-hidden="true"></a> Bad Example</h4>
If the implementation in the adapter layer returns the exception from the third-party library directly. As shown below, this causes it to leak into the caller such as <code>UseCase</code>.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="115">class EntityRepositoryImpl : EntityRepository {
override fun getEntityById(id: String): Result<Entity> {
return kotlin.runCatching {
thirdPartyMethod(id)
} // This returns the third party exception
}
}
</code></pre></div><h4 id="good-example" data-line="125" class="code-line"><a class="header-anchor-link" href="#good-example" aria-hidden="true"></a> Good Example</h4>
To prevent third-party exceptions from leaking to the caller, wrap them in a custom-defined exception.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="129">class EntityRepositoryImpl : EntityRepository {
override fun getEntityById(id: String): Result<Entity> {
return kotlin.runCatching {
thirdPartyMethod(id)
}.onFailure { cause ->
// wrap with our own exception
CustomUnexpectedException(cause)
}
}
}
</code></pre></div><h2 id="avoid-using-throw-in-functions-that-return-result" data-line="142" class="code-line"><a class="header-anchor-link" href="#avoid-using-throw-in-functions-that-return-result" aria-hidden="true"></a> Avoid Using <code>throw</code> in Functions that Return Result</h2>
If a function returns a Result type or throws an exception, the caller must handle both. Even if the function author thinks a particular exception doesn't need to be handled by the caller, there may be cases where the caller wants to handle it. For this reason, we have standardized on using the Result type and avoid throwing exceptions explicitly.
In some cases such as database connection errors, it might seem acceptable to throw an exception from the adapter layer and let it propagate directly to the API response, since recovery at the use case level is impossible. However, for issues like failure to update the database, we may still want to log inconsistencies with third-party SaaS. In that case, if we scope out using throw, there's a risk that alerts won't be triggered appropriately.
We believe it's up to the caller to decide whether error handling is necessary, so even if the function author considers it unnecessary, the exception is returned using a Result.
<h3 id="code-examples-2" data-line="150" class="code-line"><a class="header-anchor-link" href="#code-examples-2" aria-hidden="true"></a> Code Examples</h3>
Let's take the save function of a repository as an example. The save function receives the entity class and returns the result as a <code>Result<Entity></code>.
<h4 id="examples-of-what-not-to-do" data-line="154" class="code-line"><a class="header-anchor-link" href="#examples-of-what-not-to-do" aria-hidden="true"></a> Examples of what not to do</h4>
As shown below, assume that a connection error was thrown, while other errors are returned using the Result type.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="158">class EntityRepository(val db: Database) {
fun saveEntity(entity: Entity): Result<Entity> {
try {
db.connect()
db.save(entity)
} catch (e: ConnectionException) {
// return result instead
throw OurConnectionException(e)
} catch (e: throwable) {
return Result.failure(OurUnexpectedException(e))
}
return Result.success(entity)
}
}
</code></pre></div>Now, suppose the use case layer wants to take some kind of action if an error occurs during the save operation. In this case, you must use <code>runCatching</code> (which internally uses try-catch to convert to Result type).
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="177">class UseCase(val repo: EntityRepository) {
fun createNewEntity(): Result<Entity> {
val entity = Entity.new()
return runCatching { // need this runCatching in order to catch an exception
repo.saveEntity(entity).getOrThrow()
}.onFailure {
// some error handling here
}
}
}
</code></pre></div><h4 id="good-example-1" data-line="190" class="code-line"><a class="header-anchor-link" href="#good-example-1" aria-hidden="true"></a> Good Example</h4>
In the good example, all exceptions are wrapped in a custom-defined exception and returned using the Result type. This allows the caller to remove <code>runCatching</code>, simplifying the code.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="194">class EntityRepository(val db: Database) {
fun saveEntity(entity: Entity): Result<Entity> {
try {
db.connect()
db.save(entity)
} catch (e: ConnectionException) {
return Result.failure(OurConnectionException(e))
} catch (e: Exception) {
return Result.failure(OurUnexpectedException(e))
}
return Result.success(entity)
}
}
class UseCase(val repo: EntityRepository) {
fun createNewEntity(): Result<Entity> {
val entity = Entity.new()
return repo.saveEntity(entity).onFailure {
// some error handling here
}
}
}
</code></pre></div><h1 id="useful-custom-function-for-using-the-result-type" data-line="218" class="code-line"><a class="header-anchor-link" href="#useful-custom-function-for-using-the-result-type" aria-hidden="true"></a> Useful Custom Function for Using the Result Type</h1>
<h2 id="andthen" data-line="220" class="code-line"><a class="header-anchor-link" href="#andthen" aria-hidden="true"></a> <code>andThen</code></h2>
When using a Result type, there are often times when you want to use that value of a successful Result to return a different Result type. For example, updating the status of a specific entity might look like this:
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="224">fun UseCaseImpl.updataStatus(id: Id) : Result<Entity> {
val entity = repository.fetchEntityById(id).getOrElse {
return Result.failure(it)
}
val updatedEntity = entity.updateStatus().getOrElse {
return Result.failure(it)
}
return repository.save(updatedEntity)
}
</code></pre></div>In such cases, writing code becomes easier when the operations can be connected by a method chain. While the <code>kotlin-result</code> provides the <code>andThen</code> function for this purpose, Kotlin's official Result type does not. Therefore, our group defined and uses the following method:
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="238">inline fun <T, R> Result<T>.andThen(transform: (T) -> Result<R>): Result<R> {
if (this.isSuccess) {
return transform(getOrThrow())
}
return Result.failure(exceptionOrNull()!!)
}
</code></pre></div>By using this, the previous example can be rewritten as shown below. The result is a bit cleaner, with less repetitive code.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="249">fun UseCaseImpl.updataStatus(id: Id) : Result<Entity> {
return repository.fetchEntityById(id).andThen { entity ->
entity.updateStatus()
}.andThen { updatedEntity ->
repository.save(updatedEntity)
}
}
</code></pre></div><h2 id="dointransaction-for-exposed" data-line="259" class="code-line"><a class="header-anchor-link" href="#dointransaction-for-exposed" aria-hidden="true"></a> <code>doInTransaction</code> for Exposed</h2>
Our group uses <a href="https://github.com/JetBrains/Exposed" target="_blank" rel="nofollow noopener noreferrer">Exposed</a> as the ORMapper. With Exposed, all database operations must be written within the lambda scope called <code>transaction</code>. If an exception is thrown within this <code>transaction</code> scope, it automatically performs a rollback. Since using the Result type avoids throwing exceptions, we created a function that performs a rollback automatically when the Result indicates failure.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="263">fun <T> doInTransaction(db: Database? = null, f: () -> Result<T>): Result<T> {
return transaction(db) {
f().onFailure {
rollback()
}.onSuccess {
commit()
}
}
}
</code></pre></div>Applying this to the previous example of <code>UseCaseImpl</code>, it can be used as follows.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="277">fun UseCaseImpl.updataStatus(id: Id) : Result<Entity> {
return doInTransaction {
repository.fetchEntityByIdForUpdate(id).andThen { entity ->
entity.updateStatus()
}.andThen { updatedEntity ->
repository.save(updatedEntity)
}
}
}
</code></pre></div><h2 id="respondresult-for-ktor" data-line="289" class="code-line"><a class="header-anchor-link" href="#respondresult-for-ktor" aria-hidden="true"></a> <code>respondResult</code> for Ktor</h2>
Our group uses <a href="https://github.com/ktorio/ktor" target="_blank" rel="nofollow noopener noreferrer">Ktor</a> as the web framework. A function called <code>respondResult</code> was created to allow Result types from use cases to be returned directly as HTTP responses.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="293">suspend inline fun <reified T : Any> ApplicationCall.respondResult(code: HttpStatusCode, result: Result<T?>) {
result.onSuccess {
when (it) {
null, is Unit -> respond(code)
else -> respond(code, it)
}
}.onFailure {
// defined below
respondError(it)
}
}

suspend fun ApplicationCall.respondError(error: Throwable) {
val response = error.toErrorResponse()
val json = serializer.adapter(response.javaClass).toJson(response)
logger.error(json, error)

<span class="token function">respondText</span><span class="token punctuation">(</span>
    text <span class="token operator">=</span> json<span class="token punctuation">,</span>
    contentType <span class="token operator">=</span> ContentType<span class="token punctuation">.</span>Application<span class="token punctuation">.</span>Json<span class="token punctuation">,</span>
    status <span class="token operator">=</span> e<span class="token punctuation">.</span>errType<span class="token punctuation">.</span><span class="token function">toHttpStatusCode</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token punctuation">)</span>

}
</code></pre></div>Although it's simple, using this function eliminates the need to call <code>Result.getOrThrow</code>, making the code a bit cleaner.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="322">fun Route.route(useCase: UseCase) {
val result = useCase.run()
call.respondResult(HttpStatusCode.OK, result.map {it.toViewModel()} )
}
</code></pre></div>By the way, <code>respondError</code> is a function that returns an error response from the throwable. We use this function to handle exceptions thrown in the Ktor pipeline and return appropriate responses. We've also created a custom Ktor plugin to handle exceptions.
<div class="code-block-container"><pre class="language-kotlin"><code class="language-kotlin code-line" data-line="331">val ErrorHandler = createApplicationPlugin("ErrorHandler") {
on(CallFailed) { call, cause ->
call.respondError(cause)
}
}
</code></pre></div><h1 id="conclusion" data-line="339" class="code-line"><a class="header-anchor-link" href="#conclusion" aria-hidden="true"></a> Conclusion</h1>
I introduced how our group handles errors, along with some helpful custom functions for the Result type. From what I've seen in various tech blogs, many companies seem to use <code>kotlin-result</code>, while there's relatively little information out there on using Kotlin's official Result type. We've found Kotlin's official Result type to be sufficient for error handling, so we encourage you to give it a try!