Kotlin برای برنامه‌نویس JavaKotlin for the Java Developer

Backend job posts today keep repeating one pattern: "Java or Kotlin". That "or" means the team does not expect you to have written Kotlin for years. It means that if you join tomorrow, open the repo and find half the services are .kt, you can read the code, fix a bug and say something useful in code review on day one.

The good news: Kotlin is not a new language you must learn from zero. Kotlin is the same JVM with a different language layer — the same bytecode, the same garbage collector, the same class loader, the same libraries, the same profiler, the same heap dumps. Everything you learned in jvm-internals about JIT and memory holds without a single change.

The trap is that many people see Kotlin as "Java with shorter syntax", and six months later they are writing code that looks like Kotlin but thinks like Java: classes full of var, !! on every other line, JPA entities declared as data class, and coroutines abandoned in GlobalScope. That is exactly what an interviewer is probing: did you internalise the mental model, or only the syntax?

This chapter teaches the language by contrast with Java: for every concept we first say what you did in Java and what hurt, then build Kotlin's answer.

JVM fundamentals live in jvm-internals, generics in generics, Java collections in collections, functional style in functional and modern-java, virtual threads in virtual-threads, and Reactor in reactive-reactor; here we only reference them.

1. Why Kotlin exists and how it relates to the JVM

Bytecode: the compiler's output — an intermediate language the JVM executes. kotlinc emits exactly the same .class format javac emits, which is why one module can hold .java and .kt side by side.

K2: the name of Kotlin's new compiler. Since Kotlin 2.0 it is the default and Stable for every target (JVM, Native, JS, Wasm); it is faster and has sharper type inference and smart casts. If you see old code fiddling with -Xuse-k2 flags, that is pre-2.0 archaeology.

Versions: the 2.x line is current — 2.2 (the Spring Boot 4 baseline), then 2.3 and 2.4. Binary-compatibility policy is strict: code compiled with 2.0 runs against later runtimes.

Kotlin/JVM vs Multiplatform: Kotlin compiles to the JVM, to machine code (Native), to JavaScript and to WebAssembly. For a backend team only Kotlin/JVM matters; the rest you only need to recognise in an interview.

Diagram: مسیر کامپایل Java و Kotlin به یک bytecode مشترک · Compilation path of Java and Kotlin into one shared bytecode.

flowchart LR
  A[".java sources"] --> B["javac"]
  C[".kt sources"] --> D["Kotlin K2 compiler"]
  B --> E[".class bytecode"]
  D --> E
  E --> F["JAR / fat JAR"]
  F --> G["JVM: classloader, JIT, GC"]
  H["kotlin-stdlib.jar"] --> F

kotlin-stdlib is just an ordinary Maven dependency. String.trimIndent(), List.map, Sequence, Result and Pair come from there. The official Gradle plugin adds it automatically; to manage it yourself set kotlin.stdlib.default.dependency=false in gradle.properties.

What pain did Kotlin actually cure? The real list, not the marketing one: (1) NullPointerException — nullability became part of the type system; (2) boilerplate — getters/setters/equals/hashCode/toString, which Java had no answer for until records and tolerated Lombok as a patch (lombok); (3) telescoping constructors and builders — solved by default and named arguments; (4) Utils classes — solved by extension functions; (5) readable concurrency — coroutines, years before virtual threads shipped.

2. Project setup

The build file itself is Kotlin (build.gradle.kts) — this is the "Kotlin DSL" you see in job ads. You get type safety and auto-completion. Gradle details are in build-tools.

// build.gradle.kts
import org.jetbrains.kotlin.gradle.dsl.JvmTarget

plugins {
    kotlin("jvm") version "2.2.20"
    kotlin("plugin.spring") version "2.2.20"   // all-open for Spring classes
    kotlin("plugin.jpa") version "2.2.20"      // no-arg for @Entity
    id("org.springframework.boot") version "3.5.6"
    id("io.spring.dependency-management") version "1.1.7"
}

dependencies {
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")

    testImplementation("io.mockk:mockk:1.14.11")
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2")
}

kotlin {
    jvmToolchain(21)
    compilerOptions {
        jvmTarget.set(JvmTarget.JVM_21)
        freeCompilerArgs.addAll(
            "-Xjsr305=strict",                        // treat JSR-305 annotations strictly
            "-Xannotation-default-target=param-property"
        )
    }
}

kotlin("jvm") is shorthand for the real plugin id org.jetbrains.kotlin.jvm; kotlin("plugin.spring") is org.jetbrains.kotlin.plugin.spring.

On Maven you add kotlin-maven-plugin with compile and test-compile executions and fill compilerPlugins with <plugin>spring</plugin> and <plugin>jpa</plugin> (plus the kotlin-maven-allopen and kotlin-maven-noarg dependencies).

Cheat-sheet: direct Java → Kotlin mapping

3. Interop: the headline of the whole story

If you only master one section of this chapter, make it this one. Teams do not start Kotlin in an empty codebase; they drop it next to 200,000 lines of Java.

3.1 Calling Java from Kotlin

A platform type is what Kotlin assigns to any value coming back from Java when no nullability annotation is present. It shows up in error messages with an exclamation mark: String! means "either String or String? — I do not know". You cannot write it by hand; only the compiler produces it.

