TUE

Apache Kafka 공식 문서 보면서 핵심 기능 정리

tues — Mon, 10 Nov 2025 21:04:16 +0900

https://kafka.apache.org/intro?utm_source=chatgpt.com

Apache Kafka

Apache Kafka: A Distributed Streaming Platform.

kafka.apache.org

“Kafka는 단순한 메시지큐가 아니라, 데이터의 중추 신경계다.”
실시간 데이터가 생성되고, 저장되고, 처리되는 전 과정을 하나의 시스템으로 연결하는 이벤트 스트리밍 플랫폼이다.

1️⃣ 이벤트 스트리밍이란?

이벤트 스트리밍(Event Streaming) 은
데이터베이스, 센서, 모바일 앱, 클라우드, 소프트웨어 등에서 발생하는 **“사건(Event)”**을
실시간으로 수집 → 저장 → 처리 → 전달 하는 기술이다.

쉽게 말해,

“데이터를 한 번 저장하고 끝내는 게 아니라,
계속 흐르게(stream) 해서 필요한 곳에서 즉시 반응할 수 있게 만드는 기술"이다.

예시로 보면

은행 앱 → “입금/송금 이벤트”를 즉시 감지해 거래 내역에 반영
택배 서비스 → 차량 위치 이벤트를 실시간으로 추적
스마트 공장 → 센서 데이터로 기계 이상 여부를 즉시 감지
쇼핑몰 → 고객 클릭 이벤트를 바로 분석해 추천상품 표시

⚙️ 2️⃣ Kafka의 세 가지 핵심 기능

Kafka는 이벤트 스트리밍을 위한 세 가지 본질적 기능을 통합해 제공한다.
이 세 가지를 이해하면 “Kafka가 왜 단순 메시지 브로커와 다른가”를 명확히 구분할 수 있다.

1. Publish / Subscribe	데이터를 발행(Publish) 하고 구독(Subscribe) 하는 기능. Producer가 이벤트를 보내면, Consumer는 구독한 Topic에서 이를 실시간으로 읽는다.	SNS: 사용자가 게시글을 올리면 팔로워가 실시간으로 보는 구조
2. Store	들어온 이벤트 스트림을 영구적으로 저장. 보존 기간(retention)을 설정할 수 있으며, 일정 기간 후 자동 삭제 가능.	“모든 대화를 기록하는 블랙박스”
⚙️ 3. Process	들어온 데이터를 실시간으로 처리하거나, 과거 데이터를 회고적으로 재처리. Kafka Streams API로 집계·조인·변환 등 가능.	“두뇌처럼 생각하고 반응하는 데이터 흐름”

이 세 가지 기능은 모두
분산형(Distributed), 고확장성(Scalable), 내결함성(Fault-tolerant), 보안(Security) 구조로 설계되어 있다.

3️⃣ Kafka의 주요 요소 구조 (Core Components)

Producer	데이터를 Kafka로 전송	주문 서비스가 order.created 이벤트 발행
Consumer	Kafka에서 데이터를 읽음	결제 서비스가 order.created 이벤트 소비
Topic	이벤트가 저장되는 공간 (폴더 개념)	“orders”, “payments”, “clicks” 등
Partition	Topic을 나눈 단위 (병렬 처리 용도)	주문 ID 기준으로 파티션 분할
Broker	Kafka 서버 (실제 저장소)	Kafka 클러스터 내 3개의 Broker 서버
Cluster	여러 Broker의 집합	운영환경에서는 보통 3~5개 이상
Offset	메시지의 위치(순서) 정보	“Consumer가 어디까지 읽었는가”를 표시
Replica	데이터 복제본 (내결함성 보장)	3개 복제본 → 한 서버가 죽어도 복구 가능

예를 들어 Topic: orders 에 “order.created” 이벤트가 들어오면,
Producer는 이를 Kafka에 publish → Broker에 저장 → Consumer가 읽는 구조다.

4️⃣ Kafka의 다섯 가지 핵심 API

Kafka는 이벤트의 “생명주기 전체”를 다루기 위해 5개의 API를 제공한다.
이 API들은 각기 다른 역할을 맡아 완성된 스트리밍 시스템을 만든다.

Admin API	Kafka 클러스터, 토픽, 파티션 등을 관리	토픽 생성, 삭제, 파티션 확장, 브로커 상태 조회
✉️ Producer API	Kafka로 이벤트를 발행(Publish)	주문 생성 시 order.created.v1 이벤트 전송
Consumer API	Kafka에서 이벤트를 구독(Consume)	결제 서비스가 order.created.v1 이벤트를 읽음
Streams API	Kafka 내부 스트림을 실시간 처리/변환/집계	주문 + 결제 데이터를 조인해 “구매 전환율” 계산
Connect API	Kafka와 외부 시스템(DB, 클라우드 등)을 자동 동기화	PostgreSQL → Kafka → Elasticsearch 자동 전송

Streams vs Connect 차이

Streams	Connect
Kafka 내부에서 “데이터 처리”	Kafka 외부 시스템과 “데이터 이동”
코드로 로직 작성	설정으로 커넥터 실행
실시간 분석, 집계, 조인	DB 변경사항 캡처 (CDC), 클라우드 업로드 등

마무리: 내 생각

Kafka를 공부하며 느낀 점은,

“Kafka는 단순히 데이터를 옮기는 기술이 아니라,
데이터가 실시간으로 살아 움직이게 하는 인프라다.”

