--- title: "Migração de Java para Kotlin: Guia Passo a Passo Completo | Kotlin Brasil" url: "https://kotlin.dev.br/guias/migracao-java-para-kotlin/" markdown_url: "https://kotlin.dev.br/guias/migracao-java-para-kotlin.MD" description: "Aprenda como migrar seu projeto Java para Kotlin de forma segura e gradual. Estratégias, ferramentas e melhores práticas de migração." date: "2025-07-08" author: "Karina Melo" --- # Migração de Java para Kotlin: Guia Passo a Passo Completo | Kotlin Brasil Aprenda como migrar seu projeto Java para Kotlin de forma segura e gradual. Estratégias, ferramentas e melhores práticas de migração. Migrar um projeto de Java para Kotlin é uma decisão estratégica que pode trazer benefícios significativos em termos de produtividade, segurança e manutenibilidade do código. No entanto, essa migração deve ser planejada e executada com cuidado para evitar problemas e garantir que a equipe acompanhe o processo. Neste guia, apresentamos uma abordagem passo a passo para realizar essa transição de forma segura e eficiente. ## Planejamento da Migração Antes de converter qualquer arquivo, é fundamental estabelecer um plano claro. A migração de Java para Kotlin não precisa ser feita de uma vez — na verdade, a abordagem gradual é fortemente recomendada pela própria JetBrains e pelo Google. ### Avaliação do Projeto Atual Comece avaliando o estado atual do seu projeto: - **Tamanho do codebase**: quantos arquivos Java existem e qual o nível de complexidade? - **Cobertura de testes**: testes automatizados são essenciais para garantir que a migração não introduza bugs - **Dependências**: verifique se todas as bibliotecas utilizadas são compatíveis com Kotlin - **Equipe**: quantos desenvolvedores precisam ser treinados em Kotlin? Uma boa prática é categorizar os arquivos por complexidade e prioridade. Arquivos simples como POJOs, utilitários e testes são candidatos ideais para começar. Modelos de domínio complexos e classes com lógica de negócio crítica devem ser migrados por último, quando a equipe já estiver confortável com a linguagem. ### Definindo a Estratégia Existem três estratégias principais para migração: | Estratégia | Descrição | Prós | Contras | |-----------|-----------|------|---------| | Big Bang | Migrar tudo de uma vez | Resultado rápido | Alto risco, muito esforço | | Gradual | Migrar arquivo por arquivo | Baixo risco, aprendizado contínuo | Processo mais longo | | Novos em Kotlin | Apenas código novo em Kotlin | Sem risco de regressão | Codebase misto por muito tempo | A recomendação para a maioria dos projetos é combinar as estratégias gradual e novos em Kotlin. Todo código novo é escrito em Kotlin, e arquivos Java existentes são migrados progressivamente conforme são modificados. Para uma introdução às diferenças entre as linguagens, consulte nosso [guia de Kotlin para desenvolvedores Java](/guias/kotlin-para-desenvolvedores-java/). ## Configurando o Projeto para Kotlin O primeiro passo técnico é adicionar o suporte a Kotlin no seu projeto. Para projetos que usam Gradle, as alterações são simples. ### Configuração do Gradle com Kotlin DSL ```kotlin // build.gradle.kts plugins { kotlin("jvm") version "2.0.0" kotlin("plugin.spring") version "2.0.0" // se usar Spring kotlin("plugin.jpa") version "2.0.0" // se usar JPA } dependencies { implementation("org.jetbrains.kotlin:kotlin-stdlib") implementation("org.jetbrains.kotlin:kotlin-reflect") // Testes testImplementation("org.jetbrains.kotlin:kotlin-test") } kotlin { jvmToolchain(17) } ``` ### Configuração do Maven ```kotlin // pom.xml - adicione o plugin Kotlin // // org.jetbrains.kotlin // kotlin-maven-plugin // 2.0.0 // ``` Após configurar o build system, certifique-se de que o projeto compila corretamente antes de iniciar qualquer conversão. Um projeto que já não compila em Java será muito mais difícil de migrar para Kotlin. ## Processo de Conversão Passo a Passo Com o projeto configurado e compilando, é hora de iniciar a conversão propriamente dita. Siga este processo para cada arquivo: ### Passo 1: Conversão Automática O IntelliJ IDEA oferece uma ferramenta de conversão automática de Java para Kotlin. Para usá-la, abra o arquivo Java e pressione `Ctrl+Alt+Shift+K` (ou vá em Code > Convert Java File to Kotlin File). A ferramenta faz um bom trabalho na conversão inicial, mas o resultado geralmente precisa de refinamento. ### Passo 2: Refinamento Manual Após a conversão automática, revise o código e aplique padrões idiomáticos de Kotlin: ```kotlin // Resultado da conversao automática (nao idiomático) class UsuarioService { fun buscarPorId(id: Long): Usuario? { val usuario: Usuario? = repositorio.findById(id).orElse(null) if (usuario != null) { return usuario } else { throw UsuarioNaoEncontradoException("Usuário $id nao encontrado") } } } // Versão idiomática em Kotlin class UsuarioService(private val repositorio: UsuarioRepository) { fun buscarPorId(id: Long): Usuario = repositorio.findById(id).orElseThrow { UsuarioNaoEncontradoException("Usuário $id nao encontrado") } } ``` ### Passo 3: Converter POJOs para Data Classes Uma das conversões mais impactantes é transformar POJOs Java em data classes Kotlin: ```kotlin // Antes: classe Java com getters, setters, equals, hashCode, toString // Depois: data class Kotlin data class Produto( val id: Long, val nome: String, val descricao: String?, val preco: Double, val ativo: Boolean = true ) ``` Observe como parâmetros nullable são marcados com `?` e valores padrão são definidos diretamente na declaração. Isso elimina a necessidade de builders e construtores telescópicos que são comuns em Java. ### Passo 4: Executar Testes Após cada conversão, execute toda a suíte de testes para garantir que nada foi quebrado. Essa é a razão pela qual uma boa cobertura de testes é pré-requisito para uma migração segura. Consulte nosso [guia de testes Android com Kotlin](/guias/testes-android-kotlin/) para estratégias de teste eficientes. ## Tratando Interoperabilidade Java-Kotlin Durante a migração, seu projeto terá uma mistura de arquivos Java e Kotlin. A interoperabilidade é excelente, mas existem alguns pontos de atenção. ### Anotações de Interoperabilidade Kotlin oferece anotações específicas para melhorar a interação com código Java: ```kotlin class UtilsKotlin { companion object { @JvmStatic fun formatar(texto: String): String = texto.trim().lowercase() @JvmField val VERSAO = "2.0" } // Gera overloads Java para parâmetros com valor padrao @JvmOverloads fun configurar( nome: String, timeout: Int = 30, retry: Boolean = true ) { // implementacao } } ``` ### Lidando com Nullability do Código Java Quando código Kotlin chama código Java, os tipos retornados são tratados como "platform types" (tipos de plataforma), representados por um `!` no compilador. Isso significa que Kotlin não sabe se o valor pode ser null ou não: ```kotlin // Código Java retorna String (platform type: String!) val resultado = javaService.buscarNome() // Boa pratica: declare explicitamente a nullability esperada val resultadoSeguro: String? = javaService.buscarNome() // Ou use operador non-null assertion se tiver certeza val resultadoCerto: String = javaService.buscarNome()!! ``` Recomendamos adicionar anotações `@Nullable` e `@NotNull` ao código Java que ainda não foi migrado para facilitar a interoperação. Consulte o [glossário](/glossario/) para mais detalhes sobre platform types. ## Padrões Comuns de Migração Alguns padrões de código Java possuem equivalentes idiomáticos em Kotlin que vale a pena conhecer. ### Singleton Pattern ```kotlin // Java: classe com construtor privado e instância estática // Kotlin: object declaration object DatabaseConfig { val url = "jdbc:postgresql://localhost:5432/db" val driver = "org.postgresql.Driver" fun conexao(): Connection { return DriverManager.getConnection(url) } } ``` ### Builder Pattern ```kotlin // Em Kotlin, builders podem ser substituídos por parâmetros nomeados e padrao data class HttpRequest( val url: String, val method: String = "GET", val headers: Map = emptyMap(), val body: String? = null, val timeout: Int = 30000 ) // Uso com argumentos nomeados val request = HttpRequest( url = "https://api.exemplo.com/usuarios", method = "POST", body = """{"nome": "Maria"}""", timeout = 5000 ) ``` ### Streams API para Kotlin Collections ```kotlin // Java Streams // list.stream().filter(x -> x > 10).map(x -> x * 2).collect(Collectors.toList()) // Kotlin (mais conciso e nao precisa de .stream() nem .collect()) val resultado = list.filter { it > 10 }.map { it * 2 } ``` ## Ferramentas e Automação Além da conversão automática da IDE, existem ferramentas que auxiliam no processo de migração: - **Detekt**: análise estática para Kotlin, equivalente ao Checkstyle/PMD em Java - **ktlint**: formatador de código Kotlin que garante consistência - **Gradle Kotlin DSL**: migre seus scripts de build de Groovy para Kotlin DSL - **kotlinx.serialization**: substitui bibliotecas como Gson e Jackson com serialização nativa de Kotlin Para integrar essas ferramentas no seu pipeline de entrega contínua, confira nosso [guia de CI/CD para Kotlin](/guias/ci-cd-kotlin/). ## Cronograma e Métricas Estabeleça métricas para acompanhar o progresso da migração: 1. **Percentual de arquivos Kotlin**: monitore a proporção de arquivos `.kt` vs `.java` 2. **Cobertura de testes**: garanta que a cobertura não diminua durante a migração 3. **Bugs reportados**: acompanhe se a migração está introduzindo regressões 4. **Velocidade da equipe**: meça se a produtividade está aumentando conforme mais código é convertido Um cronograma realista para um projeto de tamanho médio (50-200 arquivos Java) é de três a seis meses para migração completa usando a abordagem gradual. Projetos maiores podem levar mais tempo, mas os benefícios começam a aparecer desde as primeiras conversões. ## Conclusão A migração de Java para Kotlin é um investimento que se paga rapidamente em termos de produtividade, segurança e satisfação da equipe de desenvolvimento. A chave do sucesso está em adotar uma abordagem gradual, manter boa cobertura de testes e treinar a equipe adequadamente. Comece pelos arquivos mais simples, estabeleça padrões de código Kotlin desde o início e aproveite a interoperabilidade total para migrar no ritmo que fizer sentido para o seu projeto. Se você também considera outras linguagens modernas, Go oferece simplicidade e alta performance para backend, enquanto Rust garante segurança de memória sem garbage collector. Para mais recursos práticos, explore nossos [tutoriais](/tutoriais/) e consulte o [glossário de termos Kotlin](/glossario/).