// Java
public class LegacyRepo {
    public String findName(long id) { return null; }
}

val repo = LegacyRepo()

val a = repo.findName(1)          // type: String!  — the compiler allows it
val b: String = repo.findName(1)  // compiles, but throws NPE at runtime
val c: String? = repo.findName(1) // safe: you declared it may be null

println(a.length)                 // no warning, but NPE
println(c?.length)                // safe

Nullability annotations: if the Java code is annotated, Kotlin takes it seriously and stops producing platform types. The recognised set is wide: org.jspecify.annotations (the new, recommended standard), org.jetbrains.annotations, JSR-305 (javax.annotation), Android annotations, Eclipse, lombok.NonNull and RxJava 3.

-Xjspecify-annotations=strict        # strict is the default: violations are errors
-Xjsr305=strict                      # default is warn; use strict on a serious project
-Xnullability-annotations=@com.acme.annots:strict

Mapped types: java.lang.String becomes kotlin.String, int becomes Int, java.lang.Integer becomes Int?, java.lang.Object becomes Any!. No extra class is created in bytecode.

Collections: Kotlin has two interfaces — List<T> (read-only) and MutableList<T>. java.util.List<T> maps to (Mutable)List<T>!. Be careful though: "read-only" is not "immutable". If you take an ArrayList from Java and hold it as a List<T>, Java code can still mutate that same object. For a real guarantee either copy (toList()) or use persistent structures from kotlinx.collections.immutable.

Arrays: in Java arrays are covariant (Object[] o = new String[1]; blows up at runtime). In Kotlin Array<T> is invariant, and for primitives you get dedicated types that compile to int[], long[], double[] with no boxing:

val ids: IntArray = intArrayOf(1, 2, 3)    // int[] in bytecode
val names: Array<String> = arrayOf("a")     // String[]
// val objs: Array<Any> = names             // error: invariant

Checked exceptions: Kotlin treats no exception as checked. Call Files.readAllBytes(...) without try/catch and the compiler is happy. But that means more responsibility, not less: in Java the compiler forced you to think about IOException. The senior move: document error boundaries with KDoc @throws, and for domain logic use a sealed result or Result<T> instead of exceptions (exceptions).

SAM conversion: any Java interface with a single abstract method takes a lambda: executor.execute { println("in pool") }.

Generics: Foo<? extends Bar> becomes Foo<out Bar!>!, Foo<? super Bar> becomes Foo<in Bar!>!, and the raw type List becomes List<*>!. Variance details are in generics.

3.2 Calling Kotlin from Java

Here you have to design deliberately, or your API becomes ugly from the Java side.

Top-level functions: a function outside any class in StringUtils.kt compiles to a static method on a class named StringUtilsKt.

// file: StringUtils.kt
@file:JvmName("StringUtils")          // without this the class is called StringUtilsKt
package com.acme.text

fun slugify(input: String): String = input.lowercase().replace(' ', '-')

String s = com.acme.text.StringUtils.slugify("Hello World");

If you want several files to collapse into one facade, add @file:JvmMultifileClass.

object and companion object: object Foo is visible from Java as Foo.INSTANCE; a companion object as Foo.Companion.

class TokenService {
    companion object {
        const val HEADER = "Authorization"        // static final in bytecode

        @JvmStatic
        fun parse(raw: String): String = raw.removePrefix("Bearer ")

        @JvmField
        val DEFAULT_TTL: Duration = Duration.ofMinutes(15)
    }
}

String t   = TokenService.parse("Bearer abc");   // thanks to @JvmStatic
String h   = TokenService.HEADER;                // const is already static final
Duration d = TokenService.DEFAULT_TTL;           // thanks to @JvmField

@JvmOverloads: default arguments are a language feature; in bytecode only one method with a bitmask parameter is produced, and Java cannot use it. @JvmOverloads says "also generate a real overload for each combination".

class HttpClient @JvmOverloads constructor(
    private val baseUrl: String,
    private val timeout: Duration = Duration.ofSeconds(5),
    private val retries: Int = 3,
) {
    @JvmOverloads
    fun get(path: String, headers: Map<String, String> = emptyMap()): String = TODO()
}

@JvmName: resolves signature clashes after erasure, and prettifies names — on functions, and via @get:/@set: on properties:

fun List<String>.parseAll(): List<Int> = map { it.toInt() }

@JvmName("parseAllInts")
fun List<Int>.parseAll(): List<Int> = this

@get:JvmName("url")
@set:JvmName("setUrl")
var baseUrl: String = ""

@Throws: since Kotlin has no checked exceptions, the bytecode signature carries no throws clause and Java code cannot catch it (javac says "exception is never thrown").

@Throws(IOException::class)
fun writeReport(path: Path) { Files.writeString(path, "x") }

Getter/setter naming: var firstName: String becomes getFirstName()/setFirstName(). But a property starting with is has its own rule: val isOpen: Boolean becomes isOpen() — not getIsOpen().

internal and mangling: internal means "visible only inside this compilation module". Since the JVM has no such level, it becomes public in bytecode with a mangled name (e.g. doWork$app_main). So Java can call it. internal is an API-design tool, not a security boundary; for a hard boundary use JPMS or separate build modules.

