스프링부트 애노테이션 – 실무에서 가장 많이 쓰는 핵심 10가지

// 애노테이션이 없는 순수 Java 클래스
public class UserService {
    public void save(User user) { ... }
}

// 애노테이션을 붙인 스프링 관리 클래스
@Service                      // "스프링아, 이 클래스를 Bean으로 관리해줘"
@Transactional                // "이 클래스의 메서드들은 트랜잭션 안에서 실행해줘"
public class UserService {
    public void save(User user) { ... }
}
// → 스프링이 자동으로 Bean 등록 + 트랜잭션 처리

[스프링부트 애노테이션 처리 흐름]

애플리케이션 구동
      ↓
@SpringBootApplication 발견
      ↓
컴포넌트 스캔 시작 (해당 패키지 및 하위 패키지 전체 탐색)
      ↓
@Component, @Service, @Repository, @Controller 등 발견
      ↓
IoC 컨테이너에 Bean 등록
      ↓
@Autowired, @Value 등으로 의존성·설정값 주입
      ↓
애플리케이션 정상 구동 완료

@SpringBootApplication  // 이 한 줄이 아래 세 가지를 모두 포함
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

// @SpringBootApplication은 사실 이 세 가지의 조합
@SpringBootConfiguration    // = @Configuration: 이 클래스가 Bean 설정 클래스임을 선언
@EnableAutoConfiguration    // 스프링부트 자동 설정 활성화 (classpath 기반 자동 Bean 등록)
@ComponentScan              // 현재 패키지부터 하위 패키지까지 컴포넌트 자동 탐색
public @interface SpringBootApplication { ... }

✅ 올바른 패키지 구조:
com.example.myapp
├── MyApplication.java       ← @SpringBootApplication 위치 (최상위)
├── controller/
│   └── UserController.java
├── service/
│   └── UserService.java
└── repository/
    └── UserRepository.java

❌ 잘못된 구조 (controller/ 안에 main 클래스 위치):
com.example.myapp.controller
├── MyApplication.java       ← service/, repository/ 탐색 불가!

// @Controller vs @RestController 비교

@Controller
public class OldController {
    @ResponseBody           // 없으면 뷰(View) 이름으로 해석됨
    @GetMapping("/users")
    public List<User> getUsers() {
        return userService.findAll();
    }
}

// ↓ @RestController 하나로 해결
@RestController             // = @Controller + @ResponseBody
@RequestMapping("/api/v1")  // 클래스 레벨 공통 URL 접두사
public class UserController {

    private final UserService userService;

    @GetMapping("/users")               // GET /api/v1/users
    public List<User> getUsers() {
        return userService.findAll();   // List<User> → 자동으로 JSON 배열 변환
    }

    @GetMapping("/users/{id}")          // GET /api/v1/users/1
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }

    @PostMapping("/users")              // POST /api/v1/users
    public ResponseEntity<User> createUser(@RequestBody UserDto dto) {
        User saved = userService.save(dto);
        return ResponseEntity.status(HttpStatus.CREATED).body(saved);
    }
}

@RestController
@RequestMapping("/api/v1/products")
public class ProductController {

    // @PathVariable – URL 경로에서 변수 추출
    @GetMapping("/{id}")
    public Product getProduct(@PathVariable Long id) { ... }

    // @RequestParam – 쿼리 파라미터 추출 (?page=1&size=10)
    @GetMapping
    public Page<Product> getProducts(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "10") int size) { ... }

    // @RequestBody – HTTP 요청 본문(JSON)을 Java 객체로 역직렬화
    @PostMapping
    public Product createProduct(@RequestBody @Valid ProductDto dto) { ... }

    // @RequestHeader – HTTP 요청 헤더 값 추출
    @DeleteMapping("/{id}")
    public void deleteProduct(
            @PathVariable Long id,
            @RequestHeader("Authorization") String token) { ... }
}

// ❌ 위험 – 파라미터 없으면 400 오류
@GetMapping("/search")
public List<Product> search(@RequestParam String keyword) { ... }

