Springboot RestfulAPI 서버 만들기

오픈소스 프레임워크를 배울 땐, 항상 공식 레퍼런스 문서를 참조하며 이해하는 습관을 가지면, 앞으로 새로운 프레임워크를 학습할 때도 스스로 학습할 수 있는 능력을 갖출 수 있습니다. Spring Framework는 대한민국에서 웹서버를 개발하는데 아주 많이 사용되지만, 각 종 설정 파일을 이해하는데 많은 시간이 소모되어 웹 서비스를 빠르게 개발하는데 어려움이 있습니다. 그리고, 최근 기업들은 Open API를 공개하여 다른 시스템과 연계를 편하게 할 수 있습니다. REST API를 개발한다는 것이 곧 Open API를 개발하는 것과 같은 맥락입니다.

SpringBoot는 Spring Framework의 기능을 지원함과 동시에 복잡한 설정 없이 웹 서비스를 개발할 수 있는 프레임워크입니다. 최근 기업에서도 많이 사용되고 있으며, SpringBoot에 대한 공식 레퍼런스 문서도 아주 잘 설명되어 있습니다.

https://spring.io/guides 사이트에 접속하면 다양한 Guide 문서를 확인할 수 있고, API 사용법도 익힐 수 있습니다.

이 글은 공식 가이드 중 "Building a RESTful Web Service" 항목을 실습 후 한글로 정리한 글이며, 간단한 웹 서비스를 만드는 예제입니다.

Building a RESTful Web Service

RESTful API 정의

RESTful API는 무엇을 의미할까요? REST API는 사실상 HTTP 프로토콜을 이용하여 데이터를 송수신하는 패턴입니다. RESTful API를 설계한다는 것은 아래의 특징을 가진 API를 개발하였을 때, RESTful API라고 말할 수 있습니다.

• REST, REST API
  • Representational State Transfer의 줄임말로, 아키텍처를 말함
  • REST 또는 Web 아키텍처
    • 클라이언트/서버 구조 -> 서버/클라이언트는 역할이 다르며, 독립적인 역할을 수행함.
    • 단일 인터페이스(Uniform Interface) -> 모든 플랫폼에서 사용 가능한 API를 제공해야 함
    • 무상태(Stateless) -> 클라이언트의 상태를 서버에 저장하지 말아야 함
    • 캐시 처리 가능(Cacheable) -> HTTP를 이용하므로, 캐시를 이용할 수 있어야 함.
    • 계층화(Layered System) -> 클라이언트는 어느 서버와 연결되어 있는지 알 수 없
    • 자체 표현 구조(Self-descriptiveness) -> API만 보았을 때, 어떤 역할을 수행하는지 알 수 있어야 함
  • REST 안티 패턴
    • REST 사상에 어긋나는 행위를 하는 경우를 안티 패턴이라고 봄
    • GET 또는 POST를 이용한 터널링
      • GET 또는 POST 요청 만으로 서버에 SELECT, DELTE, INSERT, UPDATE를 요청하는 패턴
    • HTTP Response Code를 사용하지 않는 경우

RESTful API 서버 만들기

HTTP Get 요청/응답을 처리할 수 있는 웹 서버를 SpringBoot로 만드는 것이 주요 실습의 목적입니다.

아래는 개발한 RESTful API 기능 설명입니다.

1. GET Request를 처리하는 서비스 만들기

http://localhost:8080/greeting

2. GET Response 만들기

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

3. name parameter를 받을 수 있도록 greeting 서비스를 커스터마이징 하기

http://localhost:8080/greeting?name=User

4. name의 default value는 “World”로 출력할 것

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

이 글에서 설명하는 SpringBoot 개발환경을 실습하기 위해서는 아래 5개의 준비사항이 필요합니다.

• 15분의 시간
• 텍스트 에디터 또는 IDE
• JDK 1.8 이상
• Gradle 4+ or Maven 3.2+
• Spring Tool Suite 또는 IntelliJ IDEA

개발한 REST API를 테스트할 때, Browser, curl, Postman를 활용하여 개발한 의도대로 REST API가 동작하는지 확인할 수 있습니다. 실습은 Java, IntelliJ IDEA로 진행합니다.

먼저, https://start.spring.io/ 에서 스프링 부트 초기 환경이 설정된 예제 프로젝트를 다운로드합니다. 설정을 마친 뒤, Generate버튼을 누르면, 프로젝트가 다운로드됩니다. 프로젝트를 압축 해제한 후, Intellij로 프로젝트를 엽니다. 프로젝트 오픈 후, build.gradle 작성된 스크립트에 필요한 파일 또는 라이브러리를 자동으로 다운로드합니다. build.gradle안에 dependencies에 spring-boot-starter-web를 추가 또는 수정해줍니다. start-web에서 지원하는 API를 사용하는 실습이므로 starter-web을 추가해주셔야 합니다.

