GDGOC 6th BE Week 2 - Backend와 Spring Boot로 첫 API 만들기

그동안 AI 서빙이나 튜닝 관련 작업만 하다가, 협업 과정에서 백엔드와 소통할 일도 많다는 것을 알았습니다. 의사소통도 하고 간단한 지식을 쌓아보고 싶어 이번 학기에 GDGOC에서 BE과정으로 참가하게 되었습니다. 첫 실습은 Spring Boot로 간단한 API를 만들고, 브라우저의 요청이 서버 코드를 거쳐 응답으로 돌아오기까지의 흐름을 따라가는 과정입니다.

1. Backend와 Client–Server 구조 이해하기

회원가입 버튼을 누르거나 게시글을 열면 화면 뒤에서는 서버가 요청을 처리합니다. Frontend가 사용자가 보는 화면과 상호작용을 담당한다면, Backend는 요청에 필요한 처리를 수행하고 데이터를 돌려주는 역할을 맡습니다.

 

이때 요청을 보내는 쪽이 Client, 요청을 받아 응답하는 쪽이 Server입니다. 브라우저로 웹 서비스를 이용할 때의 기본 흐름은 Client → Request → Server → Response → Client로 나타낼 수 있습니다. 이번 실습에서는 브라우저가 Client, 직접 실행한 Spring Boot 애플리케이션이 Server에 해당합니다.

2. HTTP와 API로 요청과 응답 주고받기

Client와 Server가 요청과 응답을 주고받을 때 사용하는 통신 규칙이 HTTP입니다. HTTP 메서드는 요청의 목적을 표현합니다. GET은 조회, POST는 생성, PUT/PATCH는 수정, DELETE는 삭제에 주로 사용합니다.

 

API는 Client가 Server의 기능을 사용할 수 있도록 정해 놓은 창구입니다. 예를 들어 회원 관련 API를 만든다면 GET /members는 회원 목록 조회에, POST /members는 회원 등록에 사용할 수 있습니다. 경로가 같아도 메서드에 따라 요청하는 작업은 달라집니다.

 

HTTP 요청과 응답에는 각각 정해진 정보가 담깁니다. 요청에는 메서드와 경로, 헤더, 필요한 경우 본문이 들어갑니다. 응답에는 상태 코드와 헤더, 필요한 경우 본문이 포함됩니다. 따라서 API의 동작을 확인할 때는 반환된 데이터와 함께 어떤 상태 코드가 왔는지도 살펴봐야 합니다. (MDN HTTP 개요)

대표적인 상태 코드는 다음과 같습니다.

• 200 OK: 요청을 성공적으로 처리한 경우
• 404 Not Found: 요청한 리소스를 찾을 수 없는 경우
• 500 Internal Server Error: 서버 내부 오류로 요청을 처리하지 못한 경우

브라우저에 원하는 결과가 나오지 않더라도 원인은 다를 수 있습니다. 상태 코드는 그 원인을 찾는 출발점이 됩니다. (MDN 상태 코드)

3. Spring과 Spring Boot 알아보기

Spring은 Java 기반 Backend 개발을 돕는 프레임워크입니다. HTTP 요청 처리, 객체 관리, 데이터베이스 연동 등 서버를 만들 때 필요한 기능을 제공합니다.

 

Spring Boot는 Spring 프로젝트의 초기 설정과 실행을 편리하게 해 줍니다. 이번 실습에서도 Spring Boot로 프로젝트를 생성한 뒤, 요청을 처리할 코드를 추가해 API를 실행했습니다.

 

이 편리함을 뒷받침하는 기능 중 하나가 자동 구성(Auto-configuration)입니다. Spring Boot는 프로젝트에 추가된 라이브러리와 설정 등을 보고 필요한 구성을 적용합니다. 예를 들어 DB 관련 라이브러리가 있고 개발자가 연결 구성을 별도로 정의하지 않았다면, 조건에 맞는 DB 연결 구성을 준비할 수 있습니다. 필요한 설정이 전부 사라지는 것은 아니지만, 시작할 때 직접 작성해야 하는 설정의 부담을 줄여 줍니다. (Spring Boot 자동 구성 문서)

4. 개발 환경 준비와 Spring Boot 프로젝트 생성하기

실습 환경은 IntelliJ IDEA와 JDK 21입니다. 프로젝트는 Java, Gradle(Groovy), Spring Boot 4.0.x로 생성했습니다. Group, Artifact, Package name을 지정하고 프로젝트를 열면 Gradle이 필요한 라이브러리를 내려받습니다.

처음에는 다음 세 곳을 중심으로 프로젝트 구조를 살펴봤습니다.

• src/main/java: Java 코드를 작성하는 공간
• src/main/resources: 설정 파일과 리소스를 두는 공간
• build.gradle: 의존성과 빌드 설정을 관리하는 파일

애플리케이션의 시작점은 메인 클래스의 main()입니다. 여기서 SpringApplication.run()을 호출합니다. 실행 후에는 콘솔의 서버 시작 로그와 포트 번호를 확인해야 브라우저에서 어느 주소로 접속할지 알 수 있습니다.

 

환경을 기록할 때는 사용한 JDK와 Spring Boot 버전도 함께 남기는 편이 좋습니다. 같은 코드를 따라 작성해도 버전이나 의존성 조합에 따라 빌드 결과가 달라질 수 있기 때문입니다.

5. /hello와 /introduce API를 만들고 응답 확인하기

서버가 실행됐다면 이제 요청을 처리할 Controller를 만들 차례입니다. 클래스에 @RestController를 붙이고, @GetMapping으로 GET 요청의 경로와 실행할 메서드를 연결합니다.

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, Spring Boot!";
    }

    @GetMapping("/introduce")
    public String introduce() {
        return "안녕하세요. 저는 OOO입니다.";
    }
}

 

/hello로 GET 요청이 오면 hello()가, /introduce로 요청이 오면 introduce()가 실행됩니다. 각 메서드가 반환한 문자열은 HTTP 응답 본문에 담깁니다. @RestController가 @Controller와 @ResponseBody를 결합한 어노테이션이기 때문입니다. 객체를 반환하고 JSON 변환기를 사용하는 예제는 Spring REST API 입문 가이드에서 볼 수 있습니다.

 

서버를 실행하고 브라우저에서 http://localhost:8080/hello에 접속하자 Hello, Spring Boot!가 나타났습니다. 주소의 localhost는 내 컴퓨터, 8080은 서버의 포트, /hello는 요청 경로입니다. /introduce에서는 코드에 작성한 자기소개 문장이 응답으로 돌아왔습니다.

 

여기서 http://localhost:8080만 입력하면 결과가 다를 수 있습니다. 루트 경로인 /에 연결한 API가 없으면 404가 나타납니다. 서버가 실행 중이어도 요청한 경로를 처리할 코드가 없을 수 있는 것입니다. 코드를 바꾼 뒤에는 서버를 다시 실행하고 해당 경로의 응답을 확인했습니다.

 

브라우저 개발자 도구의 Network 탭에서는 요청 경로, 상태 코드, 응답 본문을 함께 볼 수 있습니다. 화면에 나타난 문자열이 서버에서 어떤 응답으로 전달됐는지 살펴볼 수 있는 곳입니다. (MDN HTTP 메시지)