우리가 구축할 것: CatalogAPI

이 기사에서 우리는 카탈로그API: 카탈로그용 REST API JWT 인증, 이미지 업로드, 전체 텍스트 검색 및 속도 제한 기능을 갖춘 제품입니다. 건축 용도 홀로 Cloudflare: 컴퓨팅을 위한 작업자, 데이터베이스를 위한 D1 관계형, 자산 저장을 위한 R2, 세션 및 속도 제한을 위한 KV. 제로 서버 VPC 없이 300개 이상의 PoP에 대한 자동 글로벌 배포를 관리합니다.

사례 연구 기술 스택

  • 컴퓨팅: Cloudflare 작업자(TypeScript, Hono.js 프레임워크)
  • 데이터베이스: 자동 마이그레이션 기능이 있는 D1(SQLite)
  • 객체 스토리지: 제품 이미지용 R2
  • 캐시/세션: 노동자 KV
  • 인증: Workers Secret에 개인 키가 있는 JWT
  • 속도 제한: 원자 KV가 있는 슬라이딩 윈도우
  • CI/CD: 자동 테스트 및 배포 기능을 갖춘 GitHub Actions
  • 모니터링: Cloudflare 작업자가 R2에 로그 푸시

프로젝트 구조

catalog-api/
  src/
    index.ts              # Entry point, setup Hono
    middleware/
      auth.ts             # JWT verification middleware
      rateLimit.ts        # Sliding window rate limiter
      cors.ts             # CORS headers
    routes/
      products.ts         # CRUD prodotti
      categories.ts       # CRUD categorie
      uploads.ts          # Upload immagini su R2
      auth.ts             # Login / refresh token
    services/
      jwt.ts              # Firma e verifica JWT
      search.ts           # Full-text search su D1
    types/
      env.ts              # Interfaccia Env (binding)
      models.ts           # Interfacce dati
  migrations/
    0001_initial.sql      # Schema D1 iniziale
    0002_full_text.sql    # FTS5 extension
  test/
    routes/
      products.test.ts
      auth.test.ts
    integration/
      upload.test.ts
  wrangler.toml
  vitest.config.ts

계획 D1: 데이터베이스 설계

-- migrations/0001_initial.sql

CREATE TABLE categories (
  id        TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  name      TEXT NOT NULL UNIQUE,
  slug      TEXT NOT NULL UNIQUE,
  created_at INTEGER DEFAULT (unixepoch())
);

CREATE TABLE products (
  id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  name         TEXT NOT NULL,
  slug         TEXT NOT NULL UNIQUE,
  description  TEXT,
  price        REAL NOT NULL CHECK (price >= 0),
  stock        INTEGER NOT NULL DEFAULT 0 CHECK (stock >= 0),
  category_id  TEXT REFERENCES categories(id) ON DELETE SET NULL,
  image_key    TEXT,           -- chiave R2 per l'immagine principale
  status       TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'inactive', 'deleted')),
  created_at   INTEGER DEFAULT (unixepoch()),
  updated_at   INTEGER DEFAULT (unixepoch())
);

CREATE INDEX idx_products_category ON products(category_id);
CREATE INDEX idx_products_status ON products(status);
CREATE INDEX idx_products_price ON products(price);

CREATE TABLE users (
  id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  email        TEXT NOT NULL UNIQUE,
  password_hash TEXT NOT NULL,
  role         TEXT NOT NULL DEFAULT 'viewer' CHECK (role IN ('admin', 'editor', 'viewer')),
  created_at   INTEGER DEFAULT (unixepoch())
);

-- migrations/0002_full_text.sql
-- FTS5 per ricerca full-text efficiente
CREATE VIRTUAL TABLE products_fts USING fts5(
  id UNINDEXED,
  name,
  description,
  content='products',
  content_rowid='rowid'
);

-- Trigger per mantenere sincronizzata la FTS table
CREATE TRIGGER products_ai AFTER INSERT ON products BEGIN
  INSERT INTO products_fts(rowid, id, name, description)
  VALUES (new.rowid, new.id, new.name, new.description);
