Аннотации Spring Boot

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Разработчику Архитектору

---

Когда эта статья полезна

Эта глава нужна, когда вы уже запускаете проект на Spring Boot и хотите быстро понимать:

• какую аннотацию ставить на класс, метод или параметр;
• чем отличаются похожие аннотации (@Component и @Service, @Controller и @RestController);
• какие аннотации чаще всего используются в реальном REST-приложении.

Статья не заменяет полную документацию, а дает рабочую карту: от старта приложения до тестирования.

---

Базовые аннотации старта и конфигурации

Аннотация	Где ставят	Что делает
@SpringBootApplication	Класс с main	Включает автонастройку, сканирование компонентов и bootstrapping приложения
@Configuration	Конфиг-класс	Объявляет класс как источник bean-определений
@Bean	Метод в @Configuration	Регистрирует возвращаемый объект как bean в контексте
@Value	Поле/конструктор/параметр	Подставляет значение из application.properties/env
@ConfigurationProperties	POJO + конфиг	Типобезопасно биндингует группу настроек по префиксу

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@Configuration
public class AppConfig {
    @Bean
    public Clock appClock() {
        return Clock.systemUTC();
    }
}

---

DI и компоненты

Аннотация	Где ставят	Что делает
@Component	Класс	Базовый стереотип bean-компонента
@Service	Класс	Компонент бизнес-логики (семантический стереотип)
@Repository	Класс/интерфейс	Слой доступа к данным; трансляция исключений Spring Data
@Controller	Класс	MVC-контроллер для view-шаблонов
@RestController	Класс	REST-контроллер (@Controller + @ResponseBody)
@Autowired	Конструктор/поле/сеттер	Внедряет зависимость из контекста
@Qualifier	Параметр/поле	Уточняет, какой bean брать при нескольких реализациях
@Primary	Класс/метод @Bean	Делает bean выбором по умолчанию

Рекомендуемый стиль: конструкторная инъекция без полей @Autowired.

@Service
public class PaymentService {
    private final Clock clock;

    public PaymentService(Clock clock) {
        this.clock = clock;
    }
}

Когда реализаций несколько:

public interface Notifier {
    void send(String message);
}

@Component("emailNotifier")
class EmailNotifier implements Notifier {
    public void send(String message) {}
}

@Component
class AlertService {
    private final Notifier notifier;

    public AlertService(@Qualifier("emailNotifier") Notifier notifier) {
        this.notifier = notifier;
    }
}

---

Web (Spring MVC)

Аннотация	Где ставят	Что делает
@RequestMapping	Класс/метод	Базовый URL и HTTP-ограничения
@GetMapping, @PostMapping, @PutMapping, @DeleteMapping	Метод	Короткие формы @RequestMapping(method=...)
@PathVariable	Параметр метода	Берет значение из URL-пути
@RequestParam	Параметр метода	Берет query-параметр
@RequestBody	Параметр метода	Десериализует JSON/XML в объект
@ResponseBody	Метод	Возвращает тело ответа напрямую
@CrossOrigin	Класс/метод	Разрешает CORS для браузерных клиентов

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public UserDto getById(@PathVariable Long id) {
        return new UserDto(id, "Alex");
    }

    @PostMapping
    public UserDto create(@RequestBody CreateUserRequest request) {
        return new UserDto(1L, request.name());
    }

    @GetMapping
    public List<UserDto> search(@RequestParam(defaultValue = "0") int page) {
        return List.of(new UserDto(1L, "Alex"));
    }
}

---

Валидация запросов

Аннотация	Где ставят	Что делает
@Valid	Параметр метода	Запускает Bean Validation для объекта
@NotNull, @NotBlank, @Size, @Email, @Min и др.	Поля DTO	Описывает ограничения входных данных
@Validated	Класс/контроллер	Включает валидацию для параметров методов и групп

public record CreateUserRequest(
    @NotBlank @Size(max = 64) String name,
    @Email String email
) {}

@PostMapping
public UserDto create(@Valid @RequestBody CreateUserRequest request) {
    return service.create(request);
}

Практика: держите валидацию на границе API (DTO), а бизнес-правила - в сервисах.

---

Данные и JPA

Аннотация	Где ставят	Что делает
@Entity	Класс модели	Помечает JPA-сущность
@Table	Класс	Настраивает имя таблицы и индексы
@Id	Поле	Первичный ключ
@GeneratedValue	Поле @Id	Стратегия генерации ключа
@Column	Поле	Настройки колонки (nullable, length, unique)
@ManyToOne, @OneToMany, @JoinColumn	Поля	Связи между сущностями
@EnableJpaRepositories	Конфиг (редко вручную)	Явно включает сканирование репозиториев
@Transactional	Метод/класс	Граница транзакции

@Entity
@Table(name = "users")
public class UserEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 64)
    private String name;
}

---

Безопасность

Аннотация	Где ставят	Что делает
@EnableWebSecurity	Конфиг-класс	Включает Spring Security конфигурацию
@PreAuthorize	Метод	Проверка доступа до выполнения (SpEL)
@PostAuthorize	Метод	Проверка после выполнения
@Secured	Метод	Проверка по ролям (legacy-стиль, но используется)
@WithMockUser	Тест-метод	Поднимает тестового пользователя в SecurityContext

@Service
public class AdminService {
    @PreAuthorize("hasRole('ADMIN')")
    public void rebuildIndex() {
        // admin only
    }
}

---

Тестирование Spring Boot

Аннотация	Где ставят	Что делает
@SpringBootTest	Тест-класс	Поднимает полный контекст приложения
@WebMvcTest	Тест-класс	Срез для MVC-слоя (контроллеры)
@DataJpaTest	Тест-класс	Срез для JPA/репозиториев
@MockBean	Поле теста	Подменяет bean mock-объектом в контексте
@TestConfiguration	Внутренний тестовый конфиг	Дополнительные bean только для тестов

@WebMvcTest(UserController.class)
class UserControllerTest {
    @Autowired private MockMvc mockMvc;
    @MockBean private UserService userService;
}

---

Условная загрузка и профили

Аннотация	Где ставят	Что делает
@ConditionalOnProperty	Конфиг/bean	Создает bean только при нужном свойстве
@ConditionalOnClass	Автоконфиг	Создает bean, если класс есть в classpath
@Profile	Класс/метод @Bean	Активирует bean только для выбранного профиля

@Configuration
class StorageConfig {
    @Bean
    @Profile("dev")
    Storage localStorage() {
        return new LocalStorage();
    }

    @Bean
    @Profile("prod")
    Storage s3Storage() {
        return new S3Storage();
    }
}

---

Частые ошибки с аннотациями

1. Ставить @Autowired на поля вместо конструктора: тестировать и поддерживать сложнее.
2. Смешивать доменную модель и API-модель: валидация DTO и JPA-сущности начинают конфликтовать.
3. Помечать все подряд @Transactional: растут блокировки и сложнее понимать границы транзакций.
4. Использовать @Component везде: теряется роль класса; лучше @Service, @Repository, @RestController по назначению.
5. Добавлять @Enable... аннотации без необходимости: в Boot многое уже включается автонастройкой.

---

Мини-чеклист выбора аннотации

• Нужен управляемый объект Spring: @Component или профильный стереотип.
• Нужен HTTP endpoint: @RestController + @GetMapping/@PostMapping.
• Нужна валидация входа: @Valid на параметре + ограничения в DTO.
• Нужна работа с БД: @Entity, репозиторий, @Transactional в сервисе.
• Нужна проверка прав: @PreAuthorize на методах сервиса/контроллера.
• Нужен тест с контекстом: выбрать между @SpringBootTest, @WebMvcTest, @DataJpaTest.

---

Связанные материалы

• Первая программа на Spring Framework
• Spring Framework
• Spring Security Basic
• JWT в Spring Boot
• JPA в Spring

---