🍃 프론트 개발자가 알아야 하는 Spring Boot 구조

깽지·2026년 3월 10일

백엔드 개발자와 협업하다 보면 "Controller에서 받아서 Service 거쳐서 Repository로 가요"
라는 말을 듣게 됩니다. 근데... 그게 뭔지 모르면 소통이 안 되죠.
이 글은 Spring Boot를 직접 짜는 법이 아니라, 프론트 개발자가 협업할 때 꼭 알아야 할 구조와 개념만 정리했습니다.

🗺️ 전체 구조 한눈에 보기

[브라우저 / 앱]
      │
      │ HTTP 요청 (GET, POST, PUT, DELETE)
      ▼
┌─────────────────────────────────────────┐
│              Spring Boot 서버        │
│                                      │ 
│  ┌──────────────┐                     │
│  │  Controller │  ← 요청을 받는 창구   │
│  └──────┬───────┘                     │
│         │                            │
│  ┌──────▼──────┐                      │
│  │   Service  │  ← 비즈니스 로직       │
│  └──────┬──────┘                      │
│         │                            │
│  ┌──────▼──────┐                      │
│  │ Repository │  ← DB와 대화          │
│  └──────┬──────┘                      │
│         │                            │
└──────────┼──────────────────────────────┘
          │
          ▼
     [Database]
      MySQL, PostgreSQL 등

요청이 들어오면 Controller → Service → Repository → DB 순서로 내려가고,
응답은 반대로 DB → Repository → Service → Controller → 브라우저 순서로 올라옵니다.

1️⃣ Controller — 프론트가 직접 만나는 레이어

Controller는 API의 엔드포인트를 정의하는 곳입니다.
프론트에서 fetch('/api/users') 하면 가장 먼저 만나는 곳이 바로 여기입니다.

@RestController
@RequestMapping("/api/users")
public class UserController {

    // GET /api/users → 전체 유저 목록
    @GetMapping
    public List<UserResponse> getUsers() { ... }

    // GET /api/users/1 → 특정 유저
    @GetMapping("/{id}")
    public UserResponse getUser(@PathVariable Long id) { ... }

    // POST /api/users → 유저 생성
    @PostMapping
    public UserResponse createUser(@RequestBody UserRequest request) { ... }

    // PUT /api/users/1 → 유저 수정
    @PutMapping("/{id}")
    public UserResponse updateUser(@PathVariable Long id, @RequestBody UserRequest request) { ... }

    // DELETE /api/users/1 → 유저 삭제
    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) { ... }
}

프론트 개발자가 알아야 할 어노테이션

어노테이션	의미	프론트 관점
`@RestController`	이 클래스가 API 컨트롤러임을 선언	-
`@RequestMapping("/api/users")`	이 컨트롤러의 기본 URL 경로	fetch 경로의 앞부분
`@GetMapping`	HTTP GET 요청 처리	데이터 조회
`@PostMapping`	HTTP POST 요청 처리	데이터 생성
`@PutMapping`	HTTP PUT 요청 처리	데이터 전체 수정
`@PatchMapping`	HTTP PATCH 요청 처리	데이터 일부 수정
`@DeleteMapping`	HTTP DELETE 요청 처리	데이터 삭제
`@PathVariable`	URL 경로의 변수 (`/users/{id}`)	URL 파라미터
`@RequestParam`	쿼리 파라미터 (`?page=1`)	Query String
`@RequestBody`	요청 본문(JSON)을 객체로 변환	fetch body

프론트 코드와 1:1 매핑

// 프론트
const res = await fetch('/api/users/42');

// 백엔드 (↑ 이 요청을 받음)
@GetMapping("/{id}")
public UserResponse getUser(@PathVariable Long id) { ... }
//                                              ↑ id = 42

// 프론트
const res = await fetch('/api/users?page=1&size=10');

// 백엔드
@GetMapping
public List<UserResponse> getUsers(
    @RequestParam int page,    // 1
    @RequestParam int size     // 10
) { ... }

// 프론트
const res = await fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: '홍길동', email: 'hong@test.com' })
});

// 백엔드
@PostMapping
public UserResponse createUser(@RequestBody UserRequest request) {
    // request.name = "홍길동"
    // request.email = "hong@test.com"
}