Interface default methods: since Kotlin 2.2, interface functions with a body compile to Java default methods by default. Control it with -jvm-default: enable (default — default method plus a DefaultImpls compatibility class), no-compatibility (leaner) and disable (only DefaultImpls).

@JvmSuppressWildcards / @JvmWildcard: manual control over generated wildcards in generic signatures — for when Java wants a Box<Base> but Kotlin emitted Box<? extends Base>.

Diagram: مرز دو زبان و آنچه در هر جهت باید مراقبش باشی · The two-language boundary and what to watch in each direction.

flowchart TD
  subgraph K["Kotlin side"]
    K1["null-safe types"]
    K2["default args"]
    K3["top-level funs"]
    K4["companion object"]
  end
  subgraph J["Java side"]
    J1["platform types T!"]
    J2["@JvmOverloads needed"]
    J3["FileNameKt / @JvmName"]
    J4["Foo.Companion / @JvmStatic"]
  end
  K1 -. "annotate with JSpecify" .-> J1
  K2 --> J2
  K3 --> J3
  K4 --> J4

4. The language, by contrast with Java

4.1 val vs var

In Java you had to type final to get this behaviour, and nobody did. Kotlin inverted the equation: val is shorter than var.

val name = "ali"      // final String name = "ali";
var counter = 0       // int counter = 0;

val items = mutableListOf(1, 2)
items.add(3)          // allowed — val means the reference is not reassigned
// items = mutableListOf()  // error

A simple code-review rule: if you see more than two class-level vars in a PR, ask why. A method-local var is fine; a class-level var is mutable state that has to be explained in a multi-threaded environment (sync-locks-jmm). In Kotlin writing immutable code is so cheap that every var needs a reason.

4.2 Type inference

val n = 42                      // Int
val list = listOf("a", "b")     // List<String>
fun double(x: Int) = x * 2      // returns Int, expression body

The trap: fun findUser(id: Long) = repo.load(id) derives its return type from the implementation. If repo.load changes tomorrow, your public signature changes silently and consumers break at link time. The rule: write the return type explicitly on anything public. In library modules enforce it with explicitApi() inside the kotlin { } block.

4.3 Null safety in depth

var a: String = "abc"
// a = null                      // compile error
var b: String? = "abc"
b = null                          // allowed
// println(b.length)              // compile error

The tools, in the order you should prefer them:

val len1 = b?.length                       // safe call → Int?
val len2 = b?.length ?: 0                  // elvis: a default
val len3 = b?.length ?: return             // elvis + early return
val len4 = b?.length ?: error("no value")  // elvis + throw
val len5 = b!!.length                      // not-null assertion — a code smell

val city: String? = order?.customer?.address?.city   // safe chain
user.email?.let { mailer.send(it, subject = "welcome") }
val n = value as? Int ?: 0                 // safe cast instead of ClassCastException

lateinit is for properties you cannot initialise in the constructor (field injection, test setup) but which are non-null: @Autowired lateinit var repo: OrderRepository. It works only on var, only on non-primitive types, and not with custom accessors. You can check it with ::repo.isInitialized.

Diagram: درخت تصمیم برای برخورد با یک مقدار nullable · Decision tree for handling a nullable value.

flowchart TD
  A["value: T?"] --> B{"Can I give a sane default?"}
  B -- yes --> C["v ?: default"]
  B -- no --> D{"Is null a valid business case?"}
  D -- yes --> E["v?.let { ... } / early return"]
  D -- no --> F{"Is it a programming bug?"}
  F -- yes --> G["requireNotNull / checkNotNull with message"]
  F -- no --> H["Redesign the type: make it non-null"]

4.4 data class vs record

data class Money(val amount: BigDecimal, val currency: String)

val a = Money(BigDecimal("10.00"), "IRR")
val b = a.copy(currency = "USD")     // change exactly one field
val (amount, cur) = a                 // destructuring

The compiler generates equals(), hashCode(), toString(), copy() and componentN() — based on the properties in the primary constructor.

data class User(val id: Long) {
    var email: String = ""     // not in equals/hashCode/toString!
}
User(1).apply { email = "a@x" } == User(1).apply { email = "b@x" }  // true

4.5 sealed classes and interfaces

sealed means "the set of my subtypes is closed at compile time".

sealed interface PaymentResult {
    data class Approved(val txId: String) : PaymentResult
    data class Declined(val reason: String, val retryable: Boolean) : PaymentResult
    data object Timeout : PaymentResult          // singleton, since Kotlin 1.9
}

fun message(r: PaymentResult): String = when (r) {
    is PaymentResult.Approved -> "ok ${r.txId}"
    is PaymentResult.Declined -> if (r.retryable) "retry: ${r.reason}" else "failed"
    PaymentResult.Timeout     -> "timed out"
    // no else needed — the compiler knows every case is covered
}

Exhaustiveness means that when you add data object Fraud : PaymentResult tomorrow, every value-returning when stops compiling until you handle it. That is the best safety net you can get for domain modelling (ddd).

Guard conditions (Stable since Kotlin 2.2) attach an extra condition to a branch:

