[33~35일차] 미니 프로젝트 - 백엔드

 

 

1. 프로젝트 빌드 도구 비교 (Maven vs Gradle)

Maven이란?

2004년에 출시된 Java 기반 프로젝트 빌드 도구이다. 주로 프로젝트 빌드(컴파일, 패키징, 테스트, 배포 등)를 자동화하는 데 사용된다.

 

Maven은 XML 파일(pom.xml)을 통해 프로젝트 구조와 설정을 관리한다.

 

Maven은 일관된 구조로 인해 사용하기 쉽고, 다양한 외부 라이브러리와의 통합이 간편하다는 장점이 있으나, XML는 유연성이 부족하고 속도가 느리다는 단점이 있다.

 

예시 코드)

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>3.5.6</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.uplus</groupId>
	<artifactId>SpringBootTest</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>SpringBootTest</name>
	<description>Demo project for Spring Boot</description>
	<url/>
	<licenses>
		<license/>
	</licenses>
	<developers>
		<developer/>
	</developers>
	<scm>
		<connection/>
		<developerConnection/>
		<tag/>
		<url/>
	</scm>
	<properties>
		<java.version>17</java.version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.mybatis.spring.boot</groupId>
			<artifactId>mybatis-spring-boot-starter</artifactId>
			<version>3.0.5</version>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<scope>runtime</scope>
			<optional>true</optional>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

 

 

Gradle이란?

Maven의 단점을 보완하기 위해 2009년에 출시된 Java 기반 프로젝트 빌드 도구이다. Groovy나 Kotlin 기반의 DSL(Domain-Specific Language)을 사용해 빌드 스크립트를 작성한다.

 

이 방식은 'build.gradle' 이라는 빌드 파일을 생성하기 때문에 가독성이 좋고, XML 보다 훨씬 더 유연하다. 이러한 특징으로 인해 Gradle의 주요 장점 중 하나는 빌드 성능이 좋고 (병렬 빌드 기본 지원 등) 빌드 시간을 크게 줄일 수 있다는 장점이 있다. 그러나 스크립트 문법에 익숙해야 해서 약간의 난이도가 있다는 단점이 있다.

 

또한 Maven과의 호환성도 좋아서 기존 Maven 프로젝트를 Gradle로 마이그레이션하는 것이 가능하다.

 

예시 코드)

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.4.10'
	id 'io.spring.dependency-management' version '1.1.7'
}

group = 'com.ureca'
version = '0.0.1-SNAPSHOT'
description = 'Mini Project for Spring Boot'

java {
	toolchain {
		languageVersion = JavaLanguageVersion.of(17)
	}
}

configurations {
	compileOnly {
		extendsFrom annotationProcessor
	}
}

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	compileOnly 'org.projectlombok:lombok'
	developmentOnly 'org.springframework.boot:spring-boot-devtools'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:3.0.3'
    runtimeOnly 'com.mysql:mysql-connector-j'
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
}

tasks.named('test') {
	useJUnitPlatform()
}

 

 

이처럼 Gradle이 Maven 보다 학습 난이도가 있다는 단점이 있으나, 이를 제외하고는 Gradle을 사용하는 것이 좋다고 판단되어 이번 프로젝트 빌드 도구는 Gradle을 채택하였다.

 

 

---

2. API 명세 작성법

API 명세 작성법을 알기 전에 API가 뭔지 알아보자.

 

API란?

API(Application Programming Interface)는 정의 및 프로토콜 집합을 사용하여 두 소프트웨어 구성 요소가 서로 통신할 수 있게 하는 매커니즘이다.

API를 통해 백엔드와 프론트엔드가 통신하기 때문에 초기에 API 명세를 잘 수립하는 것이 상당히 중요하다.

 

 

API 명세 작성법

1) 개요 (Overview)

- 프로젝트의 큰 그림부터 설명한다.

- 이는 Swagger / Postman 문서의 최상단에 오는 부분이다.

 

2) 엔드포인트 구조 설계

- 리소스(Resource) 단위로 URL을 설계한다.

 

3) API 별 상세 명세 작성

- 실제 엔드포인트 단위로 세부 정보를 기입한다.

 

 

위 순서를 토대로 작성한 API 명세는 다음과 같다.

 

API 명세 작성 내용은 팀마다 다르기 때문에 어떤 것이 정답이라고 할 수 없다. 따라서 본인 팀에 잘 맞는 API 명세를 따라가는 것이 맞다.

 

---

 

3. ERD 설계 및 DB 구조 수립

 

대망의 ERD 및 DB 설계 단계이다. 실제로도 오래 걸리고 고민도 오래했던 단계였다. 

 

ERD란?

ERD는 E-R 다이어그램을 말하며, 개체 속성과 개체 간 관계를 그림으로 표현한 것이다.

 

 

우리 팀은 ERD 설계는 DB Diagram.io 툴을 사용했고, DB는 MySQL을 사용했다.

https://dbdiagram.io/

dbdiagram.io - Database Relationship Diagrams Design Tool

 

예전에는 ERDCloud를 썼었으나, dbdiagram.io의 UI가 더 깔끔해보여서 dbdiagram.io을 채택했다.

실제로도 DBML을 작성만 하면 ERD를 짜주는데 UI가 깔끔해서 보기 편했다.

 

---

4. 백엔드 폴더 구조 

Controller

- 클라이언트 요청(Request)을 받아 응답(Response)을 반환하는 API 진입점이다.

- 해당 폴더에서 API를 정의한다.

 

DTO

- 데이터 전송 객체이다.

   - Request와 Response에 따라 파일을 구분해서 정의한다.

- 계층 간 데이터만 옮긴다.

 

Service

- 실제 비즈니스 로직(핵심 기능)을 수행한다.

- controller에서 전달받은 요청 데이터를 검증하고, 필요한 데이터를 Mapper(or Repository)를 통해 가져와 처리한다.

- 주요 도메인별 로직을 담당한다.

 

Repository (혹은 Mapper)

- DB 접근 담당이다. (데이터CRUD 수행)

- SQL을 실행하고, 그 결과를 DTO나 Entity 형태로 반환한다.

- 우리 미니프로젝트에서는 Mybatis를 사용하기 때문에 Mapper를 사용한다.

 

Domain

- 프로젝트의 주요 기능 단위(업무 영역) 를 기준으로 코드를 모아둔 폴더이다.

- 예를 들어 users, todos, goals, calendars 등이 각각 하나의 도메인이 된다.

- 각 도메인 폴더 내부에는 해당 기능에 필요한 controller, service, mapper, dto, entity 등이 함께 포함된다.

- 도메인 단위로 관리하면 기능별로 코드가 구분되어 유지보수성과 확장성이 높아진다.

 

Config

- 프로젝트 전역 설정 폴더이다.

- Swagger, CORS, DB, 시큐리티 설정 등을 위치한다

 

application.yml

- DB 연결, 포트, Swagger 설정 등 환경설정 파일이다.

 

 

이를 바탕으로 우리 프로젝트의 폴더 구조는 아래와 같다. 

 

 

---

5. Swagger 적용

 

Swagger란?

Swagger는 RestAPI를 자동으로 문서화해주며, 개발자가 편리하게 API를 호출하고 테스트 할 수 있는 도구이다.

 

Swagger 적용 순서

1) build.gradle에 의존성을 추가한다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'}

 

 

2) SwaggerConfig 을 생성한다.

package com.ureca.fitlog.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI fitlogOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("FitLog API 문서")
                        .description("FitLog API 명세서")
                        .version("v1.0.0")
                        .contact(new Contact()
                                .name("URECA Team")
                                .email("ureca@fitlog.com")));
    }
}

 

3) http://localhost:8080/swagger-ui/index.html# 에서 Swagger가 잘 등록됐는지 확인한다.

우리 팀의 Swagger

 

4. 열심히 API를 개발한다. ㅎㅎ

 

---

 

위처럼 현재까지의 '프로젝트 첫 세팅 ~ API 개발' 단계를 정리해보았다.

그간 프로젝트에서 프론트엔드는 많이 해봤으나 백엔드쪽은 아예 시도조차 안하고 있었다.

그렇기에 이번에 하는 미니 프로젝트에서 ERD 설계나 DB 설계, API 구현 등을 하려고 하니 너무 어려웠다. 이 과정에서 백엔드 개발자들은 대체 뭘까.. 라는 생각이 정말 많이 들었다.

 

그래도 또 DB 설계까지는 하고 나니 아직까지는 API를 만드는 과정이 신기해서 자주 들여다보게 되는 것 같다.

사실 아직까지는 GPT의 도움을 받아 API 개발 코드를 짜고 있으나, 지금은 그 코드를 보면서 이해하는 것이 정말 중요한 단계라 생각한다.

 

지금 기초를 탄탄하게 잡아놔야 나중에 AI에 휘둘리지 않으니까 열심히 해놔야겠다는 생각이 들었다.