🚀Github와 AWS를 이용한 팀 프로젝트 초기 설정하기 (2)

 

지난 포스트에 이어 이번 글은 팀 프로젝트에서 Spring Boot 기반 백엔드 서버를 구축하며 진행한 환경 세팅 과정을 간단하게 정리하였습니다. 특히 Spring Boot 세팅, PostgreSQL과의 연동, 예외 처리 구조, Swagger 적용까지 팀원 모두가 공통된 개발 환경을 갖출 수 있도록 구성하였습니다. 

 

 

 

1. 환경 변수 설정 (application.yml + .env 파일)

---

백엔드 프로젝트 생성 후 필요한 build.gradle 의존성과 DB 생성을 완료했다면, 환경 변수를 설정해야 합니다.

개발 과정에서 데이터베이스 주소, 계정 정보처럼 민감한 정보를 직접 application.yml에 작성하면 보안상 위험할 수 있습니다. 또한 협업 시 개발자마다 설정이 달라질 수 있기 때문에 .env 파일로 분리해 관리하는 것이 좋습니다.

 

1.1) application.yml 작성 예시

---

server:
  port: 8080

spring:
  config:
    import: optional:file:.env[.properties]
  datasource:
    url: ${DB_URL}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    driver-class-name: org.postgresql.Driver
  jpa:
    hibernate:
      ddl-auto: update
    properties:
      hibernate:
        format_sql: true
    show-sql: true
  profiles:
    active: local

application.yml에서는 ${} 문법을 이용하여 외부에서 설정값을 주입받도록 구성합니다. 이 값들은 .env 파일에서 설정할 수 있습니다.

 

1.2) .env 파일 작성 예시

---

DB_URL=jdbc:postgresql://localhost:5432/kirby_db
DB_USERNAME=your_name
DB_PASSWORD=your_password

프로젝트 루트 디렉토리에 .env 파일을 만들고 위와 같이 작성합니다.

.env 파일은 절대로 Git에 커밋되면 안되므로, .gitignore에 .env를 추가해줍니다.

 

현재 application.yml 작성 / .env 파일 작성 / .gitignore에 .env 추가까지 한 상태입니다.

 

 

2. 공통 설정 구성

---

협업 개발 과정에서는 다양한 API 요청과 응답을 주고 받기 때문에, 응답을 일관된 포맷으로 제공하는 것이 중요합니다. 이를 위해 ResponseDto를 공통 응답 형식으로 만들고, 확장 가능한 응답 구조를 위해 ResponseData 인터페이스도 만들어줍니다. 또한, JPA Entity에 BaseEntity를 상속하여 공통 필드인 id/생성일/수정일을 자동으로 관리합니다.

 

2.1) 공통 응답 DTO (ResponseDto)

---

import lombok.Getter;
import java.time.LocalDateTime;

@Getter
public class ResponseDto<T> {

    private final LocalDateTime timestamp;
    private final String message;
    private final ResponseData<T> data;

    public ResponseDto(LocalDateTime timestamp, String message, ResponseData<T> data) {
        this.timestamp = timestamp;
        this.message = message;
        this.data = data;
    }

    public static <T> ResponseDto<T> of(String message) {
        return new ResponseDto<>(LocalDateTime.now(), message, null);
    }

    public static <T> ResponseDto<T> of(T body) {
        return new ResponseDto<>(LocalDateTime.now(), null, new DefaultResponseData<>(body));
    }

    public static <T> ResponseDto<T> of(T body, String message) {
        return new ResponseDto<>(LocalDateTime.now(), message, new DefaultResponseData<>(body));
    }
}

 

2.2) 확장 가능한 응답 구조 (ResponseData 인터페이스)

---

public interface ResponseData<T> {
    T getBody();
}

 

2.3) DefaultResponseData

---

import lombok.Getter;

@Getter
public class DefaultResponseData<T> implements ResponseData<T> {

    private final T body;

    protected DefaultResponseData(T body) {
        this.body = body;
    }
}

 

2.4) RestTemplate 설정 (RestTemplateConfig)

---

import org.springframework.context.annotation.Bean;
import org.springframework.web.client.RestTemplate;

public class RestTemplateConfig {

    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

 

2.5) 공통 엔티티 (BaseEntity)

---

import jakarta.persistence.*;
import lombok.Getter;
import lombok.Setter;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;

import java.time.LocalDateTime;

@MappedSuperclass
@Getter
@Setter
@EntityListeners(AuditingEntityListener.class)
public class BaseEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id", nullable = false)
    private Long id;

    @CreatedDate
    @Column(name = "created_at")
    private LocalDateTime createdAt;

    @LastModifiedDate
    @Column(name = "updated_at")
    private LocalDateTime updatedAt;
}

 

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;

@SpringBootApplication
@EnableJpaAuditing
public class KirbyApplication {

	public static void main(String[] args) {
		SpringApplication.run(KirbyApplication.class, args);
	}
}

Application 클래스에 @EnableJpaAuditing를 추가해야 BaseEntity가 작동합니다.

 

<현재까지 폴더 구조>

 

 

 

 

3. Swagger 설정

---

API 개발 시 테스트와 문서화를 함께 진행할 수 있도록, Swagger를 적용합니다.

Spring Boot에서는 springdoc-openapi 라이브러리를 사용하면 매우 간단하게 설정할 수 있습니다.

 

3.1) 의존성 추가

---

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

 

3.2) Swagger 설정 클래스 추가 (선택)

---

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

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                    .title("Kirby API")
                    .description("Kirby 프로젝트의 백엔드 API 명세서입니다.")
                    .version("v1.0.0"));
    }
}

이 설정은 Swagger 페이지에 표시될 제목, 설명, 버전 정보를 커스터마이징합니다. 꼭 필요하지는 않지만, 정돈된 문서를 위해 추천합니다. 이 밖에도 controller 별로 설명을 달아서 테스트를 편하게 할 수 있습니다. 이에 대한 코드는 생략하겠습니다.

 

3.3) Swagger 접속 주소

---

서버를 실행한 뒤, 아래 주소로 접속하면 Swagger UI를 확인할 수 있습니다.

http://localhost:8080/swagger-ui/index.html

 

 

 

 

✍️ 마무리하며

지금까지는 아주 기본적인 백엔드 개발 환경 세팅—Spring Boot 프로젝트 구성, PostgreSQL 연동, 공통 응답 구조 정의 등—을 다뤄보았습니다.

물론, 공통 설정이라는 건 정답이 있는 분야가 아니고, 개발자마다 선호하는 방식도 다릅니다. 저도 아직 많이 배우는 중이고, 이 구조가 완성형은 아닐 수도 있습니다. 하지만 협업을 조금이라도 수월하게 만들기 위해 직접 시도해보고, 하나씩 정리해보며 개선해나가려고 합니다.

만약 이 글을 보고 있는 분이 더 나은 방식이나 아이디어가 있다면 꼭 직접 적용해보시길 추천드려요. 저도 계속 시도하면서 개선해볼 예정입니다. 🙇‍♀️

다음 글에서는 AWS 프리티어를 활용해 EC2 인스턴스 생성, 탄력적 IP 설정, SSH 접속 환경까지 Spring Boot 배포를 위한 클라우드 서버 환경을 구축해보겠습니다.