REST API가 요청이 있을 때만 움직인다면,
Kafka는 “사건이 발생하는 즉시 반응하는 뇌”처럼 동작한다.

아파트 실거래가 API 연동기 - 프록시 문제 해결

tues — Thu, 2 Oct 2025 14:24:01 +0900

https://apt-trade-web.vercel.app/

Vite + React + TS

apt-trade-web.vercel.app

1️⃣ 프록시를 쓴 이유

서울시 공공데이터포털에서 제공하는 아파트 매매 실거래가 API를 React 프론트엔드에서 직접 불러오려 했습니다.
하지만 두 가지 문제가 있었습니다.

CORS 차단
브라우저에서 바로 openapi.seoul.go.kr API를 호출하면 보안 정책 때문에 차단됨.
API Key 노출
발급받은 인증키를 그대로 프론트 코드에 넣으면, 배포 후 누구나 볼 수 있어 보안에 취약.

그래서 프론트 → 프록시 서버(Express) → 공공데이터 API 구조로 바꾸었습니다.
프록시가 대신 API를 호출하고, 응답을 JSON으로 정리해 프론트로 전달하는 방식입니다.

2️⃣ 문제 원인

프록시 구조를 적용하니 로컬에서는 잘 됐지만,
Vercel에 배포했을 때는 이런 문제가 생겼습니다.

Timeout 발생 : 프론트에서 API를 직접 때릴 때 응답을 못 받음
404 Not Found : Vercel 배포 후 /api/seoul/trades 경로를 찾지 못함
@vercel/node 타입 오류 : 서버리스 함수에서 타입을 잘못 import해 빌드가 막힘

원인을 정리하면:

브라우저 직접 호출 → CORS + Key 노출
Vercel 배포 → Express 서버 자체는 지원하지 않고, 서버리스 함수 단위로 배포해야 함
타입 선언 → 런타임에는 필요 없는 @vercel/node를 import해서 에러 발생

3️⃣ 해결 방법

✅ 프록시 서버 (로컬 개발용)

개발 중에는 Express로 프록시 서버를 열어두고, vite.config.ts에서 /api 요청을 프록시로 넘기도록 설정했습니다.

app.get('/api/seoul/trades', async (req, res) => {
  const { page, size, rcptYr, cggCd } = req.query;
  const url = `http://openapi.seoul.go.kr:8088/${process.env.SEOUL_SERVICE_KEY}/json/tbLnOpendataRtmsV/1/10/${rcptYr}/${cggCd}/`;
  const { data } = await axios.get(url);
  res.json(data);
});

✅ 서버리스 함수 (배포용)

Vercel은 Express 서버를 그대로 올릴 수 없으므로,
api/seoul/trades.ts 파일을 만들어 개별 함수로 배포했습니다.

export default async function handler(req: any, res: any) {
  const { page = 1, size = 10, rcptYr, cggCd } = req.query;
  const start = (Number(page) - 1) * Number(size) + 1;
  const end = Number(page) * Number(size);

  const url = `http://openapi.seoul.go.kr:8088/${process.env.SEOUL_SERVICE_KEY}/json/tbLnOpendataRtmsV/${start}/${end}/${rcptYr}/${cggCd}/`;

  try {
    const { data } = await axios.get(url, { timeout: 20000 });
    res.status(200).json(data);
  } catch (e: any) {
    res.status(500).json({ message: 'Seoul API 호출 실패', detail: e.message });
  }
}

4️⃣ 배운 점

배포 환경 차이, 서버리스 구조의 한계까지 이해할 수 있었습니다.
이후에는 axios 요청에 타임아웃 로직을 추가하고,
Vercel Edge Cache를 활용해 응답 속도와 안정성을 높였습니다.

[error 해결기] React 페이지네이션 시 이전 데이터가 화면에 남는 문제

tues — Thu, 2 Oct 2025 14:19:51 +0900

문제 상황

아파트 실거래가 API를 연동해 React로 리스트를 보여주는 프로젝트를 진행했다.
API 응답은 정상적으로 내려오는데, 페이지 이동을 하면 이전 페이지 데이터가 한두 개씩 화면에 남아 있는 현상이 발생했다.

API 응답 예시는 아래와 같다.

{
  "page": 2,
  "totalCount": 4737,
  "items": [
    {
      "aptSeq": "11680-11200-0619-0000-20250923",
      "aptNm": "강남자곡 힐스테이트",
      "dealYmd": "2025-09-23",
      "dealAmountManwon": 128000,
      "excluUseAr": 84.39,
      "floor": 7
    },
    {
      "aptSeq": "11680-11200-0619-0000-20250923",
      "aptNm": "강남자곡 힐스테이트",
      "dealYmd": "2025-09-23",
      "dealAmountManwon": 112500,
      "excluUseAr": 59.93,
      "floor": 7
    }
  ]
}

상단에 자꾸 이전에 조회한 데이터가 남아있음

같은 aptSeq + 같은 날짜(dealYmd)로 중복된 거래 데이터가 내려올 수 있다.
그런데 React에서 <tr key={it.aptSeq}>를 쓰고 있어서 문제가 터졌다.

원인 분석

React는 key 값으로 DOM 재사용 여부를 판단한다.
그런데 aptSeq 값이 거래 단위에서 유일하지 않음 → 같은 단지, 같은 날짜, 다른 면적/금액이 존재.
결과적으로 key 충돌이 일어나면서 이전 행이 남아 보이게 됨.