fun describe(r: PaymentResult): String = when (r) {
    is PaymentResult.Declined if r.retryable -> "transient decline"
    is PaymentResult.Declined                -> "hard decline"
    is PaymentResult.Approved                -> "approved"
    PaymentResult.Timeout                    -> "timeout"
}

when is an expression — that is its main difference from switch. And the subtle part: exhaustiveness is only enforced when when returns a value. Written as a statement, the compiler (depending on version) merely warns. So if you want the safety net, always return from when — even if the value is Unit. The common trick: val ignored: Unit = when (r) { ... }.

4.6 Smart casts

fun length(x: Any): Int {
    if (x is String) return x.length      // x is a String here, no cast
    if (x !is Collection<*>) return 0
    return x.size                          // smart cast after negation
}

Limitation: if the property is a class-level var (or open, or has a custom getter), the compiler cannot guarantee it did not change between the check and the use, so it reports "smart cast is impossible". The standard fix is to capture it in a local val.

class Box(var value: String?) {
    fun show() {
        val v = value ?: return    // local copy
        println(v.length)          // now it works
    }
}

K2 widened smart-cast coverage noticeably — variables captured in lambdas and combined || conditions now work.

4.7 Default and named arguments — the end of builders

In Java, a function with five optional parameters means either 32 overloads or a hundred-line builder.

fun createOrder(
    customerId: Long,
    currency: String = "IRR",
    discount: BigDecimal = BigDecimal.ZERO,
    notifyCustomer: Boolean = true,
    idempotencyKey: String? = null,
): Order = TODO()

createOrder(42)
createOrder(42, discount = BigDecimal("10"))
createOrder(customerId = 42, notifyCustomer = false, idempotencyKey = "k-1")

Named arguments fix readability at the call site — the problem you had in Java with doThing(true, false, true).

A senior rule: every Boolean in a public signature should be passed by name — many teams enforce this with detekt. Better still: replace the Boolean with a two-valued enum (Notify.YES/Notify.NO). That is the "remove the control parameter" pattern from solid-patterns, except here the language helps you.

4.8 Extension functions and properties

The Java problem: a StringUtils class of static methods, and calls like StringUtils.isBlank(s) instead of s.isBlank().

fun String.toSlug(): String =
    trim().lowercase().replace(Regex("[^a-z0-9]+"), "-").trim('-')

val String.isValidEmail: Boolean
    get() = matches(Regex("^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"))

"Hello World!".toSlug()      // "hello-world"

In bytecode an extension is a static method taking the receiver as its first parameter; nothing is added to the original class.

open class Base
class Derived : Base()
fun Base.name() = "base"
fun Derived.name() = "derived"

val x: Base = Derived()
println(x.name())     // "base" — not "derived"!

4.9 Scope functions

Five inline stdlib functions that all do the same thing — run a block in the context of an object — and differ on only two axes: how the object is referenced and what they return.

val len: Int = maybeName?.let { it.trim().length } ?: 0

val props = Properties().apply {
    setProperty("bootstrap.servers", "kafka:9092")
    setProperty("acks", "all")
}

val order = repo.save(newOrder).also { log.info("saved order {}", it.id) }

val url = config.run { "$scheme://$host:$port/$path" }

The trap is nesting. When you have three nested lets and the outer it is shadowed by an inner it, nobody can tell which is which. Two rules: name it in any nested lambda (?.let { user -> ... }), and never go more than two levels deep — extract a private function with a clear name instead.

4.10 Strings

val greet = "Hello, $name! len=${name.length}"

val json = """
    {
      "id": $id,
      "type": "order"
    }
""".trimIndent()

val path = """C:\Users\app"""     // no escaping

Need a literal $? Use ${'$'}, or multi-dollar interpolation (Stable since Kotlin 2.2): $$"cost is $price", where $price stays literal and you need $$ to interpolate.

4.11 Collections and Sequence

val nums = listOf(1, 2, 3, 4, 5)

val evens   = nums.filter { it % 2 == 0 }
val grouped = nums.groupBy { it % 3 }              // Map<Int, List<Int>>
val assoc   = nums.associateBy { it.toString() }   // Map<String, Int>
val first   = nums.firstOrNull { it > 3 }          // Int?
val (small, big) = nums.partition { it < 3 }
val windows = nums.windowed(size = 2, step = 1)
val chunks  = nums.chunked(2)

The key difference from Java Streams: Kotlin collection operations are eager. nums.filter{}.map{} allocates two intermediate lists. The lazy equivalent is Sequence:

val result = hugeList.asSequence()
    .filter { it.isActive }
    .map { it.toDto() }
    .take(10)
    .toList()                      // this is where it actually runs

4.12 Destructuring

val (x, y) = Point(1, 2)
for ((key, value) in mapOf("a" to 1)) { println("$key=$value") }
val (name, age) = "ali" to 30       // Pair

It is built on component1(), component2() … which data class generates; for other classes you declare them yourself with operator fun component1().

4.13 Operator overloading and infix

data class Money(val cents: Long) {
    operator fun plus(other: Money) = Money(cents + other.cents)
    operator fun times(k: Int) = Money(cents * k)
    operator fun compareTo(other: Money) = cents.compareTo(other.cents)
}

