# Buenas prácticas de desarrollo en Java con Spring Boot

Guía de Bitflow Solutions. Versión web: https://bitflow-solutions.com/guias-tecnicas/buenas-practicas-java-spring-boot/

## ¿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.io` con 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).

## Lista de comprobación

- [ ] Código organizado por funcionalidad
- [ ] Dependencias inyectadas por constructor, campos final
- [ ] DTOs (records) en la API; nunca entidades JPA
- [ ] Entrada validada con @Valid y anotaciones de Jakarta Validation
- [ ] Errores centralizados en @RestControllerAdvice con ProblemDetail
- [ ] Configuración en application.yml y @ConfigurationProperties; secretos en variables de entorno
- [ ] Perfiles por entorno (dev, pro)
- [ ] @Transactional en el servicio, readOnly por defecto
- [ ] Logs con SLF4J y parámetros {}, sin secretos ni datos personales
- [ ] Comentarios que explican el porqué; Javadoc en métodos públicos; sin código comentado
- [ ] Nombres claros, métodos pequeños, constantes con nombre
- [ ] Pruebas unitarias (JUnit 5 + Mockito), @WebMvcTest, @DataJpaTest
- [ ] Actuator con solo los endpoints necesarios
- [ ] Formato, análisis estático y actualización de dependencias automatizados
- [ ] spring.jpa.open-in-view=false

## Paso a paso: ejemplos

### Inyección por constructor

```java
@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;
    }
}
```

### DTOs con records y validación

```java
// 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());
    }
}
```

```java
@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);
    }
}
```

### Errores con ProblemDetail

```java
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());
    }
}
```

```yaml
spring:
  mvc:
    problemdetails:
      enabled: true   # errores de validación y de Spring también en formato RFC 9457
```

### Configuración y secretos

```yaml
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
```

```java
@ConfigurationProperties(prefix = "pedidos")
public record PedidosProperties(BigDecimal importeMaximo, int reintentos) {
}

// En la clase principal (o en una @Configuration)
@SpringBootApplication
@ConfigurationPropertiesScan
public class PedidosApplication { ... }
```

### Transacciones en el servicio

```java
@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));
    }
}
```

### Logs

```java
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
```

### Comentarios

```java
// 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) { ... }
```

### Pruebas

```java
@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"));
    }
}
```

```java
@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());
    }
}
```

### Actuator

```yaml
management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus   # solo lo necesario
  endpoint:
    health:
      probes:
        enabled: true                     # /actuator/health/liveness y /readiness para Kubernetes
```

## 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.