dependencies {
   implementation 'org.springframework.boot:spring-boot-starter-web'
   testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

src/main/java 폴더 밑에 Resource Representation Class(리소스 표현 클래스)에 해당하는 Greeting 클래스를 생성하여 JSON으로 id와 content를 입력받고 처리할 클래스를 구현합니다.

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

intelliJ IDEA로 Springboot 프로젝트 오픈

src/main/java 폴더 밑에 Resource Controller Class(리소스 컨트롤러 클래스)에 해당하는 GreetingController 클래스를 생성하여 GET 요청/응답을 처리하는 내용을 작성합니다.

Springboot Controller 작성화면

GreetingController에 추가된 Annotation에 대한 설명은 아래와 같습니다.

• @GetMapping은 “/greeting” HTTP GET 요청을 greeting() 메서드와 대응하는 Annotation입니다
• @RequestParam은 파라미터로 전달되는 name의 값을 greeting()의 매개변수 name, name 값이 전달되지 않았을 경우, defaultValue값으로 처리하겠다는 Annotation입니다
• 전통적인 MVC Controller와 RESTFul web service controller의 차이는 HTTP 응답 Body가 생성되는 방식이 다른데, MVC Controller의 경우는 HTML과 같은 view에 의존적인 ResponseBody를 만들어야 하지만, RESTful 웹서비스 컨트롤러는 JSON형태로 Response를 생성합니다.
• JSON 포맷으로 응답이 생성되는 이유는 SpringBoot 내부적으로 Jackson을 이용하기 때문입니다.
• @RestController에서 모든 Method는 view대신 도메인 객체를 반환합니다.
• @RestController는 @Controller와 @ResponseBody가 합쳐진 축양형 Annotation입니다.

SpringBoot를 애플리케이션으로 실행시킬 Main클래스는 아래와 같습니다.

Springboot Main함수 작성화면

SpringBoot Main클래스에 달린 @SpringBootApplication은 아래 3개의 Annotatation 기능을 포함한 것입니다.

• @Configuration : Spring의 Application Context에게 Bean을 정의하는 소스임을 알립니다
• @EnableAutoConfiguration : Classpath 안에 정의된 Bean을 Spring Boot에 추가하는 작업을 시작하라는 의미입니다.
• @ComponentScan : 개발자가 구현한 Component class를 자동으로 추가하라는 의미입니다.

SpringAppliocation.run()는 SpringBoot application을 실행시키는 메서드이며, SpringBoot 애플리케이션은 Web.xml 파일 없이 순수 100% Java로 작성이 가능합니다.

작성이 완성된 SpringBoot 애플리케이션은 JAR로 패키징 하여 실행합니다. JAR로 패키징 하면, SpringBoot를 실행하는데 필요한 리소스, dependencies. class들이 포함됩니다.

실행은 프로젝트 내부에 gradlew 스크립트를 이용하여 손쉽게, 빌드 및 실행할 수 있습니다. IntelliJ의 Terminal에서 gradlew build를 커맨드를 입력하면, JAR로 빌드할 수 있습니다. 빌드가 성공하면, build/libs안에 jar가 생성됩니다.

생성된 jar는 gradlew bootrun으로 실행할 수도 있으며, java 명령어로 실행할 수 있습니다. 서버가 실행된 로그를 보시면, apache tomcat이 실행되었다는 로그가 뜨는데, SpringBoot에 tomcat 즉 웹서버가 내장되어 있어 별도의 웹서버가 설치되어 있지 않아도, 로컬에서 웹서버를 실행할 수 있습니다.

gradlew bootrun 명령어 실행 결과

springboot jar 실행화면

Browser에서 GET 요청을 통해, 응답 결과를 확인합니다. /greeting url을 호출 시, JSON으로 id와 content가 응답이 오는 것을 확인할 수 있습니다.

/greeting GET 요청에 대한 응답 결과

SpringBoot를 활용하여, RESTful API를 개발하는 방법을 알아보았습니다. 이를 통해 HTTP GET/POST/PUT/DELETE를 개발할 수 있다는 것을 이해할 수 있고, 요청에 따른 응답을 처리하는 로직을 클래스로 처리하도록 구현하는 방법을 알아보았습니다.