val total = Money(100) + Money(250)
if (Money(100) < Money(200)) { /* ... */ }

infix fun Int.upToBy(limit: Int): IntProgression = this..limit step 2
val r = 0 upToBy 10

operator works only on a predefined set of names (plus, minus, times, div, rem, get, set, contains, invoke, compareTo, rangeTo, …) — you cannot invent new operators, which is a good thing. The usage rule: Money + Money and Duration + Duration are excellent, User + Order is a crime. If the meaning is not obvious to an unfamiliar reader, write a named function. The same applies to infix — great in test DSLs (shouldBe), usually wrong in business logic.

4.14 Delegation

Three different things, all written with by.

1. by lazy — lazy, thread-safe initialisation:

val template: String by lazy { loadTemplateFromDisk() }   // computed once

The default is LazyThreadSafetyMode.SYNCHRONIZED. If you know it is single-threaded, by lazy(LazyThreadSafetyMode.NONE) { ... } is faster.

2. Delegates.observable / vetoable:

var status: String by Delegates.observable("NEW") { _, old, new ->
    log.info("status {} -> {}", old, new)
}
var quantity: Int by Delegates.vetoable(1) { _, _, new -> new > 0 }  // false rejects

3. Class delegation — "composition over inheritance" as a language feature:

interface Repository { fun findAll(): List<String> }

class DbRepository : Repository {
    override fun findAll() = listOf("a", "b")
}

class LoggingRepository(private val delegate: Repository) : Repository by delegate {
    override fun findAll(): List<String> {
        log.info("findAll called")
        return delegate.findAll()
    }
}

The compiler forwards every Repository method to delegate automatically and you override only what you care about — the Decorator pattern realised directly (solid-patterns). The trap: internal calls go to the delegate, not to your override — self-calls do not pass through the decorator. Exactly the famous Spring proxy problem from spring-core, only at the language level.

You can also write a custom property delegate, for example to read from a configuration map:

class ConfigDelegate(private val map: Map<String, String>) {
    operator fun getValue(thisRef: Any?, property: KProperty<*>): String =
        map[property.name] ?: error("missing config ${property.name}")
}

class AppConfig(map: Map<String, String>) {
    val databaseUrl: String by ConfigDelegate(map)
}

4.15 object, companion object, typealias and value class

object ConnectionPool {            // singleton, lazily and safely initialised
    fun acquire(): Connection = TODO()
}

class HttpClient private constructor(val url: String) {
    companion object {
        fun of(url: String) = HttpClient(url)
    }
}

val listener = object : EventListener {    // object expression = anonymous class
    override fun onEvent(e: Event) = println(e)
}

In bytecode an object is a class with a static final INSTANCE field initialised in <clinit> — the same safe singleton you used to build in Java with an enum or the holder idiom, for free. The selection rule: if it has no state and is not tied to a class → top-level function; if it is a factory or needs the class's private members → companion object; if it truly is a single stateful instance → object (and then you must think about thread safety and testability).

typealias UserId = Long
typealias Handler = (HttpRequest) -> HttpResponse

A typealias is only an alias and adds no type safety at all. For type safety use a value class (formerly inline class):

@JvmInline
value class UserId(val value: Long)

fun load(id: UserId) { }
// load(42L)              // compile error — exactly what you want
load(UserId(42))

A value class is erased at runtime in most positions, leaving only a long — type safety with no allocation cost. Exceptions: as a nullable, inside a collection, or in a generic position, boxing occurs.

But do not put value class on reflection-heavy boundaries. Spring Boot's documentation explicitly says support for value classes in @ConfigurationProperties is limited and you should use a data class; in JPA as a field type and on some serialization paths you will also see surprising behaviour. The right home for value class is the domain model and internal signatures.

4.16 inline, reified and visibility

inline fun <T> measure(name: String, block: () -> T): T {
    val start = System.nanoTime()
    try { return block() }
    finally { log.info("{} took {}ms", name, (System.nanoTime() - start) / 1_000_000) }
}

inline fun <reified T> ObjectMapper.readValue(json: String): T =
    readValue(json, T::class.java)

val order: Order = mapper.readValue(body)     // no need to pass Order::class.java

inline means the compiler copies the function body and its lambdas into the call site — so no lambda object is allocated, and a return inside the lambda can exit the enclosing function (non-local return). reified preserves the generic type at runtime and is only possible inside an inline function — exactly what Spring uses in its Kotlin extensions for RestClient and TestRestTemplate so you can drop ParameterizedTypeReference.

noinline prevents inlining of a specific parameter; crossinline forbids non-local returns when the lambda will run in another context.

Two important differences from Java: there is no "package-private" level — internal replaced it, and its unit is the module rather than the package; and Kotlin's protected does not include the package.

5. Coroutines, done properly

This is the main reason many teams switch, and the place Java developers get it wrong most often.

5.1 What suspend is

suspend fun fetchUser(id: Long): User {
    val profile = httpClient.get("/users/$id")     // suspension point
    val orders  = httpClient.get("/orders?u=$id")  // suspension point
    return User(profile, orders)
}

