Todas las guías
  1. Inicio
  2. Guías técnicas
  3. Desarrollo

DesarrolloNivel básico

Buenas prácticas de desarrollo en Java con Spring Boot

8 min de lectura

Todas las guías

Buenas prácticas de desarrollo en Java con Spring Boot

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

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_LOTE en vez de 500).
  • Devuelve colecciones vacías, no null; usa Optional solo 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.

Compartir

Más guías sobre

Ver todas las guías

Otras guías técnicas

Ver todas las guías

APIsIntermedio

Estructura básica de una API en IBM API Connect 10

Cómo se estructura una API en IBM API Connect 10: contrato OpenAPI con x-ibm-configuration, Client ID y Client Secret, producto con planes y límites, y validación y publicación con el CLI apic.

Leer la guía 7 min de lectura

IntegraciónIntermedio

Comandos básicos de administración de TIBCO ActiveSpaces 5.2

Los comandos del día a día en TIBCO ActiveSpaces 5.2: servicio de realm sobre servidores FTL, tibdg, definición del grid, tablas, arranque de procesos, estado, escalado con copysets, checkpoints y logs.

Leer la guía 8 min de lectura

DevOpsBásico

Estructura básica de un CI/CD con GitHub Actions

Un pipeline completo con GitHub Actions: pruebas en cada push y pull request, imagen Docker en GitHub Container Registry y despliegue a un entorno protegido, con un workflow listo para copiar.

Leer la guía 6 min de lectura

Contacto

Construye hoy tu próxima ventaja competitiva

Hablemos sobre cómo podemos ayudarte. Te respondemos con una propuesta técnica clara, sin compromiso.

Solicita información

Los campos marcados con son obligatorios.