END;

CREATE TRIGGER products_au AFTER UPDATE ON products BEGIN
  UPDATE products_fts SET name = new.name, description = new.description
  WHERE id = new.id;
END;

CREATE TRIGGER products_ad AFTER DELETE ON products BEGIN
  DELETE FROM products_fts WHERE id = old.id;
END;

진입점: 작업자의 Hono.js

Hono.js Workers에서 가장 많이 사용되는 웹 프레임워크는 다음과 같습니다. Edge(Node.js 종속성 없음)용으로 작성되었으며 초고속 라우터가 있습니다. TypeScript를 사용하는 구성 가능하고 유형이 안전한 미들웨어입니다. 

// src/index.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { secureHeaders } from 'hono/secure-headers';
import { timing } from 'hono/timing';

import { authMiddleware } from './middleware/auth';
import { rateLimitMiddleware } from './middleware/rateLimit';
import { productsRouter } from './routes/products';
import { categoriesRouter } from './routes/categories';
import { uploadsRouter } from './routes/uploads';
import { authRouter } from './routes/auth';
import type { Env } from './types/env';

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

// Middleware globali
app.use('*', cors({
  origin: ['https://myapp.com', 'https://admin.myapp.com'],
  allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
  allowHeaders: ['Content-Type', 'Authorization'],
  maxAge: 86400,
}));

app.use('*', secureHeaders());
app.use('*', timing());

// Rate limiting su tutte le route API
app.use('/api/*', rateLimitMiddleware);

// Route pubbliche (no auth)
app.route('/api/auth', authRouter);
app.get('/api/products', async (c) => {
  // GET list e pubblico, senza autenticazione
  const { default: handler } = await import('./routes/products');
  return handler.fetch(c.req.raw, c.env, c.executionCtx);
});

// Route protette (richiedono JWT)
app.use('/api/products/*', authMiddleware);
app.use('/api/categories/*', authMiddleware);
app.use('/api/uploads/*', authMiddleware);

app.route('/api/products', productsRouter);
app.route('/api/categories', categoriesRouter);
app.route('/api/uploads', uploadsRouter);

// Health check
app.get('/health', (c) => c.json({ status: 'ok', timestamp: Date.now() }));

// 404 handler
app.notFound((c) => c.json({ error: 'Not Found' }, 404));

// Error handler
app.onError((err, c) => {
  console.error('Unhandled error:', err);
  return c.json({ error: 'Internal Server Error' }, 500);
});

export default app;

인증: 작업자 비밀이 포함된 JWT

// src/services/jwt.ts
// Web Crypto API (disponibile in Workers, nessuna dipendenza esterna)

const JWT_ALGORITHM = 'HS256';

export async function signJWT(
  payload: Record<string, unknown>,
  secret: string,
  expiresInSeconds = 3600
): Promise<string> {
  const header = { alg: JWT_ALGORITHM, typ: 'JWT' };

  const now = Math.floor(Date.now() / 1000);
  const fullPayload = {
    ...payload,
    iat: now,
    exp: now + expiresInSeconds,
  };

  const encodedHeader = btoa(JSON.stringify(header)).replace(/=/g, '');
  const encodedPayload = btoa(JSON.stringify(fullPayload)).replace(/=/g, '');
  const data = `${encodedHeader}.${encodedPayload}`;

  const key = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );

  const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(data));
  const encodedSignature = btoa(String.fromCharCode(...new Uint8Array(signature))).replace(/=/g, '');

  return `${data}.${encodedSignature}`;
}