This code reads like blocking code but does not block a thread. The compiler rewrites it using CPS (Continuation-Passing Style): a hidden Continuation parameter is added to every suspend function and the body becomes a state machine that can return at each suspension point and resume later. In bytecode the signature looks roughly like:

Object fetchUser(long id, Continuation<? super User> $completion)

5.2 Structured concurrency

suspend fun loadDashboard(userId: Long): Dashboard = coroutineScope {
    val profile = async { userService.profile(userId) }
    val orders  = async { orderService.recent(userId) }
    val credit  = async { creditService.limit(userId) }
    Dashboard(profile.await(), orders.await(), credit.await())
}

coroutineScope creates a scope that does not return until all children complete, cancels every child if it is cancelled, and — if any child throws — cancels the siblings and rethrows to the caller. supervisorScope is the same with one difference: one child's failure does not cancel the others, which suits genuinely independent work.

Diagram: درخت structured concurrency و انتشار لغو و خطا · The structured-concurrency tree and how cancellation and failure propagate.

flowchart TD
  P["parent Job (coroutineScope)"] --> C1["child: async profile"]
  P --> C2["child: async orders"]
  P --> C3["child: async credit"]
  C2 -- "throws" --> P
  P -- "cancels" --> C1
  P -- "cancels" --> C3
  P -- "rethrows to caller" --> X["caller"]

5.3 Scopes, jobs and builders

A CoroutineScope is an object holding a CoroutineContext that defines coroutine lifetimes. A Job is the handle on a coroutine (cancel(), join(), state). A CoroutineContext is a Map-like set of Job, CoroutineDispatcher, CoroutineName and CoroutineExceptionHandler.

val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default + CoroutineName("worker"))

val job: Job = scope.launch { doWork() }         // fire-and-forget
val deferred: Deferred<Int> = scope.async { 42 } // produces a result

job.cancel()
scope.cancel()                                    // cancels every child

Diagram: چرخهٔ حیات یک Job · Lifecycle of a coroutine Job.

stateDiagram-v2
  [*] --> New: created lazily
  New --> Active: start()
  Active --> Completing: body finished
  Completing --> Completed: children done
  Active --> Cancelling: cancel() or child failure
  Completing --> Cancelling: failure
  Cancelling --> Cancelled: cleanup done
  Completed --> [*]
  Cancelled --> [*]

5.4 Dispatchers — which thread your code runs on

Dispatchers.IO shares threads with Dispatchers.Default; its limit is tunable through the system property kotlinx.coroutines.io.parallelism. Because the threads are shared, withContext(Dispatchers.IO) when you are already on Default usually does not switch threads at all — a deliberate optimisation in the library.

suspend fun report(): Report = coroutineScope {
    val rows = withContext(Dispatchers.IO) { jdbcTemplate.query(...) }  // blocking
    withContext(Dispatchers.Default) { heavyAggregate(rows) }           // CPU
}

val dbDispatcher = Dispatchers.IO.limitedParallelism(20)   // size of the connection pool
val legacySoap   = Dispatchers.IO.limitedParallelism(5)    // fragile service

5.5 Cancellation and error handling

Cancellation in coroutines is cooperative: nobody kills a thread. Every suspending library function (delay, withContext, await, …) is a cancellation point and throws CancellationException. But a pure CPU-bound loop is never cancelled unless you add isActive, ensureActive() or yield() yourself.

val job = scope.launch {
    while (isActive) { compute() }
}
job.cancel()

try {
    doWork()
} catch (e: CancellationException) {
    throw e                       // always rethrow
} catch (e: Exception) {
    log.error("failed", e)
}

5.6 Flow — cold streams

Flow<T> is the coroutine equivalent of an asynchronous stream. Cold means nothing happens until someone collects — just like Flux in Reactor, and unlike a Channel or SharedFlow.

fun orders(customerId: Long): Flow<Order> = flow {
    var page = 0
    while (true) {
        val batch = api.fetchPage(customerId, page++)   // suspend
        if (batch.isEmpty()) break
        batch.forEach { emit(it) }
    }
}

suspend fun report(customerId: Long) {
    orders(customerId)
        .filter { it.total > BigDecimal.TEN }
        .map { it.toDto() }
        .flowOn(Dispatchers.IO)          // affects only the upstream part
        .buffer(capacity = 64)           // decouples producer from consumer
        .catch { e -> log.error("stream failed", e) }
        .onEach { metrics.increment() }
        .collect { sink.write(it) }      // this is where it actually starts
}

Hot streams: StateFlow (always holds a current value, drops duplicates) and SharedFlow (broadcast to multiple collectors with configurable replay).

private val _health = MutableStateFlow(Health.UNKNOWN)
val health: StateFlow<Health> = _health.asStateFlow()
_health.value = Health.UP

5.7 Testing coroutines

@Test
fun `retries three times then fails`() = runTest {
    val client = FlakyClient(failures = 3)
    assertEquals("ok", withRetry(times = 3) { client.call() })
}

runTest uses a virtual scheduler: delay(10_000) is skipped instantly. That lets you test timeouts and backoff without a ten-second test. For finer control you have advanceTimeBy() and runCurrent().

6. An honest comparison: coroutines, virtual threads, Reactor

This is where a senior is separated from a mid-level engineer. "Coroutines are better" is the wrong answer.