2️⃣ DTO — 프론트와 주고받는 데이터 형태

DTO(Data Transfer Object)는 API로 주고받는 데이터의 구조를 정의한 클래스입니다.
프론트의 TypeScript 타입 정의와 똑같은 역할을 합니다.

// 요청 DTO (프론트 → 서버)
public class UserRequest {
    private String name;
    private String email;
    private String password;
    // getter, setter...
}

// 응답 DTO (서버 → 프론트)
public class UserResponse {
    private Long id;
    private String name;
    private String email;
    private LocalDateTime createdAt;
    // getter...
}

// 프론트의 TypeScript 타입 (백엔드 DTO와 맞춰야 함)
interface UserRequest {
  name: string;
  email: string;
  password: string;
}

interface UserResponse {
  id: number;
  name: string;
  email: string;
  createdAt: string; // Java LocalDateTime → JSON에서 string
}

💡 백엔드 개발자에게 DTO 구조를 공유해달라고 요청하면 API 연동이 훨씬 편해집니다.
혹은 Swagger(API 문서)를 통해 자동으로 확인할 수 있습니다.

3️⃣ Service — 비즈니스 로직의 집합

Service는 실제 기능 로직이 담기는 곳입니다.
프론트 개발자가 직접 볼 일은 적지만, 협업 시 "이 API가 어떤 처리를 하는지" 이해할 때 도움이 됩니다.

@Service
public class UserService {

    public UserResponse createUser(UserRequest request) {
        // 1. 이메일 중복 체크
        if (userRepository.existsByEmail(request.getEmail())) {
            throw new DuplicateEmailException("이미 사용 중인 이메일입니다");
        }

        // 2. 비밀번호 암호화
        String encodedPassword = passwordEncoder.encode(request.getPassword());

        // 3. DB에 저장
        User user = new User(request.getName(), request.getEmail(), encodedPassword);
        User savedUser = userRepository.save(user);

        // 4. 응답 DTO로 변환해서 반환
        return new UserResponse(savedUser);
    }
}

프론트에서 409 Conflict가 날 때, 이 Service 레이어에서 중복 체크 후 에러를 던지는 경우가 많습니다.

4️⃣ Repository — DB와 대화하는 곳

Repository는 DB에 데이터를 저장하고 조회하는 역할을 합니다.
Spring Data JPA를 쓰면 SQL을 거의 안 짜도 됩니다.

public interface UserRepository extends JpaRepository<User, Long> {

    // SELECT * FROM users WHERE email = ?
    Optional<User> findByEmail(String email);

    // SELECT COUNT(*) > 0 FROM users WHERE email = ?
    boolean existsByEmail(String email);

    // SELECT * FROM users WHERE name LIKE %keyword%
    List<User> findByNameContaining(String keyword);
}

프론트 개발자는 Repository를 직접 볼 일이 거의 없지만,
"DB에 어떤 컬럼이 있고 어떤 데이터가 저장되는지" 이해하는 데 도움이 됩니다.

5️⃣ Entity — DB 테이블과 1:1 매핑되는 클래스

Entity는 DB 테이블 구조를 Java 클래스로 표현한 것입니다.

@Entity
@Table(name = "users")
public class User {

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

    @Column(nullable = false)
    private String name;

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

    @Column(nullable = false)
    private String password;

    @CreatedDate
    private LocalDateTime createdAt;
}

-- 위 Entity는 아래 DB 테이블과 같습니다
CREATE TABLE users (
    id         BIGINT AUTO_INCREMENT PRIMARY KEY,
    name       VARCHAR(255) NOT NULL,
    email      VARCHAR(255) NOT NULL UNIQUE,
    password   VARCHAR(255) NOT NULL,
    created_at DATETIME
);

⚠️ Entity ≠ DTO
Entity는 DB 테이블 구조 그대로이고, DTO는 API 응답용으로 가공한 형태입니다.
비밀번호 같은 민감한 필드는 Entity에는 있지만 응답 DTO에는 빠집니다.

6️⃣ 예외 처리 — 에러 응답이 어떻게 오는가