export async function verifyJWT(
  token: string,
  secret: string
): Promise<Record<string, unknown> | null> {
  try {
    const [encodedHeader, encodedPayload, encodedSignature] = token.split('.');

    if (!encodedHeader || !encodedPayload || !encodedSignature) return null;

    // Verifica firma
    const data = `${encodedHeader}.${encodedPayload}`;
    const key = await crypto.subtle.importKey(
      'raw',
      new TextEncoder().encode(secret),
      { name: 'HMAC', hash: 'SHA-256' },
      false,
      ['verify']
    );

    const signatureBytes = Uint8Array.from(atob(encodedSignature.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0));
    const valid = await crypto.subtle.verify('HMAC', key, signatureBytes, new TextEncoder().encode(data));

    if (!valid) return null;

    // Verifica scadenza
    const payload = JSON.parse(atob(encodedPayload)) as { exp: number };
    if (payload.exp < Math.floor(Date.now() / 1000)) return null;

    return payload as Record<string, unknown>;
  } catch {
    return null;
  }
}

// src/middleware/auth.ts
import type { MiddlewareHandler } from 'hono';
import { verifyJWT } from '../services/jwt';
import type { Env } from '../types/env';

export const authMiddleware: MiddlewareHandler<{ Bindings: Env }> = async (c, next) => {
  const authHeader = c.req.header('Authorization');

  if (!authHeader?.startsWith('Bearer ')) {
    return c.json({ error: 'Missing or invalid Authorization header' }, 401);
  }

  const token = authHeader.slice(7);
  const payload = await verifyJWT(token, c.env.JWT_SECRET);

  if (!payload) {
    return c.json({ error: 'Invalid or expired token' }, 401);
  }

  // Passa il payload al contesto per i route handler successivi
  c.set('user', payload);
  await next();
};

속도 제한: KV를 사용한 슬라이딩 윈도우

// src/middleware/rateLimit.ts
// Sliding window rate limiter: massimo N richieste per finestra temporale

import type { MiddlewareHandler } from 'hono';
import type { Env } from '../types/env';

const WINDOW_SIZE_SECONDS = 60;  // Finestra di 1 minuto
const MAX_REQUESTS = 100;         // 100 richieste per finestra (per IP)

export const rateLimitMiddleware: MiddlewareHandler<{ Bindings: Env }> = async (c, next) => {
  // Usa l'IP del client come chiave (Cloudflare lo espone in cf.connectingIp)
  const clientIp = c.req.header('CF-Connecting-IP') ??
                   c.req.header('X-Forwarded-For') ??
                   'unknown';

  const now = Math.floor(Date.now() / 1000);
  const windowStart = now - WINDOW_SIZE_SECONDS;
  const key = `ratelimit:${clientIp}:${Math.floor(now / WINDOW_SIZE_SECONDS)}`;

  // Recupera il contatore corrente per questa finestra
  const currentCount = parseInt(await c.env.RATE_LIMIT_KV.get(key) ?? '0');

  if (currentCount >= MAX_REQUESTS) {
    const resetAt = (Math.floor(now / WINDOW_SIZE_SECONDS) + 1) * WINDOW_SIZE_SECONDS;
    return c.json(
      { error: 'Rate limit exceeded', resetAt },
      429,
      {
        'X-RateLimit-Limit': String(MAX_REQUESTS),
        'X-RateLimit-Remaining': '0',
        'X-RateLimit-Reset': String(resetAt),
        'Retry-After': String(resetAt - now),
      }
    );
  }

  // Incrementa il contatore
  const newCount = currentCount + 1;
  c.executionCtx.waitUntil(
    c.env.RATE_LIMIT_KV.put(key, String(newCount), {
      expirationTtl: WINDOW_SIZE_SECONDS * 2,
    })
  );

  // Aggiungi header informativi
  c.header('X-RateLimit-Limit', String(MAX_REQUESTS));
  c.header('X-RateLimit-Remaining', String(MAX_REQUESTS - newCount));

  await next();
};

제품 경로: D1을 사용한 CRUD

// src/routes/products.ts
import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';
import type { Env } from '../types/env';

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

// Schema di validazione con Zod
const createProductSchema = z.object({
  name: z.string().min(1).max(200),
  slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
  description: z.string().max(5000).optional(),
  price: z.number().min(0),
  stock: z.number().int().min(0).default(0),
  category_id: z.string().uuid().optional(),
});