7. Kotlin with Spring Boot

Spring Boot 4 and Spring Framework 7 set the Kotlin baseline at 2.2 and annotated their whole API with JSpecify; the Kotlin experience in Spring today is far cleaner than it was two years ago.

7.1 The two compiler plugins without which nothing works

Problem one: in Kotlin, classes and methods are final by default. For @Transactional, @Cacheable, @Async and AOP, Spring must create a subclass (a CGLIB proxy), and you cannot subclass a final class. The fix: the all-open compiler plugin, which automatically opens classes carrying given annotations. kotlin-spring is a ready-made preset of it covering @Component, @Configuration, @Service, @Repository, @Controller, @RestController, @Transactional, @Async and @Cacheable.

Problem two: JPA needs a no-argument constructor to instantiate entities reflectively, and Kotlin does not generate one. The fix: the no-arg plugin, which generates a synthetic zero-argument constructor. kotlin-jpa is its preset for @Entity, @Embeddable and @MappedSuperclass. That constructor is synthetic — you cannot call it from Kotlin or Java, only through reflection, which is exactly what Hibernate wants.

plugins {
    kotlin("plugin.spring") version "2.2.20"
    kotlin("plugin.jpa") version "2.2.20"
}

allOpen { annotation("com.acme.OpenForProxy") }        // custom annotation
noArg {
    annotation("com.acme.NoArgEntity")
    invokeInitializers = true                          // also run init blocks
}

7.2 The shape of a service

@SpringBootApplication
class ShopApplication

fun main(args: Array<String>) {
    runApplication<ShopApplication>(*args)
}

@Service
class OrderService(
    private val repository: OrderRepository,       // constructor injection, no @Autowired
    private val payments: PaymentGateway,
) {
    @Transactional
    fun place(cmd: PlaceOrder): Order =
        repository.save(Order(customerId = cmd.customerId, total = cmd.total))
}

runApplication<T>(*args) is a reified extension — the equivalent of SpringApplication.run(ShopApplication.class, args) without the class literal. Constructor injection is entirely natural in Kotlin: no @Autowired, no mutable fields, everything val and non-null. It is the same best practice from spring-core, except here the language forces you into it.

7.3 @ConfigurationProperties with a data class

@ConfigurationProperties("shop.payments")
data class PaymentProperties(
    val baseUrl: URI,
    val timeout: Duration = Duration.ofSeconds(5),
    val retries: Int = 3,
    val credentials: Credentials,
) {
    data class Credentials(val clientId: String, val clientSecret: String)
}

shop:
  payments:
    base-url: https://payments.internal/api
    timeout: 10s
    credentials:
      client-id: shop-svc
      client-secret: ${PAYMENTS_SECRET}

With a data class and vals, binding goes through the constructor (@ConstructorBinding is implicit), configuration becomes immutable, and Kotlin default values work. If a required value is missing from the YAML the application fails at startup — not three hours later in production with an NPE. Mark the main class with @ConfigurationPropertiesScan.

7.4 Coroutine controllers

@RestController
@RequestMapping("/api/orders")
class OrderController(private val service: OrderService) {

    @GetMapping("/{id}")
    suspend fun get(@PathVariable id: Long): OrderDto =
        service.find(id) ?: throw ResponseStatusException(HttpStatus.NOT_FOUND)

    @GetMapping(produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
    fun stream(): Flow<OrderDto> = service.streamAll()
}

Spring adapts suspend to Mono and Flow to Flux for you. suspend methods are also supported in plain MVC, where they run on the thread-per-request model.

7.5 Testing: MockK and Kotest

Why Mockito hurts in Kotlin: classes are final (you need mock-maker-inline), any() returns null which does not fit a non-null parameter, and mocking extension functions or objects is nearly impossible. MockK was written for Kotlin:

class OrderServiceTest {
    private val repo = mockk<OrderRepository>()
    private val service = OrderService(repo)

    @Test
    fun `saves order`() {
        every { repo.save(any()) } answers { firstArg<Order>().copy(id = 1) }

        val result = service.place(PlaceOrder(customerId = 7, total = BigDecimal.TEN))

        assertEquals(1L, result.id)
        verify(exactly = 1) { repo.save(any()) }
    }