// ✅ 안전 – 파라미터 없어도 빈 결과 반환
@GetMapping("/search")
public List<Product> search(
        @RequestParam(required = false, defaultValue = "") String keyword) { ... }

// ❌ 방식 1: 필드 주입 (Field Injection) – 편하지만 권장하지 않음
@Service
public class OrderService {

    @Autowired
    private UserRepository userRepository;   // 필드에 직접 주입
    // 단점:
    // - 테스트 시 Mock 주입 어려움
    // - 순환 참조 감지 어려움
    // - 객체 불변성 보장 불가 (final 사용 불가)
}

// ⚠️ 방식 2: Setter 주입 (Setter Injection) – 선택적 의존성에 사용
@Service
public class OrderService {

    private UserRepository userRepository;

    @Autowired
    public void setUserRepository(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
    // 단점: 객체 생성 후 주입 → 주입 전 메서드 호출 시 NullPointerException 위험
}

// ✅ 방식 3: 생성자 주입 (Constructor Injection) – 공식 권장 방식
@Service
@RequiredArgsConstructor    // Lombok이 생성자 자동 생성 (@Autowired 생략 가능)
public class OrderService {

    private final UserRepository userRepository;   // final 선언 가능
    private final ProductRepository productRepository;
    // 장점:
    // - 불변성 보장 (final 키워드)
    // - 테스트 시 Mock 주입 용이 (new OrderService(mockRepo))
    // - 순환 참조 시 애플리케이션 구동 단계에서 즉시 감지
    // - 의존성 명시적으로 드러남
}

// 생성자 주입의 테스트 용이성 확인
class OrderServiceTest {

    @Test
    void 주문_저장_테스트() {
        // Mock 객체를 생성자로 직접 주입 → @SpringBootTest 없이도 단위 테스트 가능
        UserRepository mockUserRepo = mock(UserRepository.class);
        ProductRepository mockProductRepo = mock(ProductRepository.class);

        OrderService orderService = new OrderService(mockUserRepo, mockProductRepo);

        // 테스트 로직...
    }
}

@Component      // 일반적인 컴포넌트 (어느 레이어인지 불명확할 때)
public class EmailValidator { ... }

@Service        // 비즈니스 로직을 담당하는 서비스 레이어
public class PaymentService { ... }

@Repository     // 데이터 접근 레이어 (JPA, MyBatis 등)
                // 추가 기능: 데이터 접근 예외를 스프링 DataAccessException으로 변환
public class UserRepositoryImpl { ... }

@Entity                         // 이 클래스가 DB 테이블과 매핑됨을 선언
@Table(name = "users")          // 매핑할 테이블 이름 지정 (생략 시 클래스명)
@Getter                         // Lombok
@NoArgsConstructor(access = AccessLevel.PROTECTED)  // JPA 기본 생성자 (protected)
public class User {

    @Id                         // 기본 키(Primary Key) 매핑
    @GeneratedValue(strategy = GenerationType.IDENTITY)  // AUTO_INCREMENT
    private Long id;

    @Column(nullable = false, length = 100)   // 컬럼 제약 조건
    private String name;

    @Column(unique = true, nullable = false)
    private String email;

    @Enumerated(EnumType.STRING)              // Enum → DB에 문자열로 저장
    private UserStatus status;

    @CreatedDate                              // Spring Data JPA 감사 기능
    @Column(updatable = false)
    private LocalDateTime createdAt;

    // 팩토리 메서드 패턴 (생성자 대신 사용 권장)
    public static User create(String name, String email) {
        User user = new User();
        user.name = name;
        user.email = email;
        user.status = UserStatus.ACTIVE;
        return user;
    }
}

@Service
@RequiredArgsConstructor
public class OrderService {

    private final OrderRepository orderRepository;
    private final InventoryService inventoryService;
    private final PaymentService paymentService;

    // ✅ 올바른 @Transactional 사용
    @Transactional                    // 메서드 전체가 하나의 트랜잭션
    public Order placeOrder(OrderRequest request) {
        // 1. 재고 차감
        inventoryService.decrease(request.getProductId(), request.getQty());

        // 2. 주문 저장
        Order order = Order.create(request);
        orderRepository.save(order);

        // 3. 결제 처리
        paymentService.charge(request.getUserId(), order.getTotalAmount());

        return order;
        // → 메서드 정상 종료 시 자동 COMMIT
        // → 예외 발생 시 자동 ROLLBACK (1, 2, 3 모두 취소)
    }

    // 읽기 전용 트랜잭션 – 성능 최적화
    @Transactional(readOnly = true)   // Dirty Checking 비활성화 → 성능 향상
    public List<Order> findUserOrders(Long userId) {
        return orderRepository.findByUserId(userId);
    }
}

@Service
public class UserService {

    // ❌ 같은 클래스 내부 메서드 호출 – @Transactional 무시됨!
    public void process() {
        this.save();   // 내부 호출: 스프링 프록시를 거치지 않음 → 트랜잭션 적용 안 됨
    }

    @Transactional
    public void save() {
        // 이 메서드를 같은 클래스에서 내부 호출 시 트랜잭션 동작 안 함
    }

    // ❌ private 메서드 – @Transactional 무시됨!
    @Transactional
    private void savePrivate() {
        // private 메서드에는 AOP 프록시 적용 불가
    }
}

public interface OrderRepository extends JpaRepository<Order, Long> {

    // 메서드 이름으로 자동 쿼리 생성 (간단한 조회)
    List<Order> findByUserIdAndStatus(Long userId, OrderStatus status);

    // @Query – JPQL (엔티티 기반)
    @Query("SELECT o FROM Order o WHERE o.userId = :userId AND o.createdAt >= :from")
    List<Order> findRecentOrders(
            @Param("userId") Long userId,
            @Param("from") LocalDateTime from);

    // @Query – 네이티브 SQL (복잡한 집계·성능 최적화)
    @Query(value = """
            SELECT DATE(created_at) AS date,
                   COUNT(*)         AS count,
                   SUM(amount)      AS total
            FROM orders
            WHERE user_id = :userId
            GROUP BY DATE(created_at)
            ORDER BY date DESC
            LIMIT 30
            """, nativeQuery = true)
    List<Object[]> findDailyOrderStats(@Param("userId") Long userId);

    // 벌크 업데이트 (@Modifying 필수)
    @Modifying
    @Query("UPDATE Order o SET o.status = :status WHERE o.id IN :ids")
    int bulkUpdateStatus(@Param("ids") List<Long> ids, @Param("status") OrderStatus status);
}

# application.yml
app:
  jwt:
    secret: mySecretKey2026
    expiration: 86400000
  external:
    api-url: https://api.example.com
    timeout: 5000
  pagination:
    default-size: 20

@Service
public class JwtService {

    @Value("${app.jwt.secret}")
    private String secretKey;

    @Value("${app.jwt.expiration}")
    private long expirationMs;

    // 기본값 설정 (프로퍼티 없을 때 사용)
    @Value("${app.pagination.default-size:10}")  // 없으면 10 사용
    private int defaultPageSize;

    // 환경변수도 주입 가능
    @Value("${SERVER_PORT:8080}")
    private int serverPort;

    public String generateToken(String userId) {
        return Jwts.builder()
                .subject(userId)
                .expiration(new Date(System.currentTimeMillis() + expirationMs))
                .signWith(Keys.hmacShaKeyFor(secretKey.getBytes()))
                .compact();
    }
}

// @Value – 개별 값 주입 (소수의 설정값)
@Value("${app.jwt.secret}")
private String secretKey;

// @ConfigurationProperties – 그룹 설정 주입 (관련 설정이 여러 개일 때 권장)
@Component
@ConfigurationProperties(prefix = "app.jwt")
@Getter @Setter
public class JwtProperties {
    private String secret;
    private long expiration;
    // → application.yml의 app.jwt.* 값이 모두 자동 매핑됨
}

// 통일된 에러 응답 형식
@Getter
@AllArgsConstructor
public class ErrorResponse {
    private final int status;
    private final String code;
    private final String message;
    private final LocalDateTime timestamp;

    public static ErrorResponse of(int status, String code, String message) {
        return new ErrorResponse(status, code, message, LocalDateTime.now());
    }
}

// 전역 예외 처리기
@RestControllerAdvice           // @ControllerAdvice + @ResponseBody
@Slf4j
public class GlobalExceptionHandler {

    // 비즈니스 예외 처리
    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleUserNotFound(UserNotFoundException e) {
        log.warn("[404] 사용자를 찾을 수 없음: {}", e.getMessage());
        return ResponseEntity
                .status(HttpStatus.NOT_FOUND)
                .body(ErrorResponse.of(404, "USER_NOT_FOUND", e.getMessage()));
    }

    // 유효성 검사 실패 처리 (@Valid 위반)
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException e) {
        String message = e.getBindingResult()
                .getFieldErrors()
                .stream()
                .map(err -> err.getField() + ": " + err.getDefaultMessage())
                .collect(Collectors.joining(", "));

        return ResponseEntity
                .status(HttpStatus.BAD_REQUEST)
                .body(ErrorResponse.of(400, "VALIDATION_FAILED", message));
    }

    // 인증 실패 처리
    @ExceptionHandler(UnauthorizedException.class)
    public ResponseEntity<ErrorResponse> handleUnauthorized(UnauthorizedException e) {
        return ResponseEntity
                .status(HttpStatus.UNAUTHORIZED)
                .body(ErrorResponse.of(401, "UNAUTHORIZED", e.getMessage()));
    }

    // 그 외 모든 예외 (최후 방어선)
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleException(Exception e) {
        log.error("[500] 예상치 못한 오류 발생", e);
        return ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(ErrorResponse.of(500, "INTERNAL_ERROR", "서버 내부 오류가 발생했습니다."));
    }
}

@Configuration              // 이 클래스가 Bean 설정 클래스임을 선언
public class AppConfig {

    // @Bean – 메서드가 반환하는 객체를 스프링 Bean으로 등록
    @Bean
    public RestTemplate restTemplate() {
        HttpComponentsClientHttpRequestFactory factory =
            new HttpComponentsClientHttpRequestFactory();
        factory.setConnectTimeout(3000);
        factory.setReadTimeout(10000);
        return new RestTemplate(factory);
    }

    @Bean
    public ObjectMapper objectMapper() {
        return new ObjectMapper()
                .registerModule(new JavaTimeModule())
                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
    }

    // 환경별 Bean 조건부 등록
    @Bean
    @Profile("prod")        // 운영 환경에서만 등록
    public DataSource prodDataSource() { ... }

    @Bean
    @Profile("dev")         // 개발 환경에서만 등록
    public DataSource devDataSource() { ... }
}

[스프링부트 핵심 애노테이션 10개 요약]

🟢 구동·설정 레이어
  ① @SpringBootApplication  → 앱 진입점, 컴포넌트 스캔 + 자동 설정 활성화
  ② @Configuration + @Bean  → 수동 Bean 등록 및 커스텀 설정

🔵 웹(API) 레이어
  ③ @RestController         → REST API 컨트롤러 (JSON 응답 자동화)
  ④ @RequestMapping 계열    → URL 라우팅 (Get/Post/Put/Patch/DeleteMapping)

🟡 서비스·Bean 레이어
  ⑤ @Service / @Component   → 비즈니스 로직 Bean 등록
  ⑥ @Autowired (생성자 주입) → 의존성 자동 주입

🔴 데이터 레이어
  ⑦ @Entity                 → JPA DB 테이블 매핑
  ⑧ @Repository + @Query    → 데이터 접근, 커스텀 JPQL/SQL
  ⑨ @Transactional          → 트랜잭션 자동 관리

🟣 공통·횡단 관심사
  ⑩ @RestControllerAdvice   → 전역 예외 처리 (+ @ExceptionHandler)
     + @Value                → 프로퍼티 설정값 주입