// GET /api/products - Lista con paginazione, filtri e ricerca
productsRouter.get('/', async (c) => {
  const { page = '1', limit = '20', category, search, min_price, max_price } = c.req.query();

  const pageNum = Math.max(1, parseInt(page));
  const limitNum = Math.min(100, Math.max(1, parseInt(limit)));
  const offset = (pageNum - 1) * limitNum;

  let query: string;
  const params: (string | number)[] = [];

  if (search) {
    // Full-text search via FTS5
    query = `
      SELECT p.*, c.name as category_name
      FROM products_fts f
      JOIN products p ON f.id = p.id
      LEFT JOIN categories c ON p.category_id = c.id
      WHERE products_fts MATCH ? AND p.status = 'active'
    `;
    params.push(search);
  } else {
    query = `
      SELECT p.*, c.name as category_name
      FROM products p
      LEFT JOIN categories c ON p.category_id = c.id
      WHERE p.status = 'active'
    `;
  }

  if (category) {
    query += ` AND c.slug = ?`;
    params.push(category);
  }

  if (min_price) {
    query += ` AND p.price >= ?`;
    params.push(parseFloat(min_price));
  }

  if (max_price) {
    query += ` AND p.price <= ?`;
    params.push(parseFloat(max_price));
  }

  // Count totale per paginazione
  const countQuery = `SELECT COUNT(*) as total FROM (${query})`;
  const countResult = await c.env.DB.prepare(countQuery).bind(...params).first<{ total: number }>();
  const total = countResult?.total ?? 0;

  // Query paginata
  query += ` ORDER BY p.created_at DESC LIMIT ? OFFSET ?`;
  params.push(limitNum, offset);

  const products = await c.env.DB.prepare(query).bind(...params).all();

  return c.json({
    data: products.results,
    pagination: {
      page: pageNum,
      limit: limitNum,
      total,
      pages: Math.ceil(total / limitNum),
    },
  });
});

// GET /api/products/:id
productsRouter.get('/:id', async (c) => {
  const id = c.req.param('id');

  const product = await c.env.DB.prepare(`
    SELECT p.*, c.name as category_name, c.slug as category_slug
    FROM products p
    LEFT JOIN categories c ON p.category_id = c.id
    WHERE p.id = ? AND p.status != 'deleted'
  `).bind(id).first();

  if (!product) {
    return c.json({ error: 'Product not found' }, 404);
  }

  // Aggiungi URL pre-firmato per l'immagine R2 (valido 1 ora)
  let imageUrl: string | null = null;
  if ((product as { image_key?: string }).image_key) {
    const key = (product as { image_key: string }).image_key;
    // Usa URL pubblica R2 (richiede bucket pubblico o URL custom domain)
    imageUrl = `https://assets.myapp.com/${key}`;
  }

  return c.json({ ...product, imageUrl });
});

// POST /api/products - Crea prodotto (richiede auth admin/editor)
productsRouter.post('/', zValidator('json', createProductSchema), async (c) => {
  const user = c.get('user') as { role: string } | undefined;

  if (!user || !['admin', 'editor'].includes(user.role)) {
    return c.json({ error: 'Insufficient permissions' }, 403);
  }

  const data = c.req.valid('json');

  // Verifica univocità slug
  const existing = await c.env.DB.prepare(
    'SELECT id FROM products WHERE slug = ?'
  ).bind(data.slug).first();

  if (existing) {
    return c.json({ error: 'Slug already exists' }, 409);
  }

  const result = await c.env.DB.prepare(`
    INSERT INTO products (name, slug, description, price, stock, category_id)
    VALUES (?, ?, ?, ?, ?, ?)
    RETURNING *
  `).bind(
    data.name,
    data.slug,
    data.description ?? null,
    data.price,
    data.stock,
    data.category_id ?? null
  ).first();

  return c.json(result, 201);
});

