API 문서

1. 프로젝트 구조

src/main/java
  ├── com.nhnacademy.todo
      ├── controller       // REST API 엔드포인트 정의
      ├── domain           // JPA 엔티티 클래스
      ├── dto              // 데이터 전송 객체 (DTO)
      ├── repository       // JPA 리포지토리 인터페이스
      ├── service          // 비즈니스 로직 구현
      ├── exception        // 사용자 정의 예외 처리
      └── config           // 설정 파일 (예: CORS, 데이터베이스 등)
src/main/resources
  ├── application.properties // 환경 설정 파일

2. 엔티티

package inho.domain;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import jakarta.persistence.*;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.extern.slf4j.Slf4j;

import java.time.LocalDateTime;

@Entity
@NoArgsConstructor
@Data
@Table(name = "todos")
@Slf4j
public class Todo {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "subject", nullable = false)
    private String subject;

    @Column(name = "event_at", nullable = false)
    private String eventAt;

    @Column(name = "created_at", nullable = false, updatable = false)
    private LocalDateTime createdAt;

    @JsonCreator
    public Todo(
            @JsonProperty("subject") String subject,
            @JsonProperty("eventAt") String eventAt) {
        this.subject = subject;
        this.eventAt = eventAt;
        log.debug("eventAt 테스트 {}", eventAt);
        this.createdAt = LocalDateTime.now(); // createdAt을 항상 설정
    }

    @PrePersist
    protected void onCreate() {
        if (this.eventAt == null || this.eventAt.isEmpty()) {
            throw new IllegalArgumentException("eventAt 필드는 필수입니다");
        }
        if (this.createdAt == null) {
            this.createdAt = LocalDateTime.now();
        }
    }
}

subject: 할 일 제목

eventAt: 할 일 날짜

createdAt: 생성 날짜 (자동 설정)

@PrePersist: 데이터 저장 전 필수 값 검증

3. 레포지토리

package inho.repository;

import inho.domain.Todo;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;

import java.util.List;

public interface TodoRepository extends JpaRepository<Todo, Long> {

    List<Todo> findByEventAt(String eventAt);

    long countByEventAt(String eventAt);

    boolean existsById(Long id);

    @Query("SELECT t from Todo t where t.eventAt LIKE :eventMonth%")
    List<Todo> findEventAtStartingWith(String eventMonth);
}

• 특정 날짜 또는 월별 조회 기능 제공
• @Query를 활용하여 월별 데이터 조회

4. 서비스

서비스 구현 (Service Implementation)

package inho.service.impl;

import inho.domain.Todo;
import inho.exception.MaxTodoLimitExceededException;
import inho.exception.TodoNotFoundException;
import inho.repository.TodoRepository;
import inho.service.TodoService;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

@Service
@RequiredArgsConstructor
@Transactional
public class TodoServiceImpl implements TodoService {
    private final TodoRepository todoRepository;
    private static final int DAILY_MAX_TODO_COUNT = 8;

    /**
     * 새로운 TODO를 저장
     */
    public Todo saveTodo(String subject, String eventAt) {
        long count = todoRepository.countByEventAt(eventAt);
        if (count >= DAILY_MAX_TODO_COUNT) {
            throw new MaxTodoLimitExceededException("하루 최대 8개의 TODO만 등록 가능합니다.");
        }
        Todo todo = new Todo(subject, eventAt);
        return todoRepository.save(todo);
    }

    /**
     * 특정 날짜의 모든 TODO 삭제
     */
    public void deleteTodosByDate(String eventAt) {
        List<Todo> todos = todoRepository.findByEventAt(eventAt);
        if (todos.isEmpty()) {
            throw new TodoNotFoundException("해당 날짜(" + eventAt + ")에 등록된 TODO가 없습니다.");
        }
        todoRepository.deleteAll(todos);
    }

    /**
     * 특정 ID의 TODO 삭제
     */
    public void deleteTodoById(Long id) {
        if (!todoRepository.existsById(id)) {
            throw new TodoNotFoundException("ID " + id + "에 해당하는 TODO가 존재하지 않습니다.");
        }
        todoRepository.deleteById(id);
    }

