La potencia de las anotaciones de Spring Boot

Introducción

Uno de los mayores atractivos de Spring Boot es la sensación de “magia”: unas pocas anotaciones y de repente tienes una API funcionando, un servicio detectado o una configuración cargada sin escribir casi nada de código “ceremonial”.

Esa magia se convierte en problema cuando el equipo no sabe qué hay debajo.
Entonces aparecen frases como “esto funciona porque sí”, “no toques esa anotación” o “si quitamos este @ cosas rompen”.

Este artículo no es una lista infinita de anotaciones. Es una guía para entender qué resuelve cada familia de anotaciones, cómo encajan en el modelo de Spring, y cómo usarlas sin convertir el proyecto en una caja negra.

Qué hay debajo: Spring por dentro (modelo real, sin humo)

Spring Boot se apoya en Spring Framework y gira alrededor de un concepto: el ApplicationContext. Un contenedor de objetos (beans) gestionado por el framework.

Cuando tu aplicación arranca, Spring:

• Escanea paquetes (component scanning).
• Registra definiciones de beans.
• Crea instancias y resuelve dependencias.
• Ejecuta BeanFactoryPostProcessors y BeanPostProcessors (aquí vive mucha “magia”).
• Crea proxys cuando hay AOP (transacciones, seguridad, logging, async…).
• Arranca el servidor web embebido si aplica (Tomcat/Jetty/Undertow).

Las anotaciones son metadatos que activan piezas de ese proceso. No son magia: son señales para que el contenedor haga trabajo por ti.

La anotación raíz: @SpringBootApplication

@SpringBootApplication no es “una anotación más”. Es un atajo que combina:

• @Configuration
• @EnableAutoConfiguration
• @ComponentScan

Traducción: define el punto de entrada, activa autoconfiguración y escanea componentes desde el paquete actual hacia abajo.

Componentes: @Component, @Service, @Repository, @Controller

Esta familia no es “estética”: marca roles. Y los roles importan para leer el sistema y aplicar comportamientos.

• @Component → genérico.
• @Service → lógica de negocio.
• @Repository → persistencia, y además activa traducción de excepciones.
• @Controller / @RestController → capa web / API.

Web: @RestController, @RequestMapping, @GetMapping…

Estas anotaciones definen el contrato HTTP de tu API. Lo importante aquí no es “mapear endpoints”, sino hacer el diseño mantenible: rutas coherentes, DTOs claros, validación en borde y errores consistentes.

Mini caso real: API de creación de usuarios con validación, transacción y respuesta limpia

Vamos con un ejemplo sencillo pero realista: crear un usuario. Aquí se ve cómo las anotaciones encajan entre sí sin “magia negra”.

1) DTO con validación (@Valid + Bean Validation)

public record CrearUsuarioRequest(
  @NotBlank @Email String email,
  @NotBlank @Size(min = 12, max = 128) String password
) {}
  

2) Controller: valida en el borde, no en el core

@RestController
@RequestMapping("/usuarios")
public class UsuarioController {

  private final UsuarioService usuarioService;

  public UsuarioController(UsuarioService usuarioService) {
    this.usuarioService = usuarioService;
  }

  @PostMapping
  public ResponseEntity<UsuarioDto> crear(@Valid @RequestBody CrearUsuarioRequest req) {
    return ResponseEntity.ok(usuarioService.crear(req));
  }
}
  

3) Service: transacción y reglas de negocio

@Service
public class UsuarioService {

  private final UsuarioRepository usuarioRepository;
  private final PasswordEncoder passwordEncoder;

  public UsuarioService(UsuarioRepository usuarioRepository, PasswordEncoder passwordEncoder) {
    this.usuarioRepository = usuarioRepository;
    this.passwordEncoder = passwordEncoder;
  }

  @Transactional
  public UsuarioDto crear(CrearUsuarioRequest req) {
    if (usuarioRepository.existsByEmail(req.email())) {
      throw new IllegalArgumentException("Email ya registrado");
    }
    Usuario u = new Usuario(req.email(), passwordEncoder.encode(req.password()));
    Usuario guardado = usuarioRepository.save(u);
    return new UsuarioDto(guardado.getId(), guardado.getEmail());
  }
}
  

Aquí hay dos puntos importantes:

• @Transactional funciona porque Spring crea un proxy alrededor del bean.
• Si llamas a un método @Transactional desde la misma clase (self-invocation), no pasas por el proxy y puedes romper la transacción.

Configuración: @Configuration, @Bean y @ConfigurationProperties

Si tu proyecto tiene muchos @Value, estás sembrando deuda. La forma profesional de manejar configuración es @ConfigurationProperties: tipado fuerte, validable y testeable.

@ConfigurationProperties(prefix = "gondor.seguridad")
public record SeguridadProperties(
  boolean activo,
  int tiempoSesionMin
) {}
  

Y luego lo habilitas (si hace falta) con:

@Configuration
@EnableConfigurationProperties(SeguridadProperties.class)
public class AppConfig {}
  

Perfiles: @Profile para evitar ifs de entorno

Los entornos no se gestionan con if. Se gestionan con perfiles.

@Bean
@Profile("dev")
DataSource devDataSource() { ... }

@Bean
@Profile("prod")
DataSource prodDataSource() { ... }
  

Anotaciones “peligrosas” si no entiendes el proxy

Hay una categoría de anotaciones donde la magia existe: AOP y proxys. No es malo, pero hay que saberlo.

Anotación	Qué hace	Riesgo típico
@Transactional	Transacción gestionada por proxy	Self-invocation rompe el comportamiento
@Async	Ejecución en otro hilo	Pérdida de contexto, errores silenciosos
@Cacheable	Cache en borde de método	Stale data y claves mal diseñadas
@PreAuthorize	Seguridad declarativa	Reglas dispersas si no hay criterio