즉, 중복 key 사용이 원인이었다.

✅ 해결 방법

1) key를 고유하게 만들기

중복될 수 없는 여러 필드를 조합해서 key를 만들어야 한다.

<tbody>
  {items.map((it) => {
    const rowKey = [
      it.aptSeq,
      it.dealYmd,
      it.excluUseAr,
      it.dealAmountManwon,
      it.floor,
    ].join('|');

    return (
      <tr key={rowKey}>
        <td>{fmtDate(it.dealYmd)}</td>
        <td>{it.aptNm}</td>
        <td>{fmtAmt(it.dealAmountManwon)}</td>
        <td>{fmtArea(it.excluUseAr)}</td>
        <td>{it.floor}</td>
        <td>{it.dealingGbn}</td>
        <td>{[it.roadNm, it.jibun].filter(Boolean).join(' ')}</td>
      </tr>
    );
  })}
</tbody>

→ 이렇게 하면 각 거래 건별로 고유 key가 생성되어 React가 잘 구분한다.

2) API에서 고유 ID 제공 시

백엔드가 tradeId 같은 식별자를 내려준다면 그걸 key로 사용하는 게 최선이다.

정리

React 리스트 key는 반드시 고유값이어야 한다.
API에서 고유 ID가 없다면 여러 필드를 조합해 key를 만든다.
이번 경우 aptSeq만 쓰면 중복이 발생했기 때문에 복합 key로 해결했다.

이렇게 수정하니 페이지 이동 시 이전 데이터가 남는 현상은 깔끔하게 사라졌다.

서울시 열린 데이터 광장 공공데이터 Open API 신청 & 활용

tues — Thu, 2 Oct 2025 12:35:29 +0900

공공데이터가 불이 나는 바람에 사용이 중단되었습니다ㅠㅠ

따라서 Redis 적용을 다시 하려고 서울 공공데이터를 활용했습니다.

저는 서울 열린데이터 광장의 서울시 부동산 실거래가 정보 API를 활용합니다!

1. 회원가입, 로그인

https://data.seoul.go.kr/

열린데이터광장 메인

데이터분류,데이터검색,데이터활용

data.seoul.go.kr

2. 인증키 신청

https://data.seoul.go.kr/dataList/OA-21275/S/1/datasetView.do

열린데이터광장 메인

데이터분류,데이터검색,데이터활용

data.seoul.go.kr

인증키 신청을 클릭합니다.

3. 가입 신청서 작성

활용할 목적에 맞게 신청서를 작성합니다.

사용url이 없을 경우에 localhost를 적으면 됩니다.

4. 상단 인증키 관리 클릭

5. 인증키 복사

인증키를 복사합니다.

이제 데이터를 불러옵니다!

데이터 호출

1. 샘플 URL 구조 이해하기

제가 호출할 API의 구조는 다음과 같습니다.

(인증키)에는 발급받은 개인 키를 입력하면 됩니다.

요청 인자

출력값

따라서 출력되는 결과값은 다음과 같습니다.

<?xml version="1.0" encoding="UTF-8"?>
<tbLnOpendataRtmsV>
<list_total_count>2742500</list_total_count>
<RESULT>
<CODE>INFO-000</CODE>
<MESSAGE>정상 처리되었습니다</MESSAGE>
</RESULT>
<row>
<RCPT_YR>2025</RCPT_YR>
<CGG_CD>11290</CGG_CD>
<CGG_NM>성북구</CGG_NM>
<STDG_CD>13300</STDG_CD>
<STDG_NM>정릉동</STDG_NM>
<LOTNO_SE>1</LOTNO_SE>
<LOTNO_SE_NM>대지</LOTNO_SE_NM>
<MNO>0266</MNO>
<SNO>0157</SNO>
<BLDG_NM>(266-157)</BLDG_NM>
<CTRT_DAY>20250930</CTRT_DAY>
<THING_AMT>9000</THING_AMT>
<ARCH_AREA>31.68</ARCH_AREA>
<LAND_AREA>18.000000</LAND_AREA>
<FLR>1</FLR>
<RGHT_SE/>
<RTRCN_DAY/>
<ARCH_YR>2006</ARCH_YR>
<BLDG_USG>연립다세대</BLDG_USG>
<DCLR_SE>중개거래</DCLR_SE>
<OPBIZ_RESTAGNT_SGG_NM>서울 성북구</OPBIZ_RESTAGNT_SGG_NM>
</row>
<row>
<RCPT_YR>2025</RCPT_YR>
<CGG_CD>11215</CGG_CD>
<CGG_NM>광진구</CGG_NM>
<STDG_CD>10100</STDG_CD>
<STDG_NM>중곡동</STDG_NM>
<LOTNO_SE>1</LOTNO_SE>
<LOTNO_SE_NM>대지</LOTNO_SE_NM>
<MNO>0123</MNO>
<SNO>0038</SNO>
<BLDG_NM>나경타운</BLDG_NM>
<CTRT_DAY>20250930</CTRT_DAY>
<THING_AMT>39300</THING_AMT>
<ARCH_AREA>49.59</ARCH_AREA>
<LAND_AREA>30.000000</LAND_AREA>
<FLR>2</FLR>
<RGHT_SE/>
<RTRCN_DAY/>
<ARCH_YR>2015</ARCH_YR>
<BLDG_USG>연립다세대</BLDG_USG>
<DCLR_SE>중개거래</DCLR_SE>
<OPBIZ_RESTAGNT_SGG_NM>서울 광진구</OPBIZ_RESTAGNT_SGG_NM>
</row>
<row>
<RCPT_YR>2025</RCPT_YR>
<CGG_CD>11200</CGG_CD>
<CGG_NM>성동구</CGG_NM>
<STDG_CD>12200</STDG_CD>
<STDG_NM>용답동</STDG_NM>
<LOTNO_SE>1</LOTNO_SE>
<LOTNO_SE_NM>대지</LOTNO_SE_NM>
<MNO>0229</MNO>
<SNO>0013</SNO>
<BLDG_NM>(229-13)</BLDG_NM>
<CTRT_DAY>20250930</CTRT_DAY>
<THING_AMT>8000</THING_AMT>
<ARCH_AREA>29.88</ARCH_AREA>
<LAND_AREA>41.480000</LAND_AREA>
<FLR>8</FLR>
<RGHT_SE/>
<RTRCN_DAY/>
<ARCH_YR>1991</ARCH_YR>
<BLDG_USG>오피스텔</BLDG_USG>
<DCLR_SE>직거래</DCLR_SE>
<OPBIZ_RESTAGNT_SGG_NM/>
</row>
<row>
<RCPT_YR>2025</RCPT_YR>
<CGG_CD>11530</CGG_CD>
<CGG_NM>구로구</CGG_NM>
<STDG_CD>10200</STDG_CD>
<STDG_NM>구로동</STDG_NM>
<LOTNO_SE>1</LOTNO_SE>
<LOTNO_SE_NM>대지</LOTNO_SE_NM>
<MNO>1256</MNO>
<SNO>0000</SNO>
<BLDG_NM>구로현대</BLDG_NM>
<CTRT_DAY>20250930</CTRT_DAY>
<THING_AMT>57700</THING_AMT>
<ARCH_AREA>56.49</ARCH_AREA>
<LAND_AREA>0.000000</LAND_AREA>
<FLR>2</FLR>
<RGHT_SE/>
<RTRCN_DAY/>
<ARCH_YR>1992</ARCH_YR>
<BLDG_USG>아파트</BLDG_USG>
<DCLR_SE>중개거래</DCLR_SE>
<OPBIZ_RESTAGNT_SGG_NM>서울 구로구, 서울 영등포구</OPBIZ_RESTAGNT_SGG_NM>
</row>
<row>
<RCPT_YR>2025</RCPT_YR>
<CGG_CD>11650</CGG_CD>
<CGG_NM>서초구</CGG_NM>
<STDG_CD>10800</STDG_CD>
<STDG_NM>서초동</STDG_NM>
<LOTNO_SE>1</LOTNO_SE>
<LOTNO_SE_NM>대지</LOTNO_SE_NM>
<MNO>1434</MNO>
<SNO>0011</SNO>
<BLDG_NM>CM빌</BLDG_NM>
<CTRT_DAY>20250930</CTRT_DAY>
<THING_AMT>34200</THING_AMT>
<ARCH_AREA>29.13</ARCH_AREA>
<LAND_AREA>20.000000</LAND_AREA>
<FLR>3</FLR>
<RGHT_SE/>
<RTRCN_DAY/>
<ARCH_YR>2017</ARCH_YR>
<BLDG_USG>연립다세대</BLDG_USG>
<DCLR_SE>중개거래</DCLR_SE>
<OPBIZ_RESTAGNT_SGG_NM>서울 서초구</OPBIZ_RESTAGNT_SGG_NM>
</row>
</tbLnOpendataRtmsV>

2. Postman으로 호출하기

- Method: GET

- URL: 위 샘플대로 입력합니다.

http://openapi.seoul.go.kr:8088/(인증키)/xml/tbLnOpendataRtmsV/1/5/2025/11110

http://openapi.seoul.go.kr:8088/(인증키)/xml/tbLnOpendataRtmsV/1/5/2024/11500/강서구/10300/1/대지/0151/0039/극동빌라/20240903/연립다세대

응답 확인 가능

<?xml version="1.0" encoding="UTF-8"?>
<tbLnOpendataRtmsV>
    <list_total_count>1</list_total_count>
    <RESULT>
        <CODE>INFO-000</CODE>
        <MESSAGE>정상 처리되었습니다</MESSAGE>
    </RESULT>
    <row>
        <RCPT_YR>2024</RCPT_YR>
        <CGG_CD>11500</CGG_CD>
        <CGG_NM>강서구</CGG_NM>
        <STDG_CD>10300</STDG_CD>
        <STDG_NM>화곡동</STDG_NM>
        <LOTNO_SE>1</LOTNO_SE>
        <LOTNO_SE_NM>대지</LOTNO_SE_NM>
        <MNO>0151</MNO>
        <SNO>0039</SNO>
        <BLDG_NM>극동빌라(151-39)</BLDG_NM>
        <CTRT_DAY>20240903</CTRT_DAY>
        <THING_AMT>16300</THING_AMT>
        <ARCH_AREA>57.09</ARCH_AREA>
        <LAND_AREA>31.000000</LAND_AREA>
        <FLR>1</FLR>
        <RGHT_SE/>
        <RTRCN_DAY/>
        <ARCH_YR>1998</ARCH_YR>
        <BLDG_USG>연립다세대</BLDG_USG>
        <DCLR_SE>직거래</DCLR_SE>
        <OPBIZ_RESTAGNT_SGG_NM/>
    </row>
</tbLnOpendataRtmsV>

Spring Boot + Redis로 아파트 실거래 조회 API 만들기

tues — Wed, 1 Oct 2025 18:56:44 +0900

최근에 공공데이터포털 아파트 실거래 조회 API를 이용해서 프론트엔드에서 거래 내역을 보여주는 프로젝트를 진행했다.
하지만 바로 부딪힌 문제는 속도와 중복 호출이었다.

응답 속도
- 정부 API 특성상 XML로 데이터를 내려주고, 이를 JSON으로 변환해야 했다.
- 네트워크도 느리고 응답 처리 과정까지 거치니 사용자가 같은 조건으로 여러 번 조회할 때마다 매번 느린 응답을 받아야 했다.
중복 호출
- 유저가 같은 조건(예: "강남구 2025년 9월")으로 여러 번 검색할 경우,
  매번 정부 서버를 다시 치게 되어 불필요한 트래픽이 발생했다.
최근 검색 내역 없음
- "내가 조금 전에 검색했던 조건"을 다시 보려면,
  유저가 직접 다시 입력해야 했다.

이 세 가지 문제를 해결하기 위해 Spring Boot + Redis 캐시를 도입하기로 했다.

캐시(Cache): 같은 조건으로 조회하면 일정 시간 동안은 Redis에서 바로 꺼내오기 → 빠른 응답
최근 검색(Recent List): 사용자가 조회한 조건을 Redis 리스트에 저장해 두고, 최근 검색 내역을 보여주기

전체적인 구조

[Frontend (Vite/React)]
         │
         ▼
[Spring Boot (8081)]
  - Redis Cache (@Cacheable)
  - Redis List (최근 검색)
         │
         ▼
[Node Proxy (8080, Express)]
  - 공공데이터포털 API 호출
  - XML → JSON 변환
         │
         ▼
[Government Open API]
         │
         ▼
[Redis (6379)]
  - 캐시 저장소
  - 최근 검색 내역 기록

동작 원리

프론트에서 /api/trades 호출
Spring Boot가 먼저 Redis 캐시 확인
- 캐시 HIT → 바로 응답
- 캐시 MISS → Node 프록시 호출
Node 프록시가 정부 API 호출 후 JSON 응답으로 정규화
Spring Boot가 받은 결과를 Redis에 저장
- 캐시: TTL 2분
- 최근 검색: Redis List로 기록 (최대 20개, 7일 TTL)
프론트에서 /api/recent 호출 시 Redis에 쌓인 최근 검색 내역 응답

아키텍처 다이어그램

┌───────────────────────────────┐
│         Frontend (5173)       │
│   React / Vite / TS           │
└───────────────▲───────────────┘
                │ fetch /api/*
                │
┌───────────────┴───────────────┐
│     Spring Boot (8081)        │
│  - @Cacheable (Redis Cache)   │
│  - 최근검색 (Redis List)       │
└───────────────▲───────────────┘
                │ REST call
┌───────────────┴───────────────┐
│   Node Proxy (8080, Express)  │
│   - 공공데이터포털 API 호출    │
│   - XML → JSON 변환           │
└───────────────▲───────────────┘
                │
┌───────────────┴───────────────┐
│ Government Open API (RTMS)    │
└───────────────────────────────┘

┌───────────────────────────────┐
│          Redis (6379)          │
│  - Cache (2분 TTL)             │
│  - 최근검색 리스트(20개, 7일)   │
└───────────────────────────────┘

컨트롤러

package com.example.redis_demo.api;

import com.example.redis_demo.dto.TradeListResp;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api")
@RequiredArgsConstructor
public class DealController {

    private final DealService service;

    @GetMapping("/trades")
    public TradeListResp trades(
            @RequestParam String sgg,
            @RequestParam String ym,
            @RequestParam(defaultValue = "1") int page,
            @RequestParam(defaultValue = "10") int size,
            @RequestHeader(value = "X-User-Id", required = false) String userId
    ) {
        return service.getDeals(sgg, ym, page, size, userId);
    }

    @GetMapping("/recent")
    public List<String> recent(
            @RequestParam(defaultValue = "10") int limit,
            @RequestHeader(value = "X-User-Id", required = false) String userId
    ) {
        return service.getRecent(userId, limit);
    }
}

국토교통부 아파트 실거래가 API 활용기

tues — Thu, 25 Sep 2025 18:38:57 +0900

https://www.data.go.kr/data/15126468/openapi.do#/API%20%EB%AA%A9%EB%A1%9D/getRTMSDataSvcAptTradeDev

API 기본 정보

Endpoint:

https://apis.data.go.kr/1613000/RTMSDataSvcAptTradeDev

Method: GET
주요 Path:

/getRTMSDataSvcAptTradeDev

필수 파라미터:

Name설명예시

LAWD_CD	지역코드 (법정동 10자리 중 앞 5자리)	41117 (수원 영통구)
DEAL_YMD	계약년월 (6자리, YYYYMM)	202509
serviceKey	공공데이터포털 인증키	발급받은 키
pageNo	페이지 번호	1
numOfRows	페이지당 데이터 수	10

실제 Request 예시

GET https://apis.data.go.kr/1613000/RTMSDataSvcAptTradeDev/getRTMSDataSvcAptTradeDev
  ?serviceKey=발급받은키
  &LAWD_CD=41117
  &DEAL_YMD=202509
  &pageNo=1
  &numOfRows=10

Response 분석 (XML)

응답은 기본적으로 XML 형태:

<response>
  <header>
    <resultCode>000</resultCode>
    <resultMsg>OK</resultMsg>
  </header>
  <body>
    <items>
      <item>
        <aptNm>신나무실신안</aptNm>
        <dealAmount>36,000</dealAmount>
        <dealYear>2025</dealYear>
        <dealMonth>9</dealMonth>
        <dealDay>24</dealDay>
        <excluUseAr>59.965</excluUseAr>
        <floor>3</floor>
        <buildYear>1997</buildYear>
        <umdNm>영통동</umdNm>
      </item>
      ...
    </items>
    <totalCount>325</totalCount>
  </body>
</response>

데이터 해석

aptNm: 단지명 (신나무실신안)
dealAmount: 거래금액 (36,000 → 3억 6천만 원)
dealYear, dealMonth, dealDay: 계약일자
excluUseAr: 전용면적(m²)
floor: 층
buildYear: 건축년도
umdNm: 행정동 이름

내가 겪은 깨달음

문서만 보면 쉬워 보이지만, 실제 호출 시 serviceKey 인코딩 문제나 XML 파싱 문제가 숨어있었다.
특히 응답이 XML인데, 브라우저나 axios에서 바로 JSON으로 착각할 때 파싱 에러가 났다.
정리하자면:
- 공공데이터 API는 요청 파라미터가 정확해야 함
- 응답 형식(XML/JSON)을 반드시 확인해야 함
- serviceKey는 이중 인코딩 문제를 주의해야 함

CORS? 403? API 호출 대참사 해결기

tues — Thu, 11 Sep 2025 17:58:23 +0900

"로컬에서는 되는데 EC2에서는 왜 안 되지?"

사건 개요

클라우드에 React + Spring Boot 서비스를 배포하고 나서,
프론트에서 API를 호출하자마자 403 Forbidden 오류가 발생했다.

EC2 보안 그룹? 열려 있음
백엔드 포트? 정상적으로 열려 있음
API 주소? 맞게 입력함
그런데도 계속 에러가 난다...

❓ 왜 이런 문제가 발생했을까?

CORS란?

CORS(Cross-Origin Resource Sharing)는 브라우저 보안 정책 중 하나로,
출처(origin)가 다른 도메인 간 요청을 제한하는 기능이다.

로컬에서는 localhost:3000 → localhost:8080으로 요청하니 괜찮음
EC2에 배포 후에는 브라우저: http://<IP> → API: http://<IP>:8081로 다른 포트 간 통신

브라우저는 이를 보안 위반으로 판단 → 요청 자체를 막아버린다

에러 상황 정리

// 프론트에서 fetch 요청
fetch('http://<EC2-IP>:8081/api/rewards/summary?userId=u-123')
  .then(res => res.json())
  .then(data => console.log(data));

❌ 콘솔 에러

Access to fetch at 'http://<EC2-IP>:8081/...' from origin 'http://<EC2-IP>' 
has been blocked by CORS policy: 
Response to preflight request doesn't pass access control check: 
No 'Access-Control-Allow-Origin' header is present...

해결 방법 (Spring Boot)

✅ WebMvcConfigurer를 통한 CORS 설정 추가

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**") // 전체 API 경로 허용
                .allowedOrigins("*") // 모든 출처 허용 (*은 개발 환경에서만!)
                .allowedMethods("GET", "POST", "PUT", "DELETE") // 허용 메서드
                .allowedHeaders("*");
    }
}

주의:

allowedOrigins("*")는 개발환경에서만 사용

운영 환경에서는 http://yourdomain.com과 같이 정확한 도메인 지정이 필수

디버깅 중 알게 된 사실들

프론트 요청 흐름 정리

브라우저가 Preflight 요청(OPTIONS) 전송
백엔드가 CORS 설정이 없으면 → 403 Forbidden
프론트는 본 요청(GET, POST)을 보내지 못하고 실패함

✅ 해결 이후 결과

API 요청 정상 응답
실제로 브라우저 콘솔에서 CORS 관련 에러 사라짐
프론트에서 리워드 정보 조회 및 리더보드 정상 렌더링

배운 점

CORS	단순 서버 문제 아님. 브라우저 보안 정책에 의한 차단임
Spring 설정	WebMvcConfigurer를 통해 제어 가능
로컬 vs 운영	로컬에서는 안 생기던 문제가 배포 후 발생할 수 있음

결국 로컬 개발 환경과 실제 브라우저 환경은 다르다는 걸 절실히 느꼈다.
배포 이후 브라우저에서 실제 요청 흐름을 추적하는 게 중요하다.

AWS EC2 + Docker로 React & Spring Boot 실전 배포기

tues — Thu, 11 Sep 2025 17:37:12 +0900

“진짜 유저가 접근 가능한 배포, 나도 해봤다”

개발자 포트폴리오에서 코드 구현만큼 중요한 건, 서비스를 실제 운영 환경에 띄울 수 있는 배포 경험이다.
그래서 이번에는 “로컬에서만 되는 게 아니라, 진짜 유저가 접근 가능한 서비스”를 만드는 걸 목표로 EC2에 프론트와 백엔드를 배포했다.
보안 설정, 포트 바인딩, CORS 이슈 대응 등도 직접 다루며 실제 운영에서 고려해야 할 요소들을 경험할 수 있었다.

✨ 프로젝트 개요: Share & Reward 시스템

이번 프로젝트는 상품 링크를 공유하고, 친구가 클릭하면 포인트를 받는 리워드 시스템을 구현한 것이다.
실제 서비스를 운영하는 것처럼 EC2 서버에 배포하고, 브라우저에서 접근 가능한 형태로 구성해봤다.

프로젝트명	Share & Reward
기술 스택	React (Vite), Spring Boot, Kafka
배포 대상	프론트 (80 포트), 백엔드 API (8081 포트)
구현 기능	공유 링크 생성, 클릭 추적, 리워드 지급 이벤트 처리

기술 스택 선택 이유

▶ 왜 AWS EC2를 썼을까?

항목이유

✅ 저렴한 비용	프리 티어 (t2.micro)로 테스트용 서버 운영 가능
✅ 퍼블릭 IP 제공	도메인 없이도 외부에서 접근 가능
✅ 직접 제어 가능	인바운드 포트, 디렉토리 구조, Docker 등 자유도 높음

➡️ 초보 개발자도 실제 클라우드 환경에서 배포 경험을 쌓기에 아주 적합하다.

▶ 왜 Docker로 배포했을까?

항목이유

✅ 환경 일관성	로컬에서 만든 이미지를 그대로 서버에서 실행
✅ 프로세스 격리	프론트/백엔드 컨테이너 분리 가능
✅ 간편한 재배포	docker pull + docker run으로 배포 끝

➡️ CI/CD가 없어도 운영 가능한 실전형 수동 배포를 경험할 수 있다.

✈️ EC2 인스턴스 준비하기

1. EC2 생성

Ubuntu 20.04 이상 선택
인스턴스 유형: t2.micro (프리티어)
보안 그룹 설정:
- 22 (SSH): 본인 IP만 허용
- 80 (HTTP): 전체 허용
- 8081 (API 테스트용): 전체 허용 또는 특정 IP

2. EC2 접속 (Windows 기준)

ssh -i "C:/Users/yourname/your-key.pem" ubuntu@<퍼블릭-IP>

Docker로 서비스 이미지 빌드 & 푸시

1. Docker 설치 (EC2 내부)

sudo apt update
sudo apt install docker.io -y
sudo usermod -aG docker ubuntu

설치 후 exit → 다시 접속해야 docker 권한 적용됨

2. Docker Hub 로그인

docker login

⚖️ 이미지 빌드 & 푸시

백엔드 빌드 & 푸시

# 루트에 Dockerfile 있어야 함
cd 개발 폴더명
./gradlew build -x test

docker build -t <계정명>/share-back:latest .
docker push <계정명>/share-back:latest

3. 프론트 빌드 & 푸시

cd 폴더명
npm run build

docker build -t <계정명>/share-front:latest .
docker push <계정명>/share-front:latest

☁️ EC2에서 Docker 이미지 실행

백엔드 (8081)

docker pull <계정명>/share-back:latest
docker run -d --name share-back -p 8081:8081 <계정명>/share-back:latest

프론트 실행 (nginx 내장)

docker pull <계정명>/share-front:latest
docker run -d --name share-front -p 80:80 <계정명>/share-front:latest

문제 해결: CORS 403 오류

문제

프론트에서 EC2의 백엔드 API 호출 시 403 Forbidden 발생

원인

Spring Boot에서 별도의 CORS 설정이 없으면 브라우저 요청 차단

✅ 해결 코드

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowedHeaders("*");
    }
}

배포용 환경에서는 allowedOrigins("*") 대신 도메인 또는 IP 제한 필요

테스트 및 결과 확인

백엔드 API 확인
http://<EC2-IP>:8081/api/rewards/summary?userId=u-123
프론트 웹 확인
http://<EC2-IP>

배운 점

배포는 "서버에 띄우는 것" 이상으로, 네트워크, 보안, 설정, 디버깅 등 실무 감각이 필요한 작업이다.
직접 퍼블릭 클라우드에 Docker 컨테이너를 띄우며, 운영 환경과 개발 환경의 차이를 몸으로 체감할 수 있었다.
“왜 이 기술을 선택했는가?” “무엇이 문제였고 어떻게 해결했는가?” 를 고민하는 과정에서 개발자로서 한층 성장했다.

아키텍처 구성도

 [  사용자]
     │
     ▼
 [  브라우저]
     │
     ▼
[  EC2: 프론트 (80포트, Vite + Nginx)]
     │
     ▼
[  EC2: 백엔드 API (8081포트, Spring Boot)]
     │
     ▼
[  Kafka: 공유/보상 이벤트 전송 및 처리]

Spring Boot Kafka 개발 중 “No qualifying bean” 에러 해결기

tues — Sun, 7 Sep 2025 14:54:39 +0900

Kafka 이벤트 발행/소비를 구현하면서,

ShareController 에서 ShareEventProducer 를 주입받아 /shares 요청을 처리하도록 만들었다.
하지만 실행 직후 아래와 같은 에러로 애플리케이션이 뜨지 않았다.

로그에 찍힌 에러:

Parameter 0 of constructor in com.kafka.demo.ShareController 
required a bean of type 'com.kafka.demo.ShareEventProducer' that could not be found.

원인

ShareController 는 com.kafka.demo.ShareEventProducer 타입을 의존.
실제 클래스는 com.kafka.demo.producer.ShareEventProducer 에 존재.
패키지 불일치로 인해 스프링이 해당 빈을 찾을 수 없었던 것.
스프링의 컴포넌트 스캔은 @SpringBootApplication 이 선언된 패키지의 하위 패키지만 대상으로 동작한다.
따라서 import 경로가 정확히 맞지 않으면 빈 주입에 실패한다.

해결방법

ShareController 에서 올바른 import 적용:

@Service
public class ShareEventProducer { ... }

2. ShareEventProducer 클래스에 @Service 추가:

import com.kafka.demo.producer.ShareEventProducer;

3. 메인 클래스(DemoApplication)는 com.kafka.demo 최상위에 위치해 서브 패키지를 스캔하도록 유지.

빌드 후 다시 실행하니 정상적으로 서버가 기동되었고, /shares 요청이 Kafka share.created.v1 토픽으로 메시지를 발행했다.

원칙 & 교훈

FQCN(Fully Qualified Class Name) 은 패키지 + 클래스명 조합으로 스프링 빈을 찾는 기준이다.
컨트롤러 → 서비스 → 리포지토리 구조를 만들 때는 패키지/임포트 경로를 일관되게 관리해야 한다.
스프링의 컴포넌트 스캔은 @SpringBootApplication 의 패키지를 기준으로 하위 패키지까지 탐색한다는 점을 잊지 말자.

참고자료

https://docs.spring.io/spring-framework/reference/core/beans/classpath-scanning.html

Classpath Scanning and Managed Components :: Spring Framework

By default, classes annotated with @Component, @Repository, @Service, @Controller, @Configuration, or a custom annotation that itself is annotated with @Component are the only detected candidate components. However, you can modify and extend this behavior

docs.spring.io

카프카(Kafka) 로컬 환경 구축과 기본 개념 정리

tues — Fri, 5 Sep 2025 21:57:20 +0900

1. Kafka 기본 구성 요소

Producer

메시지를 생성해서 Kafka 브로커(클러스터)에 전송하는 주체
예: 회원가입 이벤트 발생 시 user.signed-up 메시지를 발행

Broker

Kafka 서버 자체
Producer가 보낸 메시지를 받아서 토픽(Topic) 에 저장하고 Consumer에게 전달
여러 개의 Broker가 모여 클러스터를 구성

Topic

메시지가 저장되는 카테고리
예: demo.topic, user.signed-up, order.completed
토픽은 여러 개의 파티션(Partition) 으로 나눠져서 분산 저장됨

Partition & Offset

Partition: 토픽을 여러 조각으로 나눈 단위 → 병렬 처리 가능
Offset: 각 파티션에서 메시지가 기록되는 순번

Consumer

Kafka 브로커에서 메시지를 가져와 처리하는 주체
예: 이메일 서비스가 user.signed-up 메시지를 읽고 환영 메일 발송

Consumer Group

여러 Consumer가 협력해서 토픽을 분산 처리하는 구조
같은 그룹 안에서는 한 파티션을 동시에 두 Consumer가 처리하지 않음

(출처: Apache Kafka 공식 문서)

https://kafka.apache.org/documentation/#introduction

Apache Kafka

Apache Kafka: A Distributed Streaming Platform.

kafka.apache.org

흐름:

Producer가 메시지를 특정 Topic에 전송
Broker는 메시지를 받아서 Partition 단위로 저장
Consumer Group이 Topic을 구독하고 메시지를 가져옴
Consumer는 메시지를 처리 (예: DB 저장, 알림 발송 등)

2. 로컬 환경 구성 (Docker Compose)

docker-compose.yml

services:
  kafka:
    image: bitnami/kafka:latest
    ports:
      - "29092:29092"
    environment:
      - KAFKA_CFG_NODE_ID=0
      - KAFKA_CFG_PROCESS_ROLES=broker,controller
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,PLAINTEXT_HOST://:29092,CONTROLLER://:9093
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092,PLAINTEXT_HOST://localhost:29092
      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=0@kafka:9093
      - KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE=true
      - KAFKA_ENABLE_KRAFT=yes

  kafka-ui:
    image: provectuslabs/kafka-ui:latest
    ports:
      - "8080:8080"
    environment:
      - KAFKA_CLUSTERS_0_NAME=local
      - KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS=kafka:9092
    depends_on:
      - kafka

3. 토픽 생성 & 메시지 전송 실습

1) 토픽 생성

Kafka UI → Topics → Create Topic → demo.topic 생성

2) 메시지 보내기 (Producer)

docker compose exec -it kafka /opt/bitnami/kafka/bin/kafka-console-producer.sh --bootstrap-server kafka:9092 --topic demo.topic

hello
kafka
event-driven

3) 메시지 받기 (Consumer)

docker compose exec -it kafka /opt/bitnami/kafka/bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic demo.topic --from-beginning

4. 정리 및 느낀 점

이번 실습을 통해:

Kafka의 기본 원리와 요소 (Producer, Broker, Topic, Consumer)를 이해하고
로컬 환경에서 메시지를 발행하고 소비하는 과정을 직접 경험했습니다.

이 단계만으로도 “내 서비스가 이벤트를 Kafka로 흘려보내고, 다른 서비스가 이를 받아 처리한다”는 그림이 머리에 그려집니다.