Skip to content

배움의 길

평생 배워야하는 것은 우리들의 운명이다.

Menu
Menu

스프링 부트(Spring Boot)로 간단한 REST API 서버 만들기: 10분 완성 실전 가이드

Posted on 2026년 11월 02일2026년 11월 01일 by steve

 

자바(Java)로 나만의 첫 백엔드 서버를 띄워보고 싶으신가요? 복잡한 XML 설정 없이 스프링 부트(Spring Boot)로 단 10분 만에 간단한 REST API 서버를 구축하는 핵심 과정과 실전 노하우를 알기 쉽게 정리해 드립니다!

 

처음 코딩을 배우고 까만 콘솔 창에 글자만 출력하던 시절, 저도 “도대체 실제 웹이나 앱 서버는 어떻게 만드는 걸까?” 하고 막막했던 기억이 나요. 특히 예전 스프링(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) 계산기

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 서버 만들기의 핵심 포인트를 다시 한번 정리해 볼게요.

  1. Spring Initializr 활용: 프로젝트 생성 시 Spring Web 의존성만 추가하면 내장 톰캣과 JSON 변환기가 자동으로 세팅됩니다.
  2. @RestController 선언: HTML 화면이 아닌 JSON 데이터를 곧바로 반환하려면 일반 @Controller 대신 반드시 @RestController를 사용합니다.
  3. 직관적인 HTTP 매핑: 조회는 @GetMapping, 생성은 @PostMapping, 수정은 @PutMapping, 삭제는 @DeleteMapping으로 역할을 나눕니다.
  4. DTO와 파라미터 처리: 주소 경로의 값은 @PathVariable로, 본문에 담긴 JSON 데이터는 @RequestBody와 DTO(Record)로 안전하게 주고받습니다.

처음에는 생소한 어노테이션이 많아 보여도, 직접 내 손으로 서버를 띄우고 브라우저에 JSON 데이터가 찍히는 순간의 쾌감은 정말 짜릿하답니다! 오늘 소개해 드린 순서대로 지금 바로 첫 API 서버를 실행해 보세요. 따라 하시다가 막히는 부분이나 더 궁금한 점이 있다면 언제든 댓글로 물어봐주세요~ 😊

💡

스프링 부트 REST API 한눈에 보기

✨ 필수 의존성: Spring Web 스타터 추가! 내장 톰캣과 JSON 변환(Jackson)이 자동 구성됩니다.
📊 핵심 어노테이션: @RestController + @XXXMapping! CRUD 역할에 맞춰 직관적으로 주소를 연결합니다.
🧮 데이터 흐름 공식:

HTTP 요청 ➔ Controller(@RequestBody / @PathVariable) ➔ DTO(Record) ➔ JSON 응답

👩‍💻 실무 꿀팁: ResponseEntity 활용! 데이터와 함께 정확한 HTTP 상태 코드(200, 201 등)를 반환하세요.

Spring Boot 3.x 환경에서는 Java 17 이상 버전을 필수로 준비해 주세요!

자주 묻는 질문 ❓

Q: @Controller와 @RestController의 정확한 차이는 무엇인가요?
A: @Controller는 주로 HTML 같은 뷰(View) 화면을 반환할 때 쓰이며, @RestController는 @Controller에 @ResponseBody가 합쳐진 형태로 자바 객체를 JSON/XML 데이터로 즉시 변환해 응답합니다.

Q: 자바 객체를 어떻게 별도 설정 없이 JSON으로 바꿔주나요?
A: Spring Web 의존성에 기본 포함된 'Jackson' 라이브러리가 DTO 객체의 Getter(또는 Record 컴포넌트)를 읽어 자동으로 JSON 텍스트로 직렬화해 주기 때문입니다.

Q: 브라우저에서는 POST API를 바로 테스트할 수 없나요?
A: 웹 브라우저 주소창 입력은 기본적으로 GET 요청만 보냅니다. POST, PUT, DELETE 요청을 테스트하려면 포스트맨(Postman), 인섬니아(Insomnia) 또는 IntelliJ HTTP Client 도구를 사용하는 것이 편리합니다.

Q: @PathVariable과 @RequestParam은 언제 구분해서 쓰나요?
A: 특정 리소스를 식별할 때(/members/1)는 @PathVariable을 쓰고, 검색어나 페이지 번호처럼 필터링 옵션을 넘길 때(/members?page=2)는 @RequestParam을 주로 사용합니다.

Q: 데이터베이스(DB) 없이도 REST API 서버를 띄울 수 있나요?
A: 네, 가능합니다! 처음 학습할 때는 자바의 Map이나 List에 데이터를 임시 저장하며 API 통신 구조부터 익힌 뒤, 이후에 Spring Data JPA와 DB를 연결하는 단계적 학습을 추천합니다.

최신 글

  • 유료 강의 결제 전 필독! 유튜브 프리미엄급 무료 개발·디자인 채널 추천 모음
  • 비전공자가 생활코딩 유튜브로 프로그래밍 입문한 후기 및 현실 공부 순서
  • 코세라(Coursera) 해외 명문대 온라인 강의 수료 후기: 무료 청강부터 수료증 발급까지
  • 유데미(Udemy) 할인 기간 완벽 정리: 글로벌 IT 강의 80% 이상 싸게 사는 법
  • 클래스101 구독형 서비스(CLASS101+) 요금제 비교와 본전 뽑는 활용법

보관함

  • 2026년 11월
  • 2026년 10월

카테고리

  • 교육

소개 및 문의 · 개인정보처리방침 · 면책조항

©2026 배움의 길 | Design: Newspaperly WordPress Theme