[오픈소스 기여 도전기 #1] 거대한 코드 숲에서 길을 찾다 (구조 분석 & 웹훅 테스트)

지난 포스팅에서 우여곡절 끝에 로컬 개발 환경(wp-env) 구축에 성공했습니다. 하지만 기쁨도 잠시, 막상 IDE를 켜고 코드를 보니 눈앞이 캄캄해졌습니다.

"환경은 떴는데... 도대체 코드는 어디를 고쳐야 하지?"

워드프레스와 우커머스 구조에 익숙하지 않은 상태에서, 수많은 파일과 add_action() 같은 생소한 함수들은 마치 외계어처럼 보였습니다. 무작정 코드를 읽는 건 비효율적이라 판단하고, Top-Down 방식으로 프로젝트를 해부해 보기로 했습니다.

---

🧐 1. 프로젝트 구조 분석 (Feat. AI)

먼저 전체적인 숲을 보기 위해 클로드(Claude)에게 프로젝트 디렉토리 구조 분석을 요청했습니다. 다행히 제가 실무에서 관리하던 PG 모듈과 유사한 패턴이 보여 이해가 빨랐습니다.

📂 핵심 디렉토리 구조 (/includes)

가장 중요한 비즈니스 로직은 includes 폴더에 모여 있었습니다.

• class-wc-stripe.php: 플러그인의 메인 클래스 (싱글톤 패턴)
• class-wc-gateway-stripe.php: 결제 승인/취소 등을 담당하는 게이트웨이 클래스
• class-wc-stripe-webhook-handler.php: (핵심) 이번 이슈의 범인으로 추정되는 웹훅 처리 클래스
• /payment-methods: 카드, 계좌이체 등 각 결제 수단별 구현체

🏗️ 실행 흐름 파악

woocommerce_gateway_stripe_init() (초기화)
   ↓
WC_Stripe::get_instance() (싱글톤 인스턴스)
   ↓
Hooks 등록 (add_action, add_filter)

워드프레스는 거대한 Hook(갈고리) 시스템으로 돌아갑니다. 특정 시점에 걸어둔 함수가 실행되는 구조죠.

---

🔍 2. 웹훅의 진입점(Entry Point)을 찾아라

Stripe에서 결제 결과 웹훅을 쏘면, 우커머스는 그걸 어떻게 받아낼까요? 코드를 뒤지던 중 class-wc-stripe-webhook-handler.php 파일에서 결정적인 단서를 발견했습니다.

// class-wc-stripe-webhook-handler.php : 74 line
add_action( 'woocommerce_api_wc_stripe', [ $this, 'check_for_webhook' ] );

💡 wc-api의 비밀

처음엔 woocommerce_api_wc_stripe라는 훅 이름이 어디서 왔는지 도통 알 수 없었습니다. 문서를 뒤지고 코드를 파헤친 끝에 우커머스의 라우팅 규칙을 알아냈습니다.

1. 우커머스는 /?wc-api={HANDLER_NAME} 형태의 URL 요청을 받습니다.
2. 이 요청이 들어오면 내부적으로 woocommerce_api_{HANDLER_NAME}이라는 액션을 실행(do_action)합니다.
3. Stripe 플러그인은 wc_stripe라는 핸들러를 등록해 두었으므로, 최종적으로 check_for_webhook 메소드가 실행되는 것입니다.

결국, 웹훅 URL은 다음과 같은 형태가 됩니다.

http://localhost:8888/?wc-api=wc_stripe

---

🛠️ 3. 로컬에서 웹훅 테스트하기 (Stripe CLI)

진입점은 알았으니, 이제 실제로 웹훅을 쏴서 코드가 타는지 확인해야 합니다. 하지만 로컬(localhost) 환경은 외부(Stripe 서버)에서 접근할 수 없습니다.

이때 구세주처럼 등장한 것이 Stripe CLI입니다. 터널링을 통해 로컬 환경으로 웹훅을 포워딩해 줍니다.

1. Stripe CLI 설치 (WSL/Ubuntu 기준)

# GPG 키 등록
curl -s https://packages.stripe.dev/api/security/keypair/stripe-cli-gpg/public | gpg --dearmor | sudo tee /usr/share/keyrings/stripe.gpg

# 레포지토리 추가
echo "deb [signed-by=/usr/share/keyrings/stripe.gpg] https://packages.stripe.dev/stripe-cli-debian-local stable main" | sudo tee -a /etc/apt/sources.list.d/stripe.list

# 설치
sudo apt update
sudo apt install stripe

2. 로그인 및 리스닝 시작

# 로그인 (브라우저 인증)
stripe login

# 웹훅 포워딩 시작 (내 로컬 우커머스 주소로!)
stripe listen --forward-to "http://localhost:8888/?wc-api=wc_stripe"

터미널에 Ready!가 뜨고, 샌드박스에서 테스트 결제를 발생시키자 터미널에 로그가 주르륵 올라오기 시작했습니다. 드디어 외부 결제 데이터가 내 로컬 코드로 들어오기 시작한 겁니다!

---

🐛 4. 로그가 안 찍힌다? (Troubleshooting)

웹훅은 들어오는데, 코드에 심어둔 WC_Stripe_Logger::debug() 로그가 파일에 남지 않는 현상이 발생했습니다.

WC_Stripe_Logger::debug( 'Webhook received...', [ 'event' => $event ] );

알고 보니 우커머스 설정의 문제였습니다.

• 해결: 워드프레스 관리자 페이지 → WooCommerce → Settings → Payments → Stripe → "Log debug messages" 체크박스 활성화

이 옵션을 켜고 나니 /wp-content/uploads/wc-logs/ 디렉토리에 로그 파일이 생성되었고, 웹훅 페이로드가 정상적으로 기록되는 것을 확인할 수 있었습니다.

---

🚀 다음 예고: 재현(Reproduction)을 향한 여정

이제 준비는 끝났습니다.

1. 환경 구축 완료 (wp-env)
2. 코드 구조 파악 완료 (Webhook Handler)
3. 테스트 도구 세팅 완료 (Stripe CLI)

다음 포스팅에서는 이 환경을 바탕으로 이슈 #4951(ID 충돌로 인한 Fatal Error)을 **"의도적으로 재현"**해보고, 왜 코드가 터질 수밖에 없는지 분석해 보겠습니다.