// PATCH /api/products/:id
productsRouter.patch('/:id', async (c) => {
  const id = c.req.param('id');
  const user = c.get('user') as { role: string } | undefined;

  if (!user || !['admin', 'editor'].includes(user.role)) {
    return c.json({ error: 'Insufficient permissions' }, 403);
  }

  const body = await c.req.json() as Partial<{ name: string; price: number; stock: number; status: string }>;

  const updates: string[] = [];
  const values: (string | number)[] = [];

  if (body.name !== undefined) { updates.push('name = ?'); values.push(body.name); }
  if (body.price !== undefined) { updates.push('price = ?'); values.push(body.price); }
  if (body.stock !== undefined) { updates.push('stock = ?'); values.push(body.stock); }
  if (body.status !== undefined) { updates.push('status = ?'); values.push(body.status); }

  if (updates.length === 0) {
    return c.json({ error: 'No fields to update' }, 400);
  }

  updates.push('updated_at = unixepoch()');
  values.push(id);

  const result = await c.env.DB.prepare(
    `UPDATE products SET ${updates.join(', ')} WHERE id = ? AND status != 'deleted' RETURNING *`
  ).bind(...values).first();

  if (!result) {
    return c.json({ error: 'Product not found' }, 404);
  }

  return c.json(result);
});

export { productsRouter };

R2에 이미지 업로드

// src/routes/uploads.ts
import { Hono } from 'hono';
import type { Env } from '../types/env';

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

const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp', 'image/avif'];
const MAX_SIZE_BYTES = 5 * 1024 * 1024; // 5MB

uploadsRouter.post('/product-image/:productId', async (c) => {
  const productId = c.req.param('productId');
  const user = c.get('user') as { role: string } | undefined;

  if (!user || !['admin', 'editor'].includes(user.role)) {
    return c.json({ error: 'Insufficient permissions' }, 403);
  }

  // Verifica che il prodotto esista
  const product = await c.env.DB.prepare(
    "SELECT id FROM products WHERE id = ? AND status != 'deleted'"
  ).bind(productId).first();

  if (!product) {
    return c.json({ error: 'Product not found' }, 404);
  }

  const formData = await c.req.formData();
  const file = formData.get('image') as File | null;

  if (!file) {
    return c.json({ error: 'No image file provided' }, 400);
  }

  // Validazione tipo e dimensione
  if (!ALLOWED_TYPES.includes(file.type)) {
    return c.json({
      error: `Invalid file type. Allowed: ${ALLOWED_TYPES.join(', ')}`
    }, 400);
  }

  if (file.size > MAX_SIZE_BYTES) {
    return c.json({ error: 'File too large. Maximum 5MB' }, 400);
  }

  // Genera chiave R2 univoca
  const ext = file.type.split('/')[1];
  const r2Key = `products/${productId}/${crypto.randomUUID()}.${ext}`;

  // Upload su R2
  await c.env.ASSETS_BUCKET.put(r2Key, file.stream(), {
    httpMetadata: {
      contentType: file.type,
      cacheControl: 'public, max-age=31536000, immutable',
    },
    customMetadata: {
      productId,
      originalName: file.name,
      uploadedAt: new Date().toISOString(),
    },
  });

  // Aggiorna il prodotto con la nuova chiave R2
  // Prima elimina l'immagine precedente se esiste
  const oldProduct = await c.env.DB.prepare(
    'SELECT image_key FROM products WHERE id = ?'
  ).bind(productId).first<{ image_key: string | null }>();

  if (oldProduct?.image_key) {
    // Elimina la vecchia immagine in background
    c.executionCtx.waitUntil(
      c.env.ASSETS_BUCKET.delete(oldProduct.image_key)
    );
  }

  await c.env.DB.prepare(
    'UPDATE products SET image_key = ?, updated_at = unixepoch() WHERE id = ?'
  ).bind(r2Key, productId).run();

  return c.json({
    key: r2Key,
    url: `https://assets.myapp.com/${r2Key}`,
    size: file.size,
    type: file.type,
  }, 201);
});

