En este blog nos tomamos la tecnología muy en serio, y para la sección de Código & Tech quise asegurarme de traerte solo lo mejor. Por eso, me senté con el ingeniero de la casa (mi esposo) para filtrar juntos esos conceptos técnicos que a veces parecen indescifrables. Queremos hablarte de arquitecturas, desarrollo y herramientas de forma directa, sin rodeos y con ejemplos reales que sirvan para tu día a día o tus proyectos como freelance. Preparamos este contenido con mucho cuidado y, además, ¡te dejamos un regalo al final! Vamos a descubrirlo. 💜
Mi esposo me contaba que lo que cambió radicalmente su forma de trabajar en proyectos de gran escala fue aprender a combinar tres piezas clave: la programación reactiva en Java, microservicios organizados con Vertical Slicing y el uso estratégico de la Inteligencia Artificial. El gran truco que implementó fue equipar a la IA con una “skill” o instrucción avanzada. Así, el código que genera la herramienta no parece el de un programador junior con prisa, sino el de un desarrollador senior que conoce al detalle las reglas y estándares de la casa. Hoy desglosaremos este método para que tú también puedas aplicarlo.
Parte 1: ¿Qué es la programación reactiva y por qué debería importarte?
Imagina un restaurante con un solo mesero. En el modelo tradicional (bloqueante), el mesero toma tu pedido, va a la cocina, se queda parado mirando al chef hasta que el plato sale, te lo trae, y solo entonces atiende la siguiente mesa. Si la cocina se demora, todo el restaurante se paraliza.
En el modelo reactivo, el mesero toma tu pedido, lo deja en la cocina y de inmediato va a atender otras mesas. Cuando la cocina avisa “¡pedido listo!”, él reacciona y te lo trae. Un solo mesero atiende decenas de mesas sin quedarse bloqueado esperando.
En Java, ese modelo se implementa con Project Reactor (la base de Spring WebFlux) y dos tipos protagonistas:
Mono<T>: una promesa de 0 o 1 resultado (por ejemplo, buscar un pedido por ID).Flux<T>: una promesa de 0 a N resultados que van llegando como un flujo (por ejemplo, un stream de notificaciones).
¿Cuándo vale la pena? Cuando tu microservicio vive de I/O: llamadas a otras APIs, bases de datos, colas de mensajes. Ahí lo reactivo permite atender muchísimas más peticiones con los mismos recursos. Si tu servicio hace cálculos pesados de CPU y poco I/O, lo reactivo no te va a salvar (y te va a complicar la vida).
Parte 2: Vertical Slicing, o cómo dejar de organizar el código “por capas”
La mayoría de proyectos Java se organizan así: un paquete controllers, otro services, otro repositories. Se ve ordenado… hasta que tienes 40 features y tocar “crear pedido” implica abrir archivos regados en cinco paquetes distintos.
Vertical Slicing propone lo contrario: organizar por capacidad de negocio. Cada feature es una “rebanada vertical” que contiene TODO lo que necesita — su controller, su lógica, sus DTOs, su acceso a datos — en un solo paquete:
features/
├── crearpedido/
│ ├── CrearPedidoController.java
│ ├── CrearPedidoHandler.java
│ ├── CrearPedidoRequest.java
│ ├── CrearPedidoResponse.java
│ └── PedidoRepository.java
└── consultarpedido/
└── ...graph LR
sublayer["Arquitectura Tradicional"]
sublayer --> C["Controllers"]
sublayer --> S["Services"]
sublayer --> R["Repositories"]
subslice["Vertical Slicing"]
subslice --> F1["Crear Pedido"]
subslice --> F2["Consultar Pedido"]
F1 --> C1["Controller + Service + Repository"]
F2 --> C2["Controller + Service + Repository"]
style sublayer fill:#f9d0c4,stroke:#333,stroke-width:2px
style subslice fill:#c4f9d0,stroke:#333,stroke-width:2px
Los beneficios en el mundo real:
- Localidad: todo lo de una feature está en un solo lugar. Abrir un slice es entender la feature completa.
- Bajo acoplamiento: la regla sagrada es que un slice nunca importa clases de otro slice. Si rompes “crear pedido”, “consultar pedido” sigue intacto.
- Equipos en paralelo: dos personas (o dos agentes de IA 😉) trabajan en slices distintos sin pisarse.
- Borrar es fácil: ¿la feature murió? Borras la carpeta. Sin arqueología.
Y aquí viene la conexión clave con los microservicios: un slice bien hecho es, en la práctica, un microservicio en miniatura dentro de tu servicio. Si mañana ese slice crece tanto que merece su propio despliegue, extraerlo es casi un copy-paste, porque ya no tiene tentáculos hacia el resto del código.
Parte 3: El problema de pedirle esto a una IA “a pelo”
Si le escribes a cualquier IA “créame un endpoint reactivo para crear pedidos”, te va a dar código que compila. El problema es que cada vez te lo da diferente: hoy con @Service y paquetes por capas, mañana con RestTemplate bloqueante en medio de tu flujo reactivo (un pecado capital), pasado mañana con un .block() escondido que tumba el rendimiento de todo el servicio.
La IA no es mala. Simplemente no conoce las reglas de tu casa. Y repetírselas en cada conversación es agotador e inconsistente.
Parte 4: La solución — una “skill” (y por qué le gana al contexto suelto)
Hay dos formas de darle reglas a una IA:
- Contexto: pegas las instrucciones en el chat. Funciona… hasta que abres una conversación nueva y se perdió todo. Es como explicarle el proyecto a un contratista nuevo cada lunes.
- Skill: un archivo (típicamente un
SKILL.md) con las reglas, convenciones, estructura y ejemplos de referencia, escrito para que la IA lo cargue como su manual de operación. Es como entregarle al nuevo del equipo el documento de onboarding: lo lee una vez y trabaja como uno más.
El veredicto de mi esposito después de poner a prueba este método en proyectos reales es contundente: entre todas las opciones, la ganadora es la “skill” sin lugar a dudas. Y me dio tres razones muy claras de por qué funciona tan bien:
- Consistencia: el mismo archivo produce la misma arquitectura hoy, mañana y en el computador de tu colega.
- Versionable: vive en tu repo, evoluciona con
git, se revisa en PRs como cualquier código. - Portable: la misma skill funciona en Claude (que las soporta de forma nativa), como instrucciones de proyecto en ChatGPT, o como system prompt de un modelo local con Ollama.
Parte 5: El mini curso — tu primer slice reactivo generado con IA
Manos a la obra. Cuatro pasos.
Paso 1: Consigue la skill
Al final de este artículo te dejamos la versión esencial (Lite) de nuestro archivo SKILL-java-reactivo-vertical-slice.md. Contiene la configuración de la arquitectura, el stack obligatorio y las convenciones de naming para que empieces hoy mismo.
💡 Nota Pro: Si quieres ir un paso más allá y garantizar que la IA no cometa errores críticos, hemos publicado la Versión PRO de esta skill. Incluye las reglas reactivas innegociables para evitar código bloqueante, el manejo de errores global y los prompts para generación automática de tests con
StepVerifieryWebTestClient. Adquiere la Skill PRO aquí y apoya el blog.
Paso 2: Cárgala en tu IA
- Claude: crea un Proyecto y sube el archivo como conocimiento, o úsalo como skill si tu plan lo soporta.
- ChatGPT: pégalo en las instrucciones personalizadas de un GPT o de un proyecto.
- Modelo local (Ollama con Qwen, Gemma, etc.): úsalo como system prompt. Según su experiencia, los modelos locales son los que MÁS mejoran, ya que este tipo de modelos son precisamente los que más reglas necesitan en su configuración para evitar que improvisen. Al equiparlos con una skill, se les da la estructura exacta para que dejen de adivinar y empiecen a programar con la precisión que exige un proyecto real.
Paso 3: Pide tu primer slice
Con la skill cargada, el prompt se vuelve ridículamente corto:
“Genera el slice
crearpedidopara el microservicio de órdenes. Campos: código (obligatorio, alfanumérico), clienteId (UUID), items (lista no vacía). Regla de negocio: rechazar códigos duplicados.”
Y la IA, en lugar de improvisar, responde con el árbol de archivos del slice, el Handler retornando Mono<CrearPedidoResponse>, el record Request con validaciones, el manejo del duplicado con PedidoDuplicadoException, y los dos tests con StepVerifier y WebTestClient. Siempre con la misma estructura. Siempre.
Paso 4: Itera y haz crecer TU skill
Aquí está el verdadero secreto: la skill que te compartimos es el punto de partida. Cada vez que la IA genere algo que en tu empresa se hace distinto, no corrijas el código: corrige la skill. En unas semanas tendrás un archivo que codifica el conocimiento arquitectónico de tu equipo. Eso vale oro.
Errores comunes que la skill te evita (aprendidos a golpes)
- El
.block()traicionero: un solo.block()en un flujo WebFlux puede agotar los hilos del event loop y degradar todo el servicio. La skill lo prohíbe explícitamente y obliga a aislar lo bloqueante enSchedulers.boundedElastic(). - JPA dentro de WebFlux: Hibernate clásico es bloqueante. Mezclarlo con Reactor es tener un Ferrari con freno de mano puesto. La skill exige R2DBC o Mongo reactivo.
- El slice que se vuelve pulpo: cuando un slice empieza a importar clases de otro, el Vertical Slicing murió. La skill instruye a la IA a promover lo compartido a
shared/y justificarlo. - Errores que filtran stacktraces: la skill obliga a un manejador global que traduce excepciones de dominio a respuestas limpias con código, mensaje y traceId.
Descarga la skill (y lo que viene)
Aquí abajo tienes el contenido completo del archivo para copiar y usar hoy mismo, gratis, como lector del blog.
---
name: "java-reactivo-vertical-slice-lite"
version: "1.0.0"
author: "Edwin Ferreira · Mami en Código (mamiencodigo.com)"
description: >
Versión esencial para que una IA (Claude, ChatGPT, Gemini o locales)
genere microservicios Java reactivos organizados por Vertical Slicing.
Para reglas reactivas innegociables y tests automáticos, adquiere la versión PRO.
license: Uso personal. No redistribuir sin autorización.
---
# Skill: Microservicios Java Reactivos con Vertical Slicing
## Cuándo activar esta skill
Activa estas reglas cuando el usuario pida: crear un microservicio Java, agregar
una feature/endpoint a un servicio existente, migrar código imperativo a
reactivo, o revisar código WebFlux.
## Stack obligatorio
- Java 21 (usa records, pattern matching y virtual threads solo donde aplique).
- Spring Boot 3.3+ con Spring WebFlux (Project Reactor: `Mono` / `Flux`).
- Persistencia reactiva: R2DBC para SQL o Reactive MongoDB.
- Cliente HTTP: `WebClient`. NUNCA `RestTemplate`.
## Arquitectura: Vertical Slicing (regla de oro)
El código se organiza POR FEATURE, no por capa técnica. Prohibido crear
paquetes globales `controllers/`, `services/`, `repositories/`.
Estructura obligatoria:
```text
src/main/java/com/{empresa}/{servicio}/
├── features/
│ ├── crearpedido/
│ │ ├── CrearPedidoController.java
│ │ ├── CrearPedidoHandler.java # caso de uso, lógica del slice
│ │ ├── CrearPedidoRequest.java # record con validaciones
│ │ ├── CrearPedidoResponse.java # record
│ │ └── PedidoRepository.java # interfaz R2DBC del slice
├── shared/ # SOLO lo transversal real
```
Reglas del slice:
1. Un slice = una capacidad de negocio = un paquete.
2. Un slice NUNCA importa clases de otro slice.
3. El Handler recibe el Request, orquesta y devuelve `Mono<Response>` o `Flux<Response>`. El Controller solo adapta HTTP, sin lógica.
## Convenciones de naming
* Paquete del slice: minúsculas sin separador (`crearpedido`).
* Clases del slice prefijadas con el nombre de la feature en PascalCase.
* Endpoints: kebab-case, versionados: `POST /api/v1/pedidos`.
## ⚠️ Reglas reactivas innegociables, Manejo de Errores y Tests Obligatorios
[ESTA SECCIÓN ESTÁ RESERVADA PARA LA VERSIÓN PRO]
Para garantizar que la IA nunca genere código bloqueante (el famoso `.block()`), gestione correctamente los Timeouts/Circuit Breakers, y escriba automáticamente tests robustos con `StepVerifier`, actualiza a la **Skill PRO** aquí: [Adquirir Skill PRO](/link/guia-ia).¿Ya usas IA para generar código en tu trabajo? ¿Te funcionó la skill con tu modelo favorito? Cuéntanos en los comentarios qué regla le agregarías — las mejores sugerencias entrarán a la versión 1.1. ⚙️☕
Comentarios