7. Workers KV로 데이터 저장하기

Worker는 요청이 끝나면 상태가 사라지는 stateless 함수입니다. 데이터를 저장하려면 Workers KV(전역 분산 key-value 스토어) 같은 외부 저장소가 필요합니다.

7.1 KV 네임스페이스 만들기

bash
npx wrangler kv namespace create VISITS_KV

실행하면 아래와 같은 출력이 나오고, id 값을 wrangler.jsonc에 넣으라고 안내해줍니다.

text

🌀 Creating namespace with title "cloudflare-workers-course-sample-VISITS_KV"
✨ Success!
Add the following to your configuration file:
{
  "kv_namespaces": [
    {
      "binding": "VISITS_KV",
      "id": "abcd1234...."
    }
  ]
}

7.2 wrangler.jsonc에 바인딩 추가

jsonc

{
  "name": "cloudflare-workers-course-sample",
  "main": "src/index.js",
  "compatibility_date": "2024-11-01",
  "kv_namespaces": [
    {
      "binding": "VISITS_KV",
      "id": "abcd1234...."
    }
  ]
}

이 강의의 sample-worker/wrangler.jsonc에는 자리표시자(placeholder) id가 들어 있습니다. 실제로 배포하려면 위 명령으로 직접 발급받은 id로 교체해야 합니다. (로컬 개발 시에는 placeholder 그대로 두어도 로컬 시뮬레이션 KV로 동작합니다.)

7.3 코드에서 KV 사용하기

env.<BINDING_NAME>으로 접근하며, 세 가지 기본 메서드를 사용합니다.

js
await env.VISITS_KV.put("key", "value");     // 쓰기
const value = await env.VISITS_KV.get("key"); // 읽기 (없으면 null)
await env.VISITS_KV.delete("key");            // 삭제

이 강의의 샘플 프로젝트에는 방문 횟수를 세는 예제가 들어 있습니다. (sample-worker/src/index.js 의 handleVisits 함수)

js
async function handleVisits(env) {
  const current = await env.VISITS_KV.get("count");
  const next = (Number(current) || 0) + 1;
  await env.VISITS_KV.put("count", String(next));

  return Response.json({ visits: next });
}

/api/visits를 호출할 때마다 count 값을 읽어서 1 증가시키고 다시 저장합니다.

7.4 직접 실행해보기

bash
cd cloudflare-workers-course/sample-worker
npm install
npm run dev

다른 터미널에서:

bash
curl http://localhost:8787/api/visits   # {"visits":1}
curl http://localhost:8787/api/visits   # {"visits":2}
curl http://localhost:8787/api/visits   # {"visits":3}

호출할 때마다 숫자가 증가하는 것을 확인할 수 있습니다. (로컬 모드에서는 값이 .wrangler 폴더에 저장되어 개발 서버를 재시작해도 유지됩니다.)

7.5 KV 사용 시 알아둘 점

KV는 최종적 일관성(eventually consistent)을 가진 저장소입니다. 한 리전에서 쓴 값이 다른 리전에서 즉시 보이지 않을 수 있습니다.
초당 수천 회 이상의 잦은 쓰기가 필요한 카운터라면 KV보다 Durable Objects가 더 적합합니다.
관계형 데이터가 필요하다면 D1(SQLite 기반) 사용을 고려하세요.

참고 자료

➡️ 다음: 실제로 배포하기 ⬅️ 이전: 환경 변수와 시크릿