Spring Boot에서 사용되는 각종 어노테이션 (Annotation)이 굉장히 많은데 이 글에서 다양한 어노테이션을 정리해보려고 한다.

1. 스프링의 기본 어노테이션

1.1. @Component

스프링이 관리하는 일반적인 빈 (Bean)을 정의할 때 사용

사용 예시

✍️ 작성

@Component
public class MyService {
    // 비즈니스 로직
}

1.2. @Service

@Component의 특별한 형태로, 주로 비즈니스 로직을 담당하는 클래스에 사용

사용 예시

✍️ 작성

@Service
public class UserService {
    // 사용자 관련 로직
}

1.3. @Repository

데이터 접근 계층 (DAO)에 사용. 데이터베이스와의 상호작용을 담당하는 클래스에 사용하면, 예외 변환 등의 추가적인 기능을 제공

사용 예시

✍️ 작성

@Repository
public class UserRepository {
    // 데이터베이스 접근 로직
}

1.4. @Controller

웹 요청을 처리하는 컨트롤러 클래스에 사용. 주로 MVC 패턴에서 뷰를 반환할 때 사용

사용 예시

✍️ 작성

@Controller
public class HomeController {
    @GetMapping("/")
    public String home() {
        return "home";
    }
}

1.5. @RestController

@Controller와 @ResponseBody를 합친 어노테이션으로, 주로 RESTful 웹 서비스를 만들 때 사용.
JSON 같은 데이터를 반환할 때 편리

사용 예시

✍️ 작성

@RestController
public class ApiController {
    @GetMapping("/api/data")
    public Data getData() {
        return new Data();
    }
}

1.6. @Scope

@Scope 어노테이션은 스프링 빈의 생명주기와 범위를 지정하는 어노테이션으로, 기본값은 싱글턴 (singleton)
예를 들어, @Scope("prototype")이라고 설정하면 빈을 요청할 때마다 새로운 인스턴스 생성
자세한 내용은 다음글을 참고

사용 예시

✍️ 작성

@Component
@Scope("prototype")
public class MyBean {
    // Bean 내용
}

2. 의존성 주입 관련 어노테이션

2.1. @Autowired

스프링이 자동으로 필요한 빈을 주입. 생성자, 필드, 메서드에 사용가능

자세한 내용은 해당 글을 참고한다.

사용 예시

✍️ 작성

@Service
public class OrderService {
    
    @Autowired
    private PaymentService paymentService;

    // 또는 생성자 주입 방식
    /*
    private final PaymentService paymentService;

    @Autowired
    public OrderService(PaymentService paymentService) {
        this.paymentService = paymentService;
    }
    */
}

2.2. @Qualifier

동일한 타입의 빈이 여러 개일 때, 특정 빈을 지정하여 주입하고 싶을 때 사용

사용 예시

✍️ 작성

@Service
public class NotificationService {

    @Autowired
    @Qualifier("emailService")
    private MessageService messageService;
}

3. 설정 관련 어노테이션

3.1. @Configuration

스프링의 설정 클래스를 정의할 때 사용하며 빈을 직접 등록하거나 설정 가능.
@Component을 내부에 포함하고 있어 @Configuration가 붙은 설정 클래스는 자동으로 빈으로 등록됨.

3.2. @Bean

@Configuration 클래스 내에서 메서드에 사용하여 반환 값(객체)들을 빈을 등록

사용 예시

✍️ 작성

@Configuration
public class AppConfig {

    @Bean
    public MyBean myBean() {
        return new MyBean();
    }
    
    @Bean
    public MyService myService() {
        return new MyService();
    }
}

3.3. @ComponentScan

지정한 패키지 (및 그 하위 패키지) 내에서 스프링 컴포넌트(@Component, @Service, @Repository, @Controller, @Configuration 등)가 붙은 클래스를 자동으로 스캔해서 빈으로 등록

사용 예시

✍️ 작성

@Configuration
@ComponentScan(basePackages = "com.example.myapp")
public class AppConfig {
    // 이 패키지 내의 컴포넌트들이 자동 등록됨
}

3.4. @EnableAutoConfiguration

