Odyssey - Backend

유동인구 빅데이터 처리 및 분석 기반 웹 서비스 (SW기업연계 프리캡스톤)

U+ 유동인구 데이터를 가공해 프론트엔드에 제공하는 조회 전용 API 서버입니다.

기술 스택

• Java 21 / Spring Boot 4.1.1 / Gradle
• Spring Web MVC, Spring Data JPA, PostgreSQL 17
• Flyway (DB 스키마 버전 관리)
• Lombok, Bean Validation
• springdoc-openapi (Swagger UI), Spring Boot Actuator

시작하기

Docker가 실행 중이어야 합니다. bootRun 이 compose.yaml 의 postgres 컨테이너를 자동으로 띄우고 DB 접속 정보까지 주입하므로, 별도 설정 파일 없이 바로 실행됩니다.

./gradlew bootRun

• API 서버: http://localhost:8080
• API 문서: http://localhost:8080/swagger-ui.html
• 헬스체크: http://localhost:8080/actuator/health

./gradlew test          # 테스트
./gradlew build         # 빌드 (build/libs/*.jar)

폴더 구조

src/main/java/com/odyssey/
  global/                 # 공통 설정, 예외 처리, 응답 포맷
    config/               # CORS, Swagger, JPA 설정
    exception/            # 전역 예외 핸들러
    response/             # 공통 응답 래퍼
  domain/
    population/           # 도메인 단위로 분리
      controller/         # REST 엔드포인트
      service/            # 비즈니스 로직
      repository/         # 조회 (JPA / JdbcClient)
      entity/             # JPA 엔티티
      dto/                # 요청·응답 DTO (record)

src/main/resources/
  application.yaml        # 공통 설정 (프로파일 미지정 시 local)
  application-local.yaml  # 로컬 - docker compose 기반, SQL 로그 on
  db/migration/           # Flyway 마이그레이션 SQL (V1__init.sql ...)

프로파일

프로파일	DB	ddl-auto	Actuator
local (기본)	compose.yaml의 postgres 자동 기동	create	전체 노출
test	Testcontainers 가 띄우는 postgres	validate	-

배포는 아직 하지 않습니다. 필요해지면 application-prod.yaml 을 추가해 DB 접속 정보와 허용할 프론트엔드 주소를 환경변수로 받게 만들면 됩니다.

DB 스키마

스키마 변경은 Flyway 마이그레이션 파일로만 합니다. src/main/resources/db/migration/ 에 V{번호}__{설명}.sql 형식으로 추가하세요.

테스트는 ddl-auto: validate 라서 엔티티와 실제 테이블이 다르면 실패합니다. 엔티티를 고쳤다면 마이그레이션 SQL도 같이 커밋해야 합니다.

API 규약

• 응답: { "success": true, "data": ..., "error": null } 형태의 공통 래퍼
• 에러: HTTP 상태 코드 + code / message
• 조회 API는 모두 GET, 목록은 page / size 페이징

커밋 컨벤션

• feat: 기능 추가
• fix: 버그 수정
• refactor: 기능 변경 없는 코드 구조 개선
• chore: 설정/빌드 관련
• test: 테스트 작성, 수정