VSCode Spring Boot 실전: REST API 설계와 JSON 데이터 통신 완벽 가이드

데이터베이스 연결까지 성공했다면, 이제 애플리케이션의 꽃이라고 불리는 REST API를 만들 차례입니다. 우리가 매일 사용하는 스마트폰 앱이나 웹사이트는 모두 이 API를 통해 서버와 데이터를 주고받습니다. 오늘은 VSCode 환경에서 자바 객체를 JSON 형식으로 변환하여 클라이언트와 소통하는 핵심 설계 기법을 알아보겠습니다.

REST API와 JSON 통신 이해하기

REST API는 서버의 자원을 이름으로 구분하여 상태를 주고받는 방식입니다. 이때 가장 많이 사용되는 데이터 형식이 바로 JSON(JavaScript Object Notation)입니다. 스프링 부트는 내부적으로 'Jackson' 라이브러리를 탑재하고 있어, 자바 객체를 자동으로 JSON 문자열로 변환해 줍니다.

HTTP 메서드	역할 (CRUD)	URI 설계 예시
GET	데이터 조회 (Read)	/api/users/{id}
POST	데이터 생성 (Create)	/api/users
PUT	데이터 수정 (Update)	/api/users/{id}
DELETE	데이터 삭제 (Delete)	/api/users/{id}

단계별 REST 컨트롤러 구현 방법

VSCode에서 새로운 자바 클래스를 생성하고, 간단한 회원 관리 API를 만들어 보며 통신 원리를 파악해 보겠습니다.

1. DTO(Data Transfer Object) 클래스 생성: 계층 간 데이터 전달을 위한 전용 객체를 만듭니다. @Getter, @NoArgsConstructor 같은 Lombok 어노테이션을 활용하면 코드가 훨씬 깔끔해집니다.
2. RestController 작성: 클래스 상단에 @RestController를 선언합니다. 이는 @Controller와 @ResponseBody를 합친 것으로, 메서드의 반환값을 자동으로 JSON으로 응답하게 합니다.
3. Mapping 설정: 각 메서드에 @GetMapping, @PostMapping 등을 사용하여 경로를 지정합니다.
4. Request Body 처리: POST 방식처럼 데이터를 보낼 때는 메서드 파라미터에 @RequestBody를 붙여 JSON 데이터를 자바 객체로 변환(역직렬화)받습니다.

VSCode에서 API 테스트하는 꿀팁

API를 만들었다면 제대로 작동하는지 확인해야 합니다. 별도의 무거운 툴(Postman 등)을 설치하지 않고도 VSCode 안에서 해결하는 방법이 있습니다.
 

1. 썬더 클라이언트(Thunder Client) 활용

VSCode 확장 마켓플레이스에서 'Thunder Client'를 설치해 보세요. 가볍고 직관적인 UI를 통해 localhost:8080/api/users로 직접 GET/POST 요청을 보내고 응답 결과를 확인할 수 있습니다.

 

2. REST Client 확장 활용

.http 파일을 만들어 스크립트 형식으로 요청을 관리할 수 있습니다. 협업 시 팀원들과 요청 규격을 공유하기에 매우 편리한 방식입니다.

가장 많이 묻는 질문 및 트러블슈팅

Q: 405 Method Not Allowed 에러가 발생합니다.

브라우저 주소창에 URL을 직접 입력하는 방식은 오직 GET 방식만 지원합니다. POST나 PUT 요청을 브라우저 주소창에 입력하면 해당 에러가 발생하므로, 반드시 위에서 언급한 테스트 도구를 사용해야 합니다.

Q: JSON 결과값에 한글이 깨져서 나옵니다.

최신 스프링 부트 버전에서는 드문 일이지만, 인코딩 설정이 맞지 않을 때 발생할 수 있습니다. application.properties 파일에 server.servlet.encoding.charset=UTF-8 설정을 추가하면 해결됩니다.

좋은 API 설계를 위한 한 끗

실무에서는 엔티티(Entity)를 직접 API 응답으로 내보내는 것을 지양합니다. 엔티티는 DB 구조와 밀접하게 연관되어 있어, 내부 구조가 노출될 위험이 있고 순환 참조 에러가 발생할 수 있기 때문입니다. 반드시 DTO를 거쳐 필요한 데이터만 필터링하여 응답하는 구조를 갖추시길 바랍니다.
 
또한, 상태 코드(Status Code)를 명확히 사용하는 습관도 중요합니다. 성공 시 200(OK), 생성 성공 시 201(Created), 잘못된 요청 시 400(Bad Request) 등을 적절히 반환하면 클라이언트 개발자와의 협업 효율이 극대화됩니다.

VSCode Spring Boot에 데이터베이스 연결하기: H2와 MySQL 실전 가이드