프론트에서 API 에러를 처리할 때, 백엔드가 어떻게 에러를 반환하는지 알아야 합니다.

전역 예외 처리 핸들러

@RestControllerAdvice // 모든 Controller의 예외를 여기서 처리
public class GlobalExceptionHandler {

    // 404 - 리소스 없음
    @ExceptionHandler(UserNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorResponse handleUserNotFound(UserNotFoundException e) {
        return new ErrorResponse("USER_NOT_FOUND", e.getMessage());
    }

    // 409 - 중복
    @ExceptionHandler(DuplicateEmailException.class)
    @ResponseStatus(HttpStatus.CONFLICT)
    public ErrorResponse handleDuplicateEmail(DuplicateEmailException e) {
        return new ErrorResponse("DUPLICATE_EMAIL", e.getMessage());
    }

    // 400 - 유효성 검사 실패
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleValidation(MethodArgumentNotValidException e) {
        return new ErrorResponse("VALIDATION_FAILED", "입력값이 올바르지 않습니다");
    }
}

에러 응답 구조 예시

// 프론트에서 받는 에러 응답
{
  "code": "USER_NOT_FOUND",
  "message": "해당 유저를 찾을 수 없습니다"
}

// 프론트에서 에러 처리
const res = await fetch('/api/users/999');
if (!res.ok) {
  const error = await res.json();
  // error.code === "USER_NOT_FOUND"
  // error.message === "해당 유저를 찾을 수 없습니다"
  console.error(error.message);
}

💡 팀마다 에러 응답 구조가 다릅니다. 백엔드 개발자에게 에러 응답 포맷을 꼭 확인하세요.

7️⃣ Spring Security — 인증/인가

로그인, 권한 관리 등은 Spring Security가 담당합니다.

JWT 기반 인증 흐름 (가장 흔한 방식)

① 로그인 요청
   POST /api/auth/login
   { "email": "...", "password": "..." }

② 서버: 이메일/비밀번호 검증 후 JWT 토큰 발급
   { "accessToken": "eyJhbGci...", "refreshToken": "eyJhbGci..." }

③ 프론트: 토큰 저장 (localStorage 또는 httpOnly Cookie)

④ 이후 API 요청 시 토큰 첨부
   Authorization: Bearer eyJhbGci...

⑤ 서버: 토큰 검증 후 요청 처리

// 프론트 - 로그인
const loginRes = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password })
});
const { accessToken } = await loginRes.json();
localStorage.setItem('token', accessToken);