    @Test
    fun `suspend calls work too`() = runTest {
        coEvery { repo.findAsync(1) } returns Order(id = 1)
        assertNotNull(service.findAsync(1))
    }
}

coEvery/coVerify handle suspend functions, mockkStatic handles static methods and mockkObject handles objects. In Spring, the SpringMockK library provides @MockkBean and @SpykBean, the equivalents of @MockitoBean and @MockitoSpyBean.

Kotest is an alternative test framework with several spec styles and fluent matchers:

class SlugSpec : StringSpec({
    "slugify lowercases and dashes" {
        "Hello World".toSlug() shouldBe "hello-world"
    }
})

7.6 Serialization, and one SQL note at the boundary

If jackson-module-kotlin is on the classpath, Spring Boot registers it automatically. Without it, Jackson does not understand Kotlin constructors or default values and — worse — can write null straight into a non-nullable property through reflection, producing an "impossible" NPE. Three defences: always have the Kotlin module; put @Valid and validation annotations on inbound DTOs (validation-mapstruct); and explicitly test deserialization of an incomplete payload. Details in jackson-json. Spring Boot 4 also ships a spring-boot-kotlinx-serialization-json starter; when it coexists with Jackson it only handles types annotated @Serializable.

One small but daily benefit of Kotlin is that raw SQL no longer has to be glued together with +:

SELECT id, total, created_at
FROM orders
WHERE customer_id = :cid
ORDER BY created_at DESC
OFFSET :skip LIMIT :take;

SELECT id, total, created_at
FROM orders
WHERE customer_id = :cid
ORDER BY created_at DESC
OFFSET :skip ROWS FETCH FIRST :take ROWS ONLY;

A small but frequent gotcha: you cannot call trimIndent() inside an annotation, because annotations accept only compile-time constants — so the multiline string inside @Query stays raw. Extra whitespace is harmless in SQL but not in whitespace-sensitive text. And the dialect differences remain what they always were; see sql-mastery and oracle-postgres-dialects.

8. Idiomatic style and the classic Java-developer mistakes

The list below is what you actually see over and over in real code reviews:

1. !! instead of thinking — every !! means "I silenced the compiler". Use ?:, requireNotNull with a message, or redesign the type.
2. Everything is var — Kotlin classes written exactly like Java POJOs. If your class is only data, make it a data class with vals.
3. A Utils class made of object — object StringUtils { ... } instead of extensions or top-level functions.
4. data class for JPA entities — the most dangerous item on this list.
5. Optional<T> instead of T? — an extra boxing layer and unreadable. Keep Optional only at the Java boundary and convert to T? immediately.
6. Nested if/else instead of when — when is both an expression and an exhaustiveness check.
7. Hand-rolled loops instead of collection operators.
8. GlobalScope.launch — in production, almost always a bug.
9. runBlocking in a service — throws away the entire benefit of coroutines.
10. Nested ?.let chains — more than two levels means it is time to extract a named function.
11. companion object as a static dumping ground — with 15 constants and 8 methods it is the old God class. File-level private const val and extensions are usually cleaner.
12. Ignoring internal — if you have modules, it draws the API boundary far more clearly than packages.
13. catch (e: Exception) without rethrowing CancellationException — a genuine bug in coroutine code.
14. apply for everything — apply is for configuration; if you want a value, use let or run.

9. A migration strategy for an existing codebase

Diagram: مسیر مهاجرت تدریجی از Java به Kotlin · Incremental migration path from Java to Kotlin.

flowchart LR
  A["1. Add Kotlin plugin<br/>zero .kt files"] --> B["2. New tests in Kotlin"]
  B --> C["3. New code in Kotlin<br/>leaf classes first"]
  C --> D["4. Convert DTOs, value objects,<br/>utils to Kotlin"]
  D --> E["5. Convert services<br/>keep entities last"]
  E --> F["6. Optional: coroutines<br/>only where they pay"]

Step 1 — add the plugin with zero Kotlin files. Just add kotlin("jvm") to the build and make sure CI stays green. Build time rises a little; measure exactly that and report it to the team. Zero risk, and it breaks the organisational resistance.

Step 2 — write new tests in Kotlin. Tests are consumers of the API, not part of it; if they break, production is unaffected. This is where the team learns data class, named arguments and multiline strings in the safest possible environment — and backtick test names are a nice carrot: fun `rejects order when credit limit exceeded`().

Step 3 — write new code in Kotlin, starting from the leaves. Classes with few dependencies that nobody inherits from.

Step 4 — convert DTOs, value objects and utility classes. The most benefit for the least risk. The IDE's "Convert Java File to Kotlin" is a fine starting point, but never merge its output unreviewed; it is usually full of !!, var and gratuitously nullable types.

Step 5 — convert services and the web layer; leave entities for last. Entities interact most with reflection and proxies and gain least from Kotlin.

Step 6 — introduce coroutines only where they pay for themselves. Migrating to coroutines is a separate architectural decision, not part of the language migration.

10. How to talk about Kotlin in an interview when Java is your main language

The biggest mistake is pretending to experience you do not have; the interviewer will find out in two questions. The winning approach has three parts.

Be honest and reframe. "My production experience is mostly Java. I can write services and tests in Kotlin and I know its mental model — null safety as part of the type system, coroutines as suspension rather than threads, and the fact that in Spring nothing works properly without the all-open and no-arg plugins. Since both run on the same JVM, my knowledge of GC, transactions and system design transfers unchanged." That sentence shows three things: honesty, real depth, and low hiring risk.

Pull the question toward your strong ground. If asked "how do coroutines work", explain CPS and then connect it to virtual threads and the thread model.

Have one real example ready, even a small personal project: "the first thing I learned was that @Transactional silently does nothing without the kotlin-spring plugin." That kind of detail proves you actually wrote code rather than read an article.

One more difference that burns people often: in Kotlin a == b compiles to a?.equals(b) ?: (b === null) — structural, null-safe equality — and referential equality is written ===. That is the exact opposite of Java. The good news: comparing Strings with == in Kotlin is correct. And never use === to compare values; on boxed Ints it depends on the JVM's small-value cache, the same Integer cache trap as Java.