Betreazen/java-knowledge

Java: biblioteca de conocimientos y pipeline de trabajo

Esta habilidad te ayuda a escribir, revisar y optimizar código Java en cualquier dominio. Incluye tres componentes principales:

1. Biblioteca de conocimientos. Libros, artículos, charlas, documentación, JEPs, bases de código y patrones organizados por categorías. Cada recurso incluye enlace, autor, año y una explicación de por qué es relevante.
2. Cadena de herramientas. Qué JDK, herramientas de compilación y analizadores instalar, qué comandos ejecutar y en qué orden. Se incluyen plantillas de pom.xml, Gradle y CI verificadas.
3. Pipeline. Secuencia de trabajo: pruebas antes del código, verificaciones de calidad, benchmarks JMH, revisiones, búsqueda de soluciones en la biblioteca y nueva medición.

Estado de conocimiento actualizado a noviembre de 2026: JDK 27 (septiembre de 2026) es la última versión, JDK 25 es la LTS actual, JDK 21 y 17 son LTS anteriores, JDK 28 se lanzará en marzo de 2027. Maven 3.9.16 y 3.10.0 (Maven 4 sigue en RC), Gradle 9.9, JUnit 6.1, Spring Boot 4.1, Quarkus 3.40, JMH 1.37. Minecraft: 26.3 es la última versión (septiembre de 2026), 26.4 está en snapshots; desde la 26.1, el juego no está ofuscado y requiere Java 25.

Dónde mirar

Tarea	Archivo
Nueva funcionalidad, refactorización u optimización: orden de trabajo	references/pipeline.md
Distribuciones y versiones de JDK, instalación, Maven y Gradle, plugins, BOM, procesadores de anotaciones, javac -Xlint, Error Prone, NullAway, SpotBugs, PMD, Spotless, OpenRewrite, seguridad de dependencias, herramientas JDK, CI, plantillas	references/toolchain.md
JUnit 6, AssertJ, Mockito, Testcontainers, slices de Spring Boot, pruebas basadas en propiedades y de contrato, JaCoCo, PIT, pruebas inestables	references/testing.md
Código lento o con alto consumo de memoria: técnicas por síntoma, JMH, JFR, JIT, GC, inicio y calentamiento	references/performance.md — comience con la tabla «Síntoma → Técnica → Recurso»
Características del lenguaje Java 17–28 por JEP, modismos, null y Optional, excepciones, patrones y antipatrones, seguridad, lista de verificación de revisión	references/idioms-patterns.md
Estructura del proyecto, compilaciones multimódulo, paquetes y JPMS, capas y arquitectura hexagonal, DDD, ArchUnit, DI, evolución de API, bases de código de referencia	references/architecture.md
Modelo de memoria, executors, CompletableFuture, locks, hilos virtuales, concurrencia estructurada, scoped values, librerías reactivas, FFM API, JNI, Unsafe, Vector API	references/concurrency-native.md
Ámbitos de servidor: Spring Boot, Quarkus, Micronaut, Helidon, REST y gRPC, JDBC, JPA e Hibernate, migraciones, Kafka, observabilidad, seguridad, contenedores y Kubernetes	references/domains-server.md
Otros ámbitos: publicación de librerías, CLI y TUI, escritorio, datos, aplicaciones ML y LLM, juegos, embebidos, WebAssembly, interoperabilidad, scripts	references/domains-client.md
Lecturas recomendadas, blogs, charlas, podcasts, cursos, recursos en español, ruta de aprendizaje por niveles	references/books.md. Para una pregunta general sobre libros, comience con las secciones «Lista corta: 20 recursos principales» y «Ruta de lectura por niveles»; para secciones temáticas, use la tabla de contenido. El archivo es grande, no lo lea completo

Rama de Minecraft (Java Edition: mods y plugins de servidor, Minecraft 26.x y última 1.21.x):