// DELETE /api/uploads/product-image/:productId
uploadsRouter.delete('/product-image/:productId', async (c) => {
  const productId = c.req.param('productId');
  const user = c.get('user') as { role: string } | undefined;

  if (!user || user.role !== 'admin') {
    return c.json({ error: 'Admin required' }, 403);
  }

  const product = await c.env.DB.prepare(
    'SELECT image_key FROM products WHERE id = ?'
  ).bind(productId).first<{ image_key: string | null }>();

  if (!product?.image_key) {
    return c.json({ error: 'No image found for this product' }, 404);
  }

  await c.env.ASSETS_BUCKET.delete(product.image_key);

  await c.env.DB.prepare(
    'UPDATE products SET image_key = NULL, updated_at = unixepoch() WHERE id = ?'
  ).bind(productId).run();

  return new Response(null, { status: 204 });
});

export { uploadsRouter };

wrangler.toml 완료

# wrangler.toml
name = "catalog-api"
main = "src/index.ts"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]

# Worker deve avere Workers Paid Plan per D1, R2 e CPU > 10ms
account_id = "YOUR_ACCOUNT_ID"

[[d1_databases]]
binding = "DB"
database_name = "catalog-db"
database_id = "YOUR_D1_DATABASE_ID"
migrations_dir = "migrations"  # wrangler d1 migrations apply catalog-db

[[r2_buckets]]
binding = "ASSETS_BUCKET"
bucket_name = "catalog-assets"
# Configura custom domain per URL pubblici: https://assets.myapp.com

[[kv_namespaces]]
binding = "RATE_LIMIT_KV"
id = "YOUR_KV_NAMESPACE_ID"

# Secrets (impostati con: wrangler secret put JWT_SECRET)
# JWT_SECRET = ...  (non nel file, usa wrangler secret)

[vars]
ENVIRONMENT = "production"
MAX_UPLOAD_MB = "5"

# Configurazione per staging
[env.staging]
name = "catalog-api-staging"
vars = { ENVIRONMENT = "staging" }

[[env.staging.d1_databases]]
binding = "DB"
database_name = "catalog-db-staging"
database_id = "YOUR_STAGING_D1_ID"

# Routes: mappa il Worker al custom domain
[[routes]]
pattern = "api.myapp.com/*"
zone_id = "YOUR_ZONE_ID"

마이그레이션 D1: 구성표 적용

# Crea il database D1
npx wrangler d1 create catalog-db

# Applica le migration iniziali
npx wrangler d1 migrations apply catalog-db

# In staging (dry run per verificare)
npx wrangler d1 migrations apply catalog-db --env staging --dry-run

# Query diretta per debug (locale)
npx wrangler d1 execute catalog-db --local --command "SELECT count(*) FROM products"

# Esporta snapshot per backup
npx wrangler d1 export catalog-db --output backup-$(date +%Y%m%d).sql

CI/CD: GitHub 작업 완료

# .github/workflows/deploy.yml
name: Test and Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  NODE_VERSION: '20'

jobs:
  test:
    name: Test
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - run: npm ci

      - name: TypeScript check
        run: npx tsc --noEmit

      - name: Lint
        run: npm run lint

      - name: Unit + Integration tests
        run: npx vitest run --coverage
        env:
          CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

  deploy-staging:
    name: Deploy Staging
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci

      - name: Apply D1 migrations (staging)
        run: npx wrangler d1 migrations apply catalog-db --env staging
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

      - name: Deploy to staging
        run: npx wrangler deploy --env staging
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

      - name: Run smoke tests against staging
        run: npm run test:e2e
        env:
          API_BASE_URL: https://catalog-api-staging.myapp.com

  deploy-production:
    name: Deploy Production
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci

      - name: Apply D1 migrations (production)
        run: npx wrangler d1 migrations apply catalog-db
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

      - name: Deploy to production
        run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

      - name: Purge Cloudflare Cache dopo deploy
        run: |
          curl -X POST "https://api.cloudflare.com/client/v4/zones/${{ secrets.CF_ZONE_ID }}/purge_cache" \
            -H "Authorization: Bearer ${{ secrets.CF_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            --data '{"purge_everything":true}'

