처음 코딩을 배우고 까만 콘솔 창에 글자만 출력하던 시절, 저도 “도대체 실제 웹이나 앱 서버는 어떻게 만드는 걸까?” 하고 막막했던 기억이 나요. 특히 예전 스프링(Spring) 프레임워크는 시작하기 전에 환경 설정 파일만 수십 줄을 건드려야 해서 진입장벽이 정말 높았거든요. 솔직히 말해서 코딩을 시작하기도 전에 설정하다 지쳐서 포기하는 분들도 꽤 많았답니다.
하지만 스프링 부트(Spring Boot)가 등장하면서 이야기가 완전히 달라졌어요! 복잡한 설정을 알아서 처리해 주는 자동 구성 기능과 내장 서버(Tomcat) 덕분에, 이제는 클릭 몇 번이면 어엿한 백엔드 서버를 뚝딱 띄울 수 있게 되었거든요. 오늘은 저와 함께 프로젝트 생성부터 실제 동작하는 REST API 만들기까지 차근차근 따라 해 볼게요! 😊
스프링 부트와 REST API, 왜 이렇게 인기일까요? 🤔
본격적인 코드 작성에 앞서 개념부터 가볍게 짚고 넘어갈게요. REST API란 쉽게 말해 식당의 ‘점원과 메뉴판’ 같은 역할이에요. 스마트폰 앱이나 웹 브라우저(손님)가 주소(URI)를 통해 주문을 넣으면, 백엔드 서버(주방)가 약속된 JSON이라는 깔끔한 텍스트 형식으로 데이터를 포장해서 가져다주는 통신 규칙이랍니다.
여기에 스프링 부트를 결합하면 시너지가 엄청납니다. 과거에는 톰캣(Tomcat) 같은 웹 서버를 별도로 설치하고 연결해야 했지만, 스프링 부트는 내부에 이미 서버를 품고 있어서 실행 버튼만 누르면 바로 8080 포트로 서버가 켜지거든요. 그니까요, 개발자는 오직 비즈니스 로직에만 집중할 수 있는 환경이 만들어진 셈이죠.
프로젝트를 처음 만들 때는 공식 사이트인 Spring Initializr(start.spring.io)를 활용하세요. 2026년 현재 실무 표준 조합인 Java 17 이상(또는 21 LTS), Gradle, Spring Boot 3.x 버전을 선택하고, Dependencies 항목에서 ‘Spring Web’ 하나만 추가해도 REST API 서버 준비가 끝납니다!
핵심 정리! HTTP 메서드와 스프링 부트 어노테이션 📊
REST API 서버를 만든다는 건 결국 데이터를 조회(Read), 생성(Create), 수정(Update), 삭제(Delete)하는 CRUD 기능을 여는 것과 같아요. 스프링 부트에서는 코드 위에 골뱅이(@) 기호를 붙이는 어노테이션(Annotation)을 사용해 아주 직관적으로 요청 길을 연결해 줍니다.
HTTP 메서드별 매핑 어노테이션 비교
| HTTP 메서드 | 스프링 어노테이션 | 주요 역할 | 예시 URI 및 특징 |
|---|---|---|---|
| GET | @GetMapping | 데이터 조회 (Read) | /api/users/1 (파라미터 및 경로 변수 활용) |
| POST | @PostMapping | 데이터 생성 (Create) | /api/users (@RequestBody로 JSON 수신) |
| PUT / PATCH | @PutMapping | 데이터 수정 (Update) | /api/users/1 (전체 또는 일부 정보 변경) |
| DELETE | @DeleteMapping | 데이터 삭제 (Delete) | /api/users/1 (대상 리소스 삭제 처리) |
초보자가 가장 많이 겪는 실수가 바로 클래스 위에 @Controller를 붙이는 것이에요! 일반 @Controller는 HTML 화면 파일을 찾으려고 시도하기 때문에 404 에러가 나기 쉽습니다. JSON 데이터를 반환하는 REST API 서버를 만들 때는 반드시 @RestController를 사용해야 한다는 점, 꼭 기억해 주세요.
3단계로 끝내는 제작 흐름과 API 트래픽 계산기 🧮
그렇다면 스프링 부트 내부에서 클라이언트 요청은 어떤 순서로 처리될까요? 복잡한 구조를 단순화하면 아래 공식 하나로 명쾌하게 정리됩니다.
📝 스프링 부트 REST API 동작 공식
REST API 응답 = HTTP 요청(URI + 메서드) ➔ @RestController 매핑 ➔ DTO 객체 변환(JSON 직렬화)
실제 프로젝트를 구성할 때는 다음 3단계를 순서대로 적용하면 됩니다.
1) 첫 번째 단계: DTO(데이터 전달 객체) 정의 – 주고받을 데이터 구조(id, name 등)를 자바 클래스나 Record로 선언합니다.
2) 두 번째 단계: Controller 작성 – @RestController와 @GetMapping 등을 붙여 요청 주소를 메서드와 연결합니다.
→ 최종 결론: 서버 실행 후 http://localhost:8080/경로를 호출하면 내장 Jackson 라이브러리가 객체를 자동으로 JSON으로 변환해 응답합니다.
🔢 내 REST API 어노테이션 & 초당 처리량(TPS) 계산기
실무 완성도를 높이는 DTO(Record)와 ResponseEntity 👩💻👨💻
단순히 문자열("Hello World")만 반환하는 건 연습용으로는 좋지만 실무에서는 거의 쓰이지 않아요. 프론트엔드 개발자와 원활하게 협업하려면 Java Record를 활용한 DTO와 HTTP 상태 코드를 세밀하게 제어하는 ResponseEntity를 사용하는 것이 좋습니다.
특히 Java 16부터 정식 도입된 record 키워드를 쓰면, 번거로운 Getter나 생성자 코드 없이 단 한 줄로 불변 데이터 객체를 만들 수 있어 코드가 정말 깔끔해져요.
실무에서는 성공했을 때 무조건 200만 내려주기보다, 회원 가입이나 게시글 작성처럼 새로운 데이터가 생성되었을 때는 ResponseEntity.status(201).body(데이터) 형태로 명확한 HTTP 상태 코드를 함께 전달하는 것이 좋은 REST API 설계 습관입니다.
실전 예시: 회원 조회 및 등록 API 구현 사례 📚
이론만 보면 감이 잘 안 올 수 있으니, 실제로 사이드 프로젝트에서 가장 많이 만드는 '회원 조회 및 등록 API' 사례를 통해 어떻게 코드가 구성되는지 살펴볼까요?
사례 주인공의 상황
- 목표 기능: 회원 번호로 정보를 조회(GET)하고, 새로운 회원 이름을 받아 등록(POST)하는 JSON API 서버 구축
- 개발 환경: Java 17, Spring Boot 3.3, 내장 톰캣(포트 8080)
코드 작성 과정
1) 첫 번째 단계(DTO 선언): public record MemberDto(Long id, String name, String role) {} 선언으로 JSON 데이터 틀 완성
2) 두 번째 단계(조회 매핑): @GetMapping("/api/members/{id}") 메서드에서 @PathVariable Long id를 받아 new MemberDto(id, "김코딩", "ADMIN") 반환
3) 세 번째 단계(등록 매핑): @PostMapping("/api/members") 메서드에서 @RequestBody MemberDto req로 클라이언트가 보낸 JSON을 그대로 수신
최종 실행 결과
- 브라우저 접속: http://localhost:8080/api/members/1 입력 시 {"id":1,"name":"김코딩","role":"ADMIN"} 즉시 출력!
- 포스트맨(Postman) 테스트: POST 요청 시 상태 코드 200 OK와 함께 정상 수신 확인 완료
어때요? 생각보다 코드가 정말 짧고 간결하죠! 만약 실행했는데 Port 8080 was already in use라는 에러가 뜬다면 당황하지 마시고 application.properties 파일에 server.port=8081 한 줄만 적어주면 깔끔하게 해결된답니다.
마무리: 핵심 내용 요약 📝
오늘 함께 살펴본 스프링 부트 REST API 서버 만들기의 핵심 포인트를 다시 한번 정리해 볼게요.
- Spring Initializr 활용: 프로젝트 생성 시 Spring Web 의존성만 추가하면 내장 톰캣과 JSON 변환기가 자동으로 세팅됩니다.
- @RestController 선언: HTML 화면이 아닌 JSON 데이터를 곧바로 반환하려면 일반 @Controller 대신 반드시 @RestController를 사용합니다.
- 직관적인 HTTP 매핑: 조회는 @GetMapping, 생성은 @PostMapping, 수정은 @PutMapping, 삭제는 @DeleteMapping으로 역할을 나눕니다.
- DTO와 파라미터 처리: 주소 경로의 값은 @PathVariable로, 본문에 담긴 JSON 데이터는 @RequestBody와 DTO(Record)로 안전하게 주고받습니다.
처음에는 생소한 어노테이션이 많아 보여도, 직접 내 손으로 서버를 띄우고 브라우저에 JSON 데이터가 찍히는 순간의 쾌감은 정말 짜릿하답니다! 오늘 소개해 드린 순서대로 지금 바로 첫 API 서버를 실행해 보세요. 따라 하시다가 막히는 부분이나 더 궁금한 점이 있다면 언제든 댓글로 물어봐주세요~ 😊
스프링 부트 REST API 한눈에 보기
자주 묻는 질문 ❓