국내 마라톤을 즐겨하는 인구는 꾸준히 증가하고 있으며, 매년 수백 개의 대회가 전국에서 개최되고 있습니다. 그러나 현재 마라톤 대회 정보는 여러 커뮤니티, 블로그 등에 분산되어 있어 참여자와 주최자가 모두 불편을 겪고 있습니다.

RunGo는 흩어져 있는 마라톤 대회 정보를 한곳에서 조회하고, 참가자가 원하는 코스에 접수할 수 있도록 돕는 마라톤 통합 플랫폼입니다.

• 대회 조회/접수/운영
• Redis 기반 토큰 관리
• 접수 완료 및 대회 취소 비동기 이메일 알림 (Gmail SMTP)
• k6 기반 부하 테스트

• Auth

• Users

• Marathon

• Registration

• Organizer

• Admin

Frontend	Backend	Security	Database	Deployment	Other

- Frontend : Next.js
- Backend : Spring Boot, Java, JPA(Hibernate)
- Security : Spring Security, JWT, OAuth2
- Database : MySQL, Redis
- Deployment : Docker
- Documentation : Notion, Swagger
- Load Test : k6

대회 접수 기능에서는 여러 사용자가 동시에 같은 코스에 신청할 경우 정원 초과 접수와 currentCount 정합성 문제가 발생할 수 있습니다.

동시성 제어 방식으로 원자적 업데이트 vs 비관적 락을 비교하여 원자적 업데이트 방식을 채택하였습니다.

테스트 조건

• 총 요청 수: 1,000명
• 동시 요청: 100 / 500
• 시나리오: 동일 코스 접수 요청

결과

원자적 업데이트는 비관적 락보다 대기 시간이 적고, 낙관적 락처럼 재시도 정책을 두지 않아도 되기 때문에 성능과 구현 복잡도의 균형이 가장 좋다고 판단했습니다.

한 사용자는 동일한 대회에서 하나의 코스만 신청할 수 있도록 제한했습니다.

이를 위해 user_id와 marathon_id를 기준으로 복합 유니크 제약을 두는 방식을 채택했습니다.

UNIQUE (user_id, marathon_id)

복합 유니크 방식은 DB 레벨에서 중복 신청을 직접 막기 때문에, 동시 요청 상황에서도 애플리케이션에서 복잡한 중복 제어 로직을 두지 않아도 안정적으로 처리할 수 있습니다.

접수 취소 이후 사용자가 다시 신청할 수 있어야 하며, 동시에 기존 접수 이력도 관리할 수 있어야 합니다.

최종적으로 하드 딜리트 + 이력 테이블 분리 방식을 채택했습니다. 현재 접수 데이터는 활성 접수 상태만 관리하고, 취소 이력은 별도 테이블에서 관리하는 구조가 데이터 의미가 명확하고 유지보수에 유리하다고 보았습니다.

Refresh Token은 재발급과 로그아웃 처리를 위해 서버에서도 관리가 필요합니다.

Redis는 메모리 기반으로 빠르게 조회할 수 있고, TTL 기능을 통해 Refresh Token 만료 시간을 자동으로 관리할 수 있습니다. 확장성과 성능을 고려해 Redis를 도입했습니다.

동일한 사용자가 동시에 토큰 재발급을 요청하면 각각 새로운 Refresh Token이 발급되고, 마지막 요청이 Redis의 기존 값을 덮어쓸 수 있습니다. 이 경우 클라이언트가 가진 토큰과 서버에 저장된 토큰이 불일치하여 인증 오류가 발생할 수 있습니다.

이미 Refresh Token을 Redis에 저장하고 있었기 때문에 별도의 인프라 추가 없이 Redis 기반 분산 락을 적용했습니다. 향후 서버 확장 시에도 Redis가 중앙에서 락을 관리할 수 있어 인스턴스 수와 관계없이 일관된 동시성 제어가 가능합니다.

GitHub Flow 기반으로 총 3종류의 브랜치를 운영, dev 브랜치를 중심으로 통합 모든 작업은 이슈 기반 브랜치 생성 후 PR을 통해 merge

형식: type: 작업내용 (예: feat: 대회 목록 조회 API 추가)

• 제목: type: 작업내용 (#이슈번호)
• 본문: 팀 공통 템플릿 사용 (반드시 Closes #이슈번호 기입하여 이슈 자동 종료 유도)
• Merge 시 주의사항 (Squash Merge): 깃허브 머지 시 커밋 제목 뒤에 자동 생성되는 (#PR번호)는 지우고, 원래의 (#이슈번호)만 작성
  • type: 작업내용 (#이슈번호)
• PR은 최소 1명 이상의 approve 후 merge를 원칙으로 함

backend/src/main/java/com/rungo/api
├── domain
│   ├── auth               # 인증, 로그인, 토큰 관리
│   ├── marathon           # 마라톤 대회 및 코스 관리
│   ├── notification       # 메일 알림 이벤트 처리
│   ├── registration       # 참가 접수, 조회, 취소
│   └── users              # 사용자, 관리자, 주최자 승인
└── global
    ├── config             # 전역 설정
    ├── exception          # 공통 예외 처리
    ├── file               # 파일 업로드 처리
    ├── infrastructure     # 외부 인프라 연동
    ├── response           # 공통 응답 형식
    ├── security           # 인증/인가 보안
    ├── springDoc          # Swagger 문서 설정
    └── util               # 공통 유틸

• Java 21
• Docker
• Docker Compose

루트 디렉터리에서 MySQL과 Redis를 실행합니다.

docker compose up -d

기본 연결 정보는 다음과 같습니다.

애플리케이션 실행 전에 다음 환경 변수를 설정합니다. 로컬 실행 시에는 backend/.env 파일을 사용할 수 있습니다.

JWT_SECRET=your-jwt-secret
[email protected]
MAIL_PASSWORD=your-mail-password
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

메일 발송을 사용하지 않을 경우 backend/src/main/resources/application.yaml의 app.mail.enabled 값을 false로 설정합니다.

cd backend
./gradlew bootRun

서버는 기본적으로 http://localhost:8080에서 실행됩니다.

애플리케이션 실행 후 Swagger UI에서 API 명세를 확인할 수 있습니다.

• Swagger UI: http://localhost:8080/swagger-ui/index.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs

API 응답은 공통 응답 객체인 ApiResponse<T> 형식을 사용합니다.