    /**
     * 특정 날짜의 TODO 리스트 조회
     */
    public List<Todo> getTodosByDate(String eventAt) {
       return findTodos(eventAt, false);
    }

    /**
     * 특정 월의 TODO 리스트 조회
     */
    @Transactional(readOnly = true)
    public List<Todo> getTodosByMonth(String eventMonth) {
        return findTodos(eventMonth, true);
    }

    /**
     * 특정 날짜의 TODO 개수 반환
     */
    public long countTodosByDate(String date) {
        return todoRepository.countByEventAt(date);
    }

    /**
     * 특정 ID의 TODO 조회
     */
    public Todo getTodoById(Long id) {
        return todoRepository.findById(id)
                .orElseThrow(() -> new TodoNotFoundException("ID " + id + "에 해당하는 TODO가 존재하지 않습니다."));
    }

    /**
     * 특정 날짜 또는 월의 TODO 리스트 조회 (공통 로직)
     */
    private List<Todo> findTodos(String queryParam, boolean isMonthly){
        return isMonthly ? todoRepository.findEventAtStartingWith(queryParam) : todoRepository.findByEventAt(queryParam);
    }
}

서비스 인터페이스

package inho.service;

import inho.domain.Todo;
import java.util.List;

public interface TodoService {
    Todo saveTodo(String subject, String eventAt);
    void deleteTodosByDate(String eventAt);
    void deleteTodoById(Long id);
    List<Todo> getTodosByDate(String eventAt);
    List<Todo> getTodosByMonth(String eventMonth);
    long countTodosByDate(String date);
    Todo getTodoById(Long id);
}

🔹 핵심 정리

• 비즈니스 로직은 TodoServiceImpl에서 관리
• 인터페이스를 통해 서비스의 계약을 정의
• 트랜잭션을 관리하여 데이터 일관성 유지

5. 컨트롤러

컨트롤러 계층은 클라이언트로부터 HTTP 요청을 받아 서비스 계층을 호출하고, 그 결과를 적절한 HTTP 응답으로 변환하는 역할을 한다.

주요 기능

• TODO 생성: @PostMapping("/events")를 통해 새로운 할 일을 생성한다.
• TODO 삭제: 특정 ID 또는 날짜의 TODO를 삭제한다.
• TODO 조회: 특정 날짜 또는 월의 TODO 리스트를 조회할 수 있다.
• TODO 개수 확인: 특정 날짜의 TODO 개수를 반환한다.

package inho.controller;

import inho.domain.Todo;
import inho.service.TodoService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/calendar")
public class TodoController {

    private final TodoService todoService;

    /**
     * 새로운 TODO 생성
     */
    @PostMapping("/events")
    public ResponseEntity<Todo> createTodo(@RequestBody Todo todo) {
        Todo savedTodo = todoService.saveTodo(todo.getSubject(), todo.getEventAt());
        return ResponseEntity.status(201).body(savedTodo);
    }

    /**
     * 특정 ID의 TODO 삭제
     */
    @DeleteMapping("/events/{id}")
    public ResponseEntity<Void> deleteTodoById(@PathVariable Long id) {
        todoService.deleteTodoById(id);
        return ResponseEntity.noContent().build();
    }

    /**
     * 특정 날짜의 모든 TODO 삭제
     */
    @DeleteMapping("/events/daily/{eventAt}")
    public ResponseEntity<Void> deleteTodosByDate(@PathVariable String eventAt) {
        todoService.deleteTodosByDate(eventAt);
        return ResponseEntity.noContent().build();
    }

    /**
     * 특정 날짜의 TODO 리스트 조회
     */
    @GetMapping(value = "/events/", params = {"year", "month", "day"})
    public ResponseEntity<List<Todo>> getTodosByDate(
            @RequestParam int year,
            @RequestParam int month,
            @RequestParam int day
    ){
        String eventAt = String.format("%04d-%02d-%02d", year, month, day);
        List<Todo> todos = todoService.getTodosByDate(eventAt);
        return ResponseEntity.ok(todos);
    }

