Guide - RESTful 웹 서비스 구축

https://spring.io/guides/gs/rest-service

Getting Started | Building a RESTful Web Service

 

목표

HTTP GET 요청을 수락하는 서비스

• 요청 URL : http://localhost:8080/greeting
• 응답 : JSON 형식의 인사말
• 응답 예시 : {"id":1,"content":"Hello, World!"}
• 쿼리 문자열에서 name 매개변수 이용 가능
  • 요청 URL : http://localhost:8080/greeting?name=User
  • 응답 예시 : {"id":1,"content":"Hello, User!"}

 

프로젝트 초기화

 

1. https://start.spring.io 접속
2. 빌드 도구, 언어, 스프링 부트 버전 선택
3. Dependecies 추가
4. Generate 클릭 후 zip 파일 다운로드

- 설정 예시

 

리소스 표현 클래스 생성

 

서비스 동작

• /greeting 경로에 대한 GET 요청을 처리하며 선택적으로 쿼리 문자열에서 name 매개변수를 받음
• GET 요청을 받으면 200 OK 응답 코드와 JSON 형식의 인사말을 반환

{
    "id": 1,
    "content": "Hello, World!"
}

id 필드는 인사말의 고유 식별자
content 필드는 텍스트로 된 인사말

 

리소스 표현 클래스 생성

// src/main/java/com/example/restservice/Greeting.java


package com.example.restservice;

public record Greeting(long id, String content) {
}

• Java의 record 클래스를 사용하여 id와 content 필드 포함 클래스 정의
• Jackson JSON 라이브러리를 사용하여 객체를 자동으로 JSON 형식으로 변환
• Jackson 라이브러리는 Spring Web Starter에 기본적으로 포함

 

리소스 컨트롤러 생성

 

// src/main/java/com/example/restservice/GreetingController.java

package com.example.restservice;

import java.util.concurrent.atomic.AtomicLong;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {
    
    private static final String TEMPLATE = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();
    
    public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
        return new Greeting(counter.incrementAndGet(), String.format(TEMPLATE, name));
    }
}

• @RestController = @Controller + @ResponseBody
  • Spring MVC의 컨트롤러를 RESTful 웹 서비스 컨트롤러로 선언
  • 모든 메서드의 반환값이 JSON 형식의 데이터가 됨
• @GetMapping("/greeting")
  • /greeting 경로로 HTTP GET 요청이 들어오면 greeting() 메서드 실행
• @RequestParam
  • 쿼리 문자열의 name 값을 메서드의 name 매개변수로 바인딩, 기본 값은 World로 설정
• AtomicLong : id 필드를 자동 증가, 멀티스레드 환경에서도 안전
• Spring은 객체를 JSON으로 변환하여 HTTP 응답 본문에 추가

	전통 MVC 컨트롤러	RESTful 컨트롤
어노테이션	@Controller 사용	@RestController 사용
반환	ModelAndView 반환 → HTML 렌더링	데이터 객체 (JSON) 직접 반환
뷰	뷰 템플릿 (JSP, Thymeleaf 등) 사용	뷰 없이 API 응답만 반환
응답	HTML 기반 응답을 생성	JSON/XML 등의 데이터 형식 반환

 

서비스 실행

 

• Spring Initializer에서 기본적으로 생성한 애플리케이션 클래스 사용
• Gradle로 실행(두 가지 방법 중 하나 선택)

// 애플리케이션 직접 실행
./gradlew bootRun

// JAR 파일 빌드 후 실행
./gradlew build // 1. JAR 파일 빌드
ls build/libs/ // 2. JAR 파일 이름 찾기
java -jar build/libs/restservice-0.0.1-SNAPSHOT.jar // 3. JAR 파일 실행

 

브라우저에서 테스트(터미널 혹은 포스트맨과 같은 GUI에서도 테스트 가능)

// 브라우저에 http://localhost:8080/greeting 주소로 접속
결과 : {"id":1,"content":"Hello, World!"}

// 브라우저에 http://localhost:8080/greeting?name=User 주소로 접속
결과 : {"id":2,"content":"Hello, User!"}

 

JAR 파일을 사용한 배포의 장점

• 하나의 JAR 파일로 모든 설정과 종속성 포함
• 환경과 무관하게 java -jar 명령어로 실행 가능
• 서버 없이 독립 실행 가능(내장 Tomcat 사용)
• 다양한 환경에서 배포 가능(테스트, 스테이징, 프로덕션 등)