Tarea	Archivo
Cómo empezar un mod: elegir cargador (Fabric, NeoForge, Forge, Quilt), versión del juego y Java, Loom y ModDevGradle, multi-cargador y multi-versión, publicación en Modrinth y CurseForge, compilaciones de modpacks, CI, plantillas verificadas	references/minecraft-modding.md
Código de mod: lados y hilos, registros, componentes de datos, bloques, entidades, datagen, códecs, red, eventos, mixins, access wideners y transformers, renderizado, configuraciones, generación de mundo, migración a nueva versión, lista de verificación de revisión	references/minecraft-mod-api.md — para saber qué se rompió en 26.x, consulte la sección «Qué se rompió en 26.x»
Lag, TPS y MSPT, FPS, memoria, inicio lento; spark y JFR; benchmark de mundo /tick sprint; GameTest y pruebas unitarias; análisis de informes de crash y conflictos de mods	references/minecraft-performance-testing.md — comience con la tabla «Síntoma → Técnica → Recurso»
Servidor: datapack, plugin o mod; Paper, Folia, Velocity, Spigot, Sponge, Minestom; Polymer; Geyser y ViaVersion; ingeniería y plantillas de plugins	references/minecraft-server-plugins.md
Documentación y su actualidad, cómo leer tutoriales antiguos, cursos, mods de referencia por tipo, comunidad, ruta de aprendizaje	references/minecraft-resources.md

Cada guía comienza con una tabla de contenido. Lea solo la sección necesaria, no el archivo completo.

Preguntas frecuentes y secciones con respuesta:

Pregunta	Sección
Después de migrar a JDK 23+, faltan clases generadas (Lombok, MapStruct, JMH), pero la compilación funciona; otros fallos de compilación no obvios	toolchain.md → «Errores comunes: resumen»
¿Qué comando usar para verificar el proyecto antes de fusionar?	toolchain.md → «Verificaciones mínimas de calidad»
¿Qué se ve en un perfil o benchmark y qué hacer al respecto?	performance.md → «Síntoma → Técnica → Recurso»
Cómo escribir un benchmark que no mienta	performance.md → «Benchmarks: JMH»
Cómo perfilar en Windows, Linux y macOS	performance.md → «Perfilado»
¿Se puede usar una característica del lenguaje en nuestra versión de JDK?	idioms-patterns.md → «Versiones del lenguaje: Java 17–28»
¿Migrar el servicio a hilos virtuales y qué verificar?	concurrency-native.md → «Hilos virtuales», para Spring Boot 4, además domains-server.md → «Frameworks y runtimes»
¿Qué modelo de concurrencia elegir bajo carga?	concurrency-native.md → «Elección de herramienta según la carga»
¿Qué cambió en Spring Boot 4, Jackson 3, Hibernate 7 y qué se eliminó?	domains-server.md → «Versiones a noviembre de 2026»
Endpoint lento, N+1, pool de conexiones	domains-server.md → «Rendimiento del servidor: síntomas»
Cómo dividir un proyecto en módulos y fijar límites	architecture.md → «Reglas cortas por defecto»
¿Existe un libro o edición?	books.md → «Qué se ha publicado, qué está en early access y qué no existe»
Minecraft: por dónde empezar un mod, proyecto listo con GameTest y CI	minecraft-modding.md → «Plantillas», elección de cargador — «Stack por defecto»
Minecraft: tutorial antiguo o mod que no compila en 26.x (modImplementation, remapJar, ResourceLocation, Yarn)	minecraft-modding.md → «Qué es incorrecto en tutoriales antiguos», minecraft-mod-api.md → «Qué se rompió en 26.x»
Minecraft: el servidor tiene lag (MSPT, TPS), cómo encontrar la causa y demostrar que la corrección ayudó	minecraft-performance-testing.md → «Síntoma → Técnica → Recurso», orden de trabajo — pipeline.md → «Mods y plugins de Minecraft»
Minecraft: datapack, plugin o mod; plugin Paper desde cero	minecraft-server-plugins.md → «Qué elegir: datapack, plugin o mod», «Plantillas»

El script scripts/BenchCompare.java compara ejecuciones de JMH «antes» y «después» usando sus JSON, teniendo en cuenta el ruido entre ejecuciones, y devuelve código 1 si hay regresión. Se ejecuta sin compilación: java BenchCompare.java <antes> <después> en JDK 17+. Es necesario en el paso 11 del pipeline.

Para Minecraft hay dos scripts adicionales:

• scripts/tick_sprint_bench.sh — benchmark completo del servidor mediante el comando /tick sprint. El resultado se escribe en formato JSON de JMH, por lo que el mismo BenchCompare.java puede compararlo;
• scripts/EmptyStructure.java — estructura .nbt vacía para GameTest. Es necesaria en NeoForge, donde no hay una estructura vacía propia.

Los scripts están en la carpeta scripts/ junto a este SKILL.md. Al instalarlo para todos los proyectos, la ruta es ~/.claude/skills/java-knowledge/scripts/; al instalarlo en un proyecto, es .claude/skills/java-knowledge/scripts/. Use esta ruta en los comandos de las guías.

Cómo trabajar

Para tareas que abarquen más de un método, siga el pipeline:

1. Encuesta.
2. Plan y especificación.
3. Subtareas.
4. Pruebas antes del código.
5. Aislamiento en worktree.
6. Benchmarks.
7. Medición base y perfil.
8. Revisión.
9. Búsqueda de soluciones en la biblioteca.
10. Optimización.
11. Nueva medición.

Para correcciones menores, basta con el modo corto del mismo archivo: prueba, código, verificaciones, revisión.

Antes de declarar el trabajo como finalizado, ejecute las verificaciones mínimas y muestre su salida:

./mvnw -B -ntp verify                 # compilación con -Xlint -Werror, Error Prone y NullAway, pruebas, Spotless, umbral JaCoCo
./mvnw -B -ntp dependency:analyze
osv-scanner scan source -r .

En Gradle: ./gradlew build, ./gradlew buildHealth, osv-scanner scan source -r .. Los analizadores y umbrales deben estar vinculados a la compilación; las plantillas están en toolchain.md. Si no están en el proyecto, ejecute lo que haya y mencione qué verificaciones faltan. Si una herramienta no está instalada, sugiera el comando de instalación de toolchain.md, no omita el paso en silencio.

Al optimizar:

• Primero mida, luego modifique. Sin una línea base, no se puede afirmar que el código sea más rápido.
• Use JMH, no System.nanoTime() en un bucle: el JIT elimina el trabajo no utilizado. En una medición local, un cálculo con resultado descartado parecía 14 veces más barato que el real.
• Realice 5 ejecuciones «antes» y «después» en lanzamientos separados de la JVM, alternando el orden (ABBA). Las ejecuciones del mismo jar difieren entre un 12 y un 22%.
• Siempre agregue -prof gc y observe gc.alloc.rate.norm (bytes por operación): esta métrica tiene casi nada de ruido.
• Ejecute solo un JMH por máquina a la vez y no cargue la máquina con otro trabajo durante la medición.
• Busque la técnica por síntoma en performance.md e indique la fuente junto a la corrección.
• Acepte la corrección solo si el benchmark mostró una ganancia significativa y las pruebas siguen siendo verdes.

Al revisar, use las listas de verificación:

• idioms-patterns.md — para cualquier código;
• testing.md — para pruebas;
• concurrency-native.md — para código concurrente, hilos virtuales y código nativo;
• domains-server.md — para código de servidor, bases de datos y seguridad;
• domains-client.md — para librerías publicadas;
• architecture.md — para estructura del proyecto y límites de módulos.

Reglas de uso de la biblioteca

• Cite la fuente. Al recomendar un patrón u optimización, proporcione un enlace de la guía. Así el usuario puede verificar el consejo y la solución no parece inventada.
• Tenga en cuenta las anotaciones. [obsoleto] significa que el recurso tiene un reemplazo, que se indica junto a él. [no verificado] significa que la afirmación proviene de una única fuente secundaria; vale la pena verificarla antes de basar una solución en ella.
• Verifique las versiones. Las versiones están actualizadas a noviembre de 2026. En 2025-2026 se lanzaron muchas versiones principales con cambios disruptivos: Spring Boot 4 y Spring Framework 7 (starters renombrados, APIs eliminadas), Jackson 3 (paquetes tools.jackson), Hibernate 7, JUnit 6, Testcontainers 2 (nuevos artefactos y paquetes), google-java-format 2. La publicación a través de OSSRH se cerró el 30 de junio de 2025. Antes de tomar decisiones importantes, consulte Maven Central, la documentación y las notas de la versión.
• Considere la versión de Java objetivo. Verifique maven.compiler.release o toolchain en Gradle antes de sugerir una característica del lenguaje o API; consulte la tabla en idioms-patterns.md → «Versiones del lenguaje: Java 17–28».
• Use las guías paso a paso del pipeline en references/pipeline.md para cualquier tarea que no sea trivial.

Sobre esta guía

Este archivo es el punto de entrada. Todos los enlaces apuntan a la carpeta references/. La carpeta scripts/ contiene scripts auxiliares. Si la habilidad está instalada en el proyecto, las rutas relativas funcionan desde la raíz del proyecto; si está instalada globalmente, el agente debe ajustar las rutas según la sección «Scripts» anterior.

Mantenimiento y contribuciones

Si encuentra un error, un enlace roto o una versión desactualizada, cree un issue o pull request en el repositorio de la habilidad: github.com/Betreazen/java-knowledge. Las guías se actualizan junto con los lanzamientos de JDK, frameworks y Minecraft.