스프링 부트의 자동 설정 기능을 활성화.
애플리케이션의 클래스패스, 설정 파일, 환경 변수 등을 기반으로 필요한 설정을 자동으로 구성

사용 예시

✍️ 작성

@Configuration
@EnableAutoConfiguration
public class AppConfig {
    // 스프링 부트가 자동으로 필요한 설정을 적용함
}

3.5. @SpringBootConfiguration

@SpringBootConfiguration은 스프링 부트 애플리케이션에서 설정 클래스를 나타내는 어노테이션.
기본적으로 @Configuration과 동일하게 동작하지만, 스프링 부트 전용으로 사용

사용 예시

✍️ 작성

import org.springframework.boot.SpringBootConfiguration;
import org.springframework.context.annotation.Bean;

@SpringBootConfiguration
public class AppConfig {

    @Bean
    public MyService myService() {
        return new MyServiceImpl();
    }
}

3.6. @SpringBootApplication

스프링 부트 애플리케이션의 시작점을 정의하는 복합 어노테이션

하나의 어노테이션으로 스프링 부트의 주요 설정을 모두 포함시켜, 설정을 간단하게 만들고 애플리케이션을 쉽게 시작할 수 있도록 해줌.

내부적으로 @SpringBootConfiguration, @EnableAutoConfiguration, @ComponentScan의 어노테이션을 포함

사용 예시

✍️ 작성

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

다음은 @SpringBootApplication의 소스코드 내용이다. 앞서 소개한 다양한 어노테이션들을 포함하고 있음을 알 수 있다.

✍️ 작성

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@SpringBootConfiguration
@EnableAutoConfiguration
@ComponentScan(excludeFilters = { @Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class),@Filter(type = FilterType.CUSTOM, classes = AutoConfigurationExcludeFilter.class) })

public @interface SpringBootApplication {...... }

4. 웹 관련 어노테이션

4.1. @RequestMapping

특정 URL과 HTTP 메서드 (GET, POST, PUT, DELETE 등)를 컨트롤러의 특정 메서드에 연결할 때 사용.

단순한 URL 매핑뿐만 아니라, 특정 요청 파라미터, 헤더, 미디어 타입 (Consumes, Produces) 등 여러 조건에 따라 세밀하게 매핑.

예를 들어, 같은 URL이라도 GET 요청과 POST 요청을 서로 다른 메서드로 처리할 수 있고, 추가 조건 (예: 특정 헤더가 있어야 한다거나)을 붙일 수도 있음.

어노테이션의 주요 속성

• value : 매핑할 URL 경로를 지정
• method : HTTP 메서드를 지정. 예) RequestMethod.GET
• params : 클라이언트가 보내는 요청의 쿼리 스트링이나 폼 데이터에 포함된 파라미터가 조건에 맞아야 매핑.
• headers : 클라이언트가 요청 시 전송하는 HTTP 헤더 중 특정 키-값 조합이 있어야 매핑.
• consumes / produces : 요청이나 응답의 미디어 타입을 제한할 때 사용.

사용 예시

✍️ 작성

@Controller
public class ProductController {

	// active 파라미터가 있는 GET 요청에만 반응
    @RequestMapping(value = "/users", method = RequestMethod.GET, params = "active")
	public String getActiveUsers() {
        return "activeUsers";
	}
}

4.2. @GetMapping, @PostMapping 등

@RequestMapping의 축약형으로, 특정 HTTP 메서드에만 매핑할 때 사용

사용 예시

✍️ 작성

@RestController
public class UserController {

    @GetMapping("/users")
    public List<User> getUsers() {
        return userService.getAllUsers();
    }

    @PostMapping("/users")
    public User createUser(@RequestBody User user) {
        return userService.createUser(user);
    }
}

4.3. @CookieValue

@CookieValue 어노테이션은 스프링 MVC에서 컨트롤러 메소드의 파라미터에 쿠키 값을 바인딩할 때 사용하는 어노테이션

사용 예시

✍️ 작성