// 프론트 - 인증이 필요한 API 요청
const res = await fetch('/api/users/me', {
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('token')}`
  }
});

Spring Security에서 보호되는 경로

@Configuration
public class SecurityConfig {

    http
      .authorizeHttpRequests(auth -> auth
          .requestMatchers("/api/auth/**").permitAll()     // 인증 없이 접근 가능
          .requestMatchers("/api/admin/**").hasRole("ADMIN") // ADMIN만 접근 가능
          .anyRequest().authenticated()                    // 나머지는 로그인 필요
      )
}

/api/auth/login   → 누구나 접근 가능
/api/users/me     → 로그인한 사용자만
/api/admin/stats  → ADMIN 권한만

→ 401: 토큰 없음 / 만료
→ 403: 권한 부족

8️⃣ CORS — 프론트가 가장 자주 만나는 설정

로컬 개발할 때 이런 에러 보신 적 있으신가요?

Access to fetch at 'http://localhost:8080/api/users' from origin
'http://localhost:3000' has been blocked by CORS policy

CORS는 다른 출처(Origin)에서 오는 요청을 브라우저가 차단하는 보안 정책입니다.
백엔드에서 허용 설정을 해줘야 해결됩니다.

@Configuration
public class CorsConfig {

    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();

        config.addAllowedOrigin("http://localhost:3000");  // 개발 서버
        config.addAllowedOrigin("https://my-app.com");     // 프로덕션 서버

        config.addAllowedMethod("*");   // GET, POST, PUT, DELETE 모두 허용
        config.addAllowedHeader("*");   // 모든 헤더 허용
        config.setAllowCredentials(true); // 쿠키 포함 요청 허용

        // ...
    }
}

💡 CORS 에러가 나면 백엔드에 "프론트 origin 허용해주세요" 라고 요청하면 됩니다.
프론트에서 해결할 수 있는 문제가 아닙니다.

9️⃣ Swagger — API 문서 자동 생성

Spring Boot에서는 Swagger(OpenAPI)로 API 문서를 자동으로 만들어줍니다.

http://localhost:8080/swagger-ui/index.html

백엔드에 Swagger가 설정되어 있다면 위 주소에서 모든 API를 확인하고 직접 테스트해볼 수 있습니다.

Swagger에서 확인할 수 있는 것들:
✅ 엔드포인트 URL
✅ HTTP 메서드 (GET, POST, PUT, DELETE)
✅ 요청 파라미터 / Body 구조
✅ 응답 구조 (DTO)
✅ HTTP 상태 코드별 응답
✅ 직접 API 호출 테스트

🔄 실제 협업 흐름 요약

1. 백엔드 개발자가 API 설계 (엔드포인트, 요청/응답 DTO 정의)

2. Swagger 또는 Notion으로 API 명세 공유
   - URL, Method, Request Body, Response 구조, 에러 코드

3. 프론트 개발자가 TypeScript 타입 정의
   - 백엔드 DTO 기반으로 interface 작성

4. MSW로 API 모킹 후 프론트 개발 병행
   - 백엔드 완성 전에도 프론트 개발 가능

5. 백엔드 완성 후 실제 API 연동 & 테스트
   - CORS, 인증 토큰, 에러 처리 확인

📁 Spring Boot 프로젝트 폴더 구조

src/
└── main/
    └── java/
        └── com.example.app/
            ├── controller/      ← API 엔드포인트 (프론트가 직접 사용)
            │   └── UserController.java
            ├── service/         ← 비즈니스 로직
            │   └── UserService.java
            ├── repository/      ← DB 접근
            │   └── UserRepository.java
            ├── entity/          ← DB 테이블 구조
            │   └── User.java
            ├── dto/             ← 요청/응답 데이터 구조 (프론트와 직접 연관)
            │   ├── request/
            │   │   └── UserRequest.java
            │   └── response/
            │       └── UserResponse.java
            ├── exception/       ← 에러 정의 & 처리
            │   └── GlobalExceptionHandler.java
            └── config/          ← 설정 (CORS, Security, Swagger)
                ├── CorsConfig.java
                ├── SecurityConfig.java
                └── SwaggerConfig.java

💬 협업할 때 백엔드에 물어봐야 할 것들

✅ API 명세 문서가 있나요? (Swagger URL 또는 Notion)

✅ 인증 방식이 JWT인가요, 세션인가요?
   - JWT라면 토큰을 어떤 헤더에 넣어야 하나요?

✅ 에러 응답 포맷이 어떻게 되나요?
   - { code, message } 인가요?

✅ 날짜/시간 포맷이 어떻게 되나요?
   - "2024-01-01T00:00:00" (ISO 8601)?

✅ 페이지네이션은 어떻게 처리하나요?
   - ?page=0&size=10 인가요?
   - 응답에 totalPages, totalElements가 포함되나요?

✅ CORS 허용 Origin에 제 로컬 주소(localhost:3000) 추가해줄 수 있나요?

✅ 파일 업로드는 multipart/form-data인가요?

마치며

Spring Boot를 직접 개발할 필요는 없지만, 구조를 이해하면 백엔드 개발자와의 소통이 훨씬 원활해집니다.

Controller = 내가 호출하는 API 엔드포인트
DTO = API로 주고받는 데이터 타입 (TypeScript interface와 동일)
Service = 로직 처리 (에러가 여기서 많이 발생)
Repository = DB 접근
Entity = DB 테이블 구조

이 다섯 가지만 이해해도, 협업 시 "이 에러가 어디서 나는 건지", "이 API가 어떤 데이터를 주는 건지" 훨씬 빠르게 파악할 수 있습니다. 🚀

📚 참고

Spring Boot 공식 문서

Spring Data JPA 공식 문서

SpringDoc OpenAPI (Swagger)

깽지

이전 포스트

React Hook 핵심 정리(실무 위주)

다음 포스트