Companion object in Kotlin: cos'è, sintassi e utilizzo

Cos'è companion object in Kotlin?

companion object è un tipo speciale di dichiarazione object in Kotlin contrassegnato dalla parola chiave companion. Permette di dichiarare membri che appartengono alla classe piuttosto che alle sue istanze — cioè membri statici in termini Java. A differenza di Java, dove static è un modificatore per campi e metodi individuali, in Kotlin i membri statici sono raggruppati all'interno di un unico oggetto compagno.

Qualsiasi classe in Kotlin può contenere esattamente un companion object. I membri di questo oggetto sono accessibili tramite il nome della classe senza creare un'istanza: MyClass.method(). In termini di bytecode, un companion object viene compilato come una classe interna separata e i suoi metodi diventano metodi statici della classe esterna quando si utilizza l'annotazione @JvmStatic.

Secondo Google I/O 2024, companion object è diventato il modello principale per metodi factory, costanti e funzioni di utilità nelle moderne applicazioni Android scritte in Kotlin. Gli sviluppatori lo scelgono rispetto alle classi di utilità con funzioni a livello di pacchetto perché companion object mantiene una connessione logica con la classe proprietaria.

Utilizza companion object per raggruppare il contesto statico — costanti, factory, metodi di supporto che appartengono logicamente alla classe ma non richiedono un'istanza.

Sintassi di companion object: dichiarazione e accesso

La sintassi di base di companion object è semplice: la parola chiave companion viene posta prima della dichiarazione object all'interno della classe. Se non viene specificato un nome, l'oggetto riceve il nome Companion, a cui si può accedere esplicitamente o implicitamente.

class User {
    companion object {
        const val TABLE_NAME = "users"

        fun create(name: String): User {
            return User(name)
        }
    }

    val name: String
    constructor(name: String) { this.name = name }
}

// Access via class name
val table = User.TABLE_NAME
val user = User.create("Alice")

Nell'esempio sopra, TABLE_NAME e create() sono accessibili tramite User.TABLE_NAME e User.create(). Nota il modificatore const per le costanti primitive — garantisce l'inserimento del valore in fase di compilazione, simile a Java static final per primitivi e String.

Accesso implicito ed esplicito tramite Companion

Se un companion object non ha nome, è possibile accedervi tramite il nome automatico Companion: User.Companion.TABLE_NAME. In pratica questo è raramente necessario, ma utile quando si chiama da codice Java o quando si utilizza la riflessione.

// Both calls are equivalent
User.create("Bob")
User.Companion.create("Bob")

// Getting reference to companion object
val companion: User.Companion = User

Companion object nominato e caratteristiche

Un companion object può avere un nome, il che migliora la leggibilità del codice e permette di accedervi con un nome significativo. Factory è il nome più comune per un companion object usato come factory.

class HttpResponse {
    companion object Factory {
        fun ok(body: String): HttpResponse = HttpResponse(200, body)
        fun notFound(): HttpResponse = HttpResponse(404, "Not Found")
        fun serverError(): HttpResponse = HttpResponse(500, "Internal Error")
    }
}

// Access via Factory name
val response = HttpResponse.Factory.ok("data")

Un companion object nominato aiuta a documentare lo scopo dei membri statici. Nel refactoring, il nome rende il codice auto-documentante — lo sviluppatore vede immediatamente che Factory crea istanze di HttpResponse.

Limitazione: esattamente un companion object per classe

Una classe può contenere un solo companion object. Questa è una differenza fondamentale rispetto a Java, dove puoi dichiarare qualsiasi numero di campi e metodi statici senza raggruppamento. Se hai bisogno di più gruppi logici di membri statici, utilizza dichiarazioni object annidate senza companion.

Secondo la documentazione ufficiale di Kotlin (Kotlin Docs, 2025), la limitazione di un solo companion object è motivata dalla progettazione del linguaggio: i membri statici devono essere strettamente accoppiati con la classe e un oggetto compagno fornisce un confine chiaro per questa connessione. Se ci sono troppi membri statici, è un segnale per rifattorizzare la classe.

Companion object nelle interfacce

In Kotlin, anche le interfacce possono contenere un companion object. Ciò consente di definire metodi statici e costanti direttamente all'interno di un'interfaccia, cosa non possibile in Java. Questo approccio viene spesso utilizzato per dichiarare costanti relative all'interfaccia o metodi factory.

interface ApiService {
    companion object {
        const val BASE_URL = "https://api.example.com"
        const val TIMEOUT_MS = 5000

        fun create(client: OkHttpClient): ApiService =
            Retrofit.Builder()
                .baseUrl(BASE_URL)
                .client(client)
                .build()
                .create(ApiService::class.java)
    }
}

In questo esempio, BASE_URL, TIMEOUT_MS e create() appartengono all'interfaccia ApiService, non alle sue implementazioni. Questo è comodo: tutte le costanti e la logica factory per creare un'istanza del servizio API si trovano in un unico posto — all'interno dell'interfaccia stessa.

Le implementazioni dell'interfaccia non ereditano i membri del companion object — vengono chiamati solo tramite il nome dell'interfaccia: ApiService.BASE_URL.

@JvmStatic e @JvmField: compatibilità Java

Quando si chiamano metodi di companion object da codice Java, per impostazione predefinita sono accessibili come metodi della classe interna Companion, non come metodi statici della classe esterna. Per esportarli come veri metodi e campi statici per Java, usa l'annotazione @JvmStatic per i metodi e @JvmField per i campi.

class MathUtils {
    companion object {
        const val PI = 3.14159

        @JvmStatic
        fun square(x: Int): Int = x * x

        @JvmField
        val TAG: String = "MathUtils"
    }
}

// Called in Java as MathUtils.square(5), MathUtils.TAG

Si raccomanda di usare @JvmStatic per tutti i metodi pubblici di companion object che devono essere accessibili da codice Java. const si applica solo ai tipi primitivi e String — per altri tipi usa @JvmField.

Esempi pratici di utilizzo di companion object

Nei progetti reali, companion object viene utilizzato per diversi scenari standard. I metodi factory sono il modello più comune: invece di molteplici costruttori con firme diverse, si utilizzano metodi factory nominati nel companion object.

sealed class NetworkResult<out T> {
    data class Success<out T>(val data: T) : NetworkResult<T>()
    data class Error(val message: String) : NetworkResult<Nothing>()

    companion object {
        fun loading<T>(): NetworkResult<T> =
            Loading()
    }
}

private class Loading<T> : NetworkResult<T>()

companion object in NetworkResult fornisce un metodo factory loading() che crea un'istanza Loading con il tipo generico corretto. Senza questo metodo, dovresti creare un'istanza direttamente tramite Loading(), che espone l'implementazione interna.

Costanti e tag di logging

companion object viene spesso utilizzato per memorizzare costanti specifiche della classe. Le costanti dichiarate con const val vengono inserite in fase di compilazione, offrendo un overhead zero in fase di esecuzione.

class UserRepository {
    companion object {
        private const val TAG = "UserRepository"
        private const val CACHE_SIZE = 100
        private const val DEFAULT_PAGE_SIZE = 20
    }
}