Cloudflare Workers 실전 가이드 — 엣지 컴퓨팅 입문

Cloudflare Workers란 무엇인가

Wrangler CLI로 첫 Workers 프로젝트 셋업

Wrangler 설치 및 프로젝트 초기화
# Wrangler CLI 설치
npm install -g wrangler

# Cloudflare 계정 로그인
wrangler login

# 새 Workers 프로젝트 생성 (TypeScript 템플릿)
npm create cloudflare@latest my-worker -- --type=hello-world-typescript

cd my-worker

# 로컬 개발 서버 시작 (http://localhost:8787)
wrangler dev

# 프로덕션 배포
wrangler deploy

src/index.ts — 기본 Workers 핸들러 구조
export interface Env {
  MY_KV: KVNamespace
  MY_DB: D1Database
  MY_BUCKET: R2Bucket
  // 환경 변수
  API_KEY: string
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url)

    // 라우팅 예시
    if (url.pathname === '/api/hello') {
      return Response.json({ message: 'Hello from the Edge!' })
    }

    if (url.pathname === '/api/kv' && request.method === 'GET') {
      const value = await env.MY_KV.get('my-key')
      return Response.json({ value })
    }

    return new Response('Not Found', { status: 404 })
  }
}

KV / D1 / R2 — 스토리지 선택 기준

D1 데이터베이스 — wrangler.toml 설정 및 쿼리 예시
# wrangler.toml
[[d1_databases]]
binding = "MY_DB"
database_name = "my-app-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# D1 마이그레이션 파일 생성
# migrations/0001_create_users.sql

D1 쿼리 실전 예시 — Workers에서 SQLite 사용
// Workers에서 D1 쿼리
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method === 'POST' && new URL(request.url).pathname === '/api/users') {
      const { name, email } = await request.json() as { name: string; email: string }

      // D1에 데이터 삽입
      const result = await env.MY_DB
        .prepare('INSERT INTO users (name, email) VALUES (?1, ?2) RETURNING id')
        .bind(name, email)
        .first<{ id: number }>()

      return Response.json({ id: result?.id }, { status: 201 })
    }

    if (request.method === 'GET' && new URL(request.url).pathname === '/api/users') {
      const users = await env.MY_DB
        .prepare('SELECT id, name, email FROM users ORDER BY id DESC LIMIT 50')
        .all()

      return Response.json(users.results)
    }

    return new Response('Not Found', { status: 404 })
  }
}

Hono 프레임워크 — Workers에서 Express처럼 개발하기

Hono로 REST API 구축 — Workers 실전 예시
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const app = new Hono<{ Bindings: Env }>()

// 미들웨어 — API Key 인증
app.use('/api/*', async (c, next) => {
  const apiKey = c.req.header('x-api-key')
  if (apiKey !== c.env.API_KEY) {
    return c.json({ error: 'Unauthorized' }, 401)
  }
  await next()
})

const userSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
})

app.post('/api/users', zValidator('json', userSchema), async (c) => {
  const { name, email } = c.req.valid('json')
  const result = await c.env.MY_DB
    .prepare('INSERT INTO users (name, email) VALUES (?1, ?2) RETURNING id')
    .bind(name, email)
    .first<{ id: number }>()
  return c.json({ id: result?.id }, 201)
})

app.get('/api/users/:id', async (c) => {
  const id = c.req.param('id')
  const user = await c.env.MY_DB
    .prepare('SELECT * FROM users WHERE id = ?')
    .bind(id)
    .first()
  if (!user) return c.json({ error: 'Not found' }, 404)
  return c.json(user)
})

export default app

Workers가 맞는 경우, 맞지 않는 경우