Spring Security: anotaciones mínimas que verás en proyectos serios

Tarde o temprano, cualquier API real necesita control de acceso. Spring Security añade complejidad, pero también estructura. Estas son las piezas más habituales:

• @EnableMethodSecurity → habilita seguridad a nivel de método (para reglas finas).
• @PreAuthorize → reglas declarativas como roles o scopes.

Ejemplo típico

                @PreAuthorize("hasRole('ADMIN')")
                @GetMapping("/admin/reportes")
                public List<ReporteDto> reportes() { ... }
              

Errores comunes:

• Aplicar reglas dispersas sin criterio (seguridad “en parches”).
• Confiar en el front para autorización (la autorización es SIEMPRE backend).
• Mezclar autenticación con autorización y acabar con un sistema opaco.

Si una app tiene endpoints sensibles y no tiene un modelo claro de autorización, el problema no es técnico: es de diseño.

Inyección de dependencias: por qué constructor > @Autowired en campo

Inyección por constructor es la práctica recomendada: facilita testeo, reduce nulls y hace explícitas las dependencias.

@Service
public class PedidoService {
  private final PedidoRepository repo;

  public PedidoService(PedidoRepository repo) {
    this.repo = repo;
  }
}
  

Observabilidad: Actuator (lo que todo proyecto serio debería tener)

Si no sabes qué beans están cargados, qué configuración se aplicó o qué endpoints existen, la “magia” se vuelve incontrolable. Spring Boot Actuator aporta visibilidad.

• /actuator/health (salud)
• /actuator/metrics (métricas)
• /actuator/env (config efectiva)
• /actuator/beans (beans cargados)

Testing práctico con Spring Boot (sin dolor)

Un proyecto con Spring que no se testea en condiciones se vuelve frágil. Aquí hay un stack realista:

• @SpringBootTest para tests de integración con contexto.
• @WebMvcTest para testear capa web sin levantar todo.
• Testcontainers para DB/Redis reales efímeros.

Mini ejemplo: test de controller (@WebMvcTest)

@WebMvcTest(UsuarioController.class)
class UsuarioControllerTest {

  @Autowired private MockMvc mvc;
  @MockBean private UsuarioService usuarioService;

  @Test
  void creaUsuario_devuelve200() throws Exception {
    mvc.perform(post("/usuarios")
      .contentType("application/json")
      .content("{\"email\":\"a@b.com\",\"password\":\"password_segura_123\"}"))
      .andExpect(status().isOk());
  }
}
  

Cuando “la magia falla”: cómo depurar por qué un bean no se crea

En proyectos reales, el problema no suele ser “no sé qué anotación usar”, sino: “¿por qué Spring no está creando esto?”. Aquí tienes un checklist práctico para no perder horas.

1) ¿Está dentro del component scan?

• Comprueba el paquete de tu clase principal con @SpringBootApplication: Spring escanea ese paquete y sus hijos.
• Si tu clase está fuera, no se detectará. Solución: mover paquetes o ajustar @ComponentScan (con criterio).

2) ¿La clase está anotada (o registrada como bean)?

• Si quieres que sea un bean, debe ser detectada (@Component/@Service/@Repository) o definida con @Bean.
• Si no, Spring no “adivina” que debe instanciarla.

3) ¿Hay un @Profile o @Conditional impidiendo la carga?

• Revisa si el bean o su configuración están condicionados por @Profile o condiciones internas de auto-config.
• En entornos distintos (dev/prod/test), esto es una causa muy común.

4) ¿Hay varios beans del mismo tipo?

• Si hay más de uno, Spring puede fallar por ambigüedad.
• Solución: @Qualifier o @Primary (sin abusar).

5) ¿Qué te dice Actuator?

• /actuator/beans para ver qué está cargado.
• /actuator/conditions (si lo expones) para entender por qué una auto-config aplica o no.
• /actuator/env para ver configuración efectiva y perfiles activos.

Si no puedes explicar por qué un bean existe o no existe, no controlas el sistema. Y cuando no controlas el sistema, la “magia” se convierte en deuda.

Cuándo usar anotaciones y cuándo recuperar control explícito

Las anotaciones son fantásticas para eliminar boilerplate, pero conviene recuperar control cuando:

• la autoconfiguración activa cosas que no quieres,
• hay demasiada magia implícita sin visibilidad,
• el equipo no entiende qué está pasando,
• el comportamiento depende de orden de carga o proxys.

Errores habituales que luego cuestan caro

• Depender de autoconfiguración sin entender qué se ha activado.
• Abusar de @Value en vez de usar configuración tipada.
• Meter lógica en @PostConstruct y romper testabilidad.
• Confiar en @Transactional sin entender proxies.
• Beans con demasiadas responsabilidades (la magia solo lo disimula).

Checklist rápida (nivel pro)

1. ¿Entiendes qué hace el contenedor con las anotaciones que usas?
2. ¿Puedes explicar qué proxys existen en tu app y por qué?
3. ¿Tu configuración está tipada y testeada?
4. ¿Tienes observabilidad (Actuator) para ver qué está activo?
5. ¿Tus capas (controller/service/repository) están limpias y coherentes?

Conclusión

Spring Boot no es magia: es diseño de framework aplicado con criterio. Sus anotaciones son una forma de escribir menos infraestructura para centrarte en la lógica de negocio.

Un equipo maduro no vive de “poner @ y rezar”. Entiende el contexto, los proxys, la configuración y los límites.

En Gondor creemos en ese desarrollo: menos fe ciega, más arquitectura consciente y control real.