Una guía de buenas prácticas para el día a día con Java y Spring Boot: nada complejo, solo las decisiones que más se notan cuando un servicio crece, cambia de manos o hay que depurarlo en producción. Cada práctica viene con un ejemplo de qué evitar y qué hacer. En el README.md de la izquierda tienes la lista de comprobación para revisar tu código.
¿Qué vas a aprender?
- Cómo organizar el código de un servicio para que crezca sin enredarse.
- Las prácticas de base: inyección por constructor, DTOs, validación y errores centralizados.
- Cómo sacar la configuración y los secretos del código con perfiles y variables de entorno.
- Dónde poner las transacciones, cómo escribir logs útiles y cómo comentar el código.
- Qué probar en cada nivel y cómo automatizar la calidad.
Requisitos previos
- Java 17 o superior (Spring Boot 3 lo exige).
- Un proyecto Spring Boot 3, por ejemplo generado en
start.spring.iocon Spring Web, Validation, Spring Data JPA y Actuator. - Maven o Gradle, y un IDE como IntelliJ IDEA o Visual Studio Code con el Extension Pack for Java.
- Conocer lo básico de Java y de Spring (controladores, servicios y repositorios).
Paso a paso
1. Organiza el código por funcionalidad
Agrupa por funcionalidad (pedidos, clientes…) y no solo por capa técnica (todos los controladores juntos, todos los servicios juntos). Cada carpeta contiene lo que necesita su parte del negocio, y es fácil encontrar, cambiar o extraer algo sin tocar el resto.
src/main/java/com/empresa/pedidos/
├── PedidosApplication.java
├── pedido/
│ ├── PedidoController.java
│ ├── PedidoService.java
│ ├── PedidoRepository.java
│ ├── Pedido.java (entidad)
│ └── dto/
│ ├── PedidoRequest.java
│ └── PedidoResponse.java
├── cliente/
│ └── ...
└── comun/
├── error/GlobalExceptionHandler.java
└── config/...
2. Inyecta las dependencias por constructor
En lugar de esto:
@Service
public class PedidoService {
@Autowired
private PedidoRepository repositorio; // inyección por campo: difícil de probar
}
Haz esto: los campos final dejan claro qué necesita la clase, no puede quedar a medio construir y se prueba sin levantar Spring.
@Service
public class PedidoService {
private final PedidoRepository repositorio;
// Con un único constructor, Spring lo usa sin necesidad de @Autowired
public PedidoService(PedidoRepository repositorio) {
this.repositorio = repositorio;
}
}
3. Separa las entidades de lo que expone la API
No devuelvas entidades JPA en los controladores: expones campos internos, acoplas la API a la base de datos y puedes provocar consultas de más. Usa DTOs; los record de Java son perfectos para ello.
// Lo que entra en la API
public record PedidoRequest(
@NotBlank String cliente,
@NotNull @PositiveOrZero BigDecimal importe) {
}
// Lo que sale de la API: solo los campos que el consumidor necesita
public record PedidoResponse(String id, String cliente, BigDecimal importe, String estado) {
static PedidoResponse de(Pedido pedido) {
return new PedidoResponse(pedido.getId(), pedido.getCliente(),
pedido.getImporte(), pedido.getEstado().name());
}
}
4. Valida la entrada en el borde
Declara las reglas en el DTO (@NotBlank, @NotNull, @PositiveOrZero…) y actívalas con @Valid. Si la petición no las cumple, Spring responde 400 antes de llegar a tu lógica.
@RestController
@RequestMapping("/api/v1/pedidos")
public class PedidoController {
private final PedidoService servicio;
public PedidoController(PedidoService servicio) {
this.servicio = servicio;
}
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public PedidoResponse crear(@Valid @RequestBody PedidoRequest peticion) {
return servicio.crear(peticion);
}
@GetMapping("/{id}")
public PedidoResponse leer(@PathVariable String id) {
return servicio.leer(id);
}
}
5. Centraliza el manejo de errores
Un único @RestControllerAdvice traduce las excepciones a respuestas HTTP coherentes. Spring Boot 3 incluye ProblemDetail, el formato estándar de errores (RFC 9457):
public class PedidoNoEncontradoException extends RuntimeException {
public PedidoNoEncontradoException(String id) {
super("No existe el pedido " + id);
}
}
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(PedidoNoEncontradoException.class)
ProblemDetail noEncontrado(PedidoNoEncontradoException ex) {
return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
}
}
Y para que los errores de validación y de Spring salgan con el mismo formato:
spring:
mvc:
problemdetails:
enabled: true # errores de validación y de Spring también en formato RFC 9457
6. Saca la configuración y los secretos del código
Los valores que cambian entre entornos van en application.yml, y los secretos, en variables de entorno o en un gestor de secretos (Azure Key Vault, Vault…), nunca en el repositorio:
spring:
datasource:
url: ${DB_URL}
username: ${DB_USER}
password: ${DB_PASSWORD} # nunca el valor real en el repositorio
jpa:
open-in-view: false
pedidos:
importe-maximo: 10000
reintentos: 3
Agrupa la configuración propia en una clase tipada en vez de repartir @Value por el código:
@ConfigurationProperties(prefix = "pedidos")
public record PedidosProperties(BigDecimal importeMaximo, int reintentos) {
}
// En la clase principal (o en una @Configuration)
@SpringBootApplication
@ConfigurationPropertiesScan
public class PedidosApplication { ... }
Y usa perfiles para lo que cambia por entorno:
application.yml común a todos los entornos
application-dev.yml desarrollo local
application-pro.yml producción
java -jar pedidos.jar --spring.profiles.active=pro
7. Pon las transacciones en la capa de servicio
El servicio es quien sabe qué operaciones forman una unidad. Marca la clase como solo lectura y abre transacciones de escritura donde hagan falta:
@Service
@Transactional(readOnly = true) // por defecto, solo lectura
public class PedidoService {
@Transactional // las escrituras, en su propia transacción
public PedidoResponse crear(PedidoRequest peticion) {
Pedido pedido = repositorio.save(Pedido.nuevo(peticion.cliente(), peticion.importe()));
return PedidoResponse.de(pedido);
}
public PedidoResponse leer(String id) {
return repositorio.findById(id)
.map(PedidoResponse::de)
.orElseThrow(() -> new PedidoNoEncontradoException(id));
}
}
8. Escribe logs útiles con SLF4J
En lugar de esto:
System.out.println("Pedido creado: " + pedido); // no va al sistema de logs
log.info("Login de " + usuario + " con clave " + clave); // concatena siempre y filtra un secreto
Haz esto: mensajes con parámetros {} (no se construyen si el nivel está desactivado), el nivel adecuado (error para fallos que requieren acción, info para hechos de negocio, debug para detalle) y nunca contraseñas, tokens ni datos personales.
private static final Logger log = LoggerFactory.getLogger(PedidoService.class);
log.info("Pedido {} creado para el cliente {}", pedido.getId(), pedido.getCliente());
log.debug("Detalle del pedido {}: {}", pedido.getId(), pedido);
log.error("No se pudo notificar el pedido {}", pedido.getId(), ex); // la excepción, al final
9. Comenta el porqué, no el qué
El código bien nombrado ya dice qué hace; el comentario explica por qué: una regla de negocio, una limitación externa, una decisión no evidente. Documenta con Javadoc los métodos públicos que usan otros equipos, y no dejes código comentado: para eso está git.
// Mal: repite lo que ya dice el código
// suma 1 al contador
contador++;
// Bien: explica por qué
// El proveedor rechaza lotes de más de 500 líneas (contrato v2, cláusula 4)
private static final int TAMANO_MAXIMO_LOTE = 500;
/**
* Calcula el importe con impuestos de un pedido.
*
* @param pedido pedido con sus líneas; no puede ser nulo
* @return importe total, redondeado a dos decimales
* @throws PedidoNoEncontradoException si el pedido ya no existe
*/
public BigDecimal importeConImpuestos(Pedido pedido) { ... }
10. Usa nombres claros y métodos pequeños
- Clases con sustantivos (
PedidoService), métodos con verbos (crearPedido), booleanos que se lean como pregunta (estaPagado). - Un método, una responsabilidad: si necesitas un comentario para separar sus partes, probablemente son varios métodos.
- Constantes con nombre en lugar de números o textos sueltos (
TAMANO_MAXIMO_LOTEen vez de500). - Devuelve colecciones vacías, no
null; usaOptionalsolo como tipo de retorno, no en campos ni parámetros.
11. Prueba cada cosa en su nivel
Muchas pruebas unitarias rápidas de la lógica, y menos pruebas de integración para lo que toca Spring o la base de datos.
Lógica de negocio: JUnit 5 y Mockito
@ExtendWith(MockitoExtension.class)
class PedidoServiceTest {
@Mock PedidoRepository repositorio;
@InjectMocks PedidoService servicio;
@Test
void lanzaExcepcionSiElPedidoNoExiste() {
when(repositorio.findById("X")).thenReturn(Optional.empty());
assertThrows(PedidoNoEncontradoException.class, () -> servicio.leer("X"));
}
}
Capa web: @WebMvcTest
@WebMvcTest(PedidoController.class)
class PedidoControllerTest {
@Autowired MockMvc mvc;
@MockitoBean PedidoService servicio; // @MockBean en versiones anteriores a Spring Boot 3.4
@Test
void rechazaUnPedidoSinCliente() throws Exception {
mvc.perform(post("/api/v1/pedidos")
.contentType(MediaType.APPLICATION_JSON)
.content("{\"importe\": 10}"))
.andExpect(status().isBadRequest());
}
}
Para los repositorios, @DataJpaTest, y si usas una base de datos real en las pruebas, Testcontainers.
12. Expón la salud del servicio con Actuator
Actuator da endpoints de salud y métricas listos para Kubernetes y para la monitorización. Expón solo los necesarios:
management:
endpoints:
web:
exposure:
include: health,info,prometheus # solo lo necesario
endpoint:
health:
probes:
enabled: true # /actuator/health/liveness y /readiness para Kubernetes
13. Automatiza la calidad
- Un formato común aplicado de forma automática (por ejemplo, Spotless) para que las revisiones hablen de lógica y no de espacios.
- Análisis estático en el IDE (SonarLint) y en el pipeline (SonarQube o SonarCloud) con un umbral de calidad.
- Actualización automática de dependencias (Dependabot o Renovate) para no acumular vulnerabilidades.
- Las pruebas y el análisis, obligatorios en cada pull request antes de integrar.
Errores habituales
Inyección por campo con @Autowired
Funciona, pero oculta las dependencias, impide los campos final y obliga a usar Spring o reflexión para probar. Pásala al constructor (paso 2).
Devolver entidades JPA en la API
Expone campos internos y puede disparar la carga perezosa de relaciones al serializar (o fallar con LazyInitializationException). Usa DTOs (paso 3).
@Transactional que no hace nada
Spring aplica las transacciones con un proxy: no funcionan en métodos private ni cuando un método llama a otro de la misma clase. Ponla en métodos públicos llamados desde fuera.
Consultas N+1
Recorrer una lista de entidades y acceder a una relación perezosa lanza una consulta por elemento. Usa JOIN FETCH o @EntityGraph en el repositorio, y desactiva spring.jpa.open-in-view para detectarlo pronto.
Capturar Exception y seguir como si nada
Un catch (Exception e) {} vacío esconde el fallo y lo convierte en un dato incorrecto más adelante. Captura lo que sabes tratar y deja subir el resto al manejador global (paso 5).
Secretos en application.yml
Una contraseña subida a git queda en el historial aunque se borre después. Usa variables de entorno o un gestor de secretos, y si se subió una, cámbiala.
System.out.println en lugar de logs
No tiene niveles, no llega al sistema de logs del entorno y no se puede filtrar. Usa SLF4J (paso 8).
Siguientes pasos
- Documentar la API con springdoc-openapi y revisar su contrato (ver la guía del contrato OpenAPI 3 con OAuth y API Key).
- Construir la imagen del contenedor sin Dockerfile con
./mvnw spring-boot:build-image. - Montar el pipeline de pruebas, análisis y despliegue (ver la guía de CI/CD con GitHub Actions).
- Añadir métricas con Micrometer y Prometheus, y trazas distribuidas con OpenTelemetry.