WRSA Server (Weather-based Recommendation Service Application)

기상청 단기예보 API를 활용하여 날씨 데이터를 수집하고 Firestore에 동기화하는 백엔드 서비스입니다.

📑 목차

• 개요
• 주요 기능
• 기술 스택
• 프로젝트 구조
• 시작하기
  • 사전 요구사항
  • 설치
  • 환경 설정
• 성능
• 개발
  • 로그 포맷
  • 주요 함수
• 데이터 스키마
• 라이선스
• 작성자
• 관련 프로젝트

📋 개요

WRSA Server는 한국 기상청의 동네예보 API를 통해 전국 주요 지역의 날씨 정보를 수집하고, 이를 Firebase Firestore에 저장하여 모바일 앱에서 활용할 수 있도록 합니다.

해당 프로젝트는 GCP Cloud Functions에서 작동을 고려해서 설계되었습니다.

주요 기능

• 🌤️ 기상청 단기예보 API 자동 수집
• 🔄 동시성 처리를 통한 빠른 데이터 동기화 (순차 대비 25배 향상)
• 🔥 Firebase Firestore 연동
• 📊 구조화된 로깅 시스템
• 🧪 로컬 개발을 위한 Firestore 에뮬레이터 지원
• ♻️ 자동 재시도 메커니즘

기술 스택

• Language: Go 1.24.6
• Database: Firebase Firestore
• API: 기상청 단기예보 API
• Logging: Custom slog-based Logger
• Testing: Firebase Emulator Suite
• Deployment: GCP Cloud Run Functions

프로젝트 구조

wrsa_server/
├── main.go                     # 메인 애플리케이션
├── main_test.go               # 테스트 코드
├── firebase.json              # Firebase 에뮬레이터 설정
├── internal/
│   ├── db/
│   │   ├── firestore.go      # Firestore 클라이언트
│   │   ├── emulator.go       # 에뮬레이터 설정
│   │   └── schema.go         # 데이터 스키마
│   └── lib/
│       ├── logger/           # 커스텀 로거
│       ├── weather_API/      # 기상청 API 클라이언트
│       ├── calculate/        # 날씨 지수 계산
│       └── code/            # 지역 코드 및 날씨 코드
└── Dockerfile               # 도커 이미지 빌드

시작하기

사전 요구사항

• Go 1.24.6 이상
• Firebase 프로젝트 설정
• 기상청 API 인증키 (공공데이터포털)

설치

# 저장소 클론
git clone https://github.com/yourusername/wrsa_server.git
cd wrsa_server

# 의존성 설치
go mod download

환경 설정

• 환경 설정 가이드 문서

성능

• 순차 처리: 19개 지역, 95개 데이터 약 35초
• 동시 처리: 19개 지역, 95개 데이터 약 2초 (15배 향상)
• 재시도 메커니즘: 실패한 요청 자동 재시도

개발

로그 포맷

커스텀 slog 핸들러를 사용한 구조화된 로깅:

2025/11/18 18:07:12 INFO  DB 등록 완료 총건수=100 성공=95 실패=5
2025/11/18 18:07:12 WARN  API 호출 실패 건수=10
2025/11/18 18:07:12 ERROR 재등록 실패 실패건수=5
2025/11/18 18:07:12 DEBUG 디버그 모드 감지

주요 함수

자세한 작동 방식을 보기 위해서는 각 문서를 참조하십시오.

• fetchWeatherDataConcurrently(): 병렬로 날씨 데이터 수집
• insertWeatherDataConcurrently(): 병렬로 Firestore에 저장
• createWeatherData(): API 데이터를 DB 스키마로 변환

데이터 스키마

Weather Collection

type Weather struct {
FcstDate   string // 예보 날짜
NX         int    // 격자 X
NY         int    // 격자 Y
Name       string  // 지역명
AvgTempera float64 // 평균 온도
Wash       string  // 빨래 지수
Sky        weather.Sky // 하늘 상태
Wind       float64     // 풍속
TTL        *timestamppb.Timestamp // 만료 시간
}

📄 라이선스

이 프로젝트는 MIT 라이선스를 따릅니다.

👤 작성자

• terrinens

🔗 관련 프로젝트

• WRSA Flutter App - 날씨 기반 알람 모바일 앱