    /**
     * 특정 월의 TODO 리스트 조회
     */
    @GetMapping(value = "/events/", params = {"year","month"})
    public ResponseEntity<List<Todo>> getTodosByMonth(
            @RequestParam int year,
            @RequestParam int month
    ){
        String eventMonth = String.format("%04d-%02d", year, month);
        List<Todo> todos = todoService.getTodosByMonth(eventMonth);
        return ResponseEntity.ok(todos);
    }
}

🔹 핵심 정리

• 컨트롤러 계층은 클라이언트 요청을 처리하고 응답 반환
• @RequestParam을 활용하여 날짜 및 월별 조회 지원

---

전반적인 흐름

1. 백엔드 계층 구조

🔹 주요 계층

• 컨트롤러 (Controller): 클라이언트 요청을 받아 처리하고 응답을 반환
• 서비스 (Service): 비즈니스 로직을 수행
• 리포지토리 (Repository): 데이터베이스와 직접적으로 상호작용
• 도메인 (Domain/Entity): 데이터 모델 정의
• 예외 처리 (Exception Handling): 발생하는 예외를 관리하고 적절한 에러 응답을 반환

2. 주요 기능 흐름

🔹 TODO 생성

클라이언트가 POST /api/calendar/events 요청을 보냄

TodoController에서 @RequestBody로 요청 데이터를 받음

TodoService에서 비즈니스 로직 수행 (최대 8개 제한 체크 등)

TodoRepository를 통해 데이터베이스에 저장

저장된 데이터를 클라이언트에 반환 (201 Created 응답)

🔹 TODO 조회

특정 날짜 조회

클라이언트가 GET /api/calendar/events/?year=2024&month=04&day=01 요청

TodoController에서 @RequestParam을 활용해 파라미터를 받음

TodoService에서 findTodos(eventAt, false) 호출

TodoRepository에서 해당 날짜의 데이터를 조회 후 반환

클라이언트에 200 OK 응답과 함께 리스트 반환

특정 월 조회

클라이언트가 GET /api/calendar/events/?year=2024&month=04 요청

TodoService에서 findTodos(eventMonth, true) 호출

TodoRepository에서 해당 월의 데이터를 조회 후 반환

클라이언트에 200 OK 응답과 함께 리스트 반환

🔹 TODO 삭제

특정 ID 삭제

클라이언트가 DELETE /api/calendar/events/{id} 요청

TodoController에서 @PathVariable Long id로 ID 받음

TodoService에서 deleteTodoById(id) 실행

데이터베이스에서 해당 ID 삭제 후 204 No Content 반환

특정 날짜의 모든 TODO 삭제

클라이언트가 DELETE /api/calendar/events/daily/{eventAt} 요청

TodoService에서 deleteTodosByDate(eventAt) 실행

데이터베이스에서 해당 날짜의 TODO 삭제 후 204 No Content 반환

3. 예외 처리 흐름

🔹 예외 발생 시 처리 과정

MaxTodoLimitExceededException: 하루 최대 8개 제한 초과 시 발생

TodoNotFoundException: 삭제 또는 조회 시 해당 데이터가 없을 경우 발생

예외 발생 시 @ControllerAdvice를 통해 글로벌 예외 처리

적절한 HTTP 상태 코드와 메시지를 포함한 JSON 응답 반환

4. 데이터베이스 연동

🔹 TodoRepository

findByEventAt(String eventAt): 특정 날짜의 TODO 조회

findEventAtStartingWith(String eventMonth): 특정 월의 TODO 조회

countByEventAt(String eventAt): 특정 날짜의 TODO 개수 확인

existsById(Long id): 특정 ID 존재 여부 확인

deleteById(Long id): 특정 ID의 TODO 삭제

5. 전체적인 요청 & 응답 흐름

클라이언트 → 컨트롤러 → 서비스 → 리포지토리 → 데이터베이스
           ← 응답 반환 ←

Spring Boot의 핵심 계층을 활용하여 모듈화된 구조로 개발되었으며, 클린 아키텍처를 유지하면서 유지보수성이 높은 구조를 가진다!

데이터 넣기

Front

DB

데이터 삭제

Front

DB

날짜별 삭제