Spring Annotation 정리

2coconut·2025년 7월 10일

어노테이션이란?

Spring Framework를 사용하다 보면 수많은 어노테이션(Annotation)을 접하게 된다. 어노테이션은 단순한 "주석"이 아니라 코드에 특별한 의미와 기능을 부여하는 강력한 도구다. Java 5부터 도입된 기능으로, 코드에 메타데이터를 제공하는 방법이다. @ 기호로 시작하며, 컴파일러나 런타임에게 특별한 지시사항을 전달한다.

어노테이션의 장점:

코드가 깔끔해지고 가독성이 향상된다
설정을 코드에 직접 명시할 수 있다
재사용성과 유지보수성이 높아진다
XML 설정을 대체할 수 있다

Controller 계층 어노테이션

@Controller

Spring MVC의 컨트롤러임을 나타낸다
주로 뷰(View)를 반환할 때 사용한다
요청을 받아 비즈니스 로직을 처리하고 결과를 뷰에 전달한다

@RestController

@RestController
public class ApiController {
    @GetMapping("/users")
    public List<User> getUsers() {
        return userService.getAllUsers(); // JSON으로 반환
    }
}

@Controller + @ResponseBody의 결합이다
모든 메서드가 자동으로 JSON 형태로 응답한다
RESTful API 개발에 주로 사용한다

@ResponseBody

메서드의 반환값을 HTTP 응답 본문에 직접 쓴다
뷰 대신 데이터를 JSON/XML 형태로 반환한다
@Controller에서 특정 메서드만 API로 사용할 때 유용하다

요청 매핑 어노테이션

@RequestMapping

HTTP 요청을 특정 메서드에 매핑한다
URL 패턴과 HTTP 메서드를 지정할 수 있다

HTTP 메서드별 어노테이션

@GetMapping("/users")           // 조회
@PostMapping("/users")          // 생성
@PutMapping("/users/{id}")      // 전체 수정
@DeleteMapping("/users/{id}")   // 삭제

@RequestMapping보다 명확하고 간결하다
RESTful API 설계에 적합하다

요청 데이터 처리 어노테이션

@RequestParam

@GetMapping("/search")
public List<User> searchUsers(@RequestParam("name") String userName) {
    // ?name=김철수 형태의 쿼리 파라미터 처리
}

URL의 쿼리 파라미터를 메서드 파라미터로 받는다

@PathVariable

@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    // /users/123 형태의 URL에서 값 추출
}

URL 경로에서 변수를 추출한다
RESTful API에서 자주 사용된다

@RequestBody

@PostMapping("/users")
public User createUser(@RequestBody UserCreateRequest request) {
    // HTTP 요청 본문의 JSON을 객체로 변환
}

HTTP 요청 본문을 Java 객체로 변환한다
주로 JSON 데이터를 받을 때 사용한다

빈(Bean) 관리 어노테이션

@Component

클래스를 Spring 빈으로 등록한다
컴포넌트 스캔의 대상이 된다

@Service

서비스 계층의 클래스임을 명시한다
비즈니스 로직 처리를 담당하는 클래스에 사용한다

@Repository

데이터 접근 계층의 클래스임을 명시한다
데이터베이스 예외를 Spring의 DataAccessException으로 변환한다

@Configuration

@Configuration
public class AppConfig {
    @Bean
    public DataSource dataSource() {
        return new HikariDataSource();
    }
}

설정 클래스임을 나타낸다
@Bean 메서드들을 포함할 수 있다

@Bean

메서드가 반환하는 객체를 Spring 빈으로 등록한다
@Configuration 클래스 내에서 사용한다

의존성 주입 어노테이션

@Autowired

@Service
public class UserService {
    private final UserRepository userRepository;
    
    @Autowired // 생성자가 하나면 생략 가능
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
}

타입에 따라 자동으로 의존성을 주입한다
생성자 주입이 가장 권장되는 방식이다

@Qualifier

@Autowired
@Qualifier("creditCardProcessor")
private PaymentProcessor paymentProcessor;

같은 타입의 빈이 여러 개일 때 구체적으로 지정한다

@Primary

같은 타입의 빈이 여러 개일 때 우선순위를 지정한다

Spring Boot 어노테이션

@SpringBootApplication

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

Spring Boot 애플리케이션의 진입점을 나타낸다
@SpringBootConfiguration, @EnableAutoConfiguration, @ComponentScan의 조합이다

@ComponentScan

지정된 패키지에서 컴포넌트를 스캔한다
@Component, @Service, @Repository, @Controller 등을 찾아 빈으로 등록한다

@EnableAutoConfiguration

Spring Boot의 자동 설정을 활성화한다
클래스패스에 있는 라이브러리를 기반으로 자동으로 빈을 구성한다

JPA 어노테이션

@Entity

@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "user_name", nullable = false)
    private String name;
}

JPA 엔티티 클래스임을 나타낸다
데이터베이스 테이블과 매핑된다

@Id와 @GeneratedValue

@Id: 기본키(Primary Key)를 나타낸다
@GeneratedValue: 기본키 값을 자동으로 생성한다

@Column

필드를 데이터베이스 컬럼과 매핑한다
생략하면 필드명이 컬럼명이 된다

테스트 어노테이션

@Test

JUnit 테스트 메서드임을 나타낸다

@SpringBootTest

@SpringBootTest
@Transactional
class UserServiceTest {
    @Autowired
    private UserService userService;
    
    @Test
    void 사용자_생성_테스트() {
        // 테스트 후 자동으로 롤백됨
    }
}

Spring Boot 통합 테스트를 위한 어노테이션이다
실제 Spring 컨텍스트를 로드하여 테스트한다

@Transactional (테스트)

테스트에서 사용하면 테스트 완료 후 자동으로 롤백한다
테스트 간 데이터 독립성을 보장한다

@BeforeEach와 @AfterEach

@BeforeEach: 각 테스트 메서드 실행 전에 호출된다
@AfterEach: 각 테스트 메서드 실행 후에 호출된다

Lombok 어노테이션

@Getter와 @Setter

필드에 대한 getter, setter 메서드를 자동으로 생성한다

@ToString

모든 필드를 포함하는 toString() 메서드를 생성한다

@NoArgsConstructor와 @AllArgsConstructor

@NoArgsConstructor: 기본 생성자 생성
@AllArgsConstructor: 모든 필드를 포함하는 생성자 생성

@RequiredArgsConstructor

@RequiredArgsConstructor
@Service
public class UserService {
    private final UserRepository userRepository;  // 생성자에 포함됨
    private String optionalField;                  // 생성자에 포함되지 않음
}

final 필드나 @NonNull 필드만 포함하는 생성자를 생성한다
의존성 주입에서 생성자 주입을 간편하게 구현할 때 사용한다

@Data

@Getter + @Setter + @ToString + @EqualsAndHashCode + @RequiredArgsConstructor의 조합
실무에서는 세밀한 제어를 위해 개별 어노테이션 사용을 권장한다

2coconut

컴공학생

이전 포스트

Tomcat / NginX

다음 포스트