java-knowledge

---

name: java-knowledge description: Base de conhecimento e fluxo de trabalho para Java e JVM em qualquer domínio — bibliotecas, backends (Spring Boot, Quarkus, Micronaut), JDBC/JPA, Kafka, CLI, JavaFX, Spark, aplicativos ML/LLM, jogos (libGDX, LWJGL), mods/plugins Minecraft (Fabric, NeoForge, Paper, mixins), embarcados. Use para qualquer pergunta sobre código Java, mesmo aquelas que parecem rápidas de responder de memória: escrever ou revisar Java; erros javac (limites incompatíveis, símbolo não encontrado) e exceções (ConcurrentModificationException); records, sealed types, pattern matching, streams; versões JDK e JEPs; builds Maven ou Gradle, Lombok/MapStruct que pararam de funcionar; Error Prone, NullAway, SpotBugs, Spotless; JUnit, Mockito, Testcontainers, JaCoCo; código lento, frames quentes no profiler, alocações, pausas GC, inicialização lenta; JMH, JFR, async-profiler; hangs e deadlocks, threads virtuais, CompletableFuture, commonPool, Modelo de Memória Java, FFM API; estrutura multi-módulo, JPMS; livros Java. Inclui uma biblioteca curada, templates verificados por CI e um pipeline de otimização medido.

Java: Base de Conhecimento e Pipeline

Este skill ajuda a escrever, revisar e otimizar código Java em qualquer domínio. Internamente, contém três coisas:

1. Base de Conhecimento. Livros, artigos, palestras, documentação, JEPs, bases de código e padrões organizados por categoria. Cada fonte é fornecida com link, autor, ano e uma explicação de por que deve ser lida.
2. Toolchain. Quais JDKs, ferramentas de build e analisadores instalar, quais comandos executar e em qual ordem. Templates de pom.xml, Gradle e CI são fornecidos e verificados.
3. Pipeline. Ordem de trabalho: testes antes do código, verificações de qualidade, benchmarks JMH, revisão, busca de soluções na biblioteca e nova medição.

Estado do conhecimento — novembro de 2026: JDK 27 (setembro de 2026) — último lançamento, JDK 25 — LTS atual, JDK 21 e 17 — LTS anteriores, JDK 28 sairá em março de 2027. Maven 3.9.16 e 3.10.0 (Maven 4 ainda RC), Gradle 9.9, JUnit 6.1, Spring Boot 4.1, Quarkus 3.40, JMH 1.37. Minecraft: 26.3 — último lançamento (setembro de 2026), 26.4 em snapshots; a partir de 26.1, o jogo não é mais ofuscado e requer Java 25.

Onde Olhar

Tarefa	Arquivo
Nova funcionalidade, refatoração ou otimização: ordem de trabalho	references/pipeline.md
Distribuições e versões JDK, instalação, Maven e Gradle, plugins, BOM, processadores de anotação, javac -Xlint, Error Prone, NullAway, SpotBugs, PMD, Spotless, OpenRewrite, segurança de dependências, ferramentas JDK, CI, templates	references/toolchain.md
JUnit 6, AssertJ, Mockito, Testcontainers, slices Spring Boot, testes baseados em propriedades e de contrato, JaCoCo, PIT, testes instáveis	references/testing.md
Código lento ou que consome muita memória: técnica por sintoma, JMH, JFR, JIT, GC, inicialização e aquecimento	references/performance.md — comece pela tabela "Sintoma → Técnica → Fonte"
Recursos da linguagem Java 17–28 por JEP, expressões idiomáticas, null e Optional, exceções, padrões e antipadrões, segurança, checklist de revisão	references/idioms-patterns.md
Estrutura do projeto, builds multimódulo, pacotes e JPMS, camadas e arquitetura hexagonal, DDD, ArchUnit, DI, evolução de API, bases de código de referência	references/architecture.md
Modelo de Memória, executors, CompletableFuture, locks, threads virtuais, concorrência estruturada, scoped values, bibliotecas reativas, FFM API, JNI, Unsafe, Vector API	references/concurrency-native.md
Domínios de servidor: Spring Boot, Quarkus, Micronaut, Helidon, REST e gRPC, JDBC, JPA e Hibernate, migrações, Kafka, observabilidade, segurança, containers e Kubernetes	references/domains-server.md
Outros domínios: publicação de bibliotecas, CLI e TUI, desktop, dados, aplicações ML e LLM, jogos, embarcados, WebAssembly, interop, scripts	references/domains-client.md
O que ler, blogs, palestras, podcasts, cursos, recursos em português, roteiro de aprendizado por níveis	references/books.md. Para uma pergunta genérica sobre livros, comece pelas seções "Lista rápida: 20 fontes principais" e "Roteiro de leitura por níveis"; abra as seções temáticas pelo índice. O arquivo é grande, não o leia por inteiro

