현재 개발 중인 뉴스 모니터링 서비스는 다음과 같은 작업을 수행한다.

• 뉴스 기사 수집 및 저장
• AI 서버를 통한 기사 요약과 우선순위 분석
• 홍보처용 메일 생성 및 발송
• 매일 정해진 시간에 실행되는 스케줄러 작업
• 기사 조회와 편집을 위한 FastAPI API 제공

기존에는 하나의 FastAPI 서버에서 API 요청과 스케줄러를 함께 처리하고 있었다.

기능 자체는 정상적으로 동작했지만, 사용량이 증가했을 때 다음과 같은 문제가 생길 수 있었다.

1. API 서버 하나가 중단되면 전체 서비스가 중단된다.
2. 트래픽이 늘어나도 서버가 자동으로 확장되지 않는다.
3. API 서버를 여러 개 실행하면 스케줄러도 중복 실행될 수 있다.
4. 배포 도중 서버가 잠시 중단될 가능성이 있다.
5. 서버의 CPU와 메모리 사용량을 기준으로 확장하기 어렵다.

이 문제를 해결하기 위해 Docker Desktop의 로컬 Kubernetes 환경에 FastAPI 서버를 배포했다.

이번 글에서는 Kubernetes를 적용한 이유부터 구성 과정, 시행착오, 부하 테스트 결과까지 정리한다.

1. Kubernetes를 적용한 이유

1.1 API 서버 고가용성 확보

FastAPI 서버를 하나만 실행하면 해당 프로세스나 컨테이너가 종료되는 순간 서비스 전체가 중단된다.

Kubernetes에서는 같은 애플리케이션을 여러 Pod로 실행할 수 있다.

이번 구성에서는 FastAPI API Pod를 기본 3개 실행하도록 설정했다.

spec:
  replicas: 3

하나의 Pod에 문제가 생겨도 나머지 Pod가 계속 요청을 처리할 수 있다. Pod가 비정상 종료되면 Kubernetes가 자동으로 새로운 Pod를 생성한다.

1.2 트래픽에 따른 자동 확장

기사 목록 조회나 통계 처리 요청이 몰릴 경우 고정된 서버 수만으로는 응답 시간이 느려질 수 있다.

이를 위해 HPA, 즉 Horizontal Pod Autoscaler를 적용했다.

설정 기준은 다음과 같다.

• 기본 Pod 수: 3개
• 최대 Pod 수: 10개
• CPU 평균 사용률 목표: 50%

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: news-api
  namespace: news-monitor
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: news-api
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 50

CPU 사용률이 목표치를 초과하면 Kubernetes가 API Pod를 자동으로 늘린다. 부하가 줄어들면 다시 최소 Pod 수인 3개로 축소한다.

1.3 스케줄러 중복 실행 방지

가장 주의해야 했던 부분은 스케줄러였다.

기존 FastAPI 애플리케이션은 서버가 시작될 때 내부 스케줄러도 함께 실행한다. 이 상태에서 API Pod를 3개 실행하면 같은 기사 수집 작업이나 메일 발송 작업이 3번씩 실행될 수 있다.

따라서 API와 스케줄러를 논리적으로 분리했다.

flowchart LR
    U["사용자 요청"] --> S["Kubernetes Service"]
    S --> A1["FastAPI Pod 1<br/>Scheduler OFF"]
    S --> A2["FastAPI Pod 2<br/>Scheduler OFF"]
    S --> A3["FastAPI Pod 3<br/>Scheduler OFF"]

    SC["Scheduler Pod 1개<br/>Scheduler ON"] --> DB["PostgreSQL"]
    A1 --> DB
    A2 --> DB
    A3 --> DB

    SC --> AI["Dify / AI 서버"]
    SC --> CR["기사 수집 서버"]

API Pod에는 다음 환경변수를 설정했다.

env:
  - name: ENABLE_SCHEDULER
    value: "false"

별도의 Scheduler Pod에서만 스케줄러를 활성화했다.

env:
  - name: ENABLE_SCHEDULER
    value: "true"

이렇게 하면 API Pod가 10개까지 확장되더라도 기사 수집과 자동 메일 발송은 Scheduler Pod 한 곳에서만 실행된다.

2. 전체 Kubernetes 구성

Kubernetes 구성 파일은 다음과 같이 나눴다.

k8s/
├── namespace.yaml
├── api-deployment.yaml
├── api-service.yaml
├── api-hpa.yaml
├── scheduler-deployment.yaml
├── metrics-server-patch.yaml
└── README.md

각 파일의 역할은 다음과 같다.

3. Namespace 분리

관련 리소스를 한 곳에서 관리할 수 있도록 news-monitor Namespace를 만들었다.

apiVersion: v1
kind: Namespace
metadata:
  name: news-monitor

이후 모든 Deployment, Service, HPA를 같은 Namespace에 배포했다.

kubectl apply -f k8s/namespace.yaml

리소스를 조회할 때도 Namespace를 지정한다.

kubectl get pods -n news-monitor

4. FastAPI Deployment 구성

API 서버는 기본 3개의 Pod로 실행한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: news-api
  namespace: news-monitor
spec:
  replicas: 3

컨테이너는 Uvicorn으로 실행한다.

command:
  - python
  - -m
  - uvicorn
  - app.main:app
  - --host
  - 0.0.0.0
  - --port
  - "8001"
  - --workers
  - "1"

Pod 하나에 Uvicorn Worker를 하나만 실행한 이유는 프로세스 수보다 Kubernetes Pod 수를 기준으로 확장하기 위해서다.

5. 무중단 RollingUpdate

배포 중 기존 Pod가 모두 종료되지 않도록 RollingUpdate 전략을 적용했다.

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxUnavailable: 0
    maxSurge: 1

의미는 다음과 같다.

• maxUnavailable: 0: 교체 중 사용할 수 없는 Pod를 허용하지 않는다.
• maxSurge: 1: 새 Pod를 최대 1개 먼저 추가한 후 기존 Pod를 종료한다.

예를 들어 기존 Pod가 3개라면 새 버전 Pod를 먼저 하나 실행한 후 정상 상태가 확인되면 기존 Pod를 차례로 교체한다.

6. 애플리케이션 상태 검사

Kubernetes가 단순히 프로세스가 실행 중인지만 확인하면 부족하다. 프로세스는 살아 있지만 실제 HTTP 요청을 처리하지 못할 수도 있기 때문이다.

이를 위해 세 가지 Probe를 구성했다.

startupProbe

애플리케이션 초기 시작이 완료될 때까지 기다린다.

startupProbe:
  httpGet:
    path: /
    port: http
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 36

최대 약 180초 동안 애플리케이션 시작을 기다린다.

Dify, PostgreSQL 등 외부 서비스 연결 때문에 초기 실행이 늦어져도 곧바로 Pod가 재시작되는 문제를 막을 수 있다.

readinessProbe

현재 Pod가 사용자 요청을 받을 준비가 됐는지 확인한다.

readinessProbe:
  httpGet:
    path: /
    port: http
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 6

검사에 실패한 Pod는 Service의 요청 분산 대상에서 제외된다.

livenessProbe

애플리케이션이 실행 중에 멈췄는지 확인한다.

livenessProbe:
  httpGet:
    path: /
    port: http
  periodSeconds: 10
  timeoutSeconds: 2
  failureThreshold: 3

연속으로 실패하면 Kubernetes가 컨테이너를 재시작한다.

7. CPU와 메모리 제한

HPA가 CPU 사용률을 계산하려면 각 Pod에 CPU 요청량이 설정되어 있어야 한다.

API Pod에는 다음과 같이 설정했다.

resources:
  requests:
    cpu: 100m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi

• CPU 요청량: 100m, 즉 CPU 코어의 10%
• CPU 제한: 500m, 즉 CPU 코어의 50%
• 메모리 요청량: 256MiB
• 메모리 제한: 512MiB

Scheduler Pod는 API보다 작은 CPU 요청량을 사용한다.

resources:
  requests:
    cpu: 50m
    memory: 256Mi
  limits:
    cpu: 300m
    memory: 512Mi

requests는 Kubernetes가 Pod를 배치하고 HPA 사용률을 계산하는 기준이며, limits는 컨테이너가 사용할 수 있는 최대 자원이다.

8. 데이터베이스 커넥션 풀 제한

Pod 수가 늘어나면 데이터베이스 연결 수도 함께 증가한다.

예를 들어 API Pod 하나가 20개의 DB 연결을 만들고 HPA가 10개까지 확장되면, API 서버만 200개의 연결을 사용할 수 있다.

이를 방지하기 위해 Pod별 연결 수를 제한했다.

API Pod:

env:
  - name: DATABASE_POOL_SIZE
    value: "4"
  - name: DATABASE_MAX_OVERFLOW
    value: "2"

Scheduler Pod:

env:
  - name: DATABASE_POOL_SIZE
    value: "3"
  - name: DATABASE_MAX_OVERFLOW
    value: "2"

API Pod 하나가 사용할 수 있는 최대 연결 수는 4 + 2 = 6개다.

HPA가 최대 10개까지 확장되면 API 서버는 최대 약 60개, Scheduler는 약 5개의 연결을 사용한다.

Kubernetes에서 Pod만 확장하고 데이터베이스 연결 수를 고려하지 않으면 오히려 DB가 병목이 될 수 있으므로 반드시 함께 계산해야 한다.

9. Scheduler Pod의 중복 실행 방지

Scheduler Deployment는 Replica를 1개로 고정했다.

spec:
  replicas: 1

배포 중 기존 Scheduler와 새로운 Scheduler가 잠시 동시에 실행되는 것도 막아야 했다.

따라서 API의 RollingUpdate와 달리 Recreate 전략을 사용했다.

strategy:
  type: Recreate

기존 Scheduler Pod가 종료된 후 새 Scheduler Pod가 실행되므로 스케줄러가 겹칠 가능성이 줄어든다.

다만 실제 운영 환경에서는 Kubernetes Lease나 PostgreSQL Advisory Lock을 추가해 분산 락을 구현하면 더 안전하다. Pod가 비정상적으로 오래 살아 있거나 네트워크가 분리되는 예외 상황까지 방지할 수 있기 때문이다.

10. Kubernetes Secret으로 환경변수 관리

서비스에는 다음과 같은 민감한 값이 필요하다.

• PostgreSQL 연결 주소
• JWT Secret Key
• Dify API Key
• 기사 수집 서버 주소
• Dataset ID

이 값들을 Kubernetes YAML에 직접 작성하면 Git에 노출될 수 있다.

따라서 .env를 Kubernetes Secret으로 변환했다.

kubectl create secret generic news-api-env `
  -n news-monitor `
  --from-env-file=.env `
  --dry-run=client `
  -o yaml |
kubectl apply -f -

Deployment에서는 Secret 전체를 환경변수로 가져온다.

envFrom:
  - secretRef:
      name: news-api-env

중요한 점은 실제 .env와 렌더링된 Secret YAML을 Git에 커밋하면 안 된다는 것이다.

11. Pod에서 호스트 서비스 연결하기

로컬 Docker Desktop Kubernetes의 Pod에서 localhost는 Windows 호스트가 아니다.

Pod 내부에서 localhost를 사용하면 해당 Pod 자신을 가리킨다.

PostgreSQL, Dify, 기사 수집 서버가 Windows 호스트에서 실행되고 있다면 다음 주소를 사용해야 한다.

host.docker.internal

예를 들면 다음과 같다.

DATABASE_URL=postgresql+asyncpg://...@host.docker.internal:5432/...
DIFY_BASE_URL=http://host.docker.internal/...
TRANSNEWS_BASE_URL=http://host.docker.internal:8000

이 설정이 없으면 Pod는 정상적으로 생성돼도 외부 서비스 연결에서 실패할 수 있다.

12. Service로 API 요청 분산

FastAPI Pod 3개 앞에 ClusterIP Service를 배치했다.

apiVersion: v1
kind: Service
metadata:
  name: news-api
  namespace: news-monitor
spec:
  selector:
    app: news-api
  ports:
    - port: 8001
      targetPort: 8001

Kubernetes 내부에서는 다음 주소로 API를 호출할 수 있다.

http://news-api:8001

Service가 app=news-api 라벨을 가진 Pod로 요청을 전달한다.

각 API 응답에는 요청을 처리한 Pod의 이름도 포함하도록 수정했다.

{
  "status": "ok",
  "pod": "news-api-76f9fbd7c5-7bjjz"
}

이를 통해 실제로 요청이 여러 Pod에 분산되는지 확인할 수 있었다.

13. Metrics Server 설치

HPA가 CPU 사용량을 기준으로 확장하려면 Metrics Server가 필요하다.

Docker Desktop Kubernetes에는 Metrics Server가 기본으로 설치되지 않을 수 있다.

Kubernetes 1.30과 호환되는 Metrics Server 0.7.2를 설치했다.

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/download/v0.7.2/components.yaml

설치 후 다음 명령으로 확인했다.

kubectl top nodes
kubectl top pods -n news-monitor

처음에는 다음과 같은 인증서 오류가 발생했다.

x509: certificate is valid for hostname, not node IP

Docker Desktop 로컬 kubelet 인증서에 노드 IP가 포함되지 않은 것이 원인이었다.

로컬 환경에서만 다음 옵션을 적용했다.

- --kubelet-insecure-tls

kubectl patch deployment metrics-server `
  -n kube-system `
  --type=strategic `
  --patch-file k8s/metrics-server-patch.yaml

이 옵션은 인증서 검증을 완화하므로 실제 운영 클러스터에서는 사용하면 안 된다. 운영 환경에서는 정상적인 kubelet 인증서를 구성해야 한다.

14. Docker Desktop Kubernetes 실행 오류 해결

처음 Kubernetes를 활성화했을 때 kubelet이 시작되지 않았다.

주요 오류는 다음과 같았다.

invalid configuration:
cgroup ["kubepods"] has some missing paths:
/sys/fs/cgroup/cpu/kubepods

확인 결과 환경은 다음 상태였다.

• 오래된 WSL 런타임
• Linux Kernel 5.15
• Docker cgroup v1

Kubernetes 1.30 환경과 현재 Docker Desktop 구성에서 cgroup v1이 정상적으로 연결되지 않은 것이 원인이었다.

WSL을 업데이트했다.

wsl --update

업데이트 후 환경은 다음과 같이 변경됐다.

• WSL 2.7.11
• Linux Kernel 6.18
• Docker cgroup v2

확인 명령은 다음과 같다.

wsl --version
docker info --format '{{.CgroupVersion}}'

결과가 2로 표시된 뒤 Docker Desktop을 다시 시작하자 Kubernetes Node가 정상적으로 Ready 상태가 됐다.

kubectl get nodes

NAME             STATUS   ROLES           VERSION
docker-desktop   Ready    control-plane   v1.30.5

15. 이미지 빌드 및 배포

로컬 Docker Desktop Kubernetes가 사용할 이미지를 빌드했다.

docker build -t news-monitor-api:local .

Deployment에서는 로컬 이미지를 사용하도록 설정했다.

image: news-monitor-api:local
imagePullPolicy: IfNotPresent

이 방식은 Docker Desktop 로컬 클러스터에서는 사용할 수 있지만 외부 Kubernetes 클러스터에서는 사용할 수 없다.

운영 클러스터에 배포할 때는 이미지를 Docker Hub, GHCR, ECR 등의 Registry에 Push한 뒤 이미지 주소를 변경해야 한다.

전체 배포 명령은 다음과 같다.

kubectl apply -f k8s/namespace.yaml

kubectl create secret generic news-api-env `
  -n news-monitor `
  --from-env-file=.env `
  --dry-run=client `
  -o yaml |
kubectl apply -f -

kubectl apply -f k8s/api-deployment.yaml
kubectl apply -f k8s/api-service.yaml
kubectl apply -f k8s/api-hpa.yaml
kubectl apply -f k8s/scheduler-deployment.yaml

Rollout 상태도 확인했다.

kubectl rollout status deployment/news-api `
  -n news-monitor `
  --timeout=180s

kubectl rollout status deployment/news-scheduler `
  -n news-monitor `
  --timeout=180s

16. 실제 배포 결과

최종적으로 다음과 같이 실행됐다.

news-api         3/3 Ready
news-scheduler   1/1 Ready

모든 Pod의 재시작 횟수는 0이었다.

HPA 상태는 다음과 같았다.

TARGETS       MINPODS   MAXPODS   REPLICAS
cpu: 3%/50%   3         10        3

Metrics Server가 수집한 유휴 상태의 사용량은 대략 다음과 같았다.

17. Service 트래픽 분산 테스트

Service를 통해 90번의 요청을 보냈다.

결과는 다음과 같았다.

{
  "news-api-76f9fbd7c5-7bjjz": 29,
  "news-api-76f9fbd7c5-l8c9c": 34,
  "news-api-76f9fbd7c5-znhxn": 27
}

3개의 API Pod가 각각 29건, 34건, 27건을 처리했다.

정확하게 동일한 수는 아니지만 세 Pod에 요청이 고르게 분산되고 있음을 확인할 수 있었다.

주의할 점

처음에는 다음 명령으로 Service를 로컬에 연결했다.

kubectl port-forward service/news-api -n news-monitor 8001:8001

그런데 이 방식으로 테스트했을 때 한 Pod만 계속 응답했다.

kubectl port-forward service는 Service 전체의 로드밸런싱을 그대로 재현하는 것이 아니라 선택된 하나의 Endpoint에 포트포워딩할 수 있다.

따라서 Service 분산 테스트는 클러스터 내부 Pod에서 ClusterIP Service를 호출하는 방식으로 진행해야 한다.

18. HPA 부하 테스트

API에 지속적인 요청을 발생시켜 CPU 사용량을 높였다.

총 9,120번의 요청을 처리하는 동안 HPA 상태를 관찰했다.

부하 발생 전:

Pod 수: 3
CPU: 8% / 50%

부하 발생 후:

Pod 수: 6
CPU: 140% / 50%

CPU 사용률이 목표치인 50%를 초과하자 API Pod가 3개에서 6개로 증가했다.

부하 종료 후:

Pod 수: 3
CPU: 3% / 50%

일정 시간이 지나자 다시 최소 Replica인 3개로 축소됐다.

최종 결과는 다음과 같다.

이를 통해 HPA의 확장과 축소가 모두 정상적으로 동작하는 것을 확인했다.

19. Kubernetes 적용 전후 비교

20. 이번 작업에서 얻은 교훈

Pod를 늘리기 전에 스케줄러부터 분리해야 한다

서버를 여러 개 실행한다고 무조건 안정성이 높아지는 것은 아니다. 스케줄러가 애플리케이션에 포함되어 있다면 기사 수집, AI 분석, 메일 발송이 Pod 수만큼 반복될 수 있다.

API와 백그라운드 작업의 실행 책임을 먼저 분리해야 한다.

HPA에는 Metrics Server와 CPU requests가 필요하다

HPA YAML만 작성한다고 자동 확장이 동작하지 않는다.

다음 조건이 모두 필요하다.

• Metrics Server 설치
• Pod의 CPU requests 설정
• 정상적인 Metrics API
• 일정 시간 이상 지속되는 CPU 부하

DB 연결 수는 Replica 수와 함께 계산해야 한다

Pod 수가 늘어날수록 DB 연결 수도 증가한다. API는 확장됐지만 PostgreSQL의 최대 연결 수를 초과하면 오히려 전체 장애로 이어질 수 있다.

포트포워딩은 Service 분산 테스트가 아니다

kubectl port-forward service/... 결과만 보고 로드밸런싱이 동작하지 않는다고 판단하면 안 된다. 클러스터 내부에서 Service DNS나 ClusterIP를 호출해 확인해야 한다.

로컬 설정과 운영 설정을 구분해야 한다

--kubelet-insecure-tls 같은 옵션은 Docker Desktop 로컬 테스트에는 유용하지만 운영 환경에 그대로 적용하면 안 된다.

21. 앞으로 개선할 부분

현재 구성은 로컬 Kubernetes 검증 단계까지 완료된 상태다. 실제 운영을 위해서는 다음 작업이 추가로 필요하다.

1. Docker 이미지를 외부 Registry에 Push
2. Ingress와 도메인 연결
3. HTTPS 인증서 적용
4. Kubernetes Secret 외부 관리
5. PostgreSQL 최대 연결 수 점검
6. Scheduler 분산 락 적용
7. Prometheus와 Grafana 연동
8. 로그 수집 시스템 구성
9. PodDisruptionBudget 적용
10. 장애 알림 및 배포 자동화

특히 스케줄러는 현재 Replica 1 + Recreate로 중복 가능성을 낮췄지만, 운영 환경에서는 DB 기반 분산 락이나 Kubernetes Lease를 추가하는 것이 안전하다.

마무리

이번 작업을 통해 FastAPI 뉴스 모니터링 서버를 다음과 같은 구조로 변경했다.

• API Pod 기본 3개
• CPU 사용률에 따라 최대 10개까지 확장
• Service를 통한 트래픽 분산
• Scheduler Pod 1개 독립 실행
• 시작·준비·생존 상태 검사
• CPU와 메모리 제한
• DB 커넥션 풀 제한
• Secret 기반 환경변수 관리
• Metrics Server 기반 자원 수집
• 실제 부하 테스트를 통한 HPA 검증

단순히 Kubernetes YAML을 작성하는 것에서 끝내지 않고 실제 부하를 발생시켜 3개 → 6개 → 3개로 자동 확장과 축소가 이루어지는 것까지 확인했다.

이번 구성으로 뉴스 수집과 메일 발송 같은 정기 작업은 한 번만 실행하면서, 사용자 API는 트래픽에 따라 독립적으로 확장할 수 있는 기반을 마련했다.

• 멱등성 키 기반 중복 결제 방지
• 비관적 락 기반 동시성 제어
• 결제 상태 머신
• 블록체인 거래 대사
• 대사 모니터링 API
• 대사 실패 알림과 자동 재시도
• Transactional Outbox
• 실제 MySQL 기반 통합 테스트

하지만 테스트가 아무리 잘 작성되어 있어도 개발자가 매번 직접 실행해야 한다면 실수로 검증을 생략할 수 있다.

새로운 코드가 기존 결제 로직을 깨뜨렸는데도 테스트하지 않은 채 병합될 가능성도 있다.

이번 작업에서는 GitHub Actions를 이용해 다음 과정을 자동화했다.

Pull Request 생성
→ 단위 테스트 실행
→ 실제 MySQL 통합 테스트 실행
→ 테스트 성공 시 실행 JAR 빌드
→ 테스트 리포트와 JAR 보관

또한 CI 환경에서 전체 통합 테스트를 실행하며 발견한 Testcontainers 데이터베이스 공유 문제도 함께 개선했다.

1. CI란 무엇인가?

CI는 Continuous Integration의 약자로, 우리말로는 지속적 통합이라고 한다.

개발자가 코드를 원격 저장소에 올릴 때마다 빌드와 테스트를 자동으로 실행해 코드가 정상적으로 통합될 수 있는지 확인하는 방식이다.

CI가 없다면 개발자가 다음 명령어를 직접 실행해야 한다.

.\gradlew.bat test
.\gradlew.bat integrationTest
.\gradlew.bat bootJar

문제는 사람이 매번 이 과정을 빠짐없이 수행하기 어렵다는 것이다.

CI를 적용하면 다음 상황에서 자동으로 검증할 수 있다.

• develop 브랜치에 코드가 Push된 경우
• develop 브랜치를 대상으로 Pull Request가 생성된 경우
• GitHub 화면에서 수동 실행한 경우

on:
  pull_request:
    branches: [develop]

  push:
    branches: [develop]

  workflow_dispatch:

workflow_dispatch는 GitHub Actions 화면에서 워크플로를 직접 실행할 수 있게 해주는 설정이다.

2. CI 전체 구조

이번에 구성한 CI는 세 개의 Job으로 나누었다.

Job은 GitHub Actions에서 독립적으로 실행되는 작업 단위다.

unit-test
integration-test
build

전체 관계는 다음과 같다.

             ┌─ 단위 테스트 ────────┐
코드 변경 ───┤                       ├─ 실행 JAR 빌드
             └─ MySQL 통합 테스트 ──┘

단위 테스트와 통합 테스트는 서로 독립적이므로 병렬로 실행된다.

두 테스트가 모두 성공한 경우에만 빌드가 실행된다.

build:
  needs: [unit-test, integration-test]

needs는 현재 Job이 실행되기 전에 성공해야 하는 다른 Job을 지정하는 설정이다.

따라서 단위 테스트 또는 통합 테스트 중 하나라도 실패하면 실행 JAR가 만들어지지 않는다.

3. 최소 권한 설정

GitHub Actions는 저장소의 코드와 다양한 리소스에 접근할 수 있다.

필요 이상의 권한을 부여하면 사용하는 외부 Action이나 스크립트에 보안 문제가 생겼을 때 피해 범위가 커질 수 있다.

이번 CI는 코드를 읽고 테스트하는 작업만 수행하므로 저장소 읽기 권한만 부여했다.

permissions:
  contents: read

이를 최소 권한 원칙이라고 한다.

최소 권한 원칙은 작업에 꼭 필요한 권한만 부여해 사고 발생 시 피해 범위를 줄이는 보안 원칙이다.

이번 워크플로는 다음 작업을 하지 않는다.

• 코드를 수정해서 Push
• Pull Request 수정
• 패키지 배포
• Release 생성

따라서 쓰기 권한은 필요하지 않았다.

4. 중복 CI 실행 취소

같은 Pull Request에 코드를 여러 번 Push하면 이전 코드와 최신 코드에 대한 CI가 동시에 실행될 수 있다.

예를 들어 다음처럼 연속으로 코드를 올렸다고 가정해보자.

첫 번째 Push → CI 실행 중
두 번째 Push → 새로운 CI 실행

첫 번째 CI는 이미 이전 버전의 코드를 테스트하고 있으므로 완료 결과의 가치가 낮다.

이를 방지하기 위해 동시 실행 제어를 추가했다.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

concurrency는 동일한 그룹의 워크플로 실행을 제한하는 기능이다.

cancel-in-progress: true를 설정하면 같은 브랜치에서 새 CI가 시작됐을 때 기존 CI는 자동으로 취소된다.

이를 통해 불필요한 실행 시간과 GitHub Actions 사용량을 줄일 수 있다.

5. JDK와 Gradle 환경 구성

TinyPay 백엔드는 Java 17을 사용하므로 CI에도 동일한 Java 버전을 설정했다.

- name: Set up JDK 17
  uses: actions/setup-java@v5
  with:
    distribution: temurin
    java-version: '17'

Temurin은 Eclipse Adoptium에서 제공하는 OpenJDK 배포판이다.

로컬과 CI의 Java 버전이 다르면 다음과 같은 문제가 발생할 수 있다.

• 사용하는 Java 문법이 지원되지 않음
• 컴파일 결과가 달라짐
• 라이브러리 호환성 문제
• 테스트는 통과하지만 배포 환경에서 실패

따라서 프로젝트와 CI의 Java 버전을 맞췄다.

Gradle Wrapper 검증

프로젝트는 Gradle Wrapper를 사용한다.

Gradle Wrapper는 개발자가 Gradle을 별도로 설치하지 않아도 프로젝트에 지정된 Gradle 버전을 내려받아 실행하는 방식이다.

gradlew
gradlew.bat
gradle/wrapper/gradle-wrapper.jar
gradle/wrapper/gradle-wrapper.properties

이 프로젝트에서는 Gradle 9.4.1을 사용한다.

distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.1-bin.zip

CI에서는 Wrapper 파일이 알려진 정상 파일인지 검증한다.

- name: Validate Gradle wrapper
  uses: gradle/actions/wrapper-validation@v6

Gradle Wrapper JAR가 악의적으로 교체되면 CI가 공격자의 코드를 실행할 수도 있다.

Wrapper 검증은 체크섬을 비교해 변조되거나 알려지지 않은 Wrapper JAR를 탐지한다.

체크섬은 파일의 내용을 바탕으로 계산한 고유한 값으로, 파일이 변경됐는지 확인할 때 사용한다.

Gradle 캐시 적용

CI는 실행할 때마다 의존성을 처음부터 내려받으면 시간이 오래 걸린다.

이를 줄이기 위해 Gradle 캐시를 적용했다.

- name: Set up Gradle cache
  uses: gradle/actions/setup-gradle@v6

캐시는 이전 실행에서 내려받은 라이브러리나 빌드 관련 데이터를 보관했다가 다음 실행에서 재사용하는 방식이다.

이를 통해 다음 항목을 반복해서 내려받는 시간을 줄일 수 있다.

• Spring Boot 라이브러리
• MySQL Connector
• Testcontainers
• Web3j
• JWT 라이브러리
• 테스트 라이브러리

공식 Gradle Action은 Gradle Wrapper 검증과 Gradle User Home 캐싱을 지원한다.

6. 단위 테스트 Job

단위 테스트는 외부 시스템 없이 개별 서비스와 도메인 로직을 검증한다.

unit-test:
  name: Unit tests
  runs-on: ubuntu-latest
  timeout-minutes: 15

runs-on: ubuntu-latest는 GitHub에서 제공하는 최신 Ubuntu 가상 머신에서 작업을 실행한다는 의미다.

테스트 실행 명령은 다음과 같다.

- name: Run unit tests
  run: ./gradlew test --stacktrace

--stacktrace는 테스트나 빌드가 실패했을 때 예외가 발생한 호출 경로를 자세히 출력하는 옵션이다.

이를 통해 CI 실패 원인을 로그에서 더 쉽게 찾을 수 있다.

Linux 실행 권한 처리

Windows에서는 gradlew.bat을 사용하지만 GitHub Actions의 Ubuntu 환경에서는 gradlew을 실행한다.

Linux에서는 파일에 실행 권한이 필요하다.

- name: Grant execute permission
  run: chmod +x gradlew

이 과정이 없으면 다음과 같은 오류가 발생할 수 있다.

Permission denied

7. MySQL 통합 테스트 Job

결제 동시성과 트랜잭션은 Mock 객체만으로 충분히 검증하기 어렵다.

따라서 통합 테스트 Job에서는 Testcontainers로 실제 MySQL을 실행한다.

integration-test:
  name: MySQL integration tests
  runs-on: ubuntu-latest
  timeout-minutes: 25

Testcontainers는 테스트가 실행될 때 Docker 컨테이너로 MySQL과 같은 외부 시스템을 생성하는 라이브러리다.

테스트가 끝나면 생성한 컨테이너도 정리한다.

Docker 환경 확인

GitHub에서 제공하는 Ubuntu Runner에는 Docker가 설치되어 있다.

Testcontainers를 실행하기 전에 Docker가 정상적으로 동작하는지 확인한다.

- name: Verify Docker environment
  run: docker info

이 단계가 실패한다면 MySQL 컨테이너를 실행할 수 없으므로 통합 테스트도 진행하지 않는다.

통합 테스트는 다음 명령어로 실행한다.

- name: Run MySQL Testcontainers tests
  run: ./gradlew integrationTest --stacktrace

이 과정에서 다음 내용이 검증된다.

• 멱등성 키 고유 제약조건
• 동시 결제 시 잔액 차감 락
• 대사 대상의 중복 선점 방지
• 알림 재시도 대상의 중복 선점 방지
• Transactional Outbox 중복 선점 방지
• 트랜잭션 커밋 이후 처리
• 롤백 시 Outbox 저장 취소
• 전체 Spring Context 로딩

8. CI에서 발견한 통합 테스트 간 충돌

CI와 동일한 방식으로 모든 통합 테스트를 한 번에 실행하자 기존 테스트 하나가 실패했다.

WalletConcurrencyIntegrationTest FAILED
DataIntegrityViolationException
SQLIntegrityConstraintViolationException

각 테스트를 단독으로 실행하면 성공했지만 전체 통합 테스트에서는 실패했다.

이 상황은 CI를 구축하지 않았다면 발견하기 어려운 문제였다.

원인: 동일한 Testcontainers DB 이름

기존 통합 테스트들은 모두 동일한 JDBC URL을 사용하고 있었다.

"spring.datasource.url=jdbc:tc:mysql:8.0.36:///tinypay"

테스트 클래스마다 Spring Context는 달랐지만 Testcontainers JDBC URL은 같았다.

그 결과 여러 테스트가 같은 MySQL 환경과 스키마를 공유하며 다음 문제가 발생할 수 있었다.

• 다른 테스트가 저장한 데이터와 고유 키 충돌
• 한 테스트의 create-drop이 다른 테스트의 스키마에 영향
• 테스트 실행 순서에 따라 성공과 실패가 달라짐

테스트가 서로 영향을 주지 않아야 한다는 테스트 격리 원칙이 깨진 것이다.

테스트 격리는 하나의 테스트가 생성하거나 변경한 데이터가 다른 테스트 결과에 영향을 주지 않도록 분리하는 원칙이다.

해결: 테스트 클래스별 DB 이름 분리

각 통합 테스트 클래스에 독립적인 DB 이름을 부여했다.

tinypay_wallet_concurrency
tinypay_idempotency
tinypay_reliability
tinypay_chat
tinypay_context

예를 들어 지갑 동시성 테스트는 다음 DB를 사용한다.

"spring.datasource.url="
        + "jdbc:tc:mysql:8.0.36:///tinypay_wallet_concurrency"

결제 멱등성 테스트는 별도의 DB를 사용한다.

"spring.datasource.url="
        + "jdbc:tc:mysql:8.0.36:///tinypay_idempotency"

결제 신뢰성 테스트도 분리했다.

"spring.datasource.url="
        + "jdbc:tc:mysql:8.0.36:///tinypay_reliability"

DB 환경을 분리한 뒤 전체 통합 테스트를 다시 실행했다.

13 tests completed
BUILD SUCCESSFUL

이제 특정 테스트의 데이터나 스키마 변경이 다른 테스트에 영향을 주지 않는다.

다만 클래스마다 독립적인 MySQL 컨테이너를 준비하므로 테스트 시간은 길어졌다.

이 프로젝트에서는 실행 속도보다 결제 테스트의 독립성과 신뢰성이 더 중요하다고 판단했다.

9. 테스트 실패 리포트 보관

CI가 실패하면 로그만으로 원인을 찾기 어려울 수 있다.

Gradle은 테스트 결과를 HTML과 XML로 생성한다.

단위 테스트 결과:

build/reports/tests/test/
build/test-results/test/

통합 테스트 결과:

build/reports/tests/integrationTest/
build/test-results/integrationTest/

GitHub Actions에서는 이를 Artifact로 업로드한다.

Artifact는 워크플로 실행 중 생성된 파일을 GitHub에 보관하고 내려받을 수 있게 하는 기능이다.

- name: Upload integration-test reports
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: integration-test-reports
    path: |
      build/reports/tests/integrationTest/
      build/test-results/integrationTest/
    if-no-files-found: ignore
    retention-days: 7

if: always()를 적용했기 때문에 테스트가 실패해도 리포트 업로드 단계는 실행된다.

리포트는 7일 동안 보관하도록 설정했다.

이를 통해 CI가 실패했을 때 GitHub Actions 화면에서 리포트를 내려받아 다음 내용을 확인할 수 있다.

• 실패한 테스트 이름
• 예외 메시지
• Stack Trace
• 테스트 실행 시간
• 전체 성공·실패 개수

10. 테스트 성공 후 실행 JAR 빌드

단위 테스트와 통합 테스트가 모두 성공하면 Spring Boot 실행 JAR를 만든다.

build:
  name: Build executable JAR
  needs: [unit-test, integration-test]

빌드 명령은 다음과 같다.

- name: Build executable JAR
  run: ./gradlew bootJar -x test

테스트는 앞선 Job에서 이미 검증했으므로 JAR 생성 단계에서는 다시 실행하지 않는다.

생성 위치는 다음과 같다.

build/libs/tinypay-backend-0.0.1-SNAPSHOT.jar

로컬 검증에서 생성된 JAR 크기는 약 120MB였다.

생성된 JAR도 Artifact로 업로드한다.

- name: Upload executable JAR
  uses: actions/upload-artifact@v4
  with:
    name: tinypay-backend-jar
    path: build/libs/*.jar
    if-no-files-found: error
    retention-days: 7

if-no-files-found: error를 적용했기 때문에 JAR가 만들어지지 않으면 CI도 실패한다.

즉 테스트만 성공하고 실제 실행 파일을 생성하지 못하는 상황도 탐지할 수 있다.

11. README 상태 배지 추가

CI 실행 상태를 저장소 첫 화면에서 확인할 수 있도록 README에 상태 배지를 추가했다.

[![Payment Reliability CI](
https://github.com/hyeonseo1202/tinypay-backend/actions/workflows/ci.yml/badge.svg
)](
https://github.com/hyeonseo1202/tinypay-backend/actions/workflows/ci.yml
)

배지는 최근 워크플로 상태에 따라 다음과 같이 표시된다.

passing
failing

배지를 클릭하면 해당 GitHub Actions 워크플로 화면으로 이동한다.

포트폴리오를 확인하는 사람도 저장소 첫 화면에서 테스트 자동화 여부와 최근 실행 상태를 확인할 수 있다.

12. 최종 GitHub Actions 설정

최종 CI의 핵심 구조는 다음과 같다.

name: Payment Reliability CI

on:
  pull_request:
    branches: [develop]

  push:
    branches: [develop]

  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  unit-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6
      - uses: gradle/actions/wrapper-validation@v6
      - uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'
      - uses: gradle/actions/setup-gradle@v6
      - run: chmod +x gradlew
      - run: ./gradlew test --stacktrace

  integration-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6
      - uses: gradle/actions/wrapper-validation@v6
      - uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'
      - uses: gradle/actions/setup-gradle@v6
      - run: chmod +x gradlew
      - run: docker info
      - run: ./gradlew integrationTest --stacktrace

  build:
    needs: [unit-test, integration-test]
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'
      - uses: gradle/actions/setup-gradle@v6
      - run: chmod +x gradlew
      - run: ./gradlew bootJar -x test

실제 워크플로에는 테스트 리포트와 JAR 업로드 단계도 포함되어 있다.

13. 검증 결과

워크플로 YAML 문법을 확인했다.

YAML OK

단위 테스트를 실행했다.

BUILD SUCCESSFUL

전체 MySQL 통합 테스트를 실행했다.

13 tests completed
BUILD SUCCESSFUL

결제 신뢰성 통합 테스트도 독립 DB에서 다시 실행했다.

8 tests completed
BUILD SUCCESSFUL

Spring Boot 실행 JAR 생성도 확인했다.

tinypay-backend-0.0.1-SNAPSHOT.jar
약 120MB

14. 이번 작업에서 배운 점

CI는 단순히 기존 테스트를 자동으로 실행하는 도구가 아니었다.

전체 테스트를 동일한 환경에서 반복 실행하면서 로컬에서 개별 테스트만 실행할 때 발견하지 못했던 문제를 드러내기도 했다.

이번 작업에서는 CI 구축 과정에서 다음 문제를 발견했다.

각 테스트는 단독 실행 시 성공
→ 전체 통합 테스트 실행 시 고유 제약조건 충돌
→ Testcontainers DB 공유가 원인
→ 테스트 클래스별 독립 DB로 분리

결제 테스트에서 중요한 것은 테스트 개수만이 아니었다.

다음 조건도 함께 충족해야 했다.

• 실행 순서와 관계없이 성공
• 다른 테스트가 저장한 데이터에 영향받지 않음
• 로컬과 CI에서 같은 결과가 나옴
• 실제 MySQL의 락과 제약조건을 검증
• 실패 시 원인을 추적할 수 있는 리포트 제공

최종적으로 코드 변경부터 실행 파일 생성까지 다음 과정이 자동화됐다.

코드 Push 또는 Pull Request
→ 단위 테스트
→ 실제 MySQL 통합 테스트
→ 실행 JAR 빌드
→ 결과와 리포트 보관

이제 결제 안정성 기능은 구현과 테스트에 그치지 않고, 이후 코드 변경에서도 계속 검증되는 구조를 갖추게 됐다.

코드만 보면 올바르게 동작하는 것처럼 보여도 실제 데이터베이스에서는 예상과 다르게 동작할 수 있다.

특히 다음 기능은 단위 테스트만으로 충분히 검증하기 어렵다.

• 비관적 락을 이용한 동시성 제어
• 데이터베이스의 고유 제약조건
• 트랜잭션 커밋과 롤백
• 커밋 이후 이벤트 발행

이번 작업에서는 Testcontainers로 실제 MySQL을 실행하고, 결제 대사와 알림 기능이 장애 및 동시 요청 상황에서도 안전하게 동작하는지 검증했다.

1. 왜 단위 테스트만으로 부족했을까?

단위 테스트는 특정 클래스의 로직을 빠르게 검증하기에 적합하다.

예를 들어 Mockito를 사용하면 Repository가 특정 값을 반환한다고 가정한 뒤 서비스의 상태 변경을 검증할 수 있다.

when(paymentLogRepository.findById(1L))
        .thenReturn(Optional.of(payment));

service.reconcileOne(1L);

assertThat(payment.getReconciliationStatus())
        .isEqualTo(ReconciliationStatus.MATCHED);

하지만 이런 테스트는 실제 데이터베이스의 동작까지 검증하지 않는다.

다음과 같은 부분은 Mock 객체로 재현하기 어렵다.

• SELECT ... FOR UPDATE가 실제로 다른 트랜잭션을 대기시키는가?
• 먼저 처리한 트랜잭션이 커밋된 후 두 번째 트랜잭션은 변경된 데이터를 조회하는가?
• 고유 제약조건이 중복 데이터를 실제로 차단하는가?
• 트랜잭션이 롤백되면 이벤트도 취소되는가?

따라서 실제 MySQL을 사용하는 통합 테스트가 필요했다.

2. Testcontainers란?

Testcontainers는 테스트를 실행할 때 Docker 컨테이너로 데이터베이스나 외부 시스템을 실행하는 라이브러리다.

이번 테스트에서는 MySQL 8.0.36 컨테이너를 사용했다.

@DataJpaTest(properties = {
    "spring.datasource.url=jdbc:tc:mysql:8.0.36:///tinypay",
    "spring.datasource.driver-class-name="
            + "org.testcontainers.jdbc.ContainerDatabaseDriver",
    "spring.jpa.hibernate.ddl-auto=create-drop",
    "spring.jpa.show-sql=false"
})

테스트가 시작되면 다음 과정이 자동으로 실행된다.

MySQL Docker 컨테이너 실행
→ 테스트용 테이블 생성
→ 통합 테스트 수행
→ 테이블 제거
→ 컨테이너 종료

개발자의 로컬 MySQL 설정에 의존하지 않고 테스트마다 독립적인 데이터베이스 환경을 만들 수 있다는 장점이 있다.

3. 테스트 환경 구성

통합 테스트는 일반 단위 테스트와 분리했다.

@Tag("integration")

Gradle의 일반 test 작업에서는 integration 태그를 제외한다.

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

별도의 integrationTest 작업에서는 통합 테스트만 실행한다.

tasks.register('integrationTest', Test) {
    description = 'Runs integration tests against a real MySQL Testcontainer.'
    group = 'verification'

    testClassesDirs = sourceSets.test.output.classesDirs
    classpath = sourceSets.test.runtimeClasspath

    useJUnitPlatform {
        includeTags 'integration'
    }

    shouldRunAfter test
}

실행 명령어는 다음과 같다.

.\gradlew.bat integrationTest

이렇게 분리하면 빠른 단위 테스트는 자주 실행하고, Docker가 필요한 통합 테스트는 필요한 시점에 별도로 실행할 수 있다.

테스트 1. 동시에 접근해도 같은 결제는 한 번만 선점되는가?

결제 대사 배치는 처리할 결제를 조회할 때 비관적 락을 사용한다.

비관적 락은 다른 트랜잭션이 같은 데이터를 동시에 수정할 가능성이 높다고 가정하고, 데이터를 먼저 잠그는 방식이다.

Repository에는 다음과 같이 PESSIMISTIC_WRITE 락이 적용되어 있다.

@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("""
    SELECT p
    FROM PaymentLog p
    WHERE p.txHash IS NOT NULL
      AND p.paymentStatus IN :paymentStatuses
      AND (
            p.reconciliationStatus IS NULL
            OR p.reconciliationStatus IN :reconciliationStatuses
          )
      AND (
            p.nextReconciliationAt IS NULL
            OR p.nextReconciliationAt <= :now
          )
    ORDER BY p.id
    """)
List<PaymentLog> findReconciliationCandidatesForUpdate(
        Collection<PaymentStatus> paymentStatuses,
        Collection<ReconciliationStatus> reconciliationStatuses,
        LocalDateTime now,
        Pageable pageable
);

하지만 코드에 @Lock이 붙어 있다는 사실만으로 동시성 문제가 해결됐다고 단정할 수는 없다.

실제 MySQL에서 두 트랜잭션을 동시에 실행해 확인해야 한다.

두 개의 스레드로 동시 요청 재현하기

두 작업자가 동시에 같은 대사 결제를 조회하는 상황을 만들었다.

ExecutorService executor = Executors.newFixedThreadPool(2);

ExecutorService는 여러 작업을 별도 스레드에서 실행할 수 있도록 관리하는 도구다.

첫 번째 트랜잭션은 결제를 조회해 락을 획득한 뒤, 테스트 코드가 허용할 때까지 대기한다.

Future<?> first = executor.submit(() ->
        transaction.executeWithoutResult(status -> {
            List<PaymentLog> claimed = findCandidates();

            claimed.forEach(PaymentLog::startReconciliation);
            claimedCount.addAndGet(claimed.size());

            firstClaimed.countDown();
            await(releaseFirst);
        })
);

두 번째 트랜잭션도 같은 결제를 조회한다.

Future<?> second = executor.submit(() ->
        transaction.executeWithoutResult(status -> {
            List<PaymentLog> claimed = findCandidates();

            claimed.forEach(PaymentLog::startReconciliation);
            claimedCount.addAndGet(claimed.size());
        })
);

두 스레드의 실행 순서는 CountDownLatch로 제어했다.

CountDownLatch는 특정 작업이 완료될 때까지 다른 스레드를 대기시키는 동시성 제어 도구다.

첫 번째 트랜잭션이 결제 조회 및 락 획득
→ 첫 번째 트랜잭션 대기
→ 두 번째 트랜잭션 조회 시작
→ 첫 번째 트랜잭션 상태 변경 및 커밋
→ 두 번째 트랜잭션 조회 재개

첫 번째 트랜잭션은 결제 상태를 PROCESSING으로 변경한다.

claimed.forEach(PaymentLog::startReconciliation);

첫 번째 트랜잭션이 커밋된 뒤 두 번째 트랜잭션은 최신 상태를 확인한다.

해당 결제는 더 이상 PENDING이 아니므로 대사 후보 조회 결과에서 제외되어야 한다.

최종적으로 선점 횟수와 DB 상태를 검증했다.

assertThat(claimedCount).hasValue(1);

assertThat(finalStatus)
        .isEqualTo(ReconciliationStatus.PROCESSING);

실제 MySQL에서 두 작업자가 동시에 접근하더라도 같은 결제가 한 번만 선점되는 것을 확인했다.

테스트 2. 같은 알림이 중복 저장되지 않는가?

대사 알림은 다음 값으로 이벤트 고유 키를 만든다.

paymentId:reconciliationStatus:reconciliationAttempt

예를 들면 다음과 같다.

1:MISMATCHED:1

동일 결제의 동일 대사 시도에서 같은 실패 상태가 여러 번 전달되더라도 알림은 한 번만 발송되어야 한다.

이를 위해 알림 테이블의 event_key에 고유 제약조건을 설정했다.

@Table(
    name = "reconciliation_alert",
    uniqueConstraints = @UniqueConstraint(
        name = "uk_reconciliation_alert_event_key",
        columnNames = "event_key"
    )
)

고유 제약조건은 특정 컬럼에 동일한 값이 두 번 저장되지 않도록 데이터베이스가 보장하는 규칙이다.

실제 MySQL에 중복 데이터 저장하기

먼저 알림을 저장한다.

alertRepository.saveAndFlush(
        ReconciliationAlert.pending(
                "1:MISMATCHED:1",
                1L,
                ReconciliationStatus.MISMATCHED,
                1
        )
);

그다음 동일한 이벤트 키를 다시 저장한다.

assertThatThrownBy(() ->
        alertRepository.saveAndFlush(
                ReconciliationAlert.pending(
                        "1:MISMATCHED:1",
                        1L,
                        ReconciliationStatus.MISMATCHED,
                        1
                )
        )
).isInstanceOf(DataIntegrityViolationException.class);

DataIntegrityViolationException은 고유 제약조건이나 외래 키처럼 데이터베이스 무결성 규칙을 위반했을 때 Spring이 발생시키는 예외다.

서비스에서 중복 여부를 먼저 조회하더라도 동시 요청 사이에는 경쟁 조건이 발생할 수 있다.

경쟁 조건은 여러 작업의 실행 순서에 따라 결과가 달라지는 문제다.

예를 들어 다음 순서가 가능하다.

작업 A: 기존 알림 없음 확인
작업 B: 기존 알림 없음 확인
작업 A: 알림 저장
작업 B: 같은 알림 저장

따라서 애플리케이션의 중복 확인뿐 아니라 DB 고유 제약조건을 마지막 방어선으로 사용해야 한다.

테스트 3. 알림 이벤트가 커밋 이후에만 전달되는가?

결제 대사 결과와 알림 발송 시점도 중요하다.

알림을 너무 일찍 발송하면 다음 문제가 발생할 수 있다.

대사 결과를 MISMATCHED로 변경
→ 알림 발송
→ DB 트랜잭션 실패 및 롤백

이 경우 DB에는 실패 결과가 저장되지 않았지만 운영자는 실패 알림을 받게 된다.

이를 방지하기 위해 알림 리스너에 다음 설정을 적용했다.

@TransactionalEventListener(
        phase = TransactionPhase.AFTER_COMMIT
)

TransactionalEventListener는 트랜잭션의 특정 시점에 맞춰 이벤트를 처리하는 Spring 기능이다.

AFTER_COMMIT은 트랜잭션이 정상적으로 커밋된 이후에만 리스너를 실행한다는 의미다.

커밋 전에는 이벤트가 전달되지 않는지 확인

테스트에서 실제 트랜잭션을 시작하고 이벤트를 발행했다.

transaction.executeWithoutResult(status -> {
    eventPublisher.publishEvent(event);

    assertThat(recordingAlertListener.events())
            .isEmpty();
});

트랜잭션 내부에서는 이벤트가 리스너에 전달되지 않아야 한다.

트랜잭션이 종료되어 커밋된 후에는 이벤트가 기록되어야 한다.

assertThat(recordingAlertListener.events())
        .containsExactly(event);

이를 통해 알림 이벤트가 결제 데이터보다 먼저 외부로 전달되지 않는다는 것을 확인했다.

테스트 4. 트랜잭션이 롤백되면 알림도 취소되는가?

다음으로 대사 트랜잭션이 롤백되는 상황을 만들었다.

롤백은 트랜잭션 안에서 수행한 데이터 변경을 취소하고 이전 상태로 되돌리는 동작이다.

transaction.executeWithoutResult(status -> {
    eventPublisher.publishEvent(alertEvent());
    status.setRollbackOnly();
});

setRollbackOnly()를 호출하면 해당 트랜잭션은 커밋하지 않고 롤백된다.

트랜잭션이 종료된 후 이벤트가 전달되지 않았는지 검증했다.

assertThat(recordingAlertListener.events())
        .isEmpty();

결과적으로 결제 대사 결과가 DB에 반영되지 않은 상황에서는 운영 알림도 전송되지 않는다는 것을 확인했다.

4가지 테스트가 검증하는 범위

이번 통합 테스트가 검증하는 범위를 정리하면 다음과 같다.

단순히 메서드의 반환값을 확인하는 것이 아니라 실제 MySQL의 락, 고유 제약조건, 트랜잭션 동작을 검증했다.

테스트 결과

단위 테스트와 MySQL 통합 테스트를 각각 실행했다.

.\gradlew.bat test

BUILD SUCCESSFUL

통합 테스트는 다음 명령어로 실행했다.

.\gradlew.bat integrationTest `
  --tests "com.tinypay.finance.repository.PaymentReconciliationReliabilityIntegrationTest"

결과는 다음과 같다.

MySQL 통합 테스트 4개 통과
BUILD SUCCESSFUL

테스트 실행 중 만난 문제

첫 번째 통합 테스트 실행에서는 다음과 같은 오류가 발생했다.

Could not find a valid Docker environment

Testcontainers 코드의 문제가 아니라 Docker Desktop이 실행되지 않아 MySQL 컨테이너를 생성할 수 없었던 것이 원인이었다.

Docker Desktop을 실행한 뒤 다시 테스트하자 MySQL 컨테이너가 정상적으로 생성됐다.

첫 실행은 다음 이미지를 내려받아야 하므로 시간이 오래 걸릴 수 있다.

mysql:8.0.36
testcontainers/ryuk

Ryuk은 Testcontainers가 테스트 종료 후 컨테이너와 네트워크 같은 자원을 정리하기 위해 사용하는 보조 컨테이너다.

이미지를 한 번 내려받은 이후에는 테스트 준비 시간이 줄어든다.

마무리

이번 작업을 통해 “비관적 락을 적용했다”에서 끝나지 않고 실제 MySQL에서 락이 의도대로 작동한다는 것을 검증했다.

또한 애플리케이션 로직에만 의존하지 않고 DB 고유 제약조건을 통해 중복 알림을 한 번 더 차단했다.

결제 상태와 알림 사이의 일관성도 실제 트랜잭션을 이용해 검증했다.

결제 대사 트랜잭션 성공
→ DB 커밋
→ 알림 이벤트 전달

결제 대사 트랜잭션 실패
→ DB 롤백
→ 알림 이벤트 폐기

결제 시스템에서는 기능을 구현하는 것만큼 실패 상황과 실행 순서를 테스트하는 것이 중요하다.

특히 락과 트랜잭션은 코드만 보고 안전성을 판단하기 어렵기 때문에 실제 운영 DB와 동일한 종류의 데이터베이스에서 검증해야 한다는 점을 배울 수 있었다.

하지만 대사 기능이 자동으로 실행된다는 것만으로는 운영 환경에서 충분하지 않았다.

예를 들어 다음과 같은 질문에 답할 방법이 필요했다.

• 현재 대기 중인 대사는 몇 건인가?
• 결제 기록과 블록체인 거래가 일치하지 않는 건은 무엇인가?
• RPC 장애로 재시도 횟수를 모두 소진한 결제가 있는가?
• 특정 결제가 어떤 검증 과정을 거쳤는가?
• 자동 재시도에 실패한 결제를 운영자가 다시 처리할 수 있는가?

이번 작업에서는 이 문제를 해결하기 위해 결제 대사 모니터링 API, 수동 재처리 기능, Prometheus 메트릭을 구현했다.

1. 대사 기능만으로는 부족했던 이유

결제 대사란 서버 DB에 저장된 결제 기록과 실제 결제 시스템의 거래 내역을 비교해 일치 여부를 확인하는 작업이다.

TinyPay에서는 서버의 PaymentLog와 블록체인의 트랜잭션 정보를 비교한다.

기존 대사 배치는 결제를 다음과 같은 상태로 관리한다.

PENDING
→ PROCESSING
→ MATCHED
→ MISMATCHED
→ RETRY_REQUIRED
→ RETRY_EXHAUSTED

각 상태의 의미는 다음과 같다.

• PENDING: 대사 처리 대기
• PROCESSING: 대사 진행 중
• MATCHED: 서버 기록과 블록체인 거래가 일치
• MISMATCHED: 금액이나 수신자 등의 정보가 불일치
• RETRY_REQUIRED: 외부 시스템 오류로 재시도 필요
• RETRY_EXHAUSTED: 최대 재시도 횟수 초과

이 상태들은 DB에 저장되고 있었지만 운영자가 전체 현황을 한눈에 확인하거나 실패 건을 다시 처리할 방법은 없었다.

그래서 대사 결과를 조회하고 조치할 수 있는 별도의 운영 기능을 추가했다.

2. 구현 목표

이번 작업의 목표는 크게 네 가지였다.

대사 상태 요약

현재 상태별 결제 건수를 조회한다.

{
  "pending": 3,
  "processing": 1,
  "matched": 120,
  "mismatched": 2,
  "retryRequired": 4,
  "retryExhausted": 1
}

이상 결제 목록 조회

MISMATCHED, RETRY_EXHAUSTED처럼 운영자의 확인이 필요한 결제만 조회한다.

검증 이력 추적

특정 결제가 언제 어떤 이유로 검증에 실패했는지 조회한다.

수동 재처리

자동 재시도를 모두 소진했거나 거래 정보가 불일치한 결제를 운영자가 다시 대기 상태로 전환한다.

3. 상태별 건수 조회 기능

먼저 PaymentLogRepository에 상태별 건수를 조회하는 메서드를 추가했다.

long countByReconciliationStatus(ReconciliationStatus status);

long countByReconciliationStatusIsNull();

기존 데이터 중에는 대사 상태 컬럼이 추가되기 전에 저장되어 null인 데이터가 존재할 수 있다.

이 데이터는 아직 대사하지 않은 결제이므로 PENDING으로 취급했다.

public ReconciliationSummaryResponse getSummary() {
    return new ReconciliationSummaryResponse(
            paymentLogRepository.countByReconciliationStatus(
                    ReconciliationStatus.PENDING
            ) + paymentLogRepository.countByReconciliationStatusIsNull(),

            paymentLogRepository.countByReconciliationStatus(
                    ReconciliationStatus.PROCESSING
            ),

            paymentLogRepository.countByReconciliationStatus(
                    ReconciliationStatus.MATCHED
            ),

            paymentLogRepository.countByReconciliationStatus(
                    ReconciliationStatus.MISMATCHED
            ),

            paymentLogRepository.countByReconciliationStatus(
                    ReconciliationStatus.RETRY_REQUIRED
            ),

            paymentLogRepository.countByReconciliationStatus(
                    ReconciliationStatus.RETRY_EXHAUSTED
            )
    );
}

이를 통해 운영 화면이나 모니터링 도구에서 현재 대사 상태를 빠르게 파악할 수 있게 됐다.

4. 이상 결제 목록 조회

운영자가 가장 먼저 확인해야 하는 대상은 다음 두 상태다.

MISMATCHED
RETRY_EXHAUSTED

• MISMATCHED는 서버 기록과 실제 블록체인 거래가 다르다는 의미다.
• RETRY_EXHAUSTED는 외부 장애 등으로 자동 재시도 횟수를 모두 소진했다는 의미다.

두 상태를 기본 알림 대상으로 설정했다.

private static final List<ReconciliationStatus> DEFAULT_ALERT_STATUSES =
        List.of(
                ReconciliationStatus.MISMATCHED,
                ReconciliationStatus.RETRY_EXHAUSTED
        );

조회 결과가 많아질 수 있으므로 페이지네이션도 적용했다.

페이지네이션은 데이터를 한 번에 모두 가져오지 않고 일정한 크기로 나누어 조회하는 방식이다.

Page<PaymentLog> findByReconciliationStatusInOrderByIdDesc(
        Collection<ReconciliationStatus> statuses,
        Pageable pageable
);

사용자가 지나치게 큰 size 값을 보내는 것도 방지했다.

private static final int MAX_PAGE_SIZE = 100;

PageRequest.of(
        Math.max(page, 0),
        Math.min(Math.max(size, 1), MAX_PAGE_SIZE)
);

페이지 번호가 음수이면 0으로 보정하고, 페이지 크기는 최소 1건에서 최대 100건으로 제한했다.

5. 결제별 검증 이력 조회

하나의 결제는 외부 RPC 장애나 거래 반영 지연 등으로 여러 번 검증될 수 있다.

RPC는 서버가 블록체인 노드에 거래 정보를 요청할 때 사용하는 통신 방식이다.

각 검증 결과는 TxVerificationLog에 저장되어 있으므로 결제 ID를 기준으로 최신순 조회 메서드를 추가했다.

List<TxVerificationLog> findByPayment_IdOrderByIdDesc(Long paymentId);

응답에는 다음 정보가 포함된다.

• 검증 결과
• 실패 단계
• 예상 결제 금액
• 실제 결제 금액
• 예상 수신자
• 실제 수신자
• 상세 실패 원인
• 검증 시각

new ReconciliationHistoryResponse.VerificationItem(
        log.getId(),
        log.getVerificationStatus().name(),
        log.getFailedAtStep(),
        log.getExpectedAmount(),
        log.getActualAmount(),
        log.getExpectedReceiver(),
        log.getActualReceiver(),
        log.getDetail(),
        log.getCreatedAt()
);

이를 통해 운영자는 단순히 “실패했다”는 결과만 보는 것이 아니라 어느 검증 단계에서 어떤 값이 달랐는지 추적할 수 있다.

6. 수동 재처리 기능

자동 재시도가 끝났다고 해서 결제를 계속 실패 상태로 방치할 수는 없다.

일시적인 블록체인 노드 장애였다면 운영자가 다시 대사를 요청할 수 있어야 한다.

이를 위해 PaymentLog에 수동 재처리 상태 전환 메서드를 추가했다.

public void requestManualReconciliation() {
    if (reconciliationStatus != ReconciliationStatus.MISMATCHED
            && reconciliationStatus != ReconciliationStatus.RETRY_EXHAUSTED
            && reconciliationStatus != ReconciliationStatus.RETRY_REQUIRED) {
        throw new IllegalStateException(
                "수동 재시도를 요청할 수 없는 대사 상태입니다: "
                        + reconciliationStatus
        );
    }

    this.reconciliationStatus = ReconciliationStatus.PENDING;
    this.reconciliationAttempts = 0;
    this.reconciliationStartedAt = null;
    this.nextReconciliationAt = null;
    this.reconciliationError = null;
}

모든 상태에서 수동 재시도를 허용하지는 않았다.

다음 상태만 재처리할 수 있다.

MISMATCHED
RETRY_REQUIRED
RETRY_EXHAUSTED

이미 정상적으로 일치한 MATCHED 결제나 현재 처리 중인 PROCESSING 결제를 다시 대기 상태로 변경하면 중복 처리 또는 상태 충돌이 발생할 수 있기 때문이다.

서비스에서는 잘못된 상태 전이를 API 예외로 변환했다.

@Transactional
public ReconciliationRetryResponse requestRetry(Long paymentId) {
    PaymentLog payment = paymentLogRepository.findById(paymentId)
            .orElseThrow(() ->
                    new CustomException(ErrorType.PAYMENT_NOT_FOUND)
            );

    try {
        payment.requestManualReconciliation();
    } catch (IllegalStateException e) {
        throw new CustomException(
                ErrorType.INVALID_RECONCILIATION_STATUS,
                e.getMessage()
        );
    }

    metrics.recordManualRetry();

    return new ReconciliationRetryResponse(
            paymentId,
            payment.getReconciliationStatus().name()
    );
}

트랜잭션 안에서 조회한 엔티티의 상태를 변경했기 때문에 JPA의 변경 감지로 수정 내용이 DB에 반영된다.

변경 감지는 트랜잭션 안에서 조회한 엔티티의 필드가 바뀌었는지 JPA가 확인하고, 별도의 save() 호출 없이 업데이트 쿼리를 실행하는 기능이다.

7. 운영 API 보호

대사 결과에는 결제 금액, 트랜잭션 해시, 지갑 주소 등 민감한 정보가 포함될 수 있다.

또한 수동 재시도 API는 실제 시스템의 상태를 변경한다.

따라서 일반 사용자 API와 동일하게 공개해서는 안 된다.

이번에는 별도의 운영 키를 요청 헤더로 받도록 구현했다.

X-Ops-Key: 운영용 비밀 키

서버 환경변수에는 다음과 같이 운영 키를 설정한다.

OPS_API_KEY=충분히-긴-임의의-비밀키

설정 파일에서는 환경변수를 읽는다.

ops:
  api-key: ${OPS_API_KEY:}

운영 키가 설정되지 않은 경우에도 접근을 허용하지 않도록 기본 동작을 차단 방식으로 설계했다.

public void authorize(String providedOpsKey) {
    if (!StringUtils.hasText(expectedOpsKey)
            || !StringUtils.hasText(providedOpsKey)
            || !MessageDigest.isEqual(
                    expectedOpsKey.getBytes(StandardCharsets.UTF_8),
                    providedOpsKey.getBytes(StandardCharsets.UTF_8)
            )) {
        throw new CustomException(ErrorType.OPS_ACCESS_FORBIDDEN);
    }
}

문자열 비교에는 MessageDigest.isEqual()을 사용했다.

이는 비교 도중 값이 다른 위치를 기준으로 즉시 종료하는 일반 문자열 비교보다 타이밍 공격에 대한 노출을 줄이기 위한 선택이다.

타이밍 공격은 값 비교에 걸리는 시간 차이를 여러 번 측정해 비밀값을 추측하는 공격 방식이다.

운영 환경에서는 운영 키뿐만 아니라 기존 JWT 인증도 함께 적용되므로 두 인증 조건을 모두 통과해야 한다.

8. 운영 API 구성

최종적으로 다음 네 개의 API를 추가했다.

대사 상태 요약

GET /api/admin/reconciliation/summary

이상 결제 목록

GET /api/admin/reconciliation/alerts

특정 상태만 조회할 수도 있다.

GET /api/admin/reconciliation/alerts?statuses=MISMATCHED&statuses=RETRY_EXHAUSTED&page=0&size=20

결제 검증 이력

GET /api/admin/reconciliation/{paymentId}/history

수동 재시도

POST /api/admin/reconciliation/{paymentId}/retry

컨트롤러에서는 모든 요청을 처리하기 전에 운영 키를 검사한다.

@PostMapping("/{paymentId}/retry")
public ApiResponse<ReconciliationRetryResponse> retry(
        @RequestHeader(
                value = "X-Ops-Key",
                required = false
        ) String opsKey,
        @PathVariable Long paymentId
) {
    opsAuthorizer.authorize(opsKey);

    return ApiResponse.success(
            SuccessType.PROCESS_SUCCESS,
            monitoringService.requestRetry(paymentId)
    );
}

헤더를 필수로 선언하지 않은 이유는 헤더가 없을 때 Spring의 기본 400 Bad Request 대신 우리가 정의한 운영 권한 오류를 반환하기 위해서다.

9. Prometheus 메트릭 추가

API를 직접 호출하지 않아도 Grafana에서 대사 상태를 확인할 수 있도록 Prometheus 메트릭도 추가했다.

Prometheus는 서버의 상태와 처리 횟수 같은 숫자 데이터를 수집하는 모니터링 도구다.

Grafana는 Prometheus가 수집한 데이터를 그래프와 대시보드로 시각화하는 도구다.

상태별 현재 건수

tinypay_payment_reconciliation_status

상태는 태그로 구분한다.

tinypay_payment_reconciliation_status{status="MATCHED"}
tinypay_payment_reconciliation_status{status="MISMATCHED"}
tinypay_payment_reconciliation_status{status="RETRY_EXHAUSTED"}

이 값에는 게이지를 사용했다.

게이지는 현재 시점의 값을 표현하는 메트릭이다. 값이 증가하거나 감소할 수 있으므로 현재 대기 건수나 실패 건수를 나타낼 때 적합하다.

처리 결과 누적 횟수

tinypay_payment_reconciliation_results_total

tinypay_payment_reconciliation_results_total{result="MATCHED"}
tinypay_payment_reconciliation_results_total{result="MISMATCHED"}

처리 결과에는 카운터를 사용했다.

카운터는 이벤트 발생 횟수를 누적하는 메트릭으로, 일반적으로 값이 감소하지 않는다.

수동 재처리 요청 횟수

tinypay_payment_reconciliation_manual_retry_total

운영자가 수동 재시도를 요청할 때마다 값이 증가한다.

10. 배치와 메트릭 연결

대사 배치가 종료된 후 DB의 상태를 다시 집계해 게이지를 갱신하도록 했다.

public void reconcilePayments() {
    try {
        List<Long> paymentIds =
                paymentReconciliationService.claimBatch();

        if (paymentIds.isEmpty()) {
            return;
        }

        for (Long paymentId : paymentIds) {
            paymentReconciliationService.reconcileOne(paymentId);
        }
    } finally {
        metrics.refreshStatusGauges();
    }
}

finally는 정상 처리 여부와 관계없이 실행되는 영역이다.

배치 중 예외가 발생해도 메트릭 갱신을 시도하도록 finally에서 처리했다.

각 결제의 대사 결과도 별도로 기록한다.

if (result.isValid()) {
    payment.markReconciliationMatched();
    metrics.record(ReconciliationStatus.MATCHED);
} else {
    payment.markReconciliationMismatched(result.getDetail());
    metrics.record(ReconciliationStatus.MISMATCHED);
}

이를 통해 다음 두 가지 관점으로 대사 상태를 확인할 수 있다.

• 현재 실패 상태로 남아 있는 결제가 몇 건인지
• 일정 시간 동안 실패가 몇 번 발생했는지

현재 상태와 누적 발생 횟수는 서로 다른 의미이므로 두 메트릭을 분리했다.

11. 테스트

이번 작업에서는 다음 내용을 테스트했다.

운영 키 검증

• 올바른 키는 접근 허용
• 잘못된 키는 접근 거부
• 서버에 운영 키가 설정되지 않아도 접근 거부

상태 요약

• 각 대사 상태의 건수가 응답에 올바르게 포함되는지 확인
• 대사 상태가 null인 기존 데이터가 PENDING에 포함되는지 확인

수동 재시도

• MISMATCHED 결제가 PENDING으로 변경되는지 확인
• 기존 재시도 횟수가 초기화되는지 확인
• 정상 상태 결제의 잘못된 재시도 요청을 거부하는지 확인
• 수동 재시도 메트릭이 기록되는지 확인

기존 대사 서비스 테스트에도 메트릭 검증을 추가했다.

verify(metrics).record(ReconciliationStatus.MATCHED);
verify(metrics).record(ReconciliationStatus.MISMATCHED);
verify(metrics).record(ReconciliationStatus.RETRY_REQUIRED);
verify(metrics).record(ReconciliationStatus.RETRY_EXHAUSTED);

전체 테스트 결과는 다음과 같다.

BUILD SUCCESSFUL

12. 이번 작업을 통해 개선된 점

기존에는 대사 배치가 자동으로 결제를 검증하는 것까지만 가능했다.

이번 작업 이후에는 다음 흐름까지 지원할 수 있게 됐다.

자동 대사 실행
→ 상태 및 결과 메트릭 기록
→ 불일치 결제 탐지
→ 검증 이력 확인
→ 운영자의 수동 재처리
→ 다음 배치에서 재검증

특히 실패 상태를 단순히 DB에 남기는 데서 끝내지 않고 조회, 관찰, 원인 추적, 재처리까지 연결했다는 점이 중요했다.

결제 시스템에서는 정상 처리뿐만 아니라 실패를 발견하고 복구하는 운영 구조도 필요하다는 것을 배울 수 있었다.

• 멱등성 키를 이용한 중복 결제 방지
• 비관적 락을 이용한 잔액 동시성 제어
• 결제 상태 머신과 실패 단계 기록

하지만 이런 기능을 적용해도 내부 결제 기록과 블록체인의 실제 거래 결과가 항상 일치한다고 단정할 수는 없다.

예를 들어 다음과 같은 장애가 발생할 수 있다.

블록체인 결제 성공
→ 서버 응답 전에 프로세스 종료
→ 내부 DB 상태 갱신 실패

반대 상황도 생각할 수 있다.

PaymentLog에는 결제 성공으로 기록
→ 실제 블록체인 거래는 실패

따라서 결제가 끝난 뒤 내부 DB와 외부 거래 내역을 다시 비교하는 대사 작업이 필요하다.

이번 글에서는 TinyPay의 PaymentLog와 블록체인 영수증을 주기적으로 비교하는 대사 배치를 구현한 과정을 정리한다.

대사란?

대사(Reconciliation)란 내부 시스템에 저장된 거래 기록과 외부 결제 시스템의 실제 거래 내역을 비교해 불일치를 찾는 작업이다.

일반적인 결제 시스템에서는 다음 데이터를 비교할 수 있다.

내부 결제 DB
↕
카드사·은행·PG사 거래 내역

TinyPay에서는 블록체인 결제를 사용하므로 다음 두 데이터를 비교한다.

PaymentLog
↕
블록체인 트랜잭션 영수증

대사 과정에서 확인하는 항목은 다음과 같다.

• 트랜잭션이 실제로 존재하는가?
• 블록체인에서 성공한 거래인가?
• 공식 토큰 컨트랙트에서 발생한 거래인가?
• 예상한 판매자 지갑으로 전송됐는가?
• 실제 전송 금액이 결제 금액과 일치하는가?

대사가 필요한 이유

결제 처리에는 DB와 블록체인이라는 서로 다른 시스템이 참여한다.

두 시스템을 하나의 일반적인 DB 트랜잭션으로 묶을 수는 없다.

트랜잭션(Transaction)이란 여러 DB 작업을 하나의 작업 단위로 묶어 모두 성공하거나 모두 취소되도록 만드는 기능이다.

MySQL의 트랜잭션이 성공했다고 해서 블록체인 작업까지 함께 커밋되는 것은 아니다. 반대로 블록체인 거래가 성공했다고 MySQL 데이터가 자동으로 저장되는 것도 아니다.

따라서 다음과 같은 불일치가 생길 수 있다.

블록체인은 성공하고 DB는 실패한 경우

블록체인 전송 성공
→ 서버 강제 종료
→ PaymentLog 갱신 실패

DB에는 성공으로 기록했지만 외부 거래가 잘못된 경우

PaymentLog = COMPLETED
→ 실제 거래의 수신자 또는 금액 불일치

외부 시스템이 일시적으로 응답하지 않는 경우

블록체인 RPC 요청
→ 네트워크 타임아웃
→ 성공 여부를 즉시 판단할 수 없음

RPC(Remote Procedure Call)란 애플리케이션이 네트워크를 통해 외부 시스템의 기능을 호출하는 방식이다. 이번 프로젝트에서는 블록체인 노드에 거래 영수증을 요청하는 과정이 이에 해당한다.

이러한 상황을 발견하고 운영자가 확인할 수 있게 만드는 것이 대사 배치의 역할이다.

전체 대사 흐름

구현한 대사 배치는 다음 순서로 동작한다.

대사 대상 결제 조회
→ DB 락으로 대상 선점
→ PROCESSING 상태로 변경
→ 블록체인 영수증 조회
→ 거래 상태·컨트랙트·수신자·금액 검증
→ 일치하면 MATCHED
→ 불일치하면 MISMATCHED
→ RPC 오류면 RETRY_REQUIRED
→ 최대 재시도 초과 시 RETRY_EXHAUSTED

대사 상태 설계

결제 처리 상태와 대사 처리 상태는 서로 목적이 다르다.

결제 상태는 결제 업무의 진행 단계를 나타낸다.

REQUESTED
→ APPROVED
→ PAID
→ VERIFIED
→ COMPLETED

대사 상태는 해당 결제를 블록체인과 비교했는지를 나타낸다.

public enum ReconciliationStatus {
    PENDING,
    PROCESSING,
    MATCHED,
    MISMATCHED,
    RETRY_REQUIRED,
    RETRY_EXHAUSTED
}

각 상태의 의미는 다음과 같다.

불일치와 외부 오류를 구분한 것이 중요하다.

MISMATCHED
→ 블록체인 응답을 확인했고 실제 데이터가 다름

RETRY_REQUIRED
→ RPC 오류 등으로 아직 일치 여부를 판단하지 못함

외부 시스템이 잠시 응답하지 않았다는 이유만으로 결제를 불일치로 판단하면 안 된다.

PaymentLog에 대사 정보 추가

대사 상태와 실행 정보를 PaymentLog에 추가했다.

@Enumerated(EnumType.STRING)
@Column(name = "reconciliation_status")
private ReconciliationStatus reconciliationStatus;

@Column(
    name = "reconciliation_attempts",
    nullable = false
)
private int reconciliationAttempts;

@Column(name = "reconciliation_started_at")
private LocalDateTime reconciliationStartedAt;

@Column(name = "last_reconciled_at")
private LocalDateTime lastReconciledAt;

@Column(name = "next_reconciliation_at")
private LocalDateTime nextReconciliationAt;

@Column(
    name = "reconciliation_error",
    length = 1000
)
private String reconciliationError;

각 필드는 다음 목적으로 사용한다.

기존 데이터에는 대사 상태가 없기 때문에 reconciliationStatus가 null인 결제도 대기 상태로 취급한다.

대사 시작 처리

대상 결제를 선점하면 PROCESSING으로 변경한다.

public void startReconciliation() {
    if (!StringUtils.hasText(txHash)) {
        throw new IllegalStateException(
                "트랜잭션 해시가 없는 결제는 "
                        + "대사할 수 없습니다."
        );
    }

    this.reconciliationStatus =
            ReconciliationStatus.PROCESSING;

    this.reconciliationAttempts++;
    this.reconciliationStartedAt =
            LocalDateTime.now();

    this.reconciliationError = null;
}

트랜잭션 해시가 없는 결제는 블록체인에서 조회할 수 없기 때문에 대사 대상으로 선점하지 않는다.

일치 결과 기록

블록체인 거래가 내부 결제 기록과 일치하면 MATCHED로 변경한다.

public void markReconciliationMatched() {
    requireReconciliationProcessing();

    this.reconciliationStatus =
            ReconciliationStatus.MATCHED;

    this.lastReconciledAt =
            LocalDateTime.now();

    this.nextReconciliationAt = null;
    this.reconciliationError = null;
}

requireReconciliationProcessing()은 현재 상태가 PROCESSING인지 확인한다.

private void requireReconciliationProcessing() {
    if (reconciliationStatus
            != ReconciliationStatus.PROCESSING) {
        throw new IllegalStateException(
                "처리 중인 대사만 결과를 "
                        + "기록할 수 있습니다."
        );
    }
}

선점하지 않은 결제에 결과를 기록하는 실수를 방지하기 위한 검증이다.

불일치 결과 기록

거래 상태, 컨트랙트, 수신자 또는 금액이 다르면 MISMATCHED로 변경한다.

public void markReconciliationMismatched(
        String detail
) {
    requireReconciliationProcessing();

    this.reconciliationStatus =
            ReconciliationStatus.MISMATCHED;

    this.lastReconciledAt =
            LocalDateTime.now();

    this.nextReconciliationAt = null;
    this.reconciliationError = detail;
}

예를 들어 다음과 같은 내용이 저장될 수 있다.

expected=10.5, actual=5

운영자는 이 정보를 이용해 어떤 항목이 불일치했는지 확인할 수 있다.

재시도 상태 기록

RPC 타임아웃처럼 결과를 판단할 수 없는 오류는 RETRY_REQUIRED로 처리한다.

public void markReconciliationRetry(
        String detail,
        LocalDateTime nextAttemptAt
) {
    requireReconciliationProcessing();

    this.reconciliationStatus =
            ReconciliationStatus.RETRY_REQUIRED;

    this.lastReconciledAt =
            LocalDateTime.now();

    this.nextReconciliationAt =
            nextAttemptAt;

    this.reconciliationError = detail;
}

바로 다시 요청하면 장애가 발생한 외부 시스템에 부하를 더 줄 수 있기 때문에 다음 시도 가능 시각을 저장한다.

최대 재시도 초과 처리

계속 실패하는 요청을 무한히 재시도하면 시스템 자원이 낭비될 수 있다.

최대 재시도 횟수를 초과하면 RETRY_EXHAUSTED로 변경한다.

public void markReconciliationRetryExhausted(
        String detail
) {
    requireReconciliationProcessing();

    this.reconciliationStatus =
            ReconciliationStatus.RETRY_EXHAUSTED;

    this.lastReconciledAt =
            LocalDateTime.now();

    this.nextReconciliationAt = null;
    this.reconciliationError = detail;
}

RETRY_EXHAUSTED는 자동 처리 대상에서 제외하고 운영자가 확인해야 하는 상태다.

최초 검증과 대사용 검증 분리

기존 ReceiptVerifier는 결제를 처음 처리할 때 다음 검증을 수행했다.

1. Redis를 통한 영수증 재사용 확인
2. 블록체인 거래 성공 여부
3. 공식 토큰 컨트랙트 확인
4. 수신자 확인
5. 금액 확인

모든 검증을 통과하면 트랜잭션 해시를 Redis에 “사용됨”으로 등록했다.

markAsUsed(txHash);

이 구조를 대사 배치에서 그대로 사용하면 문제가 발생한다.

대사는 이미 사용된 정상 영수증을 다시 확인하는 작업이다. 따라서 Redis 재사용 검사에서 정상 거래도 재사용 공격으로 판단된다.

최초 결제 검증
→ Redis에 txHash 사용 등록

대사 배치
→ 같은 txHash 재검증
→ 이미 사용된 영수증으로 실패

이를 해결하기 위해 대사용 메서드를 별도로 추가했다.

VerificationResult verifyForReconciliation(
        String txHash,
        String expectedReceiver,
        BigInteger expectedAmount
);

대사용 검증에서는 다음 항목만 확인한다.

블록체인 거래 성공 여부
→ 공식 토큰 컨트랙트
→ 수신자
→ 결제 금액

Redis 재사용 검사와 사용 등록은 수행하지 않는다.

@Override
public VerificationResult
        verifyForReconciliation(
                String txHash,
                String expectedReceiver,
                BigInteger expectedAmount
        ) {
    return verifyOnChain(
            txHash,
            expectedReceiver,
            expectedAmount
    );
}

최초 결제 검증과 사후 대사는 목적이 다르기 때문에 같은 검증 규칙을 무조건 재사용하면 안 된다는 점을 확인할 수 있었다.

대사 대상 조회

대사 대상은 다음 조건을 만족하는 결제다.

• 트랜잭션 해시가 존재함
• 대사 가능한 결제 상태임
• 아직 대사하지 않았거나 재시도 대상임
• 다음 재시도 시각이 지났음

Repository 쿼리는 다음과 같이 구성했다.

@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("""
    SELECT p
    FROM PaymentLog p
    WHERE p.txHash IS NOT NULL
      AND p.paymentStatus
            IN :paymentStatuses
      AND (
            p.reconciliationStatus IS NULL
            OR p.reconciliationStatus
                IN :reconciliationStatuses
          )
      AND (
            p.nextReconciliationAt IS NULL
            OR p.nextReconciliationAt <= :now
          )
    ORDER BY p.id
""")
List<PaymentLog>
        findReconciliationCandidatesForUpdate(
                Collection<PaymentStatus>
                        paymentStatuses,
                Collection<ReconciliationStatus>
                        reconciliationStatuses,
                LocalDateTime now,
                Pageable pageable
        );

Pageable을 사용해 한 번에 처리할 최대 건수를 제한했다.

배치 크기의 기본값은 50건이다.

여러 서버의 중복 배치 방지

애플리케이션 서버가 여러 대라면 각 서버에서 같은 스케줄러가 동시에 실행될 수 있다.

서버 A: 결제 1 조회
서버 B: 결제 1 조회
서버 A: 결제 1 대사
서버 B: 결제 1 대사

이를 막기 위해 대사 대상 조회에 PESSIMISTIC_WRITE를 적용했다.

비관적 락(Pessimistic Lock)은 다른 작업이 같은 데이터를 수정할 가능성이 높다고 보고 조회 시점부터 DB 행을 잠그는 방식이다.

첫 번째 서버가 결제를 선점하면 같은 트랜잭션 안에서 상태를 PROCESSING으로 변경한다.

List<PaymentLog> candidates =
        paymentLogRepository
                .findReconciliationCandidatesForUpdate(
                        paymentStatuses,
                        reconciliationStatuses,
                        now,
                        PageRequest.of(0, batchSize)
                );

candidates.forEach(
        PaymentLog::startReconciliation
);

두 번째 서버는 첫 번째 서버의 트랜잭션이 끝난 뒤 해당 행을 읽는다. 이때 상태가 이미 PROCESSING이므로 대사 대상에서 제외된다.

서버 A: DB 락 획득
→ PROCESSING 변경
→ 커밋

서버 B: 락 획득 후 재확인
→ PROCESSING이므로 대상 제외

Redis 기반 분산 락을 별도로 추가하지 않고 DB 행과 상태를 이용해 작업 단위의 중복 처리를 방지했다.

중단된 PROCESSING 복구

서버가 결제를 선점한 뒤 종료되면 해당 결제가 계속 PROCESSING으로 남을 수 있다.

PENDING
→ PROCESSING
→ 서버 종료

이 상태를 그대로 두면 다시 대사되지 않는다.

이를 해결하기 위해 일정 시간 이상 PROCESSING 상태인 결제를 재시도 대상으로 복구한다.

@Modifying
@Query("""
    UPDATE PaymentLog p
       SET p.reconciliationStatus
                = :retryStatus,
           p.nextReconciliationAt
                = :now,
           p.reconciliationError
                = :error
     WHERE p.reconciliationStatus
                = :processingStatus
       AND p.reconciliationStartedAt
                < :staleBefore
""")
int resetStaleReconciliations(...);

기본 기준은 10분이다.

PROCESSING 상태로 10분 이상 유지
→ RETRY_REQUIRED로 복구
→ 다음 배치에서 다시 선점

실제 대사 처리

선점된 결제 ID를 하나씩 조회해 블록체인 영수증과 비교한다.

VerificationResult result =
        receiptVerifier
                .verifyForReconciliation(
                        payment.getTxHash(),
                        payment.getReceiverWalletAddress(),
                        rawAmount
                );

결과가 유효하면 MATCHED로 처리한다.

if (result.isValid()) {
    payment.markReconciliationMatched();
}

검증 결과가 명확한 실패라면 MISMATCHED로 처리한다.

else {
    payment.markReconciliationMismatched(
            result.getDetail()
    );
}

검증 실패 유형 매핑

블록체인 검증 결과는 실패 원인에 따라 다음 상태로 구분한다.

private TxVerificationStatus
        toVerificationStatus(
                FailReason reason
        ) {
    return switch (reason) {
        case SUCCESS ->
                TxVerificationStatus.PASSED;

        case REPLAY_ATTACK ->
                TxVerificationStatus.FAILED_REPLAY;

        case TRANSACTION_FAILED ->
                TxVerificationStatus.FAILED_TX;

        case INVALID_CONTRACT ->
                TxVerificationStatus.FAILED_CONTRACT;

        case INVALID_RECIPIENT ->
                TxVerificationStatus.FAILED_RECEIVER;

        case INSUFFICIENT_PAYMENT ->
                TxVerificationStatus.FAILED_AMOUNT;
    };
}

대사에서는 replay 검사를 수행하지 않지만 기존 검증 결과 타입과의 호환성을 위해 해당 매핑은 유지했다.

대사 이력 저장

현재 대사 상태는 PaymentLog에 저장하고, 개별 검증 결과는 TxVerificationLog에 추가한다.

txVerificationLogRepository.save(
    TxVerificationLog.builder()
        .user(payment.getUser())
        .payment(payment)
        .txHash(payment.getTxHash())
        .verificationStatus(
                toVerificationStatus(
                        result.getReason()
                )
        )
        .failedAtStep(
                result.isValid()
                        ? null
                        : result.getFailedStep()
        )
        .expectedAmount(
                payment.getAmount()
        )
        .expectedReceiver(
                payment.getReceiverWalletAddress()
        )
        .tokenAddress(tokenAddress)
        .detail(result.getDetail())
        .blockchainNetwork(
                payment.getBlockchainNetwork()
        )
        .build()
);

두 데이터를 분리한 이유는 역할이 다르기 때문이다.

PaymentLog
→ 현재 대사 상태와 재시도 정보

TxVerificationLog
→ 각 대사 실행 결과에 대한 이력

같은 결제가 여러 번 재검증되더라도 각 시도의 확정 결과를 이력으로 남길 수 있다.

RPC 오류 재시도

블록체인 노드가 응답하지 않거나 네트워크 오류가 발생하면 거래 불일치로 판단하지 않는다.

catch (Exception e) {
    String detail =
            "대사 중 외부 시스템 오류: "
                    + e.getMessage();

    // 재시도 또는 최대 횟수 초과 처리
}

최대 시도 횟수에 도달하지 않았다면 재시도를 예약한다.

Duration retryDelay =
        Duration.ofMinutes(
                retryDelayMinutes
        ).multipliedBy(
                payment.getReconciliationAttempts()
        );

payment.markReconciliationRetry(
        detail,
        LocalDateTime.now().plus(retryDelay)
);

시도 횟수에 따라 대기 시간이 늘어난다.

1번째 실패 → 5분 후 재시도
2번째 실패 → 10분 후 재시도
3번째 실패 → 15분 후 재시도

이처럼 재시도 간격을 점차 늘리는 방식을 백오프(Backoff)라고 한다.

이번 구현은 시도 횟수에 비례해 지연 시간을 늘리는 선형 백오프를 사용했다.

최대 재시도 초과

기본 최대 시도 횟수는 5회다.

if (payment.getReconciliationAttempts()
        >= maxAttempts) {
    payment.markReconciliationRetryExhausted(
            detail
    );
}

5회 이상 외부 오류가 지속되면 자동 재시도를 중단하고 운영자 확인 대상으로 남긴다.

무한 재시도로 인한 불필요한 블록체인 RPC 호출과 DB 부하를 방지할 수 있다.

스케줄러 구현

Spring의 @Scheduled를 사용해 일정 주기로 대사 배치를 실행한다.

@Scheduled(
    fixedDelayString =
        "${payment.reconciliation.fixed-delay-ms:60000}",
    initialDelayString =
        "${payment.reconciliation.initial-delay-ms:30000}"
)
public void reconcilePayments() {
    List<Long> paymentIds =
            paymentReconciliationService
                    .claimBatch();

    for (Long paymentId : paymentIds) {
        paymentReconciliationService
                .reconcileOne(paymentId);
    }
}

fixedDelay는 이전 작업이 끝난 시점부터 다음 실행까지 기다리는 시간이다.

기본 실행 간격은 60초이며 애플리케이션 시작 후 30초 뒤 처음 실행된다.

운영 환경에서만 명시적으로 활성화

배치가 개발이나 테스트 환경에서 의도치 않게 실행되지 않도록 조건부로 등록했다.

@ConditionalOnProperty(
    name = "payment.reconciliation.enabled",
    havingValue = "true"
)
public class PaymentReconciliationScheduler {
}

기본값은 비활성화다.

payment:
  reconciliation:
    enabled: ${PAYMENT_RECONCILIATION_ENABLED:false}

운영 환경에서는 다음 환경변수로 활성화할 수 있다.

PAYMENT_RECONCILIATION_ENABLED=true

추가 설정값도 환경변수로 변경할 수 있다.

PAYMENT_RECONCILIATION_FIXED_DELAY_MS=60000
PAYMENT_RECONCILIATION_INITIAL_DELAY_MS=30000
PAYMENT_RECONCILIATION_BATCH_SIZE=50
PAYMENT_RECONCILIATION_RETRY_DELAY_MINUTES=5
PAYMENT_RECONCILIATION_STALE_AFTER_MINUTES=10
PAYMENT_RECONCILIATION_MAX_ATTEMPTS=5

단위 테스트

대사 서비스에서 다음 상황을 검증했다.

대상 선점

PENDING
→ claimBatch()
→ PROCESSING
→ attempts 증가

assertThat(
    payment.getReconciliationStatus()
).isEqualTo(
    ReconciliationStatus.PROCESSING
);

assertThat(
    payment.getReconciliationAttempts()
).isEqualTo(1);

온체인 거래 일치

when(receiptVerifier
        .verifyForReconciliation(...))
        .thenReturn(
                VerificationResult.success()
        );

결과를 검증했다.

assertThat(
    payment.getReconciliationStatus()
).isEqualTo(
    ReconciliationStatus.MATCHED
);

결제 금액 불일치

VerificationResult.fail(
    FailReason.INSUFFICIENT_PAYMENT,
    "expected=10.5, actual=5"
);

결과는 MISMATCHED로 저장된다.

assertThat(
    payment.getReconciliationStatus()
).isEqualTo(
    ReconciliationStatus.MISMATCHED
);

RPC 오류

thenThrow(
    new RuntimeException("RPC timeout")
);

결과는 RETRY_REQUIRED가 되고 다음 실행 시각이 저장된다.

최대 재시도 초과

최대 횟수에 도달한 상태에서 RPC 오류가 발생하면 RETRY_EXHAUSTED가 되는지 확인했다.

테스트 결과

전체 단위 테스트와 실제 MySQL 통합 테스트를 실행했다.

전체 단위 테스트: BUILD SUCCESSFUL
MySQL 통합 테스트: BUILD SUCCESSFUL

통합 테스트에서는 변경된 엔티티 스키마와 Repository 쿼리가 실제 MySQL에서 정상적으로 생성되는 것도 확인했다.

자동 보정을 하지 않은 이유

대사 결과가 MISMATCHED라고 해서 지갑 잔액이나 결제 상태를 즉시 자동 변경하지 않았다.

금전 데이터의 자동 보정은 잘못 수행될 경우 새로운 장애를 만들 수 있기 때문이다.

예를 들어 블록체인 조회가 잘못된 네트워크나 잘못된 노드를 바라보고 있다면 실제 정상 결제를 취소하는 문제가 발생할 수 있다.

현재 구현은 다음 범위에 집중한다.

불일치 탐지
→ 실패 원인 기록
→ 재시도
→ 운영자 확인 대상 분리

불일치가 확인된 결제는 운영자가 온체인 거래와 내부 로그를 확인한 뒤 별도의 복구 작업을 실행하는 것이 안전하다.

자동 복구를 도입하려면 다음 조건이 추가로 필요하다.

• 보정 작업 자체의 멱등성
• 보정 전 이중 검증
• 관리자 승인
• 원장 형태의 잔액 변경 이력
• 보정 작업 감사 로그
• 잘못된 보정을 취소하는 역거래

현재 구현의 한계

현재 VerificationResult는 실패 단계와 상세 문자열을 제공하지만 실제 온체인 수신자와 금액을 구조화된 필드로 반환하지 않는다.

따라서 TxVerificationLog의 다음 필드는 아직 완전히 채우지 못한다.

actualReceiver
actualAmount

현재는 다음 정보를 저장한다.

• 예상 수신자
• 예상 금액
• 실패 단계
• 실패 원인
• 상세 메시지
• 토큰 주소
• 블록체인 네트워크

향후 VerificationResult에 실제 온체인 값을 추가하면 예상값과 실제값을 데이터 컬럼으로 직접 비교할 수 있다.

마무리

이번 작업에서는 내부 결제 기록과 블록체인 거래 내역을 주기적으로 비교하는 대사 배치를 구현했다.

주요 개선 내용은 다음과 같다.

• PaymentLog와 블록체인 영수증 비교
• 거래 상태·공식 컨트랙트·수신자·금액 검증
• 최초 결제 검증과 대사용 재검증 분리
• PENDING → PROCESSING → MATCHED/MISMATCHED 상태 관리
• RPC 오류 재시도와 선형 백오프
• 최대 재시도 초과 시 수동 확인 대상으로 분리
• DB 비관적 락 기반 중복 배치 방지
• 중단된 PROCESSING 작업 자동 복구
• TxVerificationLog를 통한 대사 이력 저장
• 환경변수를 이용한 배치 활성화 및 설정 관리
• 단위 테스트와 MySQL 통합 테스트

결제 시스템에서는 요청 시점의 정상 처리만큼 사후 검증도 중요하다.

멱등성과 동시성 제어는 결제 과정에서 발생할 수 있는 문제를 줄이고, 상태 머신은 처리 단계를 표현한다. 대사 배치는 그 이후에도 내부 기록과 실제 외부 거래가 일치하는지 지속적으로 확인하는 안전망 역할을 한다.

public enum PaymentStatus {
    PENDING,
    SUCCESS,
    FAILED,
    CANCELLED
}

이 구조는 결제가 성공했는지 실패했는지는 알려주지만, 결제가 어떤 단계를 거쳤고 어느 단계에서 실패했는지는 표현하기 어렵다.

블록체인 결제를 예로 들면 실제 처리 과정에는 여러 단계가 존재한다.

결제 요청 생성
→ 사용자 승인
→ 블록체인 전송
→ 블록체인 영수증 검증
→ 잔액 반영
→ 결제 완료

그런데 모든 성공을 SUCCESS, 모든 실패를 FAILED로만 저장하면 다음 질문에 답하기 어렵다.

• 사용자의 결제 승인은 완료됐는가?
• 블록체인 전송 자체가 실패했는가?
• 전송은 성공했지만 영수증 검증에서 실패했는가?
• 트랜잭션 해시는 발급됐는가?
• 어느 단계까지 재처리해야 하는가?

이 문제를 해결하기 위해 결제 흐름을 상태 머신으로 개선했다.

상태 머신이란?

상태 머신(State Machine)이란 시스템이 가질 수 있는 상태와 상태가 변경될 수 있는 규칙을 명확하게 정의하는 방식이다.

예를 들어 결제가 다음 순서로만 진행되어야 한다고 가정한다.

REQUESTED
→ APPROVED
→ PAID
→ VERIFIED
→ COMPLETED

현재 상태가 REQUESTED라면 다음 상태는 반드시 APPROVED여야 한다.

REQUESTED에서 바로 PAID나 COMPLETED로 변경되는 것은 허용하지 않는다.

REQUESTED → APPROVED   허용
REQUESTED → PAID       거부
REQUESTED → COMPLETED  거부

상태 머신을 사용하면 결제 처리 순서를 코드로 강제할 수 있고, 잘못된 상태 변경을 조기에 발견할 수 있다.

기존 구조의 문제

기존 결제 로직은 블록체인 전송과 영수증 검증이 모두 끝난 뒤 PaymentLog를 생성했다.

PaymentLog paymentLog = PaymentLog.builder()
        .txHash(txHash)
        .paymentStatus(PaymentStatus.SUCCESS)
        .verificationStatus(VerificationStatus.PENDING)
        .build();

이 방식에서는 성공한 결제의 최종 결과만 남는다.

실패하면 별도의 실패 로그를 저장했지만, 상태가 모두 FAILED로 동일했다.

.paymentStatus(PaymentStatus.FAILED)
.verificationStatus(VerificationStatus.FAILED)

따라서 블록체인 전송 전에 실패한 것인지, 전송 후 검증 단계에서 실패한 것인지 구분하기 어려웠다.

결제 상태 세분화

결제 상태를 다음과 같이 변경했다.

public enum PaymentStatus {
    REQUESTED,
    APPROVED,
    PAID,
    VERIFIED,
    COMPLETED,
    FAILED
}

각 상태는 다음 의미를 가진다.

정상적인 결제는 다음 순서로 진행된다.

REQUESTED
→ APPROVED
→ PAID
→ VERIFIED
→ COMPLETED

처리 중 오류가 발생하면 각 단계에서 FAILED로 전환될 수 있다.

REQUESTED → FAILED
APPROVED  → FAILED
PAID      → FAILED
VERIFIED  → FAILED

상태 변경을 엔티티 내부로 제한

서비스 코드가 다음처럼 상태값을 직접 변경하도록 두면 잘못된 상태 전이가 발생하기 쉽다.

paymentLog.setPaymentStatus(
        PaymentStatus.COMPLETED
);

그래서 상태 필드의 setter를 제공하지 않고, PaymentLog의 도메인 메서드로만 상태를 변경하도록 했다.

도메인 메서드란 단순히 값을 저장하는 setter가 아니라 객체가 수행하는 업무 행위를 표현하는 메서드다.

paymentLog.approve();
paymentLog.markPaid(txHash);
paymentLog.markVerified();
paymentLog.complete();

호출 코드만 보더라도 결제가 어떤 단계로 진행되는지 알 수 있다.

공통 상태 전이 검증

상태 변경 전 현재 상태가 올바른지 검사하는 공통 메서드를 추가했다.

private void transition(
        PaymentStatus expected,
        PaymentStatus next
) {
    if (paymentStatus != expected) {
        throw new IllegalStateException(
                "허용되지 않은 결제 상태 전이입니다: "
                        + paymentStatus
                        + " -> "
                        + next
        );
    }

    this.paymentStatus = next;
}

expected는 현재 상태로 기대하는 값이고, next는 변경하려는 다음 상태다.

예를 들어 결제를 승인하는 메서드는 REQUESTED 상태에서만 호출할 수 있다.

public void approve() {
    transition(
            PaymentStatus.REQUESTED,
            PaymentStatus.APPROVED
    );

    this.approvedAt = LocalDateTime.now();
}

이미 승인된 결제에서 approve()를 다시 호출하면 다음 전이가 발생한다.

APPROVED → APPROVED

이는 허용된 상태 전이가 아니므로 예외가 발생한다.

REQUESTED에서 APPROVED로 전환

결제 요청이 생성되면 기본 상태는 REQUESTED다.

this.paymentStatus =
        paymentStatus == null
                ? PaymentStatus.REQUESTED
                : paymentStatus;

사용자 확인, 비밀번호, 예산 및 잔액 검증을 통과하면 APPROVED로 변경한다.

paymentLog.approve();

이때 승인 시각도 함께 기록한다.

private LocalDateTime approvedAt;

APPROVED에서 PAID로 전환

블록체인 전송이 성공해 트랜잭션 해시를 확보하면 PAID로 변경한다.

트랜잭션 해시(Transaction Hash)는 블록체인에 등록된 거래를 식별하는 고유한 값이다.

public void markPaid(String txHash) {
    if (!StringUtils.hasText(txHash)) {
        throw new IllegalArgumentException(
                "결제 트랜잭션 해시가 필요합니다."
        );
    }

    transition(
            PaymentStatus.APPROVED,
            PaymentStatus.PAID
    );

    this.txHash = txHash;
    this.paidAt = LocalDateTime.now();
}

트랜잭션 해시가 비어 있으면 PAID 상태로 전환할 수 없다.

즉, PAID 상태는 단순히 “결제를 시도했다”는 뜻이 아니라 블록체인 전송 결과를 식별할 수 있는 상태라는 의미를 갖는다.

PAID에서 VERIFIED로 전환

블록체인 전송이 성공했다고 해서 바로 최종 결제 성공으로 처리하면 안 된다.

다음 내용도 검증해야 한다.

• 정상적인 컨트랙트를 통해 실행됐는가?
• 실제 수신자가 기대한 판매자 지갑인가?
• 전송 금액이 예상 금액과 일치하는가?
• 같은 거래가 재사용되지 않았는가?

영수증 검증을 통과하면 VERIFIED로 변경한다.

public void markVerified() {
    transition(
            PaymentStatus.PAID,
            PaymentStatus.VERIFIED
    );

    this.verificationStatus =
            VerificationStatus.SUCCESS;

    this.verifiedAt = LocalDateTime.now();
}

검증 시각과 별도의 검증 상태도 함께 기록한다.

영수증 검증 결과 누락 문제 발견

상태 머신을 적용하며 기존 코드를 검토하던 중 추가 문제를 발견했다.

verifyReceipt()의 반환형은 boolean이었지만 기존 코드에서는 결과값을 사용하지 않고 있었다.

blockchainService.verifyReceipt(
        txHash,
        receiverWalletAddress,
        rawAmount
);

검증 메서드가 false를 반환해도 예외가 발생하지 않으면 결제가 성공으로 처리될 가능성이 있었다.

이를 다음과 같이 수정했다.

boolean receiptVerified =
        blockchainService.verifyReceipt(
                txHash,
                receiverWalletAddress,
                rawAmount
        );

if (!receiptVerified) {
    throw new IllegalStateException(
            "블록체인 영수증 검증에 실패했습니다."
    );
}

검증 결과가 false이면 결제를 VERIFIED로 변경하지 않는다.

이 시점에서 결제는 이미 블록체인 전송을 완료했으므로 현재 상태는 PAID다. 이후 실패 처리에서는 다음과 같이 기록된다.

PAID → FAILED
failedFromStatus = PAID

VERIFIED에서 COMPLETED로 전환

영수증 검증까지 통과하면 지갑 잔액을 차감한다.

wallet.withdraw(estimatedCost);

잔액 반영까지 성공하면 결제 상태를 COMPLETED로 변경한다.

public void complete() {
    transition(
            PaymentStatus.VERIFIED,
            PaymentStatus.COMPLETED
    );

    this.completedAt = LocalDateTime.now();
}

COMPLETED는 모든 결제 처리가 정상적으로 끝났다는 최종 상태다.

실패 단계와 원인 기록

단순히 FAILED만 저장하면 어느 단계에서 실패했는지 알 수 없다.

그래서 다음 정보를 추가했다.

private PaymentStatus failedFromStatus;
private String failureReason;
private LocalDateTime failedAt;

실패 처리 메서드는 현재 상태를 failedFromStatus에 저장한 뒤 최종 상태를 FAILED로 변경한다.

public void fail(String reason) {
    if (paymentStatus.isSuccessful()
            || paymentStatus == PaymentStatus.FAILED) {
        throw new IllegalStateException(
                "완료되거나 실패한 결제는 "
                        + "실패 상태로 변경할 수 없습니다."
        );
    }

    this.failedFromStatus = this.paymentStatus;
    this.paymentStatus = PaymentStatus.FAILED;

    this.failureReason =
            StringUtils.hasText(reason)
                    ? reason
                    : "알 수 없는 결제 실패";

    this.failedAt = LocalDateTime.now();
    this.verificationStatus =
            VerificationStatus.FAILED;
}

예를 들어 블록체인 전송 자체가 실패하면 다음과 같이 저장된다.

paymentStatus = FAILED
failedFromStatus = APPROVED
failureReason = 블록체인 결제 실패

블록체인 전송은 성공했지만 영수증 검증에서 실패하면 다음과 같다.

paymentStatus = FAILED
failedFromStatus = PAID
failureReason = 블록체인 영수증 검증 실패

같은 FAILED 상태라도 실패 위치를 구분할 수 있다.

종결 상태 보호

COMPLETED와 FAILED는 더 이상 변경할 수 없는 종결 상태로 처리했다.

종결 상태(Terminal State)는 업무 흐름이 끝난 상태로, 일반적인 상태 전이를 더 이상 허용하지 않는 상태다.

완료된 결제를 뒤늦게 실패로 변경하거나 실패한 결제를 바로 완료로 바꾸면 결제 데이터의 신뢰성이 깨질 수 있다.

if (paymentStatus.isSuccessful()
        || paymentStatus == PaymentStatus.FAILED) {
    throw new IllegalStateException(...);
}

재처리가 필요하다면 기존 상태를 임의로 바꾸는 대신 별도의 재처리 흐름을 만들어야 한다.

결제 서비스 흐름 변경

결제 승인 서비스에서는 블록체인 호출이 끝난 뒤 성공 로그를 한 번에 만드는 대신 먼저 REQUESTED 상태의 결제 기록을 생성한다.

PaymentLog paymentLog =
        PaymentLog.builder()
                .user(aiRequest.getUser())
                .request(aiRequest)
                .wallet(wallet)
                .orderId(orderId)
                .payerWalletAddress(
                        wallet.getWalletAddress()
                )
                .receiverWalletAddress(
                        receiverWalletAddress
                )
                .amount(estimatedCost)
                .executedAt(executedAt)
                .blockchainNetwork(
                        wallet.getBlockchainNetwork()
                )
                .build();

paymentLogRepository.save(paymentLog);

이후 처리 단계에 맞춰 상태를 변경한다.

paymentLog.approve();

String txHash =
        blockchainService.transferUsdc(...);

paymentLog.markPaid(txHash);

boolean receiptVerified =
        blockchainService.verifyReceipt(...);

if (!receiptVerified) {
    throw new IllegalStateException(
            "블록체인 영수증 검증에 실패했습니다."
    );
}

paymentLog.markVerified();

wallet.withdraw(estimatedCost);

paymentLog.complete();

코드 흐름과 상태 전이가 일치하기 때문에 현재 결제가 어떤 단계인지 이해하기 쉬워졌다.

실패 상태를 롤백하지 않도록 처리

트랜잭션 안에서 예외가 발생하면 일반적으로 DB 변경사항이 롤백된다.

롤백(Rollback)이란 트랜잭션 도중 적용한 DB 변경을 모두 취소하고 시작 전 상태로 되돌리는 것이다.

하지만 결제 실패 기록까지 롤백되면 어떤 단계에서 실패했는지 남지 않는다.

블록체인 처리 중 발생한 예외를 FAILED로 기록한 뒤 CustomException을 반환할 수 있도록 결제 트랜잭션에 다음 정책을 적용했다.

@Transactional(
    noRollbackFor = CustomException.class
)
public PaymentApproveResponse paymentApprove(...) {
    // 결제 처리
}

블록체인 처리에서 오류가 발생하면 다음과 같이 실패 상태를 기록한다.

String failureReason =
        "블록체인 결제 실패: "
                + e.getMessage();

paymentLog.fail(failureReason);
aiRequest.fail(failureReason);

throw new CustomException(
        ErrorType.INTERNAL_SERVER_ERROR
);

클라이언트에는 오류 응답을 보내지만 PaymentLog의 실패 단계와 원인은 DB에 남는다.

단, noRollbackFor를 넓게 사용하면 의도하지 않은 변경까지 커밋될 수 있으므로 주의해야 한다. 이번 로직에서는 결제 데이터 변경 전 발생하는 검증 예외와 블록체인 처리 후 기록해야 하는 실패 예외의 범위를 확인하고 적용했다.

장기적으로는 실패 기록 전용 트랜잭션이나 결제 오케스트레이션 분리를 통해 경계를 더 명확히 만드는 것이 좋다.

기존 SUCCESS 데이터 호환

상태 머신 도입 전 결제 데이터는 성공 상태를 SUCCESS로 저장하고 있었다.

이를 enum에서 바로 제거하면 기존 DB의 SUCCESS 값을 Java enum으로 변환하지 못해 조회 오류가 발생할 수 있다.

그래서 SUCCESS를 레거시 호환 상태로 남겼다.

레거시(Legacy)란 현재는 새로운 방식으로 대체됐지만 기존 데이터나 기능과의 호환을 위해 유지하는 이전 방식을 의미한다.

@Deprecated
SUCCESS;

@Deprecated는 신규 코드에서 사용하지 않도록 표시하는 Java 애너테이션이다.

신규 결제에서는 COMPLETED만 사용하지만 기존 SUCCESS도 성공한 결제로 인식한다.

public boolean isSuccessful() {
    return this == COMPLETED
            || this == SUCCESS;
}

성공 상태 목록도 제공한다.

public static Set<PaymentStatus>
        successfulStatuses() {
    return Set.of(
            COMPLETED,
            SUCCESS
    );
}

결제 내역과 월 사용액 집계에서는 두 상태를 모두 포함한다.

paymentLogRepository
        .sumSuccessfulAmountThisMonth(
                userId,
                PaymentStatus.successfulStatuses()
        );

이렇게 하면 기존 데이터를 즉시 마이그레이션하지 않아도 조회 기능이 깨지지 않는다.

추후 데이터 마이그레이션을 수행해 모든 SUCCESS를 COMPLETED로 변경한 뒤 레거시 enum을 제거할 수 있다.

Repository 쿼리 변경

기존 통계 쿼리는 하나의 성공 상태만 전달받았다.

AND p.paymentStatus = :status

이제 레거시 SUCCESS와 신규 COMPLETED를 함께 조회해야 하므로 IN 조건으로 변경했다.

AND p.paymentStatus IN :statuses

메서드도 여러 상태를 받을 수 있도록 변경했다.

BigDecimal sumSuccessfulAmountThisMonth(
        Long userId,
        Collection<PaymentStatus> statuses
);

최근 결제 내역, 월 결제 횟수 및 평균 결제 금액 조회에도 같은 기준을 적용했다.

상태 머신 단위 테스트

상태 머신은 정상적인 흐름뿐 아니라 잘못된 상태 전이를 차단하는지도 중요하다.

정상 상태 전이

payment.approve();
payment.markPaid("0x-transaction");
payment.markVerified();
payment.complete();

assertThat(payment.getPaymentStatus())
        .isEqualTo(
                PaymentStatus.COMPLETED
        );

다음 정보도 함께 검증했다.

• 트랜잭션 해시 저장
• 검증 상태 SUCCESS
• 승인 시각
• 결제 시각
• 검증 시각
• 완료 시각

잘못된 상태 전이 차단

REQUESTED 상태에서 바로 PAID로 변경하는 상황을 검증했다.

assertThatThrownBy(() ->
        payment.markPaid("0x-transaction")
).isInstanceOf(
        IllegalStateException.class
);

실패 단계 기록

블록체인 결제까지 완료된 뒤 영수증 검증에서 실패한 상황을 구성했다.

payment.approve();
payment.markPaid("0x-transaction");

payment.fail("영수증 검증 실패");

검증 내용은 다음과 같다.

assertThat(payment.getPaymentStatus())
        .isEqualTo(PaymentStatus.FAILED);

assertThat(payment.getFailedFromStatus())
        .isEqualTo(PaymentStatus.PAID);

assertThat(payment.getFailureReason())
        .isEqualTo("영수증 검증 실패");

종결 상태 변경 차단

완료된 결제를 다시 완료하거나 실패로 변경할 수 없는지 검증했다.

assertThatThrownBy(() ->
        payment.fail("뒤늦은 실패")
).isInstanceOf(
        IllegalStateException.class
);

assertThatThrownBy(payment::complete)
        .isInstanceOf(
                IllegalStateException.class
        );

테스트 결과

상태 머신 단위 테스트와 실제 MySQL 기반 통합 테스트를 실행했다.

전체 단위 테스트: BUILD SUCCESSFUL
MySQL 통합 테스트: BUILD SUCCESSFUL

MySQL 통합 테스트를 통해 변경된 엔티티 필드와 Repository 쿼리도 정상적으로 생성되는 것을 확인했다.

현재 구조의 한계

현재 상태 전이는 하나의 결제 트랜잭션 안에서 실행된다.

정상 완료되거나 코드에서 처리한 실패는 단계와 원인이 기록된다. 하지만 프로세스가 갑자기 종료되는 상황에는 한계가 있다.

예를 들어 다음 시점에 서버가 종료될 수 있다.

블록체인 전송 성공
→ 서버 강제 종료
→ PAID 상태 DB 커밋 전

블록체인에서는 결제가 성공했지만 DB 트랜잭션은 롤백될 수 있다.

이 경우 멱등성 기록은 PROCESSING으로 남고 PaymentLog에는 PAID 상태가 남지 않을 수 있다.

이를 해결하려면 다음 단계로 대사 작업이 필요하다.

대사(Reconciliation)란 내부 DB 기록과 블록체인 또는 외부 결제 시스템의 실제 거래 내역을 비교해 불일치를 탐지하고 상태를 복구하는 작업이다.

오래된 PROCESSING 요청 조회
→ 블록체인 거래 내역 조회
→ 실제 결제 성공 여부 확인
→ PaymentLog 상태 복구
→ COMPLETED 또는 FAILED 판정

즉, 상태 머신은 처리 단계와 전이 규칙을 제공하고, 대사 작업은 장애로 인해 중단된 상태를 실제 외부 거래와 비교해 복구하는 역할을 한다.

마무리

이번 작업에서는 단순했던 결제 상태를 단계별 상태 머신으로 개선했다.

주요 개선 내용은 다음과 같다.

• REQUESTED → APPROVED → PAID → VERIFIED → COMPLETED 흐름 정의
• 각 처리 단계에서 FAILED 전환 지원
• 엔티티 메서드로만 상태 변경
• 허용되지 않은 상태 전이 차단
• 단계별 처리 시각 기록
• 실패 직전 상태와 실패 원인 기록
• 블록체인 영수증 boolean 결과 검증
• 완료·실패 상태를 종결 상태로 보호
• 기존 SUCCESS 데이터와 호환
• 단위 테스트로 정상·비정상 상태 전이 검증

기존에는 결제 결과가 SUCCESS인지 FAILED인지만 알 수 있었다.

상태 머신을 적용한 뒤에는 결제가 어느 단계까지 진행됐고, 어디에서 실패했으며, 어떤 정보가 확보됐는지를 코드와 데이터로 표현할 수 있게 됐다.

다음 작업에서는 이 상태 정보를 바탕으로 내부 결제 기록과 블록체인 거래 내역을 비교하는 대사 배치를 구현할 예정이다.

앞선 작업에서는 멱등성 키를 적용해 동일한 결제 요청이 반복 실행되는 문제를 방지했다.

하지만 멱등성만으로 모든 동시성 문제가 해결되는 것은 아니다.

예를 들어 한 사용자의 지갑 잔액이 100일 때 서로 다른 80원짜리 결제 두 건이 동시에 들어올 수 있다.

현재 잔액: 100

결제 A: 80
결제 B: 80

결제 A와 B는 서로 다른 요청이고 멱등성 키도 다르다. 따라서 멱등성 검사를 모두 정상적으로 통과한다.

두 요청이 동시에 잔액을 조회하면 다음 문제가 발생할 수 있다.

결제 A: 잔액 조회 → 100
결제 B: 잔액 조회 → 100

결제 A: 100 >= 80 → 결제 가능
결제 B: 100 >= 80 → 결제 가능

실제로 사용할 수 있는 잔액은 100인데 총 160의 결제가 승인될 수 있는 것이다.

이를 해결하기 위해 결제와 지갑 충전 과정에 비관적 락을 적용했다.

동시성 문제란?

동시성 문제란 여러 요청이 같은 데이터를 동시에 읽거나 수정하면서 의도하지 않은 결과가 발생하는 문제다.

이번 결제 시스템에서는 다음 데이터가 대상이었다.

• 지갑 잔액
• 월 결제 사용액
• AI 요청 상태
• 충전 후 잔액

대표적인 문제는 잔액 초과 사용과 lost update다.

Lost update란 두 작업이 같은 값을 읽고 각각 수정한 뒤, 마지막 저장이 앞선 변경을 덮어쓰는 현상이다.

예를 들어 잔액이 100인 상황에서 결제와 충전이 동시에 실행될 수 있다.

결제 요청: 100을 읽고 30을 차감해 70 저장
충전 요청: 100을 읽고 20을 더해 120 저장

정상적인 최종 잔액은 90이어야 한다.

하지만 충전 요청이 마지막에 120을 저장하면 결제의 30 차감이 사라진다. 반대로 결제가 마지막에 저장되면 충전 내역이 사라진다.

기존 코드의 문제

기존 결제 로직은 지갑을 일반 조회한 뒤 잔액을 확인했다.

Wallet wallet = walletRepository.findByUser_Id(userId)
        .orElseThrow(() ->
                new CustomException(
                        ErrorType.WALLET_NOT_FOUND
                )
        );

if (wallet.getBalance().compareTo(estimatedCost) < 0) {
    throw new CustomException(
            ErrorType.INSUFFICIENT_BALANCE
    );
}

그다음 기존 잔액에서 결제 금액을 차감했다.

wallet.updateBalance(
        wallet.getBalance().subtract(estimatedCost)
);

하나의 요청만 실행될 때는 정상적으로 동작한다.

하지만 두 요청이 동시에 같은 지갑을 조회하면 둘 다 변경 전 잔액을 읽을 수 있다.

요청 A: 잔액 100 조회
요청 B: 잔액 100 조회
요청 A: 80 차감
요청 B: 80 차감

단순히 @Transactional을 사용한다고 이 문제가 자동으로 해결되지는 않는다.

트랜잭션은 여러 DB 작업을 하나의 단위로 묶어 성공하거나 실패하도록 만드는 기능이다. 하지만 서로 다른 트랜잭션이 같은 데이터를 동시에 읽는 것까지 항상 막아주지는 않는다.

비관적 락을 선택한 이유

비관적 락(Pessimistic Lock)은 여러 요청이 같은 데이터를 수정할 가능성이 높다고 가정하고, 데이터를 조회하는 시점부터 다른 요청의 수정을 막는 방식이다.

첫 번째 요청이 지갑 행에 락을 획득하면 두 번째 요청은 첫 번째 요청의 트랜잭션이 끝날 때까지 기다린다.

결제 A: 지갑 락 획득
결제 B: 같은 지갑 락 대기

결제 A: 잔액 확인 및 차감
결제 A: 트랜잭션 커밋
결제 A: 락 해제

결제 B: 지갑 락 획득
결제 B: 변경된 잔액 확인

앞선 예시에서는 결제 A가 80을 차감한 뒤 결제 B는 잔액 20을 읽게 된다.

결제 A: 잔액 100 → 80 결제 → 잔액 20
결제 B: 잔액 20 → 80 결제 불가능

결제처럼 잔액 정합성이 중요하고 충돌 시 재실행 비용이 큰 작업에서는 비관적 락이 비교적 명확한 선택이 될 수 있다.

낙관적 락을 사용하지 않은 이유

낙관적 락(Optimistic Lock)은 충돌이 자주 발생하지 않는다고 가정하고, 데이터를 먼저 처리한 뒤 저장 시점에 버전을 비교하는 방식이다.

JPA에서는 일반적으로 엔티티에 @Version을 추가해 사용한다.

@Version
private Long version;

두 요청이 같은 버전을 읽었다면 먼저 저장한 요청만 성공하고 나중에 저장한 요청은 충돌 예외를 받는다.

일반적인 데이터 수정이라면 실패한 요청을 다시 실행할 수 있다. 하지만 현재 결제 로직에는 DB 저장 전에 블록체인 전송이라는 외부 작업이 포함되어 있다.

요청 A: 블록체인 결제 성공
요청 B: 블록체인 결제 성공
요청 A: DB 저장 성공
요청 B: 낙관적 락 충돌

DB에서는 한 요청만 성공했지만 블록체인 결제는 이미 두 번 실행됐을 수 있다.

외부 결제 실행 후 DB 충돌을 감지하는 방식은 중복 결제를 방지하기에 충분하지 않았다. 그래서 결제 전에 다른 요청을 대기시키는 비관적 락을 선택했다.

지갑 조회에 비관적 락 적용

WalletRepository에 락 조회 메서드를 추가했다.

@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("""
    SELECT w
    FROM Wallet w
    WHERE w.id = :walletId
""")
Optional<Wallet> findByIdWithLock(
        @Param("walletId") Long walletId
);

사용자 ID로 지갑을 조회하는 메서드에도 같은 락을 적용했다.

@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("""
    SELECT w
    FROM Wallet w
    WHERE w.user.id = :userId
""")
Optional<Wallet> findByUserIdWithLock(
        @Param("userId") Long userId
);

PESSIMISTIC_WRITE는 해당 데이터를 수정할 목적으로 조회하며, 현재 트랜잭션이 끝날 때까지 다른 트랜잭션의 쓰기 목적 접근을 대기시키는 락 모드다.

MySQL에서는 일반적으로 SELECT ... FOR UPDATE 형태의 행 단위 잠금으로 동작한다.

행 단위 잠금이란 테이블 전체가 아니라 조회한 특정 행만 잠그는 방식이다. 사용자 A의 지갑을 잠가도 사용자 B의 지갑 결제는 계속 처리할 수 있다.

결제 승인에서 지갑 락 사용

기존의 일반 지갑 조회를 락 조회로 변경했다.

Wallet wallet =
        walletRepository.findByUserIdWithLock(userId)
                .orElseThrow(() ->
                        new CustomException(
                                ErrorType.WALLET_NOT_FOUND
                        )
                );

이제 같은 사용자의 결제 요청은 지갑 행을 기준으로 순서대로 실행된다.

사용자 A 결제 1 → 사용자 A 지갑 락 획득
사용자 A 결제 2 → 사용자 A 지갑 락 대기
사용자 B 결제 1 → 사용자 B 지갑이므로 실행 가능

모든 사용자의 결제가 하나씩 실행되는 것이 아니라 같은 지갑을 사용하는 요청끼리만 순서가 보장된다.

월 예산 초과도 함께 방지

기존 결제 로직은 이번 달 성공 결제 금액을 합산한 뒤 새로운 결제 금액을 더해 월 한도를 검사한다.

BigDecimal monthlySpent =
        paymentLogRepository
                .sumSuccessfulAmountThisMonth(
                        userId,
                        PaymentStatus.SUCCESS
                );

if (monthlySpent.add(estimatedCost)
        .compareTo(policy.getMonthlyLimit()) > 0) {
    throw new CustomException(
            ErrorType.MONTHLY_LIMIT_EXCEEDED
    );
}

락이 없다면 두 요청이 같은 월 사용액을 조회할 수 있다.

월 한도: 100
현재 사용액: 40

결제 A: 40 조회 + 50 → 90, 승인
결제 B: 40 조회 + 50 → 90, 승인
실제 사용액: 140

지갑 락을 획득한 뒤 월 사용액을 조회하도록 하면 동일 사용자의 결제 요청이 순서대로 검사를 수행한다.

결제 A: 월 사용액 40 → 50 결제 → 사용액 90
결제 B: 월 사용액 90 → 50 추가 시 140 → 거절

지갑은 사용자별 결제의 공통 자원이므로 지갑 락을 동일 사용자의 결제 직렬화 기준으로 사용했다.

직렬화란 동시에 들어온 작업을 실제로는 하나씩 순서대로 실행되도록 만드는 것을 의미한다.

동일 AI 요청에도 락 적용

멱등성 키가 있다고 해서 클라이언트가 항상 올바른 키를 사용한다는 보장은 없다.

같은 AI 요청에 서로 다른 멱등성 키를 사용하면 멱등성 레코드만으로는 서로 다른 결제로 인식될 수 있다.

이를 막기 위해 AiRequest 조회에도 비관적 락을 적용했다.

기존 Repository에는 다음 메서드가 이미 존재했다.

@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("""
    SELECT r
    FROM AiRequest r
    WHERE r.id = :id
""")
Optional<AiRequest> findByIdWithLock(
        @Param("id") Long id
);

결제 서비스가 일반 findById() 대신 해당 메서드를 사용하도록 변경했다.

AiRequest aiRequest =
        aiRequestRepository.findByIdWithLock(requestId)
                .orElseThrow(() ->
                        new CustomException(
                                ErrorType.AI_REQUEST_NOT_FOUND
                        )
                );

첫 번째 요청이 WAITING_APPROVAL 상태를 APPROVED로 변경하면 두 번째 요청은 락이 풀린 뒤 변경된 상태를 확인한다.

따라서 서로 다른 멱등성 키를 사용하더라도 같은 AI 요청이 중복 승인되는 것을 막을 수 있다.

잠금 순서 통일

여러 개의 락을 사용할 때는 잠금 순서도 중요하다.

두 트랜잭션이 서로 다른 순서로 락을 획득하면 데드락(Deadlock)이 발생할 수 있다.

데드락이란 두 작업이 서로 상대방의 락이 풀리기를 기다리면서 둘 다 진행하지 못하는 상태다.

결제 승인에서는 잠금 순서를 다음과 같이 통일했다.

1. AiRequest 락
2. Wallet 락
3. 월 사용액과 잔액 확인
4. 블록체인 결제 실행
5. 결제 기록 저장
6. 잔액 차감
7. 트랜잭션 커밋 및 락 해제

동일한 로직에서는 항상 같은 순서로 락을 획득하도록 구성했다.

충전에도 같은 지갑 락 적용

결제만 지갑 락을 사용하면 결제와 충전이 동시에 실행될 때 lost update가 발생할 수 있다.

그래서 충전 로직도 일반 조회에서 락 조회로 변경했다.

Wallet wallet =
        walletRepository.findByIdWithLock(walletId)
                .orElseThrow(() ->
                        new CustomException(
                                ErrorType.WALLET_NOT_FOUND
                        )
                );

이제 결제와 충전은 같은 지갑 행을 기준으로 순서대로 실행된다.

결제 실행 중 → 충전 대기
충전 실행 중 → 결제 대기

먼저 실행된 작업이 커밋한 잔액을 다음 작업이 읽기 때문에 한쪽 변경이 사라지지 않는다.

잔액 변경을 도메인 메서드로 제한

기존 Wallet은 외부에서 계산한 잔액을 그대로 저장할 수 있었다.

public void updateBalance(BigDecimal balance) {
    this.balance = balance;
}

이 방식은 실수로 음수 잔액이나 잘못 계산한 값을 전달해도 엔티티가 막을 수 없다.

이를 withdraw()와 deposit()으로 분리했다.

출금 가능 여부 확인

public boolean canWithdraw(BigDecimal amount) {
    return amount != null
            && amount.compareTo(BigDecimal.ZERO) > 0
            && balance.compareTo(amount) >= 0;
}

다음 조건을 모두 만족해야 한다.

• 금액이 null이 아님
• 금액이 0보다 큼
• 현재 잔액이 출금 금액 이상임

출금

public void withdraw(BigDecimal amount) {
    if (!canWithdraw(amount)) {
        throw new IllegalStateException(
                "지갑 잔액보다 큰 금액을 차감할 수 없습니다."
        );
    }

    this.balance = this.balance.subtract(amount);
}

서비스에서 잔액을 확인하더라도 엔티티 내부에서 한 번 더 검증한다.

도메인 불변식이란 객체가 어떤 상황에서도 반드시 지켜야 하는 규칙을 뜻한다. 이번 지갑의 핵심 불변식은 “잔액보다 많은 금액을 차감할 수 없다”는 것이다.

충전

public void deposit(BigDecimal amount) {
    if (amount == null
            || amount.compareTo(BigDecimal.ZERO) <= 0) {
        throw new IllegalArgumentException(
                "충전 금액은 0보다 커야 합니다."
        );
    }

    this.balance = this.balance.add(amount);
}

잔액을 임의의 값으로 바꾸는 메서드를 제거하고 출금과 충전이라는 구체적인 행위만 허용했다.

실제 MySQL 동시성 테스트

동시성 코드는 단순한 단위 테스트만으로 충분히 검증하기 어렵다.

비관적 락은 실제 DB 트랜잭션과 여러 스레드가 함께 동작해야 하기 때문이다.

Testcontainers를 이용해 실제 MySQL 컨테이너를 실행하고 두 스레드에서 같은 지갑을 동시에 조회하도록 테스트했다.

Testcontainers는 테스트 실행 시 Docker 컨테이너로 MySQL 같은 외부 시스템을 자동 실행해주는 도구다.

테스트 조건은 다음과 같다.

초기 잔액: 100
첫 번째 결제: 80
두 번째 결제: 80

두 결제의 합은 160이므로 하나만 성공해야 한다.

첫 번째 스레드

첫 번째 스레드는 지갑 락을 획득하고 잠시 대기한다.

Wallet wallet =
        walletRepository.findByUserIdWithLock(userId)
                .orElseThrow();

firstLockAcquired.countDown();
await(releaseFirstTransaction);

if (wallet.canWithdraw(paymentAmount)) {
    wallet.withdraw(paymentAmount);
    successfulPayments.incrementAndGet();
}

두 번째 스레드

첫 번째 스레드가 락을 보유한 상태에서 두 번째 스레드도 같은 지갑을 조회한다.

Wallet wallet =
        walletRepository.findByUserIdWithLock(userId)
                .orElseThrow();

if (wallet.canWithdraw(paymentAmount)) {
    wallet.withdraw(paymentAmount);
    successfulPayments.incrementAndGet();
}

두 번째 스레드는 첫 번째 트랜잭션이 끝날 때까지 기다린다.

첫 번째 결제가 커밋된 뒤 잔액 20을 읽기 때문에 80을 차감할 수 없다.

검증 결과

assertThat(successfulPayments).hasValue(1);

assertThat(finalBalance)
        .isEqualByComparingTo("20.000000");

실제 테스트 결과는 다음과 같았다.

성공한 결제: 1건
최종 잔액: 20
MySQL 통합 테스트: BUILD SUCCESSFUL

두 요청이 동시에 실행됐지만 한 요청만 잔액을 차감했다.

비관적 락의 트레이드오프

비관적 락은 정합성을 명확하게 보장하지만 단점도 있다.

현재 구조에서는 블록체인 RPC 호출 중에도 지갑 락이 유지된다.

RPC(Remote Procedure Call)는 애플리케이션이 네트워크를 통해 외부 시스템의 기능을 호출하는 방식이다. 이번 프로젝트에서는 블록체인 노드에 거래를 요청하고 결과를 확인하는 과정이 해당한다.

외부 호출이 느리면 같은 지갑의 다음 요청은 그 시간 동안 대기해야 한다.

지갑 락 획득
→ 블록체인 요청
→ 영수증 검증
→ DB 저장
→ 트랜잭션 커밋
→ 지갑 락 해제

따라서 다음과 같은 특성이 있다.

장점

• 구현과 동작을 이해하기 쉬움
• 동일 지갑의 결제를 확실하게 순차 처리
• 잔액과 월 한도 정합성을 강하게 보장
• 외부 결제가 실행된 뒤 DB 충돌이 발생하는 문제 방지

단점

• 블록체인 응답이 늦으면 락 유지 시간이 길어짐
• 같은 지갑의 다음 요청 응답 시간이 증가
• 트래픽이 많으면 DB 커넥션 대기가 늘어날 수 있음

현재 단계에서는 결제 정확성을 우선해 비관적 락을 선택했다.

향후 거래 상태 머신을 도입하면 잔액 예약과 외부 결제를 분리해 락 유지 시간을 줄일 수 있다.

짧은 DB 트랜잭션에서 잔액 예약
→ 락 해제
→ 블록체인 결제 실행
→ 결제 결과에 따라 예약 확정 또는 해제

마무리

이번 작업에서는 동일 사용자의 여러 결제가 동시에 실행될 때 잔액과 예산이 잘못 계산되는 문제를 해결했다.

주요 개선 내용은 다음과 같다.

• 동일 AI 요청에 비관적 락 적용
• 동일 사용자의 지갑에 비관적 락 적용
• 지갑 락 이후 월 사용액과 잔액 확인
• 결제와 충전이 동일한 지갑 락을 사용하도록 통일
• 잔액 변경을 withdraw()와 deposit()으로 제한
• 실제 MySQL과 두 개의 스레드로 동시 차감 테스트
• 하나의 결제만 성공하고 최종 잔액이 음수가 되지 않는 것을 검증

멱등성은 동일한 요청의 반복 실행을 막고, 지갑 락은 서로 다른 요청이 같은 잔액을 동시에 사용하는 것을 막는다.

두 기능은 해결하는 문제가 다르다.

멱등성 키
→ 같은 결제 요청의 중복 실행 방지

비관적 지갑 락
→ 서로 다른 결제 요청 간 잔액 및 예산 충돌 방지

결제 시스템의 정합성을 지키려면 멱등성과 동시성 제어를 함께 고려해야 한다는 점을 확인할 수 있었다.

하지만 실제 서비스에서는 동일한 결제 요청이 여러 번 전달될 수 있다.

• 사용자가 결제 버튼을 연속으로 클릭한 경우
• 서버 응답이 늦어 프론트엔드가 요청을 다시 보낸 경우
• 모바일 네트워크가 끊겼다가 복구되면서 요청이 재전송된 경우
• HTTP 클라이언트가 타임아웃된 요청을 자동으로 재시도한 경우
• 동일한 요청이 서로 다른 서버 인스턴스로 전달된 경우

이런 상황에서 서버가 모든 요청을 새로운 결제로 인식하면 실제 결제가 두 번 실행될 수 있다.

이번 글에서는 TinyPay 결제 API에 멱등성 키를 적용해 중복 결제를 방지한 과정을 정리한다.

멱등성이란?

멱등성(Idempotency)이란 동일한 요청을 여러 번 실행하더라도 최종 결과가 한 번 실행한 것과 같도록 만드는 성질이다.

결제 API에서 멱등성을 보장한다는 것은 다음을 의미한다.

동일 결제 요청 1회 → 결제 1회 실행
동일 결제 요청 5회 → 결제 1회 실행

클라이언트는 결제 요청마다 고유한 idempotencyKey를 생성한다. 같은 결제를 재시도할 때는 새로운 키를 만들지 않고 기존 키를 다시 사용한다.

새로운 결제 → 새로운 idempotencyKey
같은 결제 재시도 → 기존 idempotencyKey 재사용

기존 구현의 문제

기존 코드도 성공한 결제 기록을 조회해 기본적인 중복 요청을 방어하고 있었다.

Optional<PaymentLog> existingLog =
        paymentLogRepository.findByRequestAndPaymentStatus(
                aiRequest,
                PaymentStatus.SUCCESS
        );

if (existingLog.isPresent()) {
    return 기존_결제_응답;
}

결제가 이미 완료된 뒤 동일한 요청이 다시 들어오면 기존 결과를 반환할 수 있다.

문제는 두 요청이 거의 동시에 들어오는 경우다.

요청 A: 성공한 PaymentLog 조회 → 없음
요청 B: 성공한 PaymentLog 조회 → 없음
요청 A: 블록체인 결제 실행
요청 B: 블록체인 결제 실행

두 요청 모두 결제 기록이 저장되기 전에 조회하면 둘 다 “아직 처리되지 않은 결제”라고 판단할 수 있다.

이처럼 여러 작업이 같은 데이터를 동시에 확인하고 수정하면서 실행 순서에 따라 결과가 달라지는 문제를 경쟁 상태(Race Condition)라고 한다.

기존 구조는 결제 완료 후 중복 여부를 확인했기 때문에 경쟁 상태를 충분히 막을 수 없었다. 이를 해결하기 위해 실제 결제를 실행하기 전에 한 요청만 처리 권한을 확보하도록 구조를 변경했다.

전체 처리 흐름

개선한 결제 처리 흐름은 다음과 같다.

결제 요청 수신
→ 사용자·금액·비밀번호·예산·잔액 검증
→ idempotencyKey 선점 시도
→ 선점 성공 시 블록체인 결제 실행
→ 결제 성공 시 PaymentLog 저장
→ 멱등성 상태를 COMPLETED로 변경

이미 같은 키가 존재한다면 상태에 따라 다르게 처리한다.

COMPLETED  → 기존 결제 결과 반환
PROCESSING → 처리 중이라는 409 응답
FAILED     → 이전 처리 실패라는 409 응답
요청 불일치 → 키 재사용 오류

여기서 선점이란 여러 요청 중 하나가 먼저 처리 권한을 확보하는 것을 뜻한다.

결제 요청에 idempotencyKey 추가

먼저 결제 요청 DTO에 idempotencyKey를 추가했다.

@NotBlank(message = "멱등성 키가 존재하지 않습니다.")
@Size(max = 100, message = "멱등성 키는 100자 이하여야 합니다.")
private String idempotencyKey;

@NotBlank와 @Size는 Bean Validation 기능이다. Bean Validation은 요청값이 서비스 로직에 들어가기 전에 필수값, 길이, 형식 등을 검사하는 Java 표준 검증 방식이다.

클라이언트는 다음과 같이 키를 포함해 결제를 요청한다.

{
  "idempotencyKey": "4dddbed4-3537-4ec4-82f8-643b59243e87",
  "estimatedCost": 10.500000,
  "walletPassword": "123456"
}

키는 UUID처럼 충돌 가능성이 매우 낮은 값을 사용하는 것이 적합하다.

키가 없거나 100자를 초과하면 결제 로직을 실행하지 않고 400 Bad Request를 반환한다.

멱등성 정보를 저장할 엔티티 설계

멱등성 처리 상태를 저장하기 위해 PaymentIdempotency 엔티티를 추가했다.

private Long userId;
private Long requestId;
private String idempotencyKey;
private BigDecimal requestAmount;
private PaymentIdempotencyStatus status;
private PaymentLog payment;

각 필드의 역할은 다음과 같다.

별도의 엔티티를 사용한 이유는 결제가 완료되기 전부터 요청의 처리 상태를 저장해야 하기 때문이다.

PaymentLog만 사용하면 실제 결제 내역이 생성되기 전에는 중복 요청을 식별하기 어렵다.

DB Unique Constraint 적용

동일한 사용자가 같은 키를 두 번 선점하지 못하도록 복합 유일 제약을 추가했다.

유일 제약(Unique Constraint)이란 특정 컬럼 값 또는 컬럼 조합이 테이블 안에서 중복되지 않도록 데이터베이스가 보장하는 규칙이다.

@Table(
    name = "payment_idempotency",
    uniqueConstraints = @UniqueConstraint(
        name = "uk_payment_idempotency_user_key",
        columnNames = {"user_id", "idempotency_key"}
    )
)

동작은 다음과 같다.

사용자 1 + key-123 → 저장 성공
사용자 1 + key-123 → 중복이므로 저장 실패
사용자 2 + key-123 → 저장 성공

키만 유일하게 설정하지 않고 userId와 묶은 이유는 사용자별로 키 공간을 분리하기 위해서다. 서로 다른 사용자가 우연히 같은 UUID를 생성해도 영향을 받지 않는다.

애플리케이션 코드만으로 막지 않은 이유

Java 코드에서 먼저 기존 키를 조회한 뒤 저장하는 방법도 생각할 수 있다.

if (!repository.existsByIdempotencyKey(key)) {
    repository.save(entity);
}

하지만 동시에 요청이 들어오면 다음과 같은 문제가 발생할 수 있다.

요청 A: 키 조회 → 없음
요청 B: 키 조회 → 없음
요청 A: 저장
요청 B: 저장

조회와 저장 사이에 빈틈이 있기 때문이다.

또한 서버가 여러 대라면 synchronized처럼 한 서버의 메모리에서만 동작하는 잠금으로는 다른 서버에 전달된 요청을 막을 수 없다.

모든 서버가 공유하는 DB에 유일 제약을 적용하면 여러 서버에서 동시에 요청하더라도 하나의 INSERT만 성공한다.

멱등성 상태 관리

멱등성 처리 상태는 세 가지로 구분했다.

public enum PaymentIdempotencyStatus {
    PROCESSING,
    COMPLETED,
    FAILED
}

각 상태의 의미는 다음과 같다.

• PROCESSING: 처리 권한을 확보하고 결제를 진행 중
• COMPLETED: 결제가 성공해 기존 결과를 재사용할 수 있음
• FAILED: 이전 결제 시도가 실패함

새로운 레코드는 PROCESSING 상태로 생성된다.

public static PaymentIdempotency processing(
        Long userId,
        Long requestId,
        String idempotencyKey,
        BigDecimal requestAmount
) {
    return new PaymentIdempotency(
            userId,
            requestId,
            idempotencyKey,
            requestAmount
    );
}

결제가 성공하면 실제 결제 기록을 연결하고 상태를 변경한다.

public void complete(PaymentLog payment) {
    this.payment = payment;
    this.status = PaymentIdempotencyStatus.COMPLETED;
}

실패하면 FAILED 상태로 변경한다.

public void fail() {
    this.status = PaymentIdempotencyStatus.FAILED;
}

같은 키로 요청 내용을 바꾸는 문제

동일한 키인지 확인하는 것만으로는 부족하다.

예를 들어 다음 두 요청은 키는 같지만 결제 금액이 다르다.

첫 번째 요청: key-123, requestId=10, amount=10
두 번째 요청: key-123, requestId=10, amount=100

두 번째 요청에 첫 번째 결과를 반환하거나 새로운 결제를 실행하면 안 된다.

이를 막기 위해 기존 요청의 requestId와 requestAmount도 함께 비교했다.

public boolean matches(
        Long requestId,
        BigDecimal requestAmount
) {
    return this.requestId.equals(requestId)
            && this.requestAmount.compareTo(requestAmount) == 0;
}

금액 비교에는 BigDecimal.equals() 대신 compareTo()를 사용했다.

10.0
10.00
10.000000

위 값들은 금액으로는 모두 같지만 equals()는 소수점 자릿수까지 비교하기 때문에 서로 다른 값으로 판단할 수 있다.

compareTo()는 실제 숫자의 크기를 비교하므로 결제 금액 비교에 더 적합하다.

Repository 구현

기존 멱등성 기록을 사용자 ID와 키로 조회할 수 있도록 Repository를 추가했다.

public interface PaymentIdempotencyRepository
        extends JpaRepository<PaymentIdempotency, Long> {

    @EntityGraph(attributePaths = {
        "payment",
        "payment.wallet",
        "payment.request"
    })
    Optional<PaymentIdempotency>
            findByUserIdAndIdempotencyKey(
                    Long userId,
                    String idempotencyKey
            );
}

@EntityGraph는 연관된 데이터를 어떤 범위까지 함께 조회할지 지정하는 JPA 기능이다.

완료된 요청이 다시 들어오면 기존 PaymentLog, 지갑 및 요청 정보가 필요하다. 이를 한 번에 조회해 트랜잭션 종료 후 연관 데이터 접근 시 발생할 수 있는 지연 로딩 문제를 방지했다.

지연 로딩(Lazy Loading)이란 연관 데이터를 처음부터 모두 조회하지 않고, 실제로 사용할 때 추가로 조회하는 방식이다.

멱등성 선점 서비스 구현

멱등성 선점과 상태 변경은 PaymentIdempotencyService로 분리했다.

@Transactional(propagation = Propagation.REQUIRES_NEW)
public PaymentIdempotency createClaim(
        Long userId,
        Long requestId,
        String idempotencyKey,
        BigDecimal requestAmount
) {
    return paymentIdempotencyRepository.saveAndFlush(
            PaymentIdempotency.processing(
                    userId,
                    requestId,
                    idempotencyKey,
                    requestAmount
            )
    );
}

여기서 핵심은 REQUIRES_NEW와 saveAndFlush()다.

REQUIRES_NEW란?

트랜잭션(Transaction)이란 여러 DB 작업을 하나의 작업 단위로 묶는 기능이다. 중간에 오류가 발생하면 해당 단위의 변경을 모두 취소할 수 있다.

REQUIRES_NEW는 현재 진행 중인 트랜잭션과 별개로 새로운 트랜잭션을 시작한다.

멱등성 선점 기록을 결제 처리보다 먼저 확정하기 위해 사용했다.

멱등성 PROCESSING 저장 및 커밋
→ 블록체인 결제 실행
→ PaymentLog 저장
→ 멱등성 상태 COMPLETED

블록체인 결제 이후 서버가 갑자기 종료되더라도 선점 기록은 PROCESSING으로 남는다. 재요청이 들어와도 새로운 결제를 바로 실행하지 않으므로 중복 결제보다 안전한 방향으로 실패할 수 있다.

saveAndFlush()를 사용한 이유

JPA의 save()는 SQL 실행을 트랜잭션 종료 시점까지 미룰 수 있다.

플러시(Flush)란 JPA가 메모리에 모아둔 변경사항을 실제 DB SQL로 반영하는 과정이다.

saveAndFlush()를 사용하면 INSERT를 즉시 실행하므로 DB 유일 제약 위반 여부를 블록체인 결제 전에 확인할 수 있다.

결제 승인 로직 변경

기존 사용자, 비밀번호, 예산 및 잔액 검증을 통과한 뒤 블록체인 결제 직전에 키를 선점하도록 변경했다.

PaymentIdempotency idempotency;

try {
    idempotency =
            paymentIdempotencyService.createClaim(
                    userId,
                    requestId,
                    request.getIdempotencyKey(),
                    estimatedCost
            );
} catch (DataIntegrityViolationException e) {
    // 이미 동일한 키가 존재하는 경우 처리
}

동시에 같은 키로 INSERT를 시도하면 하나만 성공한다.

요청 A → 선점 성공 → 블록체인 결제 진행
요청 B → 유일 제약 충돌 → 기존 상태 조회

이미 완료된 요청

기존 상태가 COMPLETED라면 블록체인을 다시 호출하지 않고 기존 결과를 반환한다.

if (existing.getStatus()
        == PaymentIdempotencyStatus.COMPLETED
        && existing.getPayment() != null) {
    return toResponse(
            aiRequest,
            existing.getPayment()
    );
}

첫 번째 결제는 성공했지만 네트워크 문제로 클라이언트가 응답을 받지 못한 경우에도 같은 키로 재요청하면 기존 결과를 받을 수 있다.

처리 중인 요청

기존 상태가 PROCESSING이면 두 번째 요청에 409 Conflict를 반환한다.

409 Conflict는 요청 형식은 올바르지만 현재 서버에 저장된 상태와 충돌한다는 의미의 HTTP 상태 코드다.

throw new CustomException(
        ErrorType.IDEMPOTENCY_REQUEST_IN_PROGRESS
);

이전에 실패한 요청

기존 상태가 FAILED라면 해당 키로 결제를 자동 재실행하지 않는다.

if (existing.getStatus()
        == PaymentIdempotencyStatus.FAILED) {
    throw new CustomException(
            ErrorType.IDEMPOTENCY_REQUEST_FAILED
    );
}

실패한 요청을 다시 실행하려면 새로운 키를 사용하도록 했다. 이는 실패 원인이 명확하지 않은 상태에서 동일 결제가 자동으로 다시 실행되는 것을 막기 위한 정책이다.

결제 성공과 실패 처리

결제가 성공하면 PaymentLog를 저장하고 멱등성 상태를 COMPLETED로 변경한다.

paymentLogRepository.save(paymentLog);

paymentIdempotencyService.complete(
        idempotency,
        paymentLog
);

실패하면 실패 결제 기록과 함께 멱등성 상태를 FAILED로 변경한다.

paymentLogService.saveFailedPaymentLog(...);
paymentIdempotencyService.fail(
        idempotency.getId()
);

오류 상태 구분

멱등성 처리 과정에서 발생할 수 있는 충돌을 세 가지로 구분했다.

IDEMPOTENCY_KEY_REUSED(
    HttpStatus.CONFLICT,
    "동일한 멱등성 키가 다른 결제 요청에 사용되었습니다."
),

IDEMPOTENCY_REQUEST_IN_PROGRESS(
    HttpStatus.CONFLICT,
    "동일한 결제 요청이 처리 중입니다."
),

IDEMPOTENCY_REQUEST_FAILED(
    HttpStatus.CONFLICT,
    "동일한 결제 요청이 이전 처리에서 실패했습니다."
)

모든 중복 요청을 하나의 오류로 처리하지 않고 원인을 구분하면 클라이언트도 상황에 맞게 대응할 수 있다.

테스트

엔티티 단위 테스트

단위 테스트(Unit Test)는 클래스나 메서드처럼 작은 코드 단위를 독립적으로 검증하는 테스트다.

다음 내용을 검증했다.

• 요청 ID와 금액이 같으면 동일 요청으로 판단
• 요청 ID가 다르면 불일치
• 금액이 다르면 불일치
• 실패 처리 후 상태가 FAILED로 변경
• 금액의 소수점 자릿수가 달라도 같은 값으로 판단

assertThat(
    idempotency.matches(
        10L,
        new BigDecimal("12.34")
    )
).isTrue();

저장된 금액이 12.340000이어도 동일한 금액으로 판단한다.

MySQL 통합 테스트

통합 테스트(Integration Test)는 여러 구성요소가 함께 동작할 때 결과가 올바른지 검증하는 테스트다.

Testcontainers를 이용해 실제 MySQL 환경에서 유일 제약이 동작하는지 확인했다.

Testcontainers는 테스트를 실행할 때 Docker 컨테이너로 MySQL 같은 외부 시스템을 자동 실행해주는 테스트 도구다.

paymentIdempotencyRepository.saveAndFlush(first);

assertThatThrownBy(() ->
        paymentIdempotencyRepository
                .saveAndFlush(second)
).isInstanceOf(
        DataIntegrityViolationException.class
);

동일한 사용자의 같은 키를 두 번 저장했을 때 두 번째 저장이 DB에서 거부되는 것을 검증했다.

단위 테스트: BUILD SUCCESSFUL
MySQL 통합 테스트: 1 test, 0 failures

이번 구현으로 방어할 수 있는 상황

이번 개선으로 다음 상황에서 동일한 결제가 다시 실행되는 것을 방지할 수 있다.

• 결제 버튼 중복 클릭
• 동일 요청 재전송
• 클라이언트의 자동 재시도
• 여러 서버 인스턴스로 들어온 동일 요청
• 결제 처리 중 발생한 중복 요청
• 같은 키로 결제 금액을 변경한 요청
• 결제 도중 서버가 중단된 후 들어오는 재요청

남아 있는 과제

이번 구현은 중복 결제를 막는 데 초점을 맞췄다.

다만 블록체인 결제가 성공한 직후, 멱등성 상태를 COMPLETED로 변경하기 전에 서버가 종료되면 해당 키가 계속 PROCESSING으로 남을 수 있다.

현재 구현은 이런 상황에서 결제를 자동으로 다시 실행하지 않는다. 중복 결제를 발생시키는 것보다 운영자가 확인할 수 있도록 멈추는 방향을 선택한 것이다.

향후에는 대사(Reconciliation) 작업이 필요하다.

대사란 내부 DB의 결제 내역과 외부 결제 시스템 또는 블록체인의 실제 거래 내역을 비교해 불일치를 찾고 상태를 바로잡는 작업이다.

오래된 PROCESSING 요청 조회
→ 블록체인 거래 내역 확인
→ 실제 성공이면 COMPLETED
→ 실제 실패면 FAILED
→ 판단할 수 없으면 운영 확인 대상으로 등록

이 대사 작업까지 추가하면 장애 발생 후 자동 복구가 가능한 결제 구조로 확장할 수 있다.

마무리

처음에는 성공한 PaymentLog가 있는지 조회하는 것만으로 중복 결제를 막으려고 했다.

하지만 동시에 요청이 들어오는 상황에서는 두 요청이 모두 결제 기록이 없다고 판단할 수 있었다. 이를 해결하기 위해 다음과 같이 개선했다.

• 클라이언트가 결제별 idempotencyKey 전달
• 별도의 멱등성 엔티티와 처리 상태 관리
• 사용자와 키에 대한 DB 복합 유일 제약 적용
• 결제 전에 멱등성 처리 권한 선점
• 완료 요청에는 기존 결과 반환
• 처리 중·실패·키 재사용 상황을 구분
• 실제 MySQL 통합 테스트로 유일 제약 검증

이번 작업을 통해 멱등성은 단순히 “기존 결제가 있는지 조회하는 기능”이 아니라, 요청의 처리 권한과 상태를 결제 실행 전에 안전하게 기록하는 구조라는 점을 배울 수 있었다.

기사 데이터가 적을 때는 대부분의 쿼리가 빠르게 작동한다. 하지만 기사 수가 수십만 건 이상으로 증가하면, 검색과 목록 조회 같은 기본 기능도 점점 느려질 수 있다.

이번 글에서는 데이터 증가와 운영 환경을 고려하여 다음 항목을 개선했다.

• 기사 검색을 위한 trigram 인덱스 추가
• 최신 중요도 조회 쿼리 단순화
• COUNT 결과 캐싱
• 커서 기반 페이지네이션 도입
• Dify 업로드 동시 처리
• Celery 작업 큐와 스케줄러 분리
• 운영 환경에서 reload 제거 및 worker 확장

ILIKE 검색과 trigram 인덱스

기사 제목이나 본문에서 특정 단어를 찾기 위해 다음과 같은 검색 조건을 사용할 수 있다.

WHERE title ILIKE '%검색어%'

앞뒤에 %가 붙은 검색은 일반적인 B-Tree 인덱스를 효율적으로 사용하기 어렵다. 데이터가 많아지면 데이터베이스가 많은 행을 직접 확인해야 한다.

PostgreSQL의 pg_trgm 확장은 문자열을 작은 단위로 나누어 유사 검색과 부분 문자열 검색을 빠르게 처리할 수 있도록 도와준다.

CREATE EXTENSION IF NOT EXISTS pg_trgm;

CREATE INDEX article_title_trgm_idx
ON articles
USING gin (title gin_trgm_ops);

기사 제목, 본문, 요약 검색에 trigram 인덱스를 추가하면 기존 검색 동작을 크게 변경하지 않으면서 검색 성능을 개선할 수 있다.

최신 중요도 조회에서 row_number 제거

기존 쿼리는 기사마다 가장 최근의 중요도 결과를 찾기 위해 row_number() 윈도우 함수를 사용했다.

기사별 중요도 데이터 정렬
→ 각 행에 순번 부여
→ 순번이 1인 데이터 선택

하지만 데이터베이스에 이미 현재 중요도인지 나타내는 is_current 컬럼이 존재한다면, 매번 전체 데이터를 정렬하여 순번을 계산할 필요가 없다.

WHERE is_current = true

현재 데이터가 무엇인지 저장 단계에서 관리하고, 조회 단계에서는 현재 데이터만 가져오도록 변경했다.

기사 요약처럼 최신 데이터를 직접 표시하는 컬럼이 없는 경우에는 PostgreSQL의 DISTINCT ON을 사용하여 기사별 최신 데이터를 조회하도록 개선했다.

정확한 전체 개수 COUNT 캐싱

페이지 번호를 표시하려면 전체 검색 결과 개수가 필요하다. 이를 위해 목록 API는 일반적으로 COUNT 쿼리를 실행한다.

SELECT COUNT(*)
FROM articles
WHERE ...;

복잡한 검색 조건을 사용하는 경우 목록 조회보다 전체 개수를 계산하는 작업이 더 느릴 수도 있다.

동일한 검색 조건의 COUNT 결과를 Redis에 잠시 저장하면, 사용자가 다음 페이지로 이동할 때 같은 COUNT 쿼리를 반복하지 않아도 된다.

검색 조건을 정렬하여 문자열 생성
→ 해시값 생성
→ Redis 캐시 키로 사용

캐시 키에는 검색어, 날짜, 중요도 등 COUNT 결과에 영향을 주는 모든 조건이 포함되어야 한다.

OFFSET 페이지네이션의 문제

페이지 번호 방식은 보통 OFFSET과 LIMIT을 사용한다.

SELECT *
FROM articles
ORDER BY id DESC
OFFSET 100000
LIMIT 20;

OFFSET이 커지면 데이터베이스는 앞의 많은 데이터를 확인한 후 버려야 한다. 따라서 사용자가 뒤쪽 페이지로 이동할수록 조회가 느려질 수 있다.

커서 기반 페이지네이션

커서 기반 페이지네이션은 마지막으로 조회한 데이터의 위치를 기준으로 다음 데이터를 가져온다.

첫 번째 요청:
ORDER BY id DESC
LIMIT 21

다음 요청:
WHERE id < 마지막으로 조회한 ID
ORDER BY id DESC
LIMIT 21

현재 페이지 크기보다 한 개 더 조회하면 다음 페이지가 존재하는지 확인할 수 있다. 추가로 조회한 한 개의 데이터가 있다면 다음 커서를 반환한다.

이 방식은 페이지 번호를 직접 선택하기 어렵다는 단점이 있지만, 데이터가 많아져도 일정한 속도로 다음 목록을 조회할 수 있다.

기존 페이지 번호 방식은 유지하고, 빠른 탐색이 필요한 경우 커서 방식을 선택할 수 있도록 구성했다.

Dify 업로드를 동시에 처리하기

기존에는 여러 기사를 Dify에 업로드할 때 기사마다 순서대로 처리했다.

기사 1 업로드 완료
→ 기사 2 업로드 완료
→ 기사 3 업로드 완료

기사 한 건의 업로드에 1초가 걸린다면, 기사 100건은 약 100초가 필요하다.

이를 개선하기 위해 여러 업로드를 동시에 실행하도록 변경했다. 다만 요청을 무제한으로 동시에 보내면 Dify 서버에 부담을 줄 수 있다.

따라서 asyncio.Semaphore를 사용하여 동시에 처리할 수 있는 업로드 수를 제한했다.

동시 업로드 제한: 3개

기사 1, 2, 3 업로드
→ 완료된 자리에 기사 4 업로드
→ 완료된 자리에 기사 5 업로드

이러한 방식을 bounded concurrency라고 한다. 순차 처리보다 빠르면서도 외부 API에 과도한 요청을 보내지 않는다.

Celery 작업 큐 도입

기사 분석이나 정기 크롤링은 실행 시간이 길 수 있다. 이 작업을 FastAPI 서버 내부에서 직접 실행하면, 서버 재시작 시 작업이 사라지거나 여러 worker가 같은 작업을 실행할 수 있다.

Celery를 도입하면 API 서버와 백그라운드 작업 실행 프로세스를 분리할 수 있다.

사용자 요청
→ FastAPI가 Celery 작업 등록
→ Redis가 작업 보관
→ Celery Worker가 작업 실행
→ Redis에 작업 상태 저장

FastAPI는 작업을 직접 끝낼 때까지 기다리지 않고, 작업 ID를 사용자에게 빠르게 반환할 수 있다.

Celery Beat로 정기 작업 분리

기존에는 FastAPI 애플리케이션 내부에서 스케줄러를 실행했다. 하지만 FastAPI worker를 여러 개 실행하면 각 worker에서 스케줄러가 시작될 수 있다.

FastAPI Worker 1 → 정기 크롤링 실행
FastAPI Worker 2 → 동일한 정기 크롤링 실행
FastAPI Worker 3 → 동일한 정기 크롤링 실행

결과적으로 같은 작업이 여러 번 실행될 위험이 있다.

정기 작업 등록은 Celery Beat가 담당하고, 실제 작업 실행은 Celery Worker가 담당하도록 분리했다.

Celery Beat
→ 정해진 시간에 작업 등록

Celery Worker
→ 등록된 작업 실행

운영 환경에서 reload 제거

개발 환경에서 사용하는 --reload 옵션은 파일 변경을 감지하여 서버를 자동으로 재시작한다. 개발 중에는 편리하지만 운영 환경에는 적합하지 않다.

운영 환경에서는 reload를 제거하고 여러 FastAPI worker를 실행하도록 변경했다.

개발 환경:
uvicorn app.main:app --reload

운영 환경:
uvicorn app.main:app --workers 2

API 서버, 데이터베이스 마이그레이션, Redis, Celery Worker, Celery Beat를 각각 별도 서비스로 구성했다.

전체 구조

사용자
  ↓
FastAPI Worker
  ├─ PostgreSQL 조회
  ├─ Redis 캐시 조회
  └─ Celery 작업 등록
        ↓
      Redis Broker
        ↓
      Celery Worker
        ↓
      기사 크롤링 및 분석

Celery Beat
  ↓
정기 작업 등록

정리

• trigram 인덱스로 부분 문자열 검색 성능을 개선했다.
• 현재 중요도 컬럼을 활용하여 불필요한 윈도우 함수를 제거했다.
• COUNT 결과를 Redis에 캐싱했다.
• 대용량 목록 조회를 위해 커서 페이지네이션을 추가했다.
• Dify 업로드를 동시에 최대 3개씩 처리하도록 변경했다.
• 기사 분석과 정기 작업을 Celery로 분리했다.
• 운영 환경에서 reload를 제거하고 여러 API worker를 실행하도록 구성했다.

서비스 초기에는 단순한 구조가 관리하기 쉽다. 하지만 데이터와 사용자 요청이 증가하면, API 요청 처리와 백그라운드 작업을 분리하고 반복되는 데이터베이스 작업을 줄이는 구조가 필요해진다.

이번 개선을 통해 현재 처리 속도를 높이는 것뿐만 아니라, 향후 기사 데이터와 요청량이 증가해도 확장하기 쉬운 구조를 만들 수 있었다.

뉴스 모니터링 서비스의 통계 API는 기사 수, 언론사별 기사 수, 중요도별 기사 수와 같은 데이터를 제공한다.

이러한 통계 값은 요청할 때마다 크게 달라지지 않지만, 기존 구조에서는 사용자가 통계 페이지를 열 때마다 데이터베이스에서 집계 쿼리를 다시 실행했다.

사용자 A가 통계 페이지 조회 → DB 집계 쿼리 실행
사용자 B가 통계 페이지 조회 → DB 집계 쿼리 실행
사용자 C가 통계 페이지 조회 → DB 집계 쿼리 실행

기사 데이터가 많아질수록 COUNT와 GROUP BY 같은 집계 쿼리의 처리 비용도 증가한다.

Redis 캐시를 사용하면 한 번 계산한 결과를 잠시 저장하고, 동일한 요청이 들어왔을 때 저장된 값을 바로 반환할 수 있다.

Redis란 무엇인가?

Redis는 데이터를 메모리에 저장하는 데이터 저장소다. 일반적인 데이터베이스보다 데이터를 매우 빠르게 읽을 수 있어 캐시, 로그인 세션, 작업 상태 관리 등에 자주 사용된다.

Redis에 저장되는 데이터는 기본적으로 키와 값으로 구성된다.

키: stats:articles:daily:2026-06-12
값: {"total": 1200, "important": 350}

Redis에 들어가는 값은 어떻게 정할까?

캐시 키에는 해당 결과를 구분할 수 있는 조건이 포함되어야 한다. 예를 들어 날짜와 사용자에 따라 통계 결과가 달라진다면, 날짜와 사용자 ID를 캐시 키에 포함해야 한다.

stats:user:10:date:2026-06-12
stats:user:20:date:2026-06-12

서로 다른 조건에서 같은 캐시 키를 사용하면 사용자에게 잘못된 결과를 반환할 수 있다.

캐시에 저장하는 값은 데이터베이스 쿼리 결과를 JSON 형태로 변환한 값이다.

{
  "total_articles": 1200,
  "high_importance": 350,
  "medium_importance": 500,
  "low_importance": 350
}

TTL이란 무엇인가?

캐시 데이터는 데이터베이스의 최신 상태와 달라질 수 있다. 이를 방지하기 위해 Redis 데이터에 TTL을 설정한다.

TTL은 데이터가 Redis에 유지되는 시간을 의미한다. 예를 들어 TTL을 60초로 설정하면, 캐시 데이터는 저장된 지 60초 후 자동으로 삭제된다.

첫 번째 요청
→ DB에서 통계 계산
→ Redis에 결과 저장
→ TTL 60초 설정

60초 이내의 요청
→ Redis 결과 반환

60초 이후 요청
→ DB에서 다시 계산
→ Redis 결과 갱신

TTL이 짧으면 데이터는 더 최신 상태에 가깝지만, 데이터베이스 쿼리가 더 자주 실행된다.

TTL이 길면 데이터베이스 부하는 줄어들지만, 사용자가 잠시 오래된 데이터를 볼 수 있다. 서비스 특성에 따라 적절한 값을 선택해야 한다.

Redis 객체는 하나만 있어도 될까?

일반적으로 애플리케이션 내부에서는 Redis 연결 객체를 공용으로 사용한다. 요청마다 새로운 Redis 연결을 만들 필요는 없다.

Redis 클라이언트는 내부적으로 연결 풀을 관리한다. 여러 요청이 동시에 Redis를 사용하더라도 연결 풀에서 사용 가능한 연결을 선택하여 처리한다.

FastAPI 애플리케이션
→ 공용 Redis 클라이언트
→ Redis 연결 풀
→ Redis 서버

다만 Redis 안에서 사용하는 데이터는 목적에 따라 구분해야 한다. 하나의 Redis 서버를 사용하더라도 키 이름이나 Redis DB 번호를 분리할 수 있다.

DB 0: API 통계 캐시
DB 1: Celery 작업 큐
DB 2: Celery 작업 결과

캐시 조회 흐름

1. 요청 조건을 이용하여 캐시 키를 생성한다.
2. Redis에서 캐시 키를 조회한다.
3. 값이 존재하면 Redis 값을 반환한다.
4. 값이 없으면 데이터베이스 쿼리를 실행한다.
5. 쿼리 결과를 Redis에 저장한다.
6. 사용자에게 결과를 반환한다.

Redis 장애는 어떻게 처리할까?

Redis는 성능 개선을 위한 보조 저장소다. Redis가 잠시 사용할 수 없더라도 핵심 API는 가능하면 정상 작동해야 한다.

따라서 Redis 조회 중 오류가 발생하면 데이터베이스에서 직접 데이터를 조회하도록 처리했다.

Redis 정상
→ 캐시 결과 사용

Redis 장애
→ 데이터베이스 직접 조회

이러한 방식을 사용하면 Redis 장애가 전체 서비스 장애로 이어지는 것을 줄일 수 있다.

정리

• 반복되는 통계 쿼리 결과를 Redis에 저장했다.
• 요청 조건을 기반으로 캐시 키를 생성했다.
• TTL을 설정하여 오래된 데이터가 자동으로 삭제되도록 했다.
• 공용 Redis 클라이언트와 연결 풀을 사용했다.
• Redis 장애 시 데이터베이스를 직접 조회하도록 처리했다.

Redis 캐시는 데이터베이스를 완전히 대체하는 기술이 아니다. 자주 조회되지만 자주 변경되지 않는 결과를 잠시 저장하여, 데이터베이스의 반복 작업을 줄이는 역할을 한다.

FastAPI로 뉴스 모니터링 서비스를 개발하면서, 기능은 정상적으로 작동하지만 기사 수가 많아질수록 처리 속도가 느려질 수 있는 부분들을 발견했다.

이번 글에서는 다음 성능 문제를 개선한 과정을 정리한다.

• 기사 본문을 불필요하게 다시 크롤링하는 문제
• 외부 API 요청마다 새로운 HTTP 연결을 만드는 문제
• 기사 분석 결과 저장 과정에서 발생하는 N+1 쿼리 문제
• HTML 파싱과 이메일 발송이 다른 API 요청을 막는 문제

기사 본문이 있는데도 다시 크롤링하는 문제

서비스는 TransNews API로부터 기사 정보를 전달받는다. 이 정보에는 기사 제목, URL, 본문 등이 포함될 수 있다.

기존 코드에서는 TransNews API가 기사 본문을 이미 전달했더라도, 기사 URL에 다시 접속하여 본문을 크롤링했다.

TransNews API 호출
→ 기사 URL과 본문 전달
→ 전달받은 URL에 다시 접속
→ 기사 본문 재크롤링

이 방식은 같은 데이터를 얻기 위해 외부 사이트에 불필요한 요청을 한 번 더 보내게 된다. 기사 수가 많아질수록 네트워크 요청 횟수와 전체 처리 시간이 함께 증가한다.

개선 후에는 TransNews가 전달한 본문이 존재하는지 먼저 확인한다. 본문이 없는 기사만 URL에 접속하여 다시 크롤링한다.

if article.content:
    전달받은 본문 사용
else:
    URL을 이용하여 본문 크롤링

이렇게 하면 이미 본문을 가지고 있는 기사에 대해서는 추가 네트워크 요청이 발생하지 않는다.

HTTP 연결을 요청마다 새로 만드는 문제

외부 API를 호출할 때는 서버와 HTTP 연결을 생성해야 한다. HTTPS를 사용하는 경우에는 TLS 연결 설정 과정도 필요하다.

기존 코드에서는 외부 API를 호출할 때마다 새로운 httpx.AsyncClient 객체를 생성했다.

요청 1 → 새로운 연결 생성 → 요청 처리 → 연결 종료
요청 2 → 새로운 연결 생성 → 요청 처리 → 연결 종료
요청 3 → 새로운 연결 생성 → 요청 처리 → 연결 종료

이 방식은 매번 새로운 소켓과 TLS 연결을 생성하기 때문에, 여러 기사를 연속으로 처리할 때 불필요한 시간이 반복해서 발생한다.

개선 후에는 애플리케이션 전체에서 공유하는 AsyncClient를 사용하도록 변경했다.

애플리케이션 시작
→ 공용 AsyncClient 생성

외부 API 요청
→ 기존 연결을 재사용

애플리케이션 종료
→ AsyncClient 종료

공용 클라이언트는 연결 풀과 Keep-Alive를 활용한다. 이미 생성된 연결을 재사용할 수 있어 외부 API를 반복 호출할 때 처리 속도가 개선된다.

N+1 쿼리 문제 해결

N+1 쿼리는 여러 데이터를 처리할 때, 각 데이터마다 추가 데이터베이스 쿼리를 실행하는 문제를 의미한다.

예를 들어 기사 분석 결과 1,000개를 저장한다고 가정해 보자. 기존 코드에서는 각 기사마다 기존 분석 결과가 있는지 개별적으로 조회했다.

기사 목록 조회: 1회

기사 1의 기존 분석 조회: 1회
기사 2의 기존 분석 조회: 1회
기사 3의 기존 분석 조회: 1회
...
기사 1,000의 기존 분석 조회: 1회

기사 1,000개를 처리하기 위해 약 1,001회의 쿼리가 실행되는 구조다. 기사 수가 증가하면 데이터베이스 요청 수도 비례하여 증가한다.

개선 후에는 처리할 모든 article_id를 모아서 기존 분석 결과를 한 번에 조회한다.

SELECT *
FROM article_analysis
WHERE article_id IN (1, 2, 3, ...);

조회 결과는 기사 ID를 키로 사용하는 딕셔너리 형태로 정리한다. 이후 각 기사의 기존 분석 결과를 메모리에서 빠르게 찾을 수 있다.

기존 방식:
기사 수만큼 데이터베이스 조회

개선 방식:
배치 전체를 한 번에 데이터베이스 조회

동기 작업이 이벤트 루프를 막는 문제

FastAPI의 async def 함수는 이벤트 루프 위에서 실행된다. 이벤트 루프는 여러 요청을 번갈아 처리하면서 높은 동시성을 제공한다.

하지만 HTML 파싱, Excel 파일 생성, SMTP 이메일 발송처럼 오래 걸리는 동기 작업을 이벤트 루프에서 직접 실행하면 문제가 발생한다.

요청 A: Excel 파일 생성 중
요청 B: 대기
요청 C: 대기

Excel 파일을 만드는 동안 이벤트 루프가 다른 요청을 처리하지 못할 수 있다. 사용자 입장에서는 관련 없는 API 요청까지 느려진 것처럼 보인다.

개선 후에는 이러한 동기 작업을 asyncio.to_thread()를 이용하여 별도의 스레드에서 실행한다.

await asyncio.to_thread(create_excel_report)
await asyncio.to_thread(send_email)

동기 작업이 별도 스레드에서 실행되는 동안, 이벤트 루프는 다른 API 요청을 계속 처리할 수 있다.

Celery가 반드시 필요한 것은 아닐까?

짧게 끝나는 동기 작업이라면 asyncio.to_thread()만으로도 충분할 수 있다. 하지만 작업 시간이 길거나, 서버가 종료되어도 작업이 유지되어야 한다면 Celery가 더 적합하다.

정리

• 본문이 없는 기사만 다시 크롤링하도록 변경했다.
• 공용 HTTP 클라이언트를 사용하여 연결을 재사용했다.
• 기사별 개별 조회를 배치 조회로 변경하여 N+1 쿼리를 제거했다.
• 동기 작업을 별도 스레드로 보내 이벤트 루프가 멈추지 않도록 했다.

성능 개선은 무조건 복잡한 기술을 도입하는 것이 아니다. 불필요하게 반복되는 네트워크 요청과 데이터베이스 쿼리를 줄이는 것만으로도 서비스의 처리 속도와 안정성을 크게 개선할 수 있다.

1. Introduction

In June 2024, I joined the Lee Jae-hoon professor's Network Research Lab at Dongguk University, focusing on AI-enabled networking technologies.
As part of the lab activities, I worked extensively with ONOS (Open Network Operating System) to understand and apply Software-Defined Networking (SDN) concepts through hands-on labs.

This blog post summarizes my journey. detailed version also exists in korean.

ONOS Practice - Connecting virtual networks using Mininet with ONOS 2.7.0 on Ubuntu 22.04

ONOS Practice - Setting flow rules in ONOS to control VLAN-tagged packets

ONOS Practice - Visualizing real-time switch port traffic statistics from ONOS using open-source tools

2. Setting up ONOS and Mininet

To start, I set up the ONOS 2.7.0 controller on Ubuntu 22.04 and connected it with Mininet, a popular network emulator for SDN.
I practiced creating virtual networks consisting of multiple switches and hosts, and then linked them to ONOS to control the flow of network traffic.

Key tools:

• Ubuntu 22.04
• Mininet
• ONOS 2.7.0

3. Connecting Virtual Networks

I created virtual topologies in Mininet (such as linear and tree structures) and verified that ONOS correctly discovered all devices and links.
I also explored how ONOS automatically installs default flow rules to manage packet forwarding in the network.

I built flow rules by two ways. one in reactive mode, where the SDN controller makes decision, and the other in proactive mode, where the user defines the rules manually.

4. Installing Open vSwitch on Raspberry Pi

Taking a step further, I installed Open vSwitch (OVS) on Raspberry Pi 3 devices to build a real-world SDN testbed.
After configuring the OVS bridges and ports, I connected the Raspberry Pi switches to ONOS as external network elements.

5. Controlling VLAN Packets with ONOS

Using ONOS’s Flow Rule functionality, I wrote flow rules to control VLAN-tagged packets.
This included filtering specific VLAN IDs and forwarding traffic based on VLAN properties, allowing me to manage network segmentation dynamically.

6. Visualizing Switch Traffic in Real Time

To monitor network performance, I visualized real-time switch port traffic data using ONOS metrics combined with open-source visualization tools.
This helped me gain insights into traffic patterns, detect bottlenecks, and understand SDN monitoring strategies.

7. Key Takeaways and Reflections

Through these hands-on experiences, I learned:

• How SDN controllers like ONOS manage and orchestrate network flows.
• Practical skills in setting up and controlling virtual and physical network devices.
• The importance of real-time network visualization for operational insights.

This project sparked my interest in developing custom ONOS applications and exploring deeper into SDN-enabled smart networking.

I look forward to continuing this journey by building my first ONOS application and contributing to open-source networking initiatives!

Resources

• ONOS Project Official Website
• ONOS Wiki: Setting up Your First App

Thank you for reading! 🚀

이 문제는 에라토스테네스의 체 알고리즘을 이용하여 풀 수 있다. 먼저, vector<bool> isPrime(N+1,true)를 생성하여 모든 수를 소수로 가정한다. 그리고 2부터 N까지 배수를 제거하여 소수만 남기는 구조이다. 코드는 아래에 적어두었다.

ios::sync_with_stdio(false);와 cin.tie(nullptr);는 c++에서 입출력 성능을 최적화 하기 위한 코드이다. 1️⃣ios::sync_with_stdio(false);

• c++의 표준 입출력인 cin,cout과 c의 표준 입출력인 scanf,printf의 동기화를 해제하는 역할을 한다.
• 기존적으로 c++의 cin,cout은 c의 scanf,printf와 동기화되어 같이 사용될 때 정상적으로 동작하도록 보장된다.
• 하지만 동기화과정이 불필요한 경우 성능을 향상시킬 수 있다.
• 즉, sacnf,printf를 사용해야한다면 이 옵션은 쓰면 안된다. 2️⃣cin.tie(nullptr);
• 기본적으로 cin과 cout은 연결(tie)되어있다.
• 즉, cin이 사용될 때마다 자동으로 cout이 flush(출력 버퍼 비움)이 되어 즉시 출력된다. 이를 해제(nullptr로 설정)하려면 불필요한 flush를 방지하여 입출력 속도를 높일 수 있다.

#include<iostream>
#include<vector>

using namespace std;

void sieve(int M, int N) {
    vector<bool> isPrime(N+1, true);
    isPrime[0] = isPrime[1] = false;

    //에라토스테네스의 체 알고리즘
    for(int i = 2; i*i <=N; i++){
        if(isPrime[i]){
            for(int j = i * i; j<= N; j+=i){
                isPrime[j] = false;
            }
        }
    }

    //결과 출력
    for(int i = M; i<=N; i++){
        if(isPrime[i]){
            cout<<i<<'\n';
        }
    }
}

int main(){
    ios::sync_with_stdio(false);
    cin.tie(nullptr);

    int M, N;
    cin >> M >> N;
    sieve(M, N);

    return 0;
}

이번에는 위 사진의 순서대로 실습을 진행해볼 것이다. 실습의 편의성을 위해 모든 오픈소스 소프트웨어는 모두 하나의 PC에 설치된다.

1️⃣ ONOS + Mininet 구성

Mininet으로 가상 네트워크를 생성하여 SDN 제어기인 ONOS에 연결을 구성하는 방식이다.

ONOS 2.7.0, Ubuntu 22.04이용해 mininet 가상 네트워크 연결 링크된 포스트와 동일하게 진행하면 된다.

위 포스팅대로 진행을 완료하면, 현재 ONOS와 연결된 Mininet기반 가상 네트워크 구조를 조회하면 다음과 같은 결과가 출력된다. dpid가 '0000000000000001'인 OVS스위치(s1) 1대에 1번 포트(s1-eth1)과 2번 포트(s1-eth2)에 각각 호스트가 하나씩 연결된 것을 알 수 있다.

구성정보를 표현한 그림이다.

2️⃣ Celery 구성

Celery로 OVS 포트 별 실시간 송/수신 트래픽 처리량 계산

💡 Celery란 무엇인가? Celery는 분산 작업 큐(distributed task queue)이다. python으로 작성되었으며, 비동기 작업 및 스케줄링에 널리 사용된다. 즉, 시간이 오래걸리는 작업을 백그라운드에서 실행할 수 있도록 도와주는 도구이다. 이는 웹 애플리케이션의 응답 속도를 높이기 위해 많이 사용된다.

Celery를 설치하는 가장 간단한 방법은 python라이브러리 설치패키지 매니저인 pip을 통해 설치하는 방법이다. 이를 위해 python3와 python3를 지원하는 pip을 pc에 설치해준다. pip 설치가 완료되면 pip3를 이용하여 Celery를 설치해준다. pip3를 통해 설치된 python모듈을 조회하면 나는 5.4.0 버전이 조회된다.

Celery설치를 완료했다면, 이제 Celery 기본 Broker인 RabbitMQ를 아래와같이 설치해준다.

비유를 들어 설명하자면,

• Celery는 "심부름 명령을 내리는 사람"이다. 심부름이 많을 때 효율적으로 각 심부름꾼(worker)에게 지시한다.
• RabbitMQ는 "심부름 메모를 전달하는 게시판"이다. 모든 심부름꾼은 게시판에서 심부름 내용을 확인하고 수행한다.

설치가 다 되었다면 실행해준다. 이제는 Broker(RabbitMQ)를 통해 Worker에 분배 될 Celery Task를 생성하면 된다. 하지만, 그 전에 먼저 Celery Task에 반영해주기 위한, OVS 스위치 포트 별 트래픽 정보를 가지고 트래픽처리량을 계산하는 과정을 알아보아야 한다.

그래서 일단 REST API를 통해서 ONOS와 연결된 스위치 별 포트정보를 조회해서, 어떤 정보가 수집되는지 확인해볼 필요가 있다. 이를 위해 우선 cURL, jq를 설치해주자.

• cURL: HTTP 요청을 전송하는 도구
• jq: JSON 데이터를 읽기 쉽게 포맷하여 출력하는 도구 그런 다음 다음과같이 ONOS의 REST API를 이용해 Mininet으로 구성한 OVS 스위치 s1의 포트 별 트래픽 정보를 조회하는 스크립트 파일을 만들어준다. ONOS_IP는 본인의 IP로 바꾸어주어야 한다.

이 스크립트를 실행하면, ONOS와 연결된 스위치 별 포트 정보를 알 수 있다. 여기서는 OVS 스위치 s1의 1번포트와 2번포트에 대한 정보를 확인할 수 있다. 각 포트 별 bytesReceived, bytesSent, durationSec 값을 이용하면 스위치 포트 별 수신(RX), 송신(TX)패킷에 대한 트래픽처리량 계산이 가능하다.

• bytesReceived() : 포트를 통해 수신받은 패킷의 누적 사이즈(단위: bytes)

• byteSent() : 포트를 통해 송신된 패킷의 누적 사이즈(단위:bytes)
• durationSec() : 포트가 활성화된 시간(sec)

여기까지 완료되었다면, 이제는 위의 송/수신 트래픽처리량(TX/RX Throughput)에 대한 공식을 가지고, 매 단위시간마다 트래픽 처리량 정보를 계산하는 Celery Task를 생성하겠다. Celery Task를 통하여 ONOS의 REST API를 호출하기 위하여, Python requests 모듈을 설치한다.

처음 계산되는 송/수신 트래픽 처리량 값을 임시로 저장하기 위한 data디렉토리를 생성하고, 읽고 쓰기 권한을 아래와같이 변경해준다. (권한 변경 시 sudo 붙여주는 것을 잊지말자 ㅎㅎ)

다음으로, 아래와같이 task.py라는 파일을 생성하여 ONOS_CELERY_TASK라는 celery task함수를 하나 작성한다. 해당 task는 ONOS의 REST API를 통해 ONOS와 연결된 모든 스위치의 활서화된 포트 별 bytesSent,bytesReceived,durationSec값을 조회하고, 앞에서 도출한 공식 두 가지를 통해서 송수신 트래픽에 대한 처리량(TX/RX Throughput)을 계산한다.

from celery import Celery
import json
import requests
import os

# Broker(RabbitMQ) 설정
app = Celery('ONOS_TASK', broker='pyamqp://guest@localhost//')

# celeryconfig.py에 정의한 Celery Task 환경설정 정보 가져오기
app.config_from_object('celeryconfig')

# 파일 저장 및 읽기 함수 정의
def FILE_WRITE(file_dir, data):
    with open(file_dir, 'w') as f:
        f.write(data)

def FILE_READ(file_dir):
    with open(file_dir, 'r') as f:
        return f.readline()

# Celery Task 함수 정의
@app.task
def ONOS_CELERY_TASK(CTRL_IP, CTRL_PORT, CTRL_ID, CTRL_PW):
    try:
        # ONOS REST API를 통해 스위치 정보 조회
        ONOS_URI = f"http://{CTRL_IP}:{CTRL_PORT}/onos/v1/devices"
        result = requests.get(ONOS_URI, auth=(CTRL_ID, CTRL_PW))
        DEVICE_INFO = result.json().get("devices", [])

        for device in DEVICE_INFO:
            SW_DPID = device["id"]
            print(f"Processing SW_DPID: {SW_DPID}")
            ONOS_URI_PORTS = f"http://{CTRL_IP}:{CTRL_PORT}/onos/v1/statistics/ports"
            result_ports = requests.get(ONOS_URI_PORTS, auth=(CTRL_ID, CTRL_PW))
            SW_STATE_INFO = result_ports.json().get("statistics", [])

            for state_info in SW_STATE_INFO:
                if state_info["device"] == SW_DPID:
                    for port in state_info["ports"]:
                        MATCH_PORT = port["port"]
                        RX_BYTE_COUNT = port["bytesReceived"]
                        TX_BYTE_COUNT = port["bytesSent"]
                        DURATION_TIME = port["durationSec"]

                        FILE_NAME = f"dpid_{SW_DPID.replace(':', '')}_port_{MATCH_PORT}"
                        FILE_DIR = f"./data/{FILE_NAME}.log"

                        # 파일이 없으면 새로 생성
                        if not os.path.exists(FILE_DIR):
                            data = f"{TX_BYTE_COUNT}_{RX_BYTE_COUNT}_{DURATION_TIME}"
                            FILE_WRITE(FILE_DIR, data)
                        else:
                            # 파일이 있으면 데이터 읽기
                            DATA = FILE_READ(FILE_DIR).split("_")
                            PREVIOUS_TX_BYTE_COUNT = float(DATA[0])
                            PREVIOUS_RX_BYTE_COUNT = float(DATA[1])
                            PREVIOUS_DURATION_TIME = float(DATA[2])

                            CURRENT_TX_BYTE_COUNT = float(TX_BYTE_COUNT)
                            CURRENT_RX_BYTE_COUNT = float(RX_BYTE_COUNT)
                            CURRENT_DURATION_TIME = float(DURATION_TIME)

                            data = f"{TX_BYTE_COUNT}_{RX_BYTE_COUNT}_{DURATION_TIME}"
                            FILE_WRITE(FILE_DIR, data)

                            # Duration Time이 0일 경우 로그 출력
                            if CURRENT_DURATION_TIME - PREVIOUS_DURATION_TIME == 0:
                                print(f"Duration time is 0 for Port No. {MATCH_PORT}. The SDN controller has not updated.")
                            else:
                                # Throughput 계산
                                TX_THROUGHPUT = (CURRENT_TX_BYTE_COUNT - PREVIOUS_TX_BYTE_COUNT) * 8 / (CURRENT_DURATION_TIME - PREVIOUS_DURATION_TIME)
                                RX_THROUGHPUT = (CURRENT_RX_BYTE_COUNT - PREVIOUS_RX_BYTE_COUNT) * 8 / (CURRENT_DURATION_TIME - PREVIOUS_DURATION_TIME)

                                TX_THROUGHPUT = round(TX_THROUGHPUT, 4)
                                RX_THROUGHPUT = round(RX_THROUGHPUT, 4)

                                print(f"Port No. : {MATCH_PORT}")
                                print(f"TX_THROUGHPUT = {TX_THROUGHPUT} bps")
                                print(f"RX_THROUGHPUT = {RX_THROUGHPUT} bps")

    except Exception as error:
        print(f"Error: {error}")

CTRL: Controller의 준말 DPID: (Device Port Identifier) OpenFlow 프로토콜에서 각 스위치를 식별하기 위해 사용되는 64비트 길이의 식별자

이어서, 앞에 작성한 task.py의 Celery Task함수 "ONOS_CELERY_TASK"가 매 3초마다 호출되도록 "celeryconfig.py"파일을 생성해, 스케줄링 내용을 아래와 같이 작성한다. 참고로, celery는 celery Beat이라는 스케줄러를 통해 Task들의 실행 순서를 결정할 수 있는데, 여기서 작성하는 "celeryconfig.py"파일 내용을 가지고 Celery Beat을 통해 Task가 매 3초간 수행되게 된다.

from datetime import timedelta

# ONOS의 IP/Port/ID/PW 정의
CTRL_IP = "192.168.224.128"
CTRL_PORT = "8101"
CTRL_ID = "karaf"
CTRL_PW = "karaf"

# task.ONOS_CELERY_TASK(task.py 파일에 정의된 ONOS_CELERY_TASK)의 스케줄링 정보 정의
beat_schedule = {
    'add-every-3-seconds': {
        'task': 'task.ONOS_CELERY_TASK',
        'schedule': timedelta(seconds=3),
        'args': (CTRL_IP, CTRL_PORT, CTRL_ID, CTRL_PW)
    }
}

# 타임존 설정
timezone = 'UTC'

broker_connection_retry_on_startup = True

💣트러블 슈팅(1) - broker_connection_retry_on_startup = True

• 이 옵션이 필요한 이유는 Celery워커 또는 비트 프로세스가 브로커(RabbitMQ, Redis 등)에 연결할 수 없을 때 자동으로 재시도하도록 설정하기 위함이다.
• 브로커 서비스가 아직 시작하지 않았거나, 일시적으로 응답하지 않을 수 있다. 위 옵션을 설정하면, 연결 실패 시 바로 종료되지 않고 일정 시간 동안 재시도를 시도한다.
• 🔍초기값이 False인 이유? 초기 재시도 시 무한 루프처럼 실행되는 것을 방지하기 위해서이다.

해당 Task를 CeleryBeat를 통해 3초 단위로 실행할 것이므로 -B 옵션을 포함하여 아래와같은 명령어를 실행한다.

Celery Beat: 주기적으로 작업을 스케줄링하여 실행할 수 있도록 해주는 Celery의 확장 패키지

성공적으로 Celery가 실행되면 아래와같이 Celery서버의 로그화면이 출력되면서 "task.py"에서 작성했던 Celery Task함수 "ONOS_CELERY_TASK"가 호출되는 것을 확인할 수 있다.

그리고 매 3초마다 DPID가 of:0000000000000001인 OVS 스위치 s1의 현재 활성화된 포트 1번, 2번의 송/수신 트래픽 처리량(TX/RX Troughput)이 계산되어 출력되는 것을 알 수 있다.

💣트러블슈팅(2)

1. celerybeat-schedule 파일 문제 celerybeat-schedule파일은 Celery Beat가 작업 일정을 관리하기 위해 사용하는 데이터베이스 파일이다. 이 파일은 일정이 저장되어 있으므로, 비정상적인 종료나 파일 손상이 발생하면 Beat 프로세스가 해당 파일을 읽을 수 없어 오류를 발생시킨다.

-> 따라서, 파일이 손상된 경우에는 rm 명령어로 해당 파일을 지우고, 다시 Beat 프로세스를 실행해야한다. 2. -n 옵션을 통해 워커 이름을 실행 때마다 변경해주어야 한다. Celery 워커는 이름을 기준으로 프로세스를 구분한다. 기본적으로 여러 개의 동일한 이름을 가진 워커가 동시에 실행되면, 충돌이 발생한다. 즉, PID가 겹치고 메시지 큐 관리에서 문제가 생기는 것이다. 같은 이름의 워커가 이미 실행 중이면 Address already in use 또는 Another worker with the same name exists 등의 오류가 발생할 수 있다. -> 즉, -n옵션을 사용해 각 워커가 고유한 이름을 가지도록 설정해야한다.

3️⃣ InfluxDB 구성

InfluxDB는 시계열 데이터를 저장하고 관리하는 오픈소스 데이터베이스이다. 주로 온도, 시간, 속도 등 시간별 수치로 측정될 수 있는 시계열 데이터에 특화되어있다. 그래서 이번엔 해당 InfluxDB에다가 앞서 Celery를 통해 매 3초마다 계산되는 송/수신 트래픽처리량(TX/RX Throughput) 정보를 주기적으로 한 번 저장해볼 것이다.

influxdb와 influxdb-client 패키지를 아래와 같이 설치한다.

• sudo service influxdb start: InfluxDB 실행
• influx: influxDB CLI환경으로 접속됨. 버전 확인도 가능
• 트래픽처리량을 저장하기위한 sdn이라는 DB 생성, 확인, influxDB CLI종료

그리고, 생성한 데이터베이스 sdn에 매 3초간 Celery Task로 계산되는 송/수신 트래픽처리량을 저장하기 위해 먼저 InfluxDB의 Python패키지를 아래와같이 설치한다.

그리고, task.py파일을 열어서, 최상단에는 InfluxDBClient라는 파이썬 모듈을 가져와 InfluxDB에 데이터를 저장해주기 위한 함수 InfluxDB_InsertData()를 아래와같이 저장해주고, 송/수신 트래픽처리량을 계산하는 소스코드 아래에 계산된 트래픽처리량을 InfluxDB에 저장할 수 있도록 위쪽과 들여쓰기를 맞추어서 InfluxDB_InsertData()를 호출하는 코드를 추가해준다.

from celery import Celery
import json
import requests
import os
from influxdb import InfluxDBClient  # InfluxDB 라이브러리 import

# Broker(RabbitMQ) 설정
app = Celery('ONOS_TASK', broker='pyamqp://guest@localhost//')

# celeryconfig.py에 정의한 Celery Task 환경설정 정보 가져오기
app.config_from_object('celeryconfig')

# InfluxDB에 데이터 저장 함수 정의
def InfluxDB_InsertData(dpid, port_no, tx_throughput, rx_throughput):
    DB_HOST = "192.168.224.128"  # InfluxDB 호스트 IP
    DB_PORT = "8086"         # InfluxDB 포트
    DB_USER = "root"         # InfluxDB 사용자 ID
    DB_PSWD = "root"         # InfluxDB 비밀번호
    DB_NAME = "sdn"          # InfluxDB 데이터베이스 이름

    json_body = [{
        "measurement": dpid,
        "tags": {
            "port": port_no
        },
        "fields": {
            "tx_throughput": tx_throughput,
            "rx_throughput": rx_throughput
        }
    }]

    client = InfluxDBClient(DB_HOST, DB_PORT, DB_USER, DB_PSWD, DB_NAME)
    print(f"Write points: {json_body}")
    client.write_points(json_body)

# ONOS REST API를 통해 조회된 정보를 파일로 저장하기 위한 함수 정의
def FILE_WRITE(file_dir, data):
    with open(file_dir, 'w') as f:
        f.write(data)

# 파일로 저장된, ONOS REST API를 통해 조회된 정보를 읽어오기 위한 함수 정의
def FILE_READ(file_dir):
    with open(file_dir, 'r') as f:
        data = f.readline()
    return data

# Celery를 통해 실행시켜줄 ONOS TASK "ONOS_CELERY_TASK" 함수 정의
@app.task
def ONOS_CELERY_TASK(CTRL_IP, CTRL_PORT, CTRL_ID, CTRL_PW):
    try:
        ONOS_URI = f"http://{CTRL_IP}:{CTRL_PORT}/onos/v1/devices"
        result = requests.get(ONOS_URI, auth=(CTRL_ID, CTRL_PW))
        DEVICE_INFO = result.json()["devices"]

        # ONOS REST API를 통해 스위치별 Port 상태 조회
        for device in DEVICE_INFO:
            SW_DPID = device["id"]
            print(f"SW_DPID: {SW_DPID}")
            ONOS_URI = f"http://{CTRL_IP}:{CTRL_PORT}/onos/v1/statistics/ports"
            result = requests.get(ONOS_URI, auth=(CTRL_ID, CTRL_PW))
            SW_STATE_INFO = result.json()["statistics"]

            for state in SW_STATE_INFO:
                if state["device"] == SW_DPID:
                    for port in state["ports"]:
                        MATCH_PORT = port["port"]
                        RX_BYTE_COUNT = port["bytesReceived"]
                        TX_BYTE_COUNT = port["bytesSent"]
                        DURATION_TIME = port["durationSec"]
                        FILE_NAME = f"dpid_{SW_DPID.replace(':', '')}_port_{MATCH_PORT}"
                        FILE_DIR = f"./data/{FILE_NAME}.log"

                        if not os.path.exists(FILE_DIR):
                            data = f"{TX_BYTE_COUNT}_{RX_BYTE_COUNT}_{DURATION_TIME}"
                            FILE_WRITE(FILE_DIR, data)
                        else:
                            DATA = FILE_READ(FILE_DIR).split("_")
                            PREVIOUS_TX_BYTE_COUNT = float(DATA[0])
                            PREVIOUS_RX_BYTE_COUNT = float(DATA[1])
                            PREVIOUS_DURATION_TIME = float(DATA[2])

                            CURRENT_TX_BYTE_COUNT = float(TX_BYTE_COUNT)
                            CURRENT_RX_BYTE_COUNT = float(RX_BYTE_COUNT)
                            CURRENT_DURATION_TIME = float(DURATION_TIME)

                            data = f"{TX_BYTE_COUNT}_{RX_BYTE_COUNT}_{DURATION_TIME}"
                            FILE_WRITE(FILE_DIR, data)

                            if CURRENT_DURATION_TIME - PREVIOUS_DURATION_TIME == 0:
                                print(f"The SDN controller has not updated The Port No. {MATCH_PORT} State!!")
                            else:
                                TX_THROUGHPUT = (CURRENT_TX_BYTE_COUNT - PREVIOUS_TX_BYTE_COUNT) * 8 / (
                                    CURRENT_DURATION_TIME - PREVIOUS_DURATION_TIME)
                                RX_THROUGHPUT = (CURRENT_RX_BYTE_COUNT - PREVIOUS_RX_BYTE_COUNT) * 8 / (
                                    CURRENT_DURATION_TIME - PREVIOUS_DURATION_TIME)

                                TX_THROUGHPUT = round(TX_THROUGHPUT, 4)
                                RX_THROUGHPUT = round(RX_THROUGHPUT, 4)

                                print(f"Port No. : {MATCH_PORT}")
                                print(f"TX_THROUGHPUT = {TX_THROUGHPUT} bps")
                                print(f"RX_THROUGHPUT = {RX_THROUGHPUT} bps")

                                # InfluxDB에 트래픽 처리량 저장
                                InfluxDB_InsertData(SW_DPID, MATCH_PORT, TX_THROUGHPUT, RX_THROUGHPUT)

    except Exception as error:
        print("Error:", error)

이렇게 수정한 task.py파일이 정상적으로 동작하는지 Celery서버를 실행한다. 아래 사진과같이 정상적으로 실행되었다면, 로그 화면에서 influxDB에 저장되는 데이터 정보를 확인할 수 있다. 로그 내용을 살펴보면 DPID가 of:0000000000000001인 OVS스위치의 현재 활성화된 1번,2번 포트의 송수신 트래픽 처리량 값이 계산되어 JSON형식으로 influxDB에 전달되는 것을 알 수 있다.

이제는 InfluxDB에 실제로 데이터가 저장되었는지 확인해보자. InfluxDB CLI에 접속하여 앞서 생성했던 "sdn" DB를 선택한다. 그리고 select문을 통해 저장된 데이터를 조회해보면, 시간대별로 Celery Task가 실행되면서 저장된 스위치 포트별 송/수신 트래픽 처리량 데이터 정보를 확인할 수 있다.

4️⃣ Grafana 구성

지금까지 Celery Task를 통해 송수신 트래픽처리량도 계산했고, 이를 InfluxDB라는 시계열 데이터베이스에 저장도 했다.

이번에는 Grafana라는 데이터 시각화 도구를 통해 InfluxDB에 저장된 트래픽처리량 데이터를 실시간 그래프로 출력하는 과정이다.

먼저, grafana를 다운받아야한다. 위 사진의 url로 접근하여, Ubuntu and Debien에서 grafana 다운로드 부분을 복사한다. 복사해온 명령어를 실행시켜주면 된다. 위의 wget은 설치파일을 받아오는 것이다. 이제 받은 파일을 가지고 Grafana를 PC에 설치해준다.

grafana를 실행한 뒤 Grafana UI(192.168.224.128:3000)에 접속하자. 위 사진처럼 로그인 화면이 뜨면 성공이다.

다음으로는 Grafana와 InfluxDB를 연동해야한다. 로그인화면에서는 초기아이디,패스워드인 admin/admin을 입력하고 로그인한다. influxDB로 data source를 만들어주면 된다.

save&test 버튼을 누른다.

Mininet CLI로 접속해서 h1에서 h2로 ping메시지를 보낸다.

💣 트러블슈팅(3)

1. Mininet은 ~(root)에서 접속해야만한다. 예를들어, onos디렉토리 안에서는 접근하려하면 오류가 발생한다.
2. 실행했던 Mininet에서 exit하면, 꼭 sudo mn --clear 명령어를 통해 지워주어야한다. 지워주지 않으면 다시 Mininet CLI로 접속이 되지 않는다.

그리고, 다른 터미널에서 ping 정보를 DB에 저장해주어야 grafana에 그래프로 반영이 된다. 기존에 만들어두었던 것을 실행해주면 된다. 그래프 설정을 아래 사진을 쭉 따라하면 된다. 대시보드와 그래프의 이름은 원하는 것으로 바꾸어도 좋다.

Grafana의 Dashboard를 확인해보면, 현재 가상 호스트 h1에서 h2로 트래픽이 흐르면서 가상 호스트와 연결된 OVS 스위치 1번 포트의 수신 트래픽처리량(RX Throughput)은 약 1.3kbps, 송신 트래픽처리량(TX Throughput)은 약 0.7kbps인 것을 확인할 수 있다.

이 실습은 ununtu 22.04버전, ONOS 2.7.0 버전이 필요하다. vmware와 Ubuntu설치는 검색해보면 자세히 정리된 블로그들이 많다. onos 설치과정은 아래 블로그에 적혀있으니 그대로 따라하면 된다. ONOS 2.7.0, Ubuntu 22.04이용해 mininet 가상 네트워크 연결

위의 포스팅에서는 Mininet기반의 가상 네트워크 환경을 구축하여 Host간 통신이 되도록 flow rule을 reactive, proactive 방식으로 각각 설정해보았다. 이번에는 가상으로만 패킷제어를 해보는 방식이 아닌, 물리적 장치인 라즈베리파이3를 추가하여 진행한다. 라즈베리파이3에 OVS를 설치하여 하나의 SDN스위치를 만들고 여기에 연결된 단말 장치 간 VLAN패킷을 주고받을 수 있도록 ONOS로 flow rule을 설정해보는 것이다.

자 이제 실습을 시작해보자!!

준비물

참고로, 나는 라즈베리파이의 usb 단자와 노트북을 연결하기 위해 usb 이더넷 어댑터를 산 것이다. 사진에는 두 개 라고 나와있지만, 이번 실습에서는 하나는 물리적으로, 하나는 가상으로 구성하여 실습을 진행할 것이다. 최근 노트북은 대부분 c타입으로 연결하기 때문에 usb to c 선 1개 가 있으면 될 것 같다!

1️⃣ ONOS 환경 구축

먼저, 실습을 진행할 컴퓨터를 준비한다. 아래 조건을 만족해야한다.

나의 경우 컴퓨터와 유무선공유기 사이에 인터넷 선을 연결하여 인터넷에 연결했다. pc의 IP주소는 아래 사진처럼 확인할 수 있다.

선행 post부터 쭉 따라했다면, ONOS가 잘 설치되어있을 것이다. 확인한 pc주소를 넣어 명령어를 실행하면 ONOS CLI 접속이 잘 될 것이다. 초기 비밀번호는 karaf이다. 다시 기본 터미널로 나오고싶다면, ctrl+D버튼을 누르면 된다.

SDN의 openflow프로토콜을 지원하는 ONOS의 애플리케이션인 org.onosproject.openflow를 활성화시킨다.

💣 트러블슈팅

명령어를 올바르게 작성했는데 이런 오류가 나온다면, SSH 호스트 키가 변경되어 발생하는 문제이다. 이를 해결하기 위해 known_hosts파일에 저장된 이전 키를 삭제해야한다.

ssh-keygen -f "/home/hyeonseo/.ssh/known_hosts" -R "[192.168.224.128]:8101"

이 명령어를 통해 키를 제거한 후 다시 SSH 연결을 시도하면 잘 된다.

2️⃣ 라즈베리파이 연결

이제 라즈베리파이에 ubuntu를 설치해주어야 하는데, 이 과정에서는 micro sd카드와 micro sd카드 리더기가 필요하다.

raspberry pi imager를 다운로드 한다. raspberry pi imager를 설치한 후 실행해 다음과같이 선택해준다.

저장소는 micro sd카드를 micro sd card 리더기에 연결하여 pc 본체에 연결해주면 저장소 선택이 된다. 운영체제는 기존 컴퓨터에 설치된 버전과 맞춰주면 된다. 나는 22.04버전이 기존 컴퓨터에 설치되어있어서 동일하게 22.04버전으로 선택했다.

세부 설정을 이렇게 바꾸어주어야한다.

그런 후, 완료되었다고 나오면, sd카드를 raspberrypi에 연결해준다. 연결 후 전원 케이블을 뺏다 꽂아주면 초록 불이 깜빡거리며 바로 설치가 된다.

내부 네트워크설정으로 들어가 스크롤을 내려보면, 이렇게 자동할당 되어있는 raspberrypi의 ip주소를 확인할 수 있다.

그리고 putty를 설치해야한다. 동일하게 "putty"를 검색하여 최상단에 나오는 것을 다운로드 받은 후 실행하면 된다. 참고로, sd카드를 라즈베리파이에 삽입한 후 putty에 접속되기까지는 1-2분의 시간이 소요된다! hostname 부분에 아까 확인한 raspberrypi의 ip주소를 넣어준 후, open한다. accept를 하고, imager의 추가 설정에서 설정했던대로 로그인 해주면 된다. ubuntu로 로그인이 잘 되었다.

3️⃣ 물리 연결 Host에 VLAN 설정하기

이번에는 아래와 같이 라즈베리파이에 연결된 usb이더넷 어댑터에 연결되어있는 Host의 vlan을 설정해줄 것이다.

이를 위해서는 호스트에 vmware를 설치하고 ubuntu 22.04LTS 버전을 실행시켜주어야 한다. ubuntu 설치가 완료되었다면, Host1(노트북)의 ubuntu에 접근하여 라즈베리파이와 연결된 이더넷 장치를 확인한 후 vlan 설정을 해줄 것이다. 먼저 vlan을 설치하고, 802.1q모듈을 커널에 올린다. 먼저, 연결된 이더넷의 이름을 확인하기 위해 ip a 명령어를 이용한다. 여기에선 3번에 이더넷이 보인다. 그리곤, vlan을 생성해준다. 다시 ip a를 해보면 vlan이 확인된다.

물리 연결 Host의 인터페이스 vlan10을 조회해보면 아래와같이 ip주소가 20.0.0.1/24로 할당된 것을 확인할 수 있다. 라우팅 테이블을 확인해보았을 때도 20.0.0.0/24대역의 패킷을 보낼 때 vlan10 인터페이스를 이용하는 것을 확인할 수 있다.

4️⃣ 라즈베리파이 OVS 네트워크 구성하기

일단 라즈베리파이에 Open vSwitch(이하 OVS)를 설치해준다. 설치가 성공적으로 완료되었다면 아래와같이 OVS 설치버전이 조회된다.

br-int라는 브릿지를 하나 생성하자.

내가 사용하는 ONOS 2.7.0버전은 OpenFlow 1.0 및 1.3을 지원한다고 한다. 따라서, 해당 버전을 사용하도록 설정해준다. 이 설정을 하지 않을 경우 ONOS가 지원하는 OpenFlow버전과 일치하지 않아, OVS 브릿지 'br-int'가 ONOS와 연결 수립이 되지 않을 수 있다.

이렇게 생성됭 OVS 브릿지 br-int의 상태를 조회해보면 아래와 같이 br-int란 브릿지에 br-int라는 포트가 현재 생성된 상태임을 알 수 있다.

다음으로 생성한 br-int 브릿지에 포트를 생성해 라즈베리파이의 이더넷 포트(enxc84d4420046d)를 연결해준다.

이더넷 포트의 이름은 ip a명령어를 통해 확인했다.(2번에 이더넷 포트가 쓰여있다.)

5️⃣ OVS 브릿지에 ONOS 연결하기

ONOS가 OVS 브릿지 br-int에 연결되기 위해서는 ONOS와 OVS 브릿지 br-int가 동일한 네트워크 대역으로 묶여 서로 통신을 할 수 있어야 한다. 이를 위해 라즈베리파이에 접속하여 /etc/netplan 내부의 파일을 확인한다. 나는 50-cloud-init.yaml파일이 존재했다. 이는 다를 수 있으니 직접 확인해보아야 한다. 그리고, 이 파일을 다음과같이 수정해주어야 한다. 이 또한 라즈베리파이의 ip주소에 따라 다르니, 본인의 상황에 맞는 ip주소,대역 설정을 해주어야 한다.

network:
  version: 2
  renderer: networkd
  wifis:
    wlan0:
      dhcp4: no
      addresses:
        - 192.168.0.137/24  # 실제 무선 네트워크 IP
      gateway4: 192.168.0.1  # 공유기/라우터의 게이트웨이 IP
      nameservers:
        addresses:
          - 8.8.8.8  # Google DNS
      access-points:
        'Wi-Fi SSID':  
          password: "네트워크 비밀번호"

  bridges:
    br-int:
      interfaces:
        - wlan0  # 무선 네트워크 인터페이스를 브릿지에 연결
      dhcp4: no
      addresses:
        - 192.168.0.200/24  # 브릿지용 고정 IP (무선 네트워크와 같은 대역)
      gateway4: 192.168.0.1  # 공유기/라우터의 게이트웨이
      nameservers:
        addresses:
          - 8.8.8.8

• 브릿지용 고정 IP는 처음에 확인했듯이 사용중인 IP주소 정보를 보고, 사용하지 않는 IP로 해주어야 한다. 나의 경우 200은 사용중이지 않다.
• 공유기/라우터의 게이트 웨이 IP를 확인하는 방법은 다음과 같다. default에 쓰여있는 것이 게이트웨이 ip이다.

이렇게 netplan내부의 파일을 수정한 후 적용해준다.

지난번에 설치했던 onos를 실행해줄 것이다. 먼저, bazel을 이용해 onos를 실행해주어야 한다. 시간이 조금 걸리니, 마음을 편히 먹고 기다리자. 이렇게하면, 8101포트가 활성화된다. 다른 터미널을 열어서 다음과같이 확인할 수 있다. 접속이 되었다.

이후, ONOS GUI에 접근한다. 접근 주소는 다음과 같다.

http://{ONOS 설치 IP주소}:8181/onos/ui/index.html

6️⃣ 가상 HOST 설정하기

미니넷을 설치하여 접속한다. sudo mn --controller=remote,ip=192.168.224.128,port=6653 --switch=ovs,protocols=OpenFlow13 이 명령어를 통해 Mininet CLI로 접근할 수 있다. 참고로, 이 CLI에서 나오려면 exit을 치면 된다. 이번 실습에서는 host 하나만 필요하지만, 미니넷에서는 호스트 하나만 만드는게 불가하다. 컨트롤러와 스위치도 함께 만들어진다.

이제는 물리연결 HOST와의 ping을 위해 미니넷 호스트를 설정해야하는데, sudo ovs-vsctl set port h1-eth0 tag=10으로 한다.

7️⃣ Flow Rule 설정하기

현재 상태를 보면 라즈베리파이에서 br-int 브릿지가 있고, Mininet에 가상 스위치 s1과 가상 호스트 h1(10.0.0.1) 및 h2(10.0.0.2)가 생성된 상태이다. 또한 br-int에 실제 물리 네트워크 인터페이스가 연결되어 있다.

이제 호스트 간 ping 테스트를 위한 플로우 엔트리 설정을 위해 ONOS에 JSON 파일을 작성하여 플로우 규칙을 추가해야 한다. flow_h1_to_host2.json

{
  "flows": [
    {
      "priority": 40000,
      "timeout": 0,
      "isPermanent": true,
      "deviceId": "of:0000000000000001",
      "treatment": {
        "instructions": [
          {
            "type": "L2MODIFICATION",
            "subtype": "VLAN_PUSH",
            "vlanId": 10
          },
          {
            "type": "OUTPUT",
            "port": "enxc84d4420046d"
          }
        ]
      },
      "selector": {
        "criteria": [
          {
            "type": "ETH_TYPE",
            "ethType": "0x0800"
          },
          {
            "type": "VLAN_VID",
            "vlanId": 10
          },
          {
            "type": "IPV4_SRC",
            "ip": "10.0.0.1/32"
          },
          {
            "type": "IPV4_DST",
            "ip": "20.0.0.1/32"
          }
        ]
      }
    },
    {
      "priority": 40000,
      "timeout": 0,
      "isPermanent": true,
      "deviceId": "of:0000000000000001",
      "treatment": {
        "instructions": [
          {
            "type": "OUTPUT",
            "port": "s1-eth1"
          }
        ]
      },
      "selector": {
        "criteria": [
          {
            "type": "ETH_TYPE",
            "ethType": "0x0800"
          },
          {
            "type": "VLAN_VID",
            "vlanId": 10
          },
          {
            "type": "IPV4_SRC",
            "ip": "20.0.0.1/32"
          },
          {
            "type": "IPV4_DST",
            "ip": "10.0.0.1/32"
          }
        ]
      }
    }
  ]
}

deviceId: br-int 브릿지의 OpenFlow ID (onos> devices 명령어로 확인 가능). port: h1 -> br-int → Host2: 물리 포트(enxc8...)로 출력. Host2 -> br-int → h1: 가상 포트(s1-eth1 등)로 출력.

그리고 위에 작성한 json파일을 적용하는 명령어이다. onos에서 flows를 쳤을 때, br-int OpenFlowId부분을 확인해보면, priorty, deviceId, selector 등의 정보가 등록된 것을 확인할 수 있다.

❓ VLAN을 사용하는 이유?

VLAN(Virtual Local Area Network) 하나의 물리적 네트워크를 여러개의 가상 네트워크로 나누는 기술이다. 장비에 VLAN태그를 추가하여 특정 네트워크 트래픽을 격리하거나 구분함. VLAN태그를 통해 같은 네트워크 스위치를 이용하지만, 서로 다른 VLAN에 속한 장치들은 기본적으로 서로 통신할 수 없다.

현재 구성에서 VLAN을 사용한 이유는 가상 HOST에서 br-int(OVS)를 거쳐 물리 연결 HOST로 패킷이 이동할 때, 네트워크 환경을 VLAN 10으로 구분한다. 즉, VLAN 10 태그가 없는 트래핏은 해당 포트를 통과하지 못하는 것이다.

만일 호스트 간 패킷이 VLAN 태그 없이 전송되면, 다른 VLAN트래픽과 충돌하거나 의도치 않게 외부로 노출될 수 있다. 또한, OVS나 ONOS 플로우 설정에서 VLAN 태그를 필터링하지 않으면, 모든 패킷이 해당 경로로 전송될 수 있어 보안 및 네트워크 정책이 무너질 수 있다.

8️⃣ 실습 실패의 원인

flow rule까지 등록을 다 했는데, 결론은 ping테스트가 성공하지 못했다.

mininet으로 만든 가상 스위치인 s1과 라즈베리파이에서 만든 ovs인 br-int의 컨트롤러가 각각 존재했기 때문에 ONOS를 통한 패킷제어가 애초에 불가능했다.

기존의 블로그에서는 HOST 두 개와 라즈베리파이, ONOS를 설치한 컴퓨터 전부를 유선으로 연결하여 같은 대역에서 패킷제어를 시도했기 때문에 가능했던 것이었다.

나의 경우 라즈베리파이의 유선연결이 되지 않아, 무선연결로 수행했고, 준비했던 두 개의 Host 중 하나의 Host가 오래된 노트북이었어서 이더넷 선 연결을 인식하지 못하여 Host를 하나밖에 연결하지 못했다.

그럼에도 불구하고, 이번 실습을 통해 ONOS의 패킷 라우팅 구조와 원리에 대해 깊이있게 이해할 수 있게 되었다는 점에 있어서 큰 의의가 있었던 실습이라고 생각한다.

window 사용자 기준 Ubuntu를 실행하기 위한 가상머신이 필요합니다! 저는 vmware을 설치하여 사용했습니다.

그리고, Ununtu 22.04버전 이미지를 다운로드받아서, vmware에서 실행시켜주면 됩니다.

ONOS 설치 블로그 위 블로그를 참고하여 ONOS를 설치했습니다. 그대로 쭉 따라하시면 잘 설치 될겁니다! 저는 이렇게 설치가 잘 되었습니다.

ONOS CLI를 실행하는데, 먼저 컴퓨터의 IP주소를 알아야 해요!

ip route | grep default 

위 명령어를 통해 공유기의 IP주소를 확인했습니다. 저는 192.168.224.2 인 것으로 확인했습니다.

그 다음으로는 pc의 주소인데,

ip addr show 

위 명령어를 통해 192.168.224.128인 것을 확인했습니다.

그러면 이렇게 본인의 IP주소를 넣어 ONOS에 접속할 수 있습니다. 초기 비밀번호는 karaf입니다. -p 옵션은 포트번호를 지정합니다. 로컬인 클라이언트가 ONOS 컨트롤러로 SSH 연결을 시도할 때 서버의 8101포트를 통해서 SSH 요청을 보내도록 지정하는 것입니다. 즉, 나가는 포트는 랜덤한 동적 포트로 설정되지만, ONOS컨트롤러는 고정된 포트(여기서는 8101) 포트로 SSH 연결을 수신합니다.

이제는 가상 네트워크를 구성해서 OpenFlow 프로토콜을 기반으로 ONOS와 연결해볼 것입니다.

여기에서 OpenFlow는 SDN에서 사용하는 프로토콜입니다!

OpenFlow를 사용하기 위해서는 ONOS CLI로 접속하여 OpenFlow프로토콜을 지원하는 ONOS 애플리케이션인 'org.onosproject.openflow'를 활성화 해주어야 합니다. 다음과 같이 진행합니다. 두 번째로 친 명령어는 현재 실행중인 앱을 조회하는 명령어입니다. openflow 관련 애플리케이션들이 실행되는 것을 확인할 수 있습니다.

그리곤, 다른 터미널을 열어 apt-get을 이용해 mininet을 설치해주어야 합니다.

sudo apt-get install mininet

오픈소스 SW인 OpenFlow 기반의 가상 스위치를 제공해주는 Open vswitch(이하 OVS)도 패키지 관리도구인 apt-get으로 설치해줍니다.

sudo apt-get install openvswitch-switch

설치가 완료되면, mininet으로 1개의 OVS 스위치(s1)에 두 개의 가상 Host(h1,h2)와 ONOS 제어기(c0)가 연결되도록 가상네트워크를 구성하기 위해서

아까 확인했던 pc의 ip주소를 넣어 명령어를 실행시켜 주면 됩니다. 명령어의 옵션은 위와 같습니다.

명령어 실행 후, ONOS CLI에서 현재 ONOS와 연결된 스위치 정보를 조회해보면 OVS 스위치 1대가 ONOS와 연결이 되었음을 확인할 수 있습니다.

mininet cli에서 ping테스트를 해보면, 아직 flow rule을 설정하지 않아 서로 메시지를 주고받을 순 없다고 나옵니다.

Mininet으로 가상 네트워크 구조 파악하기

nodes 명령어를 통해 확인해보면, c0,h1,h2,s1 이렇게 4개의 Node가 생긴 것을 확인할 수 있습니다.

이러한 상황입니다. 여기에서 각 Node들의 interface정보들을 확인해보면,

• h1은 h1-eth0인터페이스에 IP주소 10.0.0.1 할당
• h2는 h2-eth0인터페이스에 IP주소 10.0.0.2 할당
• OVS 스위치 s1에는 eth1,eth2인터페이스 생성
• onos에 해당하는 node인 c0는 ip주소/포트 192.168.224.128/6653 dump와 net 명령어를 통해 더 자세히 확인할 수 있습니다. dump는 인터페이스 ip주소를 보여주고, net은 각 node들의 네트워크 인터페이스 별 연결정보를 알려줍니다. h1의 h1-eth0 인터페이스는 OVS 스위치 s1의 s1-eth1 인터페이스와 연결되고, 호스트 h2의 h2-eth0 인터페이스는 OVS 스위치 s1의 s1-eth2인터페이스와 연결되어있는 것을 확인할 수 있습니다. ONOS인 c0는 당연하게 OVS 스위치 s1과 local로 연결되므로, Mininet으로 살펴본 가상 네트워크 구성은 이러합니다.

ONOS가 바라본 가상 네트워크 구조 파악하기

ONOS가 바라보는 가상 네트워크 구조는 앞서 Mininet으로 파악한 가상 네트워크 구조와 동일하지만, ONOS는 직접 Flow Rule을 설정해주어야 하기 때문에 각 장치별 요소를 구분하기 위한 값이 Mininet을 통해 파악한 것과는 조금 다릅니다.

먼저 ONOS CLI로 접속하여 현재 연결된 OVS 스위치 정보를 조회해보면, Mininet에서는 s1이라는 노드로 표현되었지만, 여기서는 of:0000000000000001라는 고유의 장치 ID 값을 가집니다.

이번에는 hosts명령어를 통해 확인한 것입니다. locations=[of:0000000000000001/2]는 호스트 of:0000000000000001가 스위치의 2번포트에 연결되어있음을 의미합니다.

이 사진이 최종 연결구조입니다.

h1이 연결된 OVS 스위치(s1)의 s1-eth1 인터페이스는 1번 포트이고, h2가 연결된 s1-eth2는 2번 포트로 인식됨을 확인할 수 있습니다.

이제 이렇게 최종 확인된 가상 네트워크 구조를 가지고, ONOS의 Flow Rule 설정을 통해 두 Host 간 통신이 되도록 해볼 것입니다.

Flow Rule 설정하기 - reactive mode

Openflow 프로토콜에서는 flow rule 설정 방식이 두 가지 있습니다. 하나는 flow rule이 정의되지 않은 미지의 패킷이 SDN 스위치로 유입되었을 때, SDN 제어기에 의해 flow rule이 결정되는 reactive 모드이고, 다른 하나는 네트워크 관리자에 의하여 SDN 스위치에 미리 flow rule을 등록하는 proactive 모드입니다.

reactive모드를 실행하기 위해서는 ONOS CLI에서 org.onosproject.fwd애플리케이션을 실행시켜야 합니다. 이 애플리케이션은 packet-in메시지를 SDN 제어기인 ONOS로 보내도록 flow rule을 설정하여 ONOS가 reactive모드로 동작하도록 합니다. 명령어가 잘 실행되었습니다. mininet cli에서 다시 ping을 보내보면, 기존에는 안되던 h1과 h2의 ping이 성공적으로 잘 수행된 것을 확인할 수 있습니다. ONOS를 통해 직접 flow rule이 OVS 스위치 s1에 설정된 것입니다. ONOS CLI에서 flows 명령어를 통해 flow rule을 조회해보면 ADDED상태로 추가된 rule을 확인할 수 있습니다.

Flow Rule 설정하기 - Proactive 모드

이제부터는 ONOS에서 제공하는 REST API를 활용해서 Proactive모드로써 직접 Flow Rule을 설정해볼 것입니다. 일단 ONOS CLI에 접속하여 Reactive 모드를 테스트하기 위해 앞서 실행했던 org.onosproject.fwd를 비활성화해줍니다.

그리고 flow_rule_post.sh라는 스크립트 파일을 만들 것입니다. 이 스크립트 파일은 ONOS REST API를 이용해서 JSON파일로 정의된 Flow Rule을 해당 OVS 스위치에 설정하는 역할을 수행합니다. flow_rule_post.sh에는 아래 내용을 넣어주면 됩니다. 역시 IP주소는 바꾸어 넣어야 합니다.

ONOS_IP=192.168.224.128
ONOS_PORT=8181

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d @$1 "http://$ONOS_IP:$ONOS_PORT/onos/v1/flows/" --user karaf:karaf

이제 flow rule을 정의해볼 것입니다. h1에서 h2로 데이터를 보낼 수 있도록 OVS스위치 s1의 1번포트로 패킷이 들어오면 2번포트로 내보내라는 flow rule을 정의해볼 것입니다. 이를 위해 OVS 스위치 s1의 입력포트(IN_PORT)는 1번, 출력포트(OUTPUT)는 2번으로 지정된 flow rule을 5000이라는 우선순위를 적용하여 flow_h1_to_h2.json라는 JSON포맷 파일로 생성합니다.

{
  "flows": [
    {
      "priority": "50000",
      "timeout": 0,
      "isPermanent": true,
      "deviceId": "of:0000000000000001",
      "treatment": {
        "instructions": [
          {
            "type": "OUTPUT",
            "port": "2"
          }
        ]
      },
      "selector": {
        "criteria": [
          {
            "type": "IN_PORT",
            "port": "1"
          }
        ]
      }
    }
  ]
}

이번에는 반대로 h2에서 h1으로 데이터를 보낼 수 있도록 OVS스위치 s1의 2번 포트로 패킷이 들어오면 1번 포트로 내보내라는 Flow Rule을 정의해볼 것입니다. 이를 위해 OVS 스위치 s1 (of:0000000000000001) 의 입력포트 (IN_PORT) 는 2번, 출력포트 (OUTPUT) 는 1번으로 지정된 Flow Rule을 5000이라는 우선순위 (Priority) 를 적용해 'flow_h2_to_h1.json' 라는 JSON 포맷 파일로 생성합니다.

{
  "flows": [
    {
      "priority": "50000",
      "timeout": 0,
      "isPermanent": true,
      "deviceId": "of:0000000000000001",
      "treatment": {
        "instructions": [
          {
            "type": "OUTPUT",
            "port": "1"
          }
        ]
      },
      "selector": {
        "criteria": [
          {
            "type": "IN_PORT",
            "port": "2"
          }
        ]
      }
    }
  ]
}

편의를 위해 생성한 파일의 권한까지 변경해준 모습입니다.

JSON 파일로 정의한 Flow Rule 파일 (flow_h2_to_h1.json, flow_h2_to_h1.json) 들을 먼저 앞에서 작성한 flow_rule_post.sh 스크립트 파일을 이용하여, ONOS를 통해 OVS 스위치 s1 (of:0000000000000001) 로 Flow Rule 정보를 등록해줍니다. Flow Rule이 정상적으로 내려갔다면 스위치 s1의 Device ID와 등록한 Flow Rule의 ID 값이 출력됩니다.

./flow_rule_post.sh flow_h1_to_h2.json flow_h2_to_h1.json

./flow_rule_post.sh flow_h2_to_h1.json

ONOS CLI로 접근하여 실제 등록된 FlowRule정보를 확인해보면, 성공적으로 등록된 것을 확인할 수 있습니다. 이제 네트워크 구조를 도식화해보면 다음과 같습니다. 이 사진 역시 블로그에서 가져온 것이라 세부적 flow Id, c0 address, MAC address는 다릅니다. flow rule이 등록된 상태에서 mininet CLI를 통해 h1과 h2의 ping테스트를 해보면 성공적으로 수행되는 것을 확인할 수 있습니다.

먼저 h1에서 h2로 Ping 메시지를 보낼 경우, h1은 h2의 MAC 주소를 알아내기 위해 ARP 요청 메시지를 보내고, 해당 메시지는 OVS 스위치 s1의 1번포트로 전달됩니다. 이때 OVS 스위치 s1은 메시지의 처리를 위해 자신의 Flow Table에 등록된 Flow Rule을 찾아봅니다. Flow Table에서 입력포트 (IN_PORT) 가 1번인 Match Field가 일치하여, 해당 ARP 요청 메시지는 출력포트 (OUTPUT) 인 OVS 스위치 s1의 2번포트를 통해서 h2로 전달됩니다.

h1로부터 ARP 요청 메시지를 받은 h2는 자신의 MAC 주소를 포함한 ARP 응답 메시지를 보내고, 해당 메시지는 OVS 브릿지 s1의 2번포트로 전달됩니다. 이때 OVS 스위치 s1은 메시지의 처리를 위해 자신의 Flow Table에서 Flow Rule을 찾아봅니다. Flow Table에서 입력포트 (IN_PORT) 가 2번인 Match Field가 일치하여, 해당 ARP 응답 메시지는 출력포트 (OUTPUT) 인 OVS 스위치 s1의 1번포트를 통해서 h1로 전달됩니다.

h2로부터 ARP 응답 메시지를 전달받은 h1은 해당 메시지에 포함된 h2의 MAC 주소를 파악하고 해당 MAC 주소를 이용하여 ICMP 요청 메시지를 h2에 전달합니다. 이때 해당 메시지는 OVS 스위치 s1의 1번 포트로 제일 먼저 전달되며, OVS 스위치 s1은 메시지의 처리를 위해 자신의 Flow Table에 등록된 Flow Rule을 찾아봅니다. Flow Table에서 입력포트 (IN_PORT) 가 1번인 Match Field가 일치하여, 해당 ICMP 요청 메시지는 출력포트 (OUTPUT) 인 OVS 스위치 s1의 2번포트를 통해서 h2로 전달됩니다.

h1로부터 ICMP 요청 메시지(echo request)를 받은 h2는 이에 대한 응답으로 ICMP 응답 메시지(echo reply)를 생성해 h1으로 전달합니다. 이때 해당 메시지는 OVS 브릿지 s1의 2번포트로 먼저 전달됩니다. 그리고 OVS 스위치 s1은 메시지의 처리를 위해 자신의 Flow Table에서 Flow Rule을 찾아봅니다. Flow Table에서 입력포트 (IN_PORT) 가 2번인 Match Field가 일치하여, 해당 ARP 응답 메시지는 출력포트 (OUTPUT) 인 OVS 스위치 s1의 1번포트를 통해서 h1으로 전달됩니다.

여기까지 h1에서 h2로 Ping 메시지를 보내는 동안 OVS 스위치 s1에 등록된 Flow Rule이 어떻게 적용되어 데이터를 전달하는지 살펴보았습니다. h2에서 h1으로 Ping 메시지를 보내는 경우에도 마찬가지로 동일한 방식으로 Flow Rule이 적용되어 통신이 이루어집니다.

mininet이란

가상 네트워크를 통해 SDN이나 Openflow와 같은 네트워크 환경을 시뮬레이션 할 수 있는 오픈 소스 프로그램입니다. Mininet은 가상 스위치, 호스트를 사용해 네트워크를 시뮬레이션하는 소프트웨어로 SDN 및 Openflow와 같은 네트워크 프로토콜을 시험하고 개발하는 데 사용된다고 합니다. Mininet은 python기반으로 작성되었으며, 가상화 기술을 사용해 다중 사용자를 지원하고, 빠르고 쉽게 네트워크를 생성, 시험할 수 있습니다.

Mininet은 학술연구, 프로토타입 및 시스템 테스트, 교육 및 교육용 목적으로 사용됩니다. Mininet은 또한 Openflow 교육 및 SDN 프로토타입 개발 등의 목적으로도 사용됩니다.

mininet 사용해 네트워크 토폴로지 생성해보기.

mininet 설치

from mininet.net import Mininet
from mininet.cli import CLI
from mininet.node import Host
from mininet.node import OVSKernelSwitch
from mininet.log import setLogLevel, info

Mininet: 네트워크를 시뮬레이션하는 객체. CLI: Mininet의 명령어 인터페이스로 사용자가 명령을 입력할 수 있게 함. Host: 가상 호스트를 생성. OVSKernelSwitch: Open vSwitch 기반 스위치를 생성. setLogLevel: 로그 출력 레벨을 설정.

def myTopo():
    net = Mininet( topo=None, autoSetMacs=True, build=False, ipBase='10.0.1.0/24' )

net: Mininet 객체를 생성합니다. topo=None: 사용자 정의 토폴로지를 사용할 것을 의미합니다. autoSetMacs=True: 자동으로 MAC 주소를 설정합니다. build=False: 네트워크는 명시적으로 build() 메서드를 호출할 때까지 빌드되지 않습니다. ipBase='10.0.1.0/24': 호스트들이 사용할 기본 IP 주소 대역입니다.

h1 = net.addHost( 'h1', cls=Host, defaultRoute=None )
h2 = net.addHost( 'h2', cls=Host, defaultRoute=None )
h3 = net.addHost( 'h3', cls=Host, defaultRoute=None )
s1 = net.addSwitch( 's1', cls=OVSKernelSwitch, failMode='standalone' )

net.addHost: 네트워크에 호스트를 추가합니다. h1, h2, h3라는 이름의 호스트를 추가. net.addSwitch: 네트워크에 스위치를 추가합니다. s1이라는 이름의 스위치를 생성. failMode='standalone': 스위치가 컨트롤러 없이 독립적으로 동작합니다.

net.addLink(h1, s1)
net.addLink(h2, s1)
net.addLink(h3, s1)

호스트 h1, h2, h3를 스위치 s1과 연결합니다.

h1.setIP(intf="h1-eth0", ip='10.0.1.2/24')
h2.setIP(intf="h2-eth0", ip='10.0.1.3/24')
h3.setIP(intf="h3-eth0", ip='10.0.1.4/24')

각 호스트의 네트워크 인터페이스에 IP 주소를 설정합니다. 인터페이스 이름: h1-eth0, h2-eth0, h3-eth0. IP 주소:

• h1: 10.0.1.2/24
• h2: 10.0.1.3/24
• h3: 10.0.1.4/24

  net.build()
  net.start()

  build(): 네트워크를 빌드합니다. start(): 네트워크를 시작합니다.

  CLI(net)
  net.stop()

  CLI(net): Mininet 명령어 인터페이스를 시작합니다. 사용자가 명령을 입력해 네트워크 상태를 확인하거나 테스트할 수 있습니다. net.stop(): 네트워크를 종료합니다.

  if __name__ == '__main__':
    setLogLevel("info")
    myTopo()

  setLogLevel("info"): 로그 출력 레벨을 "info"로 설정. myTopo(): 위에서 정의한 네트워크 토폴로지 함수 실행.

pingall명령어를 통해 잘 연결되는 것을 확인할 수 있다.

1. EC2 생성
2. RDS 생성
3. Dockerfile 작성
4. github secrets에 환경변수 선언
5. github-actions.yml 코드 작성

EC2 생성과 RDS 생성은 자료들이 많을 것이라고 생성한다. 주의할 점은 같은 VPC 안에서 생성되어야하기 때문에 RDS 생성 시 기존에 생성해두었던 EC2를 지정해주어야 한다. 같은 VPC안에 있어야 서버에서 RDS를 찾아 생성할 수 있다.

1. EC2 생성

2. RDS 생성

3. DockerFile 작성

프로젝트의 루트 디렉토리 내에 생성하면 된다.

# 베이스 이미지: Java 17 (필요에 따라 Java 버전 변경 가능)
FROM openjdk:17-jdk-slim

# 컨테이너 내부의 작업 디렉토리 설정
WORKDIR /app

# 빌드된 JAR 파일을 컨테이너로 복사
COPY ./build/libs/*.jar app.jar

# 컨테이너에서 열릴 포트
EXPOSE 8080

# 애플리케이션 실행 명령어
ENTRYPOINT ["java", "-jar", "app.jar"]

4. github secrets 환경변수 선언

github actions를 이용할건데, github에 개인정보는 올리면 안되니까 환경변수를 이용한다. 아래의 github-actions.yml 코드 내부에 이용되는 것들을 환경변수로 미리 선언하는 것이다.

YML

YML
spring:
  application:
    name: forest
  profiles:
    group:
      dev: dev, local
      deploy: deploy
    active: dev

YML_DEV

spring:
  datasource:
    url: jdbc:mysql://<엔드포인트>:<포트번호>/<DB인스턴스식별자이름>
    username: <rds 생성 시 지정한 마스터사용자 이름>
    password: <rds 생성 시 지정한 마스터암호>
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update
logging:
  level:
    org.hibernate.SQL: debug

hibernate: ddl-auto: update 데이터베이스 내부에 자동으로 테이블이 만들어지도록 하는 명령어이다. 이 코드를 써주지 않으면 actions파일을 실행시켰을 때 오류가 나므로 꼭 포함시켜주어야한다.

USERNAME

ubuntu

DOCKER_USERNAME

docker 가입할 때 지정한 사용자 이름

DOCKER_PASSWORD

docker 가입할 때 지정한 비밀번호

HOST_DEV

EC2로 할당받은 public IPv4 주소

PRIVATE KEY

ppk파일을 다운로드 했다면, 이를 cat명령어를 이용해 확인한 후, 키 부분을 떼어 위와같이 작성한 후 PRIVATE KEY 환경변수로 등록해준다.

5. github-actions.yml 코드 작성

먼저 루트 디렉토리 내부의 .github 패키지 내부에 workflows 패키지를 만들고, 그 안에 github-actions.yml 파일을 만든다. 나의 경우에는 dev를 실행하도록 코드를 작성했다.

# github repository actions 페이지에 나타날 이름
name: CI/CD using github actions & docker

# event trigger
# main브랜치에 push가 되었을 때 실행
on:
  push:
    branches: [ "main" ]

permissions:
  contents: read

jobs:
  CI-CD:
    runs-on: ubuntu-latest
    steps:

      # JDK setting - github actions에서 사용할 JDK 설정 (프로젝트나 AWS의 java 버전과 달라도 무방)
      - uses: actions/checkout@v3
      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          java-version: '17'
          distribution: 'temurin'

      # gradle caching - 빌드 시간 향상
      - name: Gradle Caching
        uses: actions/cache@v3
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
          restore-keys: |
            ${{ runner.os }}-gradle-
      # 권한 부여
      - name: Add execution permissions to Gradle Wrapper
        run: chmod +x ./gradlew

      # 환경별 yml 파일 생성(1) - application.yml
      - name: make application.yml
        if: |
          contains(github.ref, 'main')
        run: |
          mkdir ./src/main/resources # resources 폴더 생성
          cd ./src/main/resources # resources 폴더로 이동
          touch ./application.yml # application.yml 생성
          echo "${{ secrets.YML }}" > ./application.yml # github actions에서 설정한 값을 application.yml 파일에 쓰기
        shell: bash

      # 환경별 yml 파일 생성(2) - dev
      - name: make application-dev.yml
        run: |
          cd ./src/main/resources
          touch ./application-dev.yml
          echo "${{ secrets.YML_DEV }}" > ./application-dev.yml
        shell: bash




      # gradle build
      - name: Build with Gradle
        run: ./gradlew build -x test


      # docker build & push to develop
      - name: Docker build & push to dev
        run: |
          docker login -u ${{ secrets.DOCKER_USERNAME }} -p ${{ secrets.DOCKER_PASSWORD }}
          docker build -f Dockerfile-dev -t ${{ secrets.DOCKER_USERNAME }}/docker-test-dev .
          docker push ${{ secrets.DOCKER_USERNAME }}/docker-test-dev



      ## deploy to develop
      - name: Deploy to dev
        uses: appleboy/ssh-action@master
        id: deploy-dev
        with:
          host: ${{ secrets.HOST_DEV }} # EC2 퍼블릭 IPv4 DNS
          username: ${{ secrets.USERNAME }} # ubuntu
          password: ${{ secrets.PASSWORD }}
          port: 22
          key: ${{ secrets.PRIVATE_KEY }}
          script: |
            port=8080
            echo "Checking for containers using port $port..."

            # Find the container ID using the specified port
            container_id=$(docker ps --filter "publish=$port" --format "{{.ID}}")

            if [ -n "$container_id" ]; then
              echo "Found container with ID: $container_id. Stopping it..."
              docker stop "$container_id"
              docker rm "$container_id"
              echo "Container stopped successfully."
            else
              echo "No container is using port $port."
            fi
            sudo docker ps
            sudo docker pull ${{ secrets.DOCKER_USERNAME }}/docker-test-dev
            sudo docker run --name team-18 -d -p 8080:8080 ${{ secrets.DOCKER_USERNAME }}/docker-test-dev

application.yml코드 작성

spring:
  application:
    name: <애플리케아션 이름>
  profiles:
    group:
      dev: dev, local
      deploy: deploy
    active: dev

💻 코드 설명

• spring.application
  • name Spring Boot 애플리케이션의 이름을 지정하는데 사용된다. 지정된 이름은 주로 로그 출력, Spring Cloud 환경에서 서비스 식별, 그리고 애플리케이션 상태 모니터링 등 여러 곳에서 활용된다. 로깅에 표시되는 예시는 다음과같다. 예를들어 애플리케이션 이름을 "hyeondooori"로 했다면 2024-11-22 12:00:00.000 INFO 12345 --- [ main] hyeondooori.Application : Started Application in 5.123 seconds (JVM running for 5.678)
• spring.profiles
  • group 프로파일 그룹을 정의한다. dev그룹은 dev와 local프로파일이 함께 활성화되고, deploy그룹은 deploy 프로파일만 활성화된다. 이를통해 여러 프로파일일을 하나의 그룹으로 묶어서 사용할 수 있다.
  • active 현재 활성화된 프로파일을 지정한다. 여기서는 dev프로파일이 활성화된 상태이다.

💻동작 방식

1. spring.profiles.active에 따라 프로파일 로드

• active: dev 설정에 따라 application-dev.yml 또는 dev 관련 설정이 로드된다.

2. 그룹 활성화

• dev 프로파일이 활성화되면, 그룹 설정에 따라 dev와 local 두 프로파일의 설정이 모두 적용된다.

3. 우선순위

• 기본설정(application.yml) -> 활성화된 프로파일(application-dev.yml 또는 application-deploy.yml) 순서로 설정이 병합된다.
• 동일한 키가 중복되면, 활성화된 프로파일의 설정이 우선된다.

  개발 환경에 따라 application.yml 내부의 spring.profiles.active를 변경하여 활성되는 프로파일을 변경할 수 있다. 로컬환경에서 작업할 때는 active를 local로 하고, 개발환경에서는 dev로 하는 방식!

❓AWS 서버에서의 Docker Desktop

로컬에서 Docker컨테이너를 실행하려면 Docker Desktop이 실행중이어야만 했다. 이는 Windows나 Mac과 같은 운영체제에서 Docker engine을 실행하는데 필요하다.

하지만, AWS에서 실행되는 Docker는 해당 서버(AWS 인스턴스)에 설치된 Docker engine 위에서 동작한다. 이 Docker engine은 AWS 서버 자체에서 관리되며, 로컬 Docker Desktop과는 전혀 관계가 없다.

AWS에서 퍼블릭IP를 할당받은 인스턴스(AWS EC2 등)에서 Docker컨테이너를 실행했다면:

• docker 컨테이너는 AWS 인스턴스 내에서 자체적으로 동작한다.
• 퍼블릭 IP를 통해 외부에서 접근할 수 있다.

컨테이너 실행 유지 조건

1. AWS EC2 인스턴스가 계속 실행 중이어야 한다. EC2가 중지되면, Docker 컨테이너도 중단된다.
2. Docker 컨테이너가 백그라운드에서 실행중이어야한다. 컨테이너를 실행할 때 -d(detached mode)옵션을 사용하여 컨테이너를 백그라운드에 유지한다. docker run -d -p 3306:3306 --name mysql-container -e MYSQL_ROOT_PASSWORD=<password> mysql

1. 실행 설정 (Run Configuration 확인)

• IntelliJ IDEA의 Run Configuration에 정의된 설정을 기반으로 애플리케이션을 실행합니다.
• 기본적으로 Spring Boot 프로젝트에서는 다음을 설정할 수 있습니다:
  • 실행할 클래스: 예를 들어 @SpringBootApplication이 포함된 메인 클래스.
  • 활성화할 프로파일: spring.profiles.active 값을 설정 가능.
  • JVM 옵션 및 환경 변수 설정 가능.

Run Configuration 설정 확인 방법

• IntelliJ 메뉴에서 Run > Edit Configurations를 클릭.
• 실행하려는 Run Configuration을 선택하여 실행 환경을 확인하고 수정할 수 있습니다.

2. Maven/Gradle 빌드 과정

Spring Boot 프로젝트에서는 실행 전에 Maven 또는 Gradle 빌드 작업이 수행됩니다.

1. 프로젝트 컴파일:

   • 소스 코드(Java/Kotlin)를 컴파일하여 .class 파일을 생성.
   • 컴파일된 파일은 기본적으로 /target/classes(Maven) 또는 /build/classes/java/main(Gradle) 디렉토리에 저장.

2. 의존성 확인 및 다운로드:

   • Maven 또는 Gradle이 pom.xml 또는 build.gradle 파일을 읽어 프로젝트에 필요한 라이브러리 의존성을 확인.
   • 누락된 라이브러리가 있다면, 원격 저장소에서 자동으로 다운로드.

3. Spring Boot 애플리케이션 실행 파일 생성:

   • Gradle/Maven에 의해 빌드된 .jar 또는 .war 파일이 생성됩니다(필요한 경우).

3. JVM 실행

빌드가 완료된 후, IntelliJ는 Java Virtual Machine(JVM)을 실행하여 애플리케이션을 시작합니다.

1. 메인 클래스 실행:

   • Spring Boot 애플리케이션에서는 기본적으로 @SpringBootApplication이 정의된 클래스(보통 Application.java)가 실행됩니다.
   • 이 클래스는 내부적으로 SpringApplication.run() 메서드를 호출하여 애플리케이션을 부트스트랩(초기화)합니다.

   예:

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

2. JVM 옵션 적용:

   • Run Configuration에서 설정된 JVM 옵션이 적용됩니다. 예: -Xmx1024m 같은 메모리 관련 설정.

3. 환경 변수 적용:

   • Run Configuration에서 정의한 환경 변수도 JVM에 전달됩니다.
   • 예: spring.profiles.active=dev

4. Spring Boot 애플리케이션 초기화

Spring Boot 애플리케이션이 JVM 위에서 실행되며 초기화 과정을 거칩니다:

1. Spring 컨텍스트 초기화:

   • ApplicationContext가 생성되고, 모든 빈(Bean)이 초기화됩니다.
   • @Component, @Service, @Repository 등의 애너테이션으로 정의된 클래스가 빈으로 등록됩니다.

2. 외부 설정 로드:

   • application.yml, application.properties, 또는 환경 변수에서 설정 값을 읽어옵니다.
   • 활성화된 프로파일(spring.profiles.active)에 따라 추가 설정을 병합합니다.

3. 내장 웹 서버 실행:

   • Spring Boot 프로젝트는 기본적으로 내장형 웹 서버(Tomcat, Jetty 등)를 사용합니다.
   • 내장 웹 서버가 지정된 포트(기본값: 8080)에서 시작됩니다.

4. 애플리케이션 실행 준비 완료:

   • 초기화가 완료되면 로그에 Started Application in [time] seconds 메시지가 표시됩니다.
   • 이 시점에서 애플리케이션이 요청을 받을 준비가 됩니다.

5. IntelliJ에서 로그 출력

IntelliJ IDEA의 Run 창에 애플리케이션 로그가 출력됩니다:

• Spring Boot 로고와 버전 정보.
• 로드된 설정 파일(application.yml 또는 application.properties).
• 초기화된 빈(Bean) 목록.
• 내장 웹 서버가 시작된 포트 정보.

예:

2024-11-22 10:00:00.000  INFO 12345 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http)
2024-11-22 10:00:00.000  INFO 12345 --- [           main] com.example.Application                  : Started Application in 5.123 seconds (JVM running for 5.678)

6. 애플리케이션 실행 중 동작

• 애플리케이션이 실행되면서 HTTP 요청을 수신하고, Controller, Service, Repository 계층이 동작.
• 로컬에서 실행 중인 애플리케이션에 접근하려면 브라우저나 Postman 등을 사용하여 다음 URL에 접근:

  http://localhost:8080

7. 정리

IntelliJ IDEA에서 Run 버튼을 누르면 아래 과정이 실행됩니다:

1. Run Configuration을 기반으로 애플리케이션 실행 설정 확인.
2. Maven/Gradle 빌드로 소스 코드 컴파일 및 의존성 다운로드.
3. JVM 실행 및 main() 메서드 실행.
4. Spring Boot 초기화:
   • 빈 등록, 설정 파일 로드, 내장 웹 서버 시작.
5. 애플리케이션 시작 및 로그 출력.

이 과정을 통해 로컬에서 Spring Boot 애플리케이션이 실행되고, 브라우저를 통해 접근할 수 있는 상태가 됩니다.

스프링의 요청 처리 과정

Spring이 요청에 대한 처리를 어떤 흐름으로 진행하는지에 대한 그림이다.

1. 클라이언트의 요청을 디스패처 서블릿이 받음.
2. 요청 정보를 통해 요청을 위임할 컨트롤러 찾음
3. 요청을 컨트롤러로 위임할 핸들러 어댑터를 찾아 전달함.
4. 핸들러어댑터가 컨트롤러로 요청을 위임함.
5. 비즈니스 로직을 처리함.
6. 컨트롤러가 반환값을 처리함.
7. 핸들러어댑터가 반환값을 처리함.
8. 서버의 응답을 클라이언트로 반환함.

• Dispatcher-Servlet 디스패처 서블릿의 dispatch는 "보내다"라는 뜻을 가지고 있다. 그리고 이러한 단어를 포함하는 디스패처 서블릿은 HTTP 프로토콜로 들어오는 모든 요청을 가장 먼저 받아 적합한 컨트롤러에 위임해주는 프론트 컨트롤러(front Controller)라고 정의할 수 있다. 클라이언트로부터 어떤 요청이 오면 톰캣(Tomcat)과 같은 서블릿 컨테이너가 요청을 받게된다. 그리고 이 모든 요청을 프론트 컨트롤러인 디스패처 서블릿이 가장 먼저 받게된다. 그러면 디스패처 서블릿은 공통작업을 먼저 처리한 후 해당 요청을 처리해야하는 컨트롤러를 찾아 작업을 위임한다. 여기서 프런트 컨트롤러(front controller)라는 용어가 사용되는데, Front Controller는 주로 서블릿 컨테이너의 제일 앞에서 서버로 들어오는 클라이언트의 모든 요청을 받아 처리해주는 컨트롤러로서, MVC 구조에서 함께 사용되는 디자인 패턴이다. 과거에는 모든 서블릿을 URL 매핑을 위해 web.xml에 모두 등록해주어야 했지만, dispatcher-servlet이 해당 어플리케이션으로 들어오는 모든 요청을 핸들링해주고 공통 작업을 처리면서 상당히 편리하게 이용할 수 있게 되었습니다. 우리는 컨트롤러를 구현해두기만 하면 디스패처 서블릿가 알아서 적합한 컨트롤러로 위임을 해주는 구조가 되었습니다.

❓ 만약 Controller에서 로직을 처리하던 중 예상치못한 에러가 발생한다면 어떻게될까?

스프링의 기본적인 예외 처리 방법

이와같은 컨트롤러의 getProduct에서 NoSuchElementFoundException 예외가 발생했다면 우리는 접속한 환경에 따라 다른 에러처리를 받게 된다. 만약 웹페이지로 접속했다면 Whitelabel Error Page를 반환받게된다.

Spring은 만들어질 때부터 에러처리를 위한 BasicErrorController를 구현해두었고, 스프링 부트는 예외가 발생하면 기본적으로 /error로 에러 요청을 다시 전달하도록 WAS 설정을 해두었다.

WAS는 웹 서버와 웹 컨테이너가 합쳐진 형태로서 웹 서버 단독으로는 처리할 수 없는 데이터베이스의 조회나 다양한 로직 처리가 필요한 동적 컨텐츠를 제공한다. 대표적인 WAS 종류: Tomcat WAS에 대한 더욱 자세한 설명은! ->CLICK!!

그래서 별도의 설정이 없다면 예외 발생 시에 BasicErrorController로 에러 처리 요청이 전달된다. 참고로 이는 스프링 부트의 WebMvcAutoConfiguration을 통해 자동 설정이 되는 WAS의 설정이다. 여기서 요청이 /error로 다시 전달된다는 부분에 주목해야한다. 일반적인 요청 흐름은 다음과 같이 진행된다. WAS(톰캣) -> 필터 -> 서블릿(디스패처 서블릿) -> 인터셉터 -> 컨트롤러 그리고 컨트롤러 하위에서 예외가 발생했을 때, 별도의 예외 처리를 하지 않으면 WAS까지 에러가 전달된다. 그러면 WAS는 애플리케이션에서 처리를 못하는 예외라 exception이 올라왔다고 판단을 하고 대응 작업을 진행한다. 컨트롤러(예외발생) -> 인터셉터 -> 서블릿(디스패처 서블릿) -> 필터 -> WAS(톰캣)

WAS는 스프링 부트가 등록한 에러 설정(/error)에 맞게 요청을 전달하는데, 이러한 흐름을 총 정리하면 다음과 같다. WAS(톰캣) -> 필터 -> 서블릿(디스패처 서블릿) -> 인터셉터 -> 컨트롤러 -> 컨트롤러(예외발생) -> 인터셉터 -> 서블릿(디스패처 서블릿) -> 필터 -> WAS(톰캣) -> WAS(톰캣) -> 필터 -> 서블릿(디스패처 서블릿) -> 인터셉터 -> 컨트롤러(BasicErrorController)

기본적인 에러 처리 방식은 결국 에러 컨트롤러를 한 번 더 호출하는 것이다. 그러므로 필터나 인터셉터가 다시 호출될 수 있는데, 이를 제어하기 위해서는 별도의 설정이 필요하다.

서블릿은 dispatcherType으로 요청의 종류를 구분하는데, 일반적인 요청은 REQUEST이며 에러 처리 요청은 ERROR이다. 필터는 서블릿 기술이므로 필터등록(FilterRegistrationBean) 시에 호출될 dispatcherType 타입을 설정할 수 있고, 별도의 설정이 없다면 REQUEST일 경우에만 필터가 호출된다. 하지만, 인터셉터는 스프링 기술이므로 dispatcherType을 설정할 수 없어 URI 패턴으로 처리가 필요하다. 스프링 부트에서는 WAS까지 직접 제어하게 되면서 이러한 WAS의 에러 설정까지 가능해졌다. 또한 이는 요청이 2번 생기는 것은 아니고, 1번의 요청이 2번 전달되는 것이다. 그러므로 클라이언트는 이러한 에러 처리 작업이 진행되었는지 알 수 없다.

BasicErrorController

BasicErrorController는 accept헤더에 따라 에러 페이지를 반환하거나 에러 메시지를 반환한다. 에러 경로는 기본적으로 /error로 정의되어있으며 properties에서 server.error.path로 변경할 수 있다.

errorHtml()과 errer()는 모두 getAttributeOptions를 호출해 반환할 에러 속성을 얻는데, 기본적으로 DefaultErrorAttributes로부터 반환할 정보를 가져온다. DefaultErrorAttributes는 전체 항목들에서 설정에 맞게 불필요한 속성들을 제거한다.

• timestamp: 에러가 발생한 시간
• status: 에러의 http상태
• error: 에러코드
• path: 에러가 발생한 uri
• exception: 최상위 예외 클래스의 이름(설정 필요)
• message: 에러에 대한 내용(설정 필요)
• errors: BindingException에 의해 생긴 에러 목록(설정 필요)
• trace: 에러 스택 트레이스(설정 필요)

위는 기본 설정으로 받는 에러 응답이다. 나름 잘 갖추어져 있지만 클라이언트 입장에서 유용하지 못하다. 클라이언트는 "Item with id 5000 not found"라는 메시지와 함께 404 status로 에러 응답을 받으면 훨씬 유용할 것이다. 다음과 같이 properties를 통해 에러 응답을 조정할 수 있다. 물론 운영 환경에서 구현이 노출되는 trace는 제공하지 않는 것이 좋다.

참고로 SpringBoot 2.3 이전에는 message를 기본적으로 제공했었지만, SpringBoot 2.3부터는 클라이언트에게 너무 많은 정보가 노출되는 것을 방지하기 위해 기본적으로 제공하지 않게 되었다.

스프링이 제공하는 다양한 예외 처리 방법

JAVA에서는 예외 처리를 위해 try-catch를 사용해야 하지만 try-catch를 모든 코드에 붙이는 것은 비효율적이다. Spring은 에러 처리라는 공통 관심사(cross-cutting concerns)를 메인 로직으로부터 분리하는 다양한 예외 처리 방식을 고안했고, 예외 처리 전략을 추상화한 HandlerExceptionResolver 인터페이스를 만들었다. (전략 패턴이 사용된 것이다.)

대부분의 HandlerExceptionResolver는 발생한 Exception을 catch하고 HTTP상태나 응답메시지 등을 설정한다. 그래서 WAS입장에서는 해당 요청이 정상적인 응답인 것으로 인식되며, 위에서 설명한 복잡한 WAS의 에러 전달이 진행되지 않는다.

위의 Object 타입인 handler는 예외가 발생한 컨트롤러 객체이다. 예외가 던져지면 디스패처 서블릿까지 전달되는데, 적합한 예외처리를 위해 HandlerExceptionResolver구현체들을 빈으로 등록해서 관리한다. 그리고 적용 가능한 구현체를 찾아 예외를 처리하는데, 우선순위대로 아래의** 4가지 구현체**들이 빈으로 등록되어있다.

• DefaultErrorAttributes: 에러 속성을 저장하며 직접 예외를 처리하지 않는다.
• ExceptionHandlerExceptionResolver: 에러 응답을 위한 Controller나 ControllerAdvice에 있는 ExceptionHandler를 처리한다.
• ResponseStatusExceptionResolver: Http상태코드를 지정하는 @ResponseStatus 또는 ResponseStatusException을 처리한다.
• DefaultHandlerExceptionResolver: 스프링 내부의 기본 예외들을 처리한다.

Spring에서 ExceptionResolver를 동작시켜 에러를 처리할 때 사용하는 도구들을 살펴보자. ExceptionHandler, RestControllerAdvice의 두 개가 있다. ResponseStatusException의 한계점들을 보완해준 방식들이라 이것들을 사용한다.

ResponseStatusException의 한계점

• 직접 예외처리를 프로그래밍하므로 일관된 예외처리가 어려움
• 예외처리 코드가 중복될 수 있음
• Spring 내부의 예외를 처리하는 것이 어려움
• 예외가 WAS까지 전달되고, WAS의 에러 요청 전달이 진행됨

@ExceptionHandler

• 매우 유연한 에러처리 제공
• 에러 응답(payload)자유롭게 다룰 수 있음.
• 컨트롤러의 메소드에 해당 어노테이션을 적용할 수 있는데, 이는 전역적으로 사용할 수 없다. 전역적인 사용을 위해서는 @RestControllerAdvice 또는 @ControllerAdvice 애노테이션을 사용해야 한다.

@RestControllerAdvice

• Spring 4.3부터 제공하는 애노테이션
• @ExceptionHandler를 전역적으로 사용할 수 있도록 도와줌
• @ControllerAdvice와의 차이점은 에러응답을 JSON으로 내려준다는 것이다.
• 사용방법: 애노테이션을 적용해 전역적으로 에러를 핸들링하는 class를 만들어 사용한다.(에러처리 위임)

출처: https://mangkyu.tistory.com/18 [MangKyu's Diary:티스토리] 출처: https://mangkyu.tistory.com/204 [MangKyu's Diary:티스토리]