Spring Boot 게시판 개발, 핵심 어노테이션 정리

Spring Boot 기반으로 웹 애플리케이션을 개발할 때 반복적으로 사용되는 어노테이션들이 있으며, 각 계층(Layer)에서의 역할과 용도를 명확히 이해하는 것은 중요하다.

게시판 프로젝트를 기준으로, 각 계층에서 필수적으로 사용되는 어노테이션들을 그 역할과 함께 기술한다.

1. 스프링 부트 시작과 설정을 위한 어노테이션

애플리케이션의 구동과 전반적인 설정을 담당하는 기본 어노테이션이다.

• @SpringBootApplication: 스프링 부트 프로젝트의 시작과 핵심 설정을 담당하는 어노테이션이다. 이 어노테이션은 자동 설정(@EnableAutoConfiguration), 컴포넌트 스캔(@ComponentScan) 등의 기능을 포함하고 있어, 개발자가 복잡한 초기 설정 없이 애플리케이션 개발에 집중할 수 있도록 돕는다.사용 시점: 애플리케이션의 진입점이 되는 메인 클래스에 선언한다. 일반적으로 프로젝트 생성 시 기본으로 포함되어 있다.
• @SpringBootApplication public class BoardApplication { public static void main(String[] args) { SpringApplication.run(BoardApplication.class, args); } }
• @Configuration & @Bean: 스프링 컨테이너에 개발자가 직접 빈(Bean)을 등록해야 할 경우 사용된다. @Configuration을 클래스에 적용하여 해당 클래스가 설정 파일임을 명시하고, 내부 메서드에 @Bean을 선언하여 반환되는 객체를 스프링 빈으로 등록한다.사용 시점: 외부 라이브러리의 클래스나, 복잡한 생성 로직이 필요한 객체를 스프링 컨테이너에 등록할 때 유용하다.
• @Configuration public class AppConfig { @Bean // 해당 메서드가 반환하는 객체를 Bean으로 등록 public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } }

2. 요청 처리를 위한 컨트롤러 어노테이션

클라이언트의 HTTP 요청을 받아 처리하는 프레젠테이션 계층(Presentation Layer)에서 사용된다.

• @Controller와 @RestController의 구분:
  • @Controller: 주로 뷰(View)를 반환하기 위해 사용된다. 메서드가 반환하는 문자열(String)은 뷰 리졸버(View Resolver)를 통해 해석되어 해당 뷰 템플릿(예: *.html)을 렌더링한다.
  • @RestController: @Controller와 @ResponseBody가 결합된 어노테이션으로, 데이터(주로 JSON/XML)를 반환하는 RESTful API를 개발할 때 사용된다. 메서드가 반환한 객체는 HTTP 응답 본문(Body)에 직접 작성된다.
• @GetMapping, @PostMapping, @PutMapping, @DeleteMapping: URL 경로를 특정 HTTP 메서드(GET, POST, PUT, DELETE)와 매핑하는 어노테이션이다. @RequestMapping(method = ...)의 축약형으로, 코드를 더 직관적으로 만들어준다.
• @PathVariable: URL 경로의 일부를 파라미터로 추출할 때 사용한다. 예를 들어 /posts/{id}와 같은 URL에서 {id} 값을 메서드 인자로 받아올 수 있다.
• @GetMapping("/posts/{id}") public String postDetail(@PathVariable Long id, Model model) { // URL의 {id} 값이 id 파라미터에 바인딩된다. Post post = postService.findById(id); model.addAttribute("post", post); return "posts/detail"; }
• @RequestParam: URL의 쿼리 파라미터(?key=value)를 메서드 인자로 받아올 때 사용한다. 페이징이나 검색 기능 구현 시 주로 활용된다.
• @RequestBody: HTTP 요청의 본문(Body)에 포함된 데이터를 자바 객체로 변환(역직렬화)한다. 클라이언트가 전송한 JSON 데이터를 DTO(Data Transfer Object)로 매핑할 때 필수적이다.
• @RestController @PostMapping("/api/posts") public Post createPost(@RequestBody PostCreateRequest dto) { // JSON 요청 본문이 dto 객체에 매핑된다. return postService.create(dto); }

3. 비즈니스 로직과 데이터 접근 어노테이션

애플리케이션의 핵심 로직을 처리하는 서비스 계층과 데이터 영속성을 담당하는 계층에서 사용된다.

• @Service: 비즈니스 로직을 수행하는 서비스 계층의 클래스임을 나타내는 스테레오타입 어노테이션이다.
• @Repository: 데이터베이스에 접근하는 DAO(Data Access Object) 클래스, 즉 데이터 접근 계층임을 나타낸다. JPA의 예외를 스프링의 DataAccessException으로 변환하는 역할도 수행한다.
• @Component: 위와 같이 명확한 역할이 없는 범용 컴포넌트를 등록할 때 사용한다. @Service, @Repository 등은 모두 @Component를 상속한다.
• @Autowired: 의존성 주입(DI) 시 사용되며, 필요한 타입의 빈을 찾아 자동으로 연결한다. 단, 최근에는 불변성 확보와 테스트 용이성을 위해 필드 주입보다 생성자 주입이 권장된다.
• @Transactional: 데이터베이스의 상태를 변경하는 작업을 하나의 트랜잭션 단위로 묶어준다. 메서드 실행 중 예외가 발생하면 모든 작업을 롤백(Rollback)하여 데이터의 일관성을 보장한다. 주로 데이터 변경이 있는 서비스 메서드에 적용한다.

4. 데이터베이스 매핑을 위한 JPA 엔티티

데이터베이스 테이블에 대응되는 자바 클래스, 즉 엔티티(Entity)를 정의할 때 사용된다.

• @Entity: 해당 클래스가 JPA가 관리하는 엔티티임을 선언한다.
• @Id & @GeneratedValue: 필드가 테이블의 기본 키(Primary Key)임을 나타내며, 기본 키의 생성 전략(예: IDENTITY - 자동 증가)을 지정한다.
• @Column: 엔티티의 필드와 테이블의 컬럼을 매핑한다. nullable, length 등 컬럼의 세부 속성을 설정할 수 있다.
• @ManyToOne, @OneToMany: 엔티티 간의 관계를 정의한다. @JoinColumn을 함께 사용하여 외래 키(Foreign Key)를 매핑한다.

@Entity
public class Post {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 100)
    private String title;

    @Lob // CLOB, BLOB 등 대용량 데이터 타입으로 매핑
    private String content;

    @ManyToOne(fetch = FetchType.LAZY) // 지연 로딩 전략
    @JoinColumn(name = "user_id")
    private User author;
}

5. 코드 간소화를 위한 Lombok

어노테이션 프로세서를 통해 반복적인 보일러플레이트 코드(Getter, Setter, 생성자 등)를 컴파일 시점에 자동으로 생성해주는 라이브러리다.

• @Getter / @Setter: 필드에 대한 접근자/설정자 메서드를 생성한다.
• @NoArgsConstructor / @AllArgsConstructor: 각각 파라미터가 없는 기본 생성자와 모든 필드를 인자로 받는 생성자를 생성한다.
• @RequiredArgsConstructor: final 또는 @NonNull로 선언된 필드만을 인자로 받는 생성자를 생성한다. 생성자 주입 패턴과 함께 사용하면 코드가 매우 간결해진다.
• @Service @RequiredArgsConstructor // final 필드에 대한 생성자 자동 생성 public class PostService { private final PostRepository postRepository; // 의존성 주입을 위한 생성자를 직접 작성할 필요가 없음 }
• @Builder: 빌더 패턴(Builder Pattern)을 적용하여 객체 생성을 용이하게 한다.
• @Data: 여러 어노테이션(@Getter, @Setter, @RequiredArgsConstructor, @ToString 등)을 한 번에 적용한다. 편리하지만, 엔티티 클래스에서는 양방향 연관관계 등에서 의도치 않은 문제를 유발할 수 있어 선별적 사용이 권장된다.
• @Slf4j: 로깅 프레임워크 SLF4J의 Logger 객체를 log라는 이름으로 자동 생성한다.