관찰 가능성: 로그 및 모니터링

// src/middleware/logging.ts
// Middleware di logging strutturato verso R2 (via Logpush) o console

import type { MiddlewareHandler } from 'hono';
import type { Env } from '../types/env';

interface RequestLog {
  timestamp: string;
  method: string;
  path: string;
  status: number;
  durationMs: number;
  country: string;
  datacenter: string;
  ip: string;
  userAgent: string;
  userId?: string;
}

export const loggingMiddleware: MiddlewareHandler<{ Bindings: Env }> = async (c, next) => {
  const startTime = Date.now();

  await next();

  const durationMs = Date.now() - startTime;
  const user = c.get('user') as { id?: string } | undefined;

  const log: RequestLog = {
    timestamp: new Date().toISOString(),
    method: c.req.method,
    path: new URL(c.req.url).pathname,
    status: c.res.status,
    durationMs,
    country: c.req.header('CF-IPCountry') ?? 'unknown',
    datacenter: (c.req.raw as Request & { cf?: { colo?: string } }).cf?.colo ?? 'unknown',
    ip: c.req.header('CF-Connecting-IP') ?? 'unknown',
    userAgent: c.req.header('User-Agent') ?? 'unknown',
    userId: user?.id,
  };

  // Log strutturato verso console (visibile in Cloudflare Dashboard)
  console.log(JSON.stringify(log));

  // Configura Cloudflare Logpush nel dashboard per inviare automaticamente
  // i Workers logs verso R2, Datadog, Splunk, ecc.
};

// Alerting: monitora errori 5xx su Workers Analytics Engine

비용 및 확장: 경제적 분석

요소 가격 유료 플랜에 포함됨($5/월)
근로자의 요청 $0.30/백만(포함 후) 천만 / 월
작업자 CPU 시간 $0.02/백만 CPU-ms 3천만 CPU-ms/월
D1 행 읽기 $0.001/백만 250억/월
D1 행 작성됨 $1.00/백만 5천만/월
R2 스토리지 $0.015/GB/월 10GB
R2 작업 $0.36/백만 달러 클래스 A 100만 클래스 A, 10M 클래스 B
KV 읽기 $0.50/백만 천만 / 월

중간 트래픽 API의 경우(1M 요청/월, 100K D1 쓰기, 10GB R2): 총 비용은 대략 $5-15/월. 아키텍처 AWS(API Gateway + Lambda + RDS + S3 + CloudFront)에서는 이에 상응하는 비용이 발생합니다. 쉽게 $150-400/월 같은 규모로.

시리즈의 결론

이 사례 연구는 REST API 구축이 가능함을 보여주었습니다. 인증, 업로드, 전체 텍스트 검색 및 속도 제한 기능을 갖춘 완벽한 제작, 사용하여 홀로 Cloudflare 플랫폼. 결과는 응용 프로그램입니다 300개 이상의 글로벌 데이터 센터에 분산되어 있으며 지연 시간은 밀리초 미만입니다. 무한 자동이며 기존 클라우드 아키텍처에 비해 비용이 훨씬 저렴합니다.

기사 1에서 소개한 V8 분리물은 모든 것의 기초입니다. 콜드 스타트 없이 전 세계 어디에서나 TypeScript 코드를 실행할 수 있습니다. VPC 없이 서버 관리. 운영상의 복잡성이 제거됩니다. 비즈니스 복잡성은 여전히 ​​귀하의 것입니다.

관련 시리즈: 기타 리소스

  • 대규모 Kubernetes(시리즈 36): 작업자가 충분하지 않아 필요한 경우 더 많은 CPU와 RAM을 갖춘 컨테이너.
  • 이벤트 기반 아키텍처(시리즈 39): 작업자 + 큐 바인딩 비동기 패턴 및 처리 파이프라인.
  • DevSecOps(시리즈 05): 종속성 및 정책을 코드로 보안 검색 노동자 생태계에 적용됩니다.