Companion object em Kotlin: o que é, sintaxe e uso

O que é companion object em Kotlin?

companion object é um tipo especial de object declaration em Kotlin marcado com a palavra-chave companion. Ele permite declarar membros que pertencem à classe em vez de suas instâncias — ou seja, membros estáticos em termos Java. Diferente do Java, onde static é um modificador para campos e métodos individuais, em Kotlin os membros estáticos são agrupados dentro de um único objeto companheiro.

Qualquer classe em Kotlin pode conter exatamente um companion object. Os membros deste objeto são acessíveis através do nome da classe sem criar uma instância: MyClass.method(). Em termos de bytecode, um companion object é compilado como uma classe interna separada, e seus métodos tornam-se métodos estáticos da classe externa ao usar a anotação @JvmStatic.

De acordo com o Google I/O 2024, companion object tornou-se o padrão principal para métodos fábrica, constantes e funções auxiliares em aplicativos Android modernos escritos em Kotlin. Os desenvolvedores o escolhem em vez de classes utilitárias com funções de nível de pacote porque companion object mantém uma conexão lógica com a classe proprietária.

Use companion object para agrupar contexto estático — constantes, fábricas, métodos auxiliares que pertencem logicamente à classe mas não requerem uma instância.

Sintaxe do companion object: declaração e acesso

A sintaxe básica do companion object é simples: a palavra-chave companion é colocada antes da declaração object dentro da classe. Se nenhum nome for especificado, o objeto recebe o nome Companion, que pode ser acessado explícita ou 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")

No exemplo acima, TABLE_NAME e create() são acessíveis via User.TABLE_NAME e User.create(). Observe o modificador const para constantes primitivas — ele garante a inserção do valor em tempo de compilação, similar ao Java static final para primitivos e String.

Acesso implícito e explícito via Companion

Se um companion object não tem nome, pode ser acessado através do nome automático Companion: User.Companion.TABLE_NAME. Na prática isso raramente é necessário, mas é útil ao chamar código Java ou ao usar reflexão.

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

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

Companion object nomeado e características

Um companion object pode ter um nome, o que melhora a legibilidade do código e permite acessá-lo por um nome significativo. Factory é o nome mais comum para um companion object usado como fábrica.

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")

Um companion object nomeado ajuda a documentar o propósito dos membros estáticos. Em refatoração, o nome torna o código autodocumentável — o desenvolvedor vê instantaneamente que Factory cria instâncias de HttpResponse.

Limitação: exatamente um companion object por classe

Uma classe pode conter apenas um companion object. Esta é uma diferença fundamental do Java, onde você pode declarar qualquer número de campos e métodos estáticos sem agrupamento. Se precisar de múltiplos grupos lógicos de membros estáticos, use declarações object aninhadas sem companion.

De acordo com a documentação oficial do Kotlin (Kotlin Docs, 2025), a limitação de um companion object é motivada pelo design da linguagem: membros estáticos devem estar fortemente acoplados à classe, e um objeto companheiro fornece um limite claro para essa conexão. Se houver muitos membros estáticos, é um sinal para refatorar a classe.

Companion object em interfaces

Em Kotlin, as interfaces também podem conter um companion object. Isso permite definir métodos estáticos e constantes diretamente dentro de uma interface, algo impossível em Java. Esta abordagem é frequentemente usada para declarar constantes relacionadas à interface ou métodos fábrica.

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)
    }
}

Neste exemplo, BASE_URL, TIMEOUT_MS e create() pertencem à interface ApiService, não às suas implementações. Isso é conveniente: todas as constantes e a lógica de fábrica para criar uma instância do serviço API estão localizadas em um só lugar — dentro da própria interface.

As implementações da interface não herdam os membros do companion object — eles são chamados apenas através do nome da interface: ApiService.BASE_URL.

@JvmStatic e @JvmField: compatibilidade com Java

Ao chamar métodos de companion object do código Java, por padrão eles são acessíveis como métodos da classe interna Companion, não como métodos estáticos da classe externa. Para exportá-los como métodos e campos estáticos reais para Java, use a anotação @JvmStatic para métodos e @JvmField para campos.

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

Recomenda-se usar @JvmStatic para todos os métodos públicos de companion object que devem ser acessíveis a partir de código Java. const aplica-se apenas a tipos primitivos e String — para outros tipos use @JvmField.

Exemplos práticos de uso do companion object

Em projetos reais, companion object é usado para vários cenários padrão. Métodos fábrica são o padrão mais comum: em vez de múltiplos construtores com assinaturas diferentes, usam-se métodos fábrica nomeados no 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 em NetworkResult fornece um método fábrica loading() que cria uma instância Loading com o tipo genérico correto. Sem este método, você teria que criar uma instância diretamente via Loading(), o que expõe a implementação interna.

Constantes e tags de logging

companion object é frequentemente usado para armazenar constantes específicas da classe. Constantes declaradas com const val são inseridas em tempo de compilação, proporcionando zero overhead em tempo de execução.

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