Ramo Minecraft (Java Edition: mods e plugins de servidor, Minecraft 26.x e último 1.21.x):

Tarefa	Arquivo
Iniciar um mod: escolha do loader (Fabric, NeoForge, Forge, Quilt), versão do jogo e Java, Loom e ModDevGradle, multi-loader e multi-versão, publicação no Modrinth e CurseForge, builds de modpacks, CI, templates verificados	references/minecraft-modding.md
Código do mod: sides e threads, registries, componentes de dados, blocos, entidades, datagen, codecs, rede, eventos, mixins, access wideners e transformers, render, configurações, geração de mundo, migração para nova versão, checklist de revisão	references/minecraft-mod-api.md — o que quebrou no 26.x, veja na seção "O que quebrou no 26.x"
Lag, TPS e MSPT, FPS, memória, inicialização lenta; spark e JFR; benchmark de mundo /tick sprint; GameTest e testes unitários; análise de crash reports e conflitos de mods	references/minecraft-performance-testing.md — comece pela tabela "Sintoma → Técnica → Fonte"
Servidor: datapack, plugin ou mod; Paper, Folia, Velocity, Spigot, Sponge, Minestom; Polymer; Geyser e ViaVersion; engenharia e templates de plugins	references/minecraft-server-plugins.md
Documentação e sua atualidade, como ler tutoriais antigos, cursos, mods de referência por tipo, comunidade, roteiro de aprendizado	references/minecraft-resources.md

Cada referência começa com um índice. Leia apenas a seção necessária, não o arquivo inteiro.

Perguntas frequentes e seções com respostas:

Pergunta	Seção
Após migrar para JDK 23+, classes geradas desapareceram (Lombok, MapStruct, JMH), mas o build passa; outras falhas de build não óbvias	toolchain.md → "Armadilhas: resumo"
Qual comando executar para verificar o projeto antes de um merge	toolchain.md → "Verificações mínimas de qualidade"
O que aparece no perfil ou benchmark e o que fazer com isso	performance.md → "Sintoma → Técnica → Fonte"
Como escrever um benchmark que não minta	performance.md → "Benchmarks: JMH"
Como fazer profiling no Windows, Linux e macOS	performance.md → "Profiling"
Posso usar um recurso da linguagem na nossa versão JDK	idioms-patterns.md → "Versões da linguagem: Java 17–28"
Devo migrar o serviço para threads virtuais e o que verificar	concurrency-native.md → "Threads Virtuais", para Spring Boot 4 — também domains-server.md → "Frameworks e Runtimes"
Qual modelo de concorrência escolher sob carga	concurrency-native.md → "Escolha da ferramenta por carga"
O que mudou no Spring Boot 4, Jackson 3, Hibernate 7 e o que foi removido	domains-server.md → "Versões em novembro de 2026"
Endpoint lento, N+1, pool de conexões	domains-server.md → "Desempenho do servidor: sintomas"
Como dividir o projeto em módulos e fixar limites	architecture.md → "Regras curtas padrão"
Existe um livro ou edição específica?	books.md → "O que foi lançado, o que está em early access e o que não existe"
Minecraft: por onde começar um mod, projeto pronto com GameTest e CI	minecraft-modding.md → "Templates", escolha do loader — "Stack padrão"
Minecraft: tutorial antigo ou mod não compila no 26.x (modImplementation, remapJar, ResourceLocation, Yarn)	minecraft-modding.md → "O que está errado em tutoriais antigos", minecraft-mod-api.md → "O que quebrou no 26.x"
Minecraft: servidor lagando (MSPT, TPS), como encontrar a causa e provar que a correção ajudou	minecraft-performance-testing.md → "Sintoma → Técnica → Fonte", ordem de trabalho — pipeline.md → "Mods e Plugins Minecraft"
Minecraft: datapack, plugin ou mod; plugin Paper do zero	minecraft-server-plugins.md → "O que escolher: datapack, plugin ou mod", "Templates"

O script scripts/BenchCompare.java compara execuções JMH "antes" e "depois" através de seus JSONs, levando em conta o ruído entre execuções, e retorna código 1 em caso de regressão. Execute sem build: java BenchCompare.java <antes> <depois> no JDK 17+. Ele é necessário na etapa 11 do pipeline.

Para Minecraft, há mais dois scripts:

• scripts/tick_sprint_bench.sh — benchmark do servidor inteiro com o comando /tick sprint. O resultado é escrito no formato JMH JSON, portanto é comparado pelo mesmo BenchCompare.java;
• scripts/EmptyStructure.java — estrutura .nbt vazia para GameTest. Necessário no NeoForge, onde não há estrutura vazia própria.

Os scripts estão na pasta scripts/ junto com este SKILL.md. Quando instalado para todos os projetos, o caminho é ~/.claude/skills/java-knowledge/scripts/; quando instalado no projeto, é .claude/skills/java-knowledge/scripts/. Substitua este caminho nos comandos das referências.

Como Trabalhar

Para tarefas maiores que um único método, siga o pipeline:

1. Levantamento.
2. Plano e especificação.
3. Subtarefas.
4. Testes antes do código.
5. Isolamento em worktree.
6. Benchmarks.
7. Medição base e perfil.
8. Revisão.
9. Busca de soluções na biblioteca.
10. Otimização.
11. Nova medição.

Para pequenas correções, basta o modo curto do mesmo arquivo: teste, código, verificações, revisão.

Antes de declarar o trabalho como concluído, execute as verificações mínimas e mostre sua saída:

./mvnw -B -ntp verify                 # compilação com -Xlint -Werror, Error Prone e NullAway, testes, Spotless, limiar JaCoCo
./mvnw -B -ntp dependency:analyze
osv-scanner scan source -r .

No Gradle: ./gradlew build, ./gradlew buildHealth, osv-scanner scan source -r .. Os analisadores e limiares devem estar vinculados ao build — templates em toolchain.md. Se não houver no projeto, execute o que existe e informe quais verificações estão faltando. Se uma ferramenta não estiver instalada, sugira o comando de instalação de toolchain.md, não pule a etapa silenciosamente.

Ao otimizar:

• Meça primeiro, depois altere. Sem uma linha de base, não é possível afirmar que o código ficou mais rápido.
• Meça com JMH, não com System.nanoTime() em loop: o JIT elimina trabalho não utilizado. Em uma medição local, um cálculo com resultado descartado parecia 14 vezes mais barato do que realmente era.
• Faça 5 execuções "antes" e "depois" em JVMs separadas, alternando a ordem (ABBA). Execuções do mesmo jar variam de 12% a 22%.
• Sempre adicione -prof gc e observe gc.alloc.rate.norm (bytes por operação): essa métrica quase não tem ruído.
• Execute apenas um JMH por vez na máquina e não a sobrecarregue com outro trabalho durante a medição.
• Procure a técnica pelo sintoma em performance.md e indique a fonte junto com a alteração.
• Aceite a alteração somente se o benchmark mostrar um ganho significativo e os testes permanecerem verdes.

Ao revisar, use os checklists:

• idioms-patterns.md — para qualquer código;
• testing.md — para testes;
• concurrency-native.md — para código multi-thread, threads virtuais e código nativo;
• domains-server.md — para código de servidor, banco de dados e segurança;
• domains-client.md — para bibliotecas publicadas;
• architecture.md — para estrutura do projeto e limites de módulos.

Regras de Uso da Biblioteca

• Referencie a fonte. Ao recomendar um padrão ou otimização, forneça um link da referência. Assim, o usuário pode verificar o conselho e a solução não parece inventada.
• Considere as marcações. [obsoleto] significa que o material tem um substituto, indicado ao lado. [não verificado] significa que a afirmação veio de uma única fonte secundária; vale a pena verificar novamente antes de construir uma solução sobre ela.
• Verifique as versões. As versões são de novembro de 2026. Em 2025-2026, muitas versões principais com mudanças que quebram compatibilidade foram lançadas: Spring Boot 4 e Spring Framework 7 (starters renomeados, APIs removidas), Jackson 3 (pacotes tools.jackson), Hibernate 7, JUnit 6, Testcontainers 2 (novos artefatos e pacotes), google-java-format 2. A publicação via OSSRH foi encerrada em 30 de junho de 2025. Antes de decisões importantes, consulte o Maven Central, a documentação e as notas de versão.
• Considere a versão alvo do Java. Especifique maven.compiler.release ou toolchain no Gradle antes de sugerir recursos da linguagem. Nem todo padrão vale a pena se a base precisar rodar em JDK 17.