@GetMapping("/visit")
public String showVisit(@CookieValue(name = "lastVisit", defaultValue = "N/A") String lastVisit, Model model) {
    // 쿠키 "lastVisit"의 값이 있으면 lastVisit 변수에 할당, 없으면 "N/A" 할당됨
    model.addAttribute("lastVisit", lastVisit);
    return "visit";
}

1. 쿠키 읽기

• 클라이언트가 HTTP 요청을 할 때, 브라우저는 요청 헤더에 여러 쿠키를 함께 보낸다. 스프링은 이 요청 헤더를 분석해서 요청에 포함된 쿠키들을 찾는다.

2. @CookieValue의 역할

• @CookieValue(name = "lastVisit")는 "lastVisit"이라는 이름의 쿠키 값을 찾아서 해당 메소드의 파라미터 lastVisit에 할당한다.
• 만약 "lastVisit" 쿠키가 요청에 포함되어 있지 않다면, defaultValue = "N/A" 설정에 의해 lastVisit 변수에 "N/A"가 할당된다.

3. 컨트롤러 메소드 실행

• 이 방식으로, 컨트롤러 메소드는 별도의 코드로 쿠키를 직접 추출하지 않아도, @CookieValue 덕분에 필요한 쿠키 값을 바로 사용할 수 있게 된다. 즉, 코드가 깔끔해지고, 개발자가 직접 쿠키를 파싱하는 수고를 덜어준다.

4.4. @SessionAttributes

@SessionAttributes 어노테이션은 Spring MVC 컨트롤러에서 Model에 담긴 특정 속성을 세션에 저장해두도록 지정하는 어노테이션

즉, 컨트롤러 메소드가 반환한 Model의 데이터 중 지정한 이름이나 타입의 속성을 HttpSession에 저장해서 여러 요청 간에 공유할 수 있도록 도와줌.

예를 들어, 로그인 폼이나 멀티스텝 폼 처리에서 사용자가 입력한 정보를 여러 요청에 걸쳐 유지해야 할 때 유용

사용 예시

✍️ 작성

@Controller
@SessionAttributes("user")
public class UserController {

    @GetMapping("/userForm")
    public String showForm(Model model) {
        model.addAttribute("user", new User());
        return "userForm";
    }

    @PostMapping("/userForm")
    public String processForm(@ModelAttribute("user") User user) {
        // 입력된 user 정보를 세션에 저장해두고, 이후 단계에서 사용할 수 있음
        return "redirect:/nextStep";
    }
}

여기서, "user"라는 이름의 Model 속성이 자동으로 세션에 저장되며, 이후 요청 시 해당 속성을 바로 사용할 수 있음.

5. 데이터 바인딩 및 검증 어노테이션

※ 바인딩이란?

바인딩은 외부에서 들어온 데이터를 코드에서 정의한 변수 (혹은 파라미터)에 맞게 자동으로 연결해주는 작업인데 간단하게 말해서 값을 연결하는 것을 의미한다. 예를 들어, 웹 요청이 들어오면 URL 쿼리 파라미터나 폼 데이터 같은 데이터들이 있는데, 이 데이터들을 메서드의 파라미터에 넣어주는 과정을 바인딩이라고 한다.

✍️ 작성

@GetMapping("/greet")
public String greet(@RequestParam("name") String name) {
    return "Hello, " + name + "!";
}

위 예시 코드를 보면 쉽게 이해할 수 있는데, 여기서 클라이언트가 /greet?name=Alice로 요청하면, 스프링은 name 파라미터에 "Alice"를 바인딩 (연결)해서 넣어준다. 그래서 메서드 내에서는 name 변수에 "Alice"가 들어있게 된다.

5.1. @RequestParam

HTTP 요청의 파라미터를 메서드 파라미터에 바인딩할 때 사용

String 형태의 데이터를 int, long, Date 등으로 자동 변환해주기 때문에 따로 파싱할 필요 없음.

파라미터가 필수인지, 기본값은 뭔지 설정 가능.

어노테이션의 주요 속성

• value : 바인딩할 요청 파라미터의 이름 지정.
• required : 해당 파라미터의 필수 여부 (true/false, 기본은 true).
• defaultValue : 요청 파라미터가 없을 때 사용할 기본 값.

사용 예시

✍️ 작성

@RequestMapping("/search")
public String search(@RequestParam(value = "query", required = false, defaultValue = "") String query) {
    // query 파라미터가 없으면 빈 문자열로 처리
    return "searchResult";
}

5.2. @PathVariable

URL 경로의 변수를 메서드 파라미터에 바인딩할 때 사용

리소스의 식별자를 URL 경로에 넣어 표현할 때 유용

URL 경로에 여러 변수가 있을 경우 각각의 값을 별도의 @PathVariable로 받아 처리

사용 예시

✍️ 작성

@RequestMapping("/users/{userId}")
public String getUser(@PathVariable("userId") Long userId) {
    // URL 경로의 {userId} 값을 받아서 처리
    return "userDetail";
}

※ 쿼리 파라미터와 경로 변수의 차이점

경로는 리소스의 위치를 나타내는 부분이고, 쿼리 파라미터는 그 위치에 추가 정보를 덧붙이는 것이다.

예를 들어,

• 경로 변수 : /users/{abc}에서는 /users/123처럼 실제 리소스 (여기서는 사용자 'abc')를 가리키는 위치이다.
• 쿼리 파라미터 : /greet?name=Alice에서 ?name=Alice는 리소스 경로(/greet)에 추가 정보를 전달하는 역할이다.

즉, URL 경로는 요청할 리소스의 "주소"를 의미하고, 쿼리 파라미터는 그 주소에 대해 추가적인 조건이나 데이터를 제공한다.

5.3. @RequestBody

HTTP 요청의 본문 (body)에 담긴 데이터를 컨트롤러 메서드의 파라미터로 바인딩할 때 사용하는 어노테이션

예를 들어, 클라이언트가 JSON 데이터를 보내면, Spring이 HTTP 메시지 컨버터를 통해 그 JSON을 우리가 원하는 객체 타입으로 변환해서 파라미터에 넣어주는 역할을 수행.

주로 REST API에서 많이 사용

사용 예시

예를 들어, 클라이언트가 아래와 같은 JSON 데이터를 보낸다고 가정.

JSON 데이터

✍️ 작성

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

Spring은 HTTP 메시지 컨버터를 사용해서 해당 JSON 데이터를 자동으로 우리가 지정한 객체 타입으로 변환. 다음과 같은 User 클래스가 있다고 할 때,

User 클래스

✍️ 작성

public class User {
    private String name;
    private String email;
    private int age;
    
    // getter와 setter 생략
}

컨트롤러에서는 아래와 같이 사용

✍️ 작성

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
    // 클라이언트가 보낸 JSON 데이터를 HTTP 메시지 컨버터가 User 객체로 변환해서 user 변수에 넣어줌
    // 이후 user 객체를 이용해 로직 처리
    return ResponseEntity.ok(user);
}

여기서 클라이언트가 보내는 JSON의 각 필드 ("name", "email", "age")가 User 클래스의 필드와 매핑되어, 별도의 파싱 작업 없이 바로 user 객체에 들어감. 이 과정이 바로 HTTP 메시지 컨버터에 의한 자동 변환.

5.4. @ModelAttribute

@ModelAttribute 어노테이션의 사용방식으로는 2가지가 있다.

[1] 메서드 파라미터에 사용

• 요청 파라미터 바인딩
  컨트롤러의 핸들러 메서드 (@GetMapping, @PostMapping, @RequestMapping)에서 @ModelAttribute가 메서드 파라미터에 붙으면, 스프링은 HTTP 요청 파라미터들을 자동으로 객체의 필드에 바인딩.

  예를 들어, 로그인 폼에서 전달된 email, password 값을 LoginForm 객체의 email, password 필드에 자동으로 할당해주는 역할을 수행.

(HTTP 요청 파라미터(쿼리 파라미터(GET 방식)나 폼 데이터(POST 방식))의 이름과 해당 객체의 필드명을 비교하고 일치하면 자동으로 할당)

• 모델에 자동 등록
  @ModelAttribute를 메서드 파라미터에 붙이면, 그 객체는 모델 (Model)에 자동으로 추가
  따라서 핸들러 메서드 내부나 뷰에서 해당 객체를 바로 사용가능.

• 유효성 검사와 결합
  보통 @Valid와 함께 사용해서, 바인딩된 객체에 대해 유효성 검증을 진행 가능. 만약 유효성 오류가 발생하면 BindingResult에 에러 정보가 담기고, 이후 #fields와 th:errors 등을 통해 뷰에 표시할 수 있음.

✍️ 예제 코드 작성

@PostMapping("/login")
public String login(@Valid @ModelAttribute("loginForm") LoginForm loginForm, BindingResult bindingResult) {
    if (bindingResult.hasErrors()) {
        return "login"; // 에러가 있으면 다시 로그인 폼으로
    }
    // 정상 처리 로직
    return "result";
}

@ModelAttribute("loginForm")를 사용하면, HTTP 요청 파라미터가 LoginForm 객체에 매핑된다. 이 객체는 자동으로 "loginForm"이라는 이름 (key)으로 모델 (Model)에 등록되기 때문에, 뷰 템플릿에서 ${loginForm} 같은 식으로 접근할 수 있음.
유효성 검증 (@Valid)을 함께 사용하면, 검증 결과는 BindingResult에 담기고, 이를 통해 에러 처리도 할 수 있다.

[2] 메서드 레벨에 사용

1. 공통 모델 속성 추가

• 컨트롤러 내에 @ModelAttribute가 붙은 메서드는, 해당 컨트롤러의 모든 요청 핸들러(@RequestMapping, @GetMapping, @PostMapping 등)가 실행될 때 마다 먼저 호출됨.

2. 모델에 데이터 자동 추가

• 이 메서드에서 반환하는 객체 (또는 Model 파라미터에 직접 추가한 속성)는 모델에 자동으로 포함돼서, 모든 핸들러 메서드와 뷰에서 공통적으로 사용 가능

3. 데이터 준비 역할

• 예를 들어, 모든 페이지에서 공통으로 필요한 메뉴 목록, 현재 시간, 공지사항 등 반복적으로 사용하는 데이터를 한 번만 준비해서 모델에 넣어두는 데 유용

✍️ 예제 코드 작성

@Controller
public class MyController {

    // 모든 요청 전에 자동 실행되어, 모델에 "currentTime"이라는 속성 추가
    @ModelAttribute("currentTime")
    public String getCurrentTime() {
        return LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
    }
    
    // 또는 Model 파라미터를 사용해서 속성을 추가 가능
    @ModelAttribute
    public void addCommonAttributes(Model model) {
        model.addAttribute("msg", "Welcome to the Application!");
    }

    @GetMapping("/home")
    public String home() {
        // 위의 @ModelAttribute 메서드들 덕분에, "currentTime"과 "msg"가 이미 모델에 추가되어 있음.
        return "home"; // home.html 뷰 렌더링
    }
}

위의 두 메서드 (getCurrentTime(), addCommonAttributes())는 /home 요청이 들어오기 전에 먼저 실행. 그래서, home() 메서드에서 반환하는 뷰 템플릿에서는 이미 ${currentTime}과 ${msg}를 사용할 수 있음.

getCurrentTime() 메서드는 String을 리턴하면서 그 값이 "currentTime"이라는 이름으로 모델에 추가.
addCommonAttributes(Model model) 메서드는 void 타입이지만, Model 객체에 직접 속성을 추가하면 그 값이 모델에 등록.

6. 기타 유용한 어노테이션

6.1. @Transactional

메서드나 클래스에 적용하여 트랜잭션 관리. 주로 데이터베이스 작업 시 사용

사용 예시

✍️ 작성

@Service
public class BankService {

    @Transactional
    public void transferMoney(Long fromAccount, Long toAccount, BigDecimal amount) {
        // 송금 로직
    }
}

6.2. @Value

프로퍼티 파일이나 환경 변수를 주입받을 때 사용

사용 예시

✍️ 작성

@Component
public class AppConfig {

    @Value("${app.name}")
    private String appName;
}

7. 해당 게시글 작성에 참고한 글 목록

멋쟁이 사자처럼 강의자료