Cloudflare開発のベストプラクティス

概要

このスキルは、Workers、Pages、KVストレージ、D1データベース、R2オブジェクトストレージ、Durable Objectsを含む、Cloudflareのエッジプラットフォーム上でのアプリケーション開発に関する包括的なガイドラインを提供します。

コア原則

• エッジ実行に最適化された軽量で高速なコードを記述する
• コールドスタート時間と実行時間を最小化する
• 各ユースケースに適したストレージソリューションを使用する
• エッジコンピューティングのセキュリティベストプラクティスに従う
• Cloudflareのグローバルネットワークを活用してパフォーマンスを向上させる

Cloudflare Workersガイドライン

基本的なWorker構造

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

      // Route handling
      if (url.pathname === '/api/data') {
        return handleApiRequest(request, env);
      }

      return new Response('Not Found', { status: 404 });
    } catch (error) {
      console.error('Worker error:', error);
      return new Response('Internal Server Error', { status: 500 });
    }
  },
} satisfies ExportedHandler<Env>;

環境型定義

interface Env {
  // KV Namespaces
  MY_KV: KVNamespace;

  // D1 Databases
  MY_DB: D1Database;

  // R2 Buckets
  MY_BUCKET: R2Bucket;

  // Durable Objects
  MY_DURABLE_OBJECT: DurableObjectNamespace;

  // Environment Variables
  API_KEY: string;
}

ベストプラクティス

• 型安全性のためTypeScriptを使用する
• エッジでエラーを適切に処理する
• 適切なリクエスト検証を実装する
• バックグラウンドタスクにctx.waitUntil()を使用する
• 可能な限り外部APIコールを最小化する

Wranglerの設定

wrangler.toml構造

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[vars]
ENVIRONMENT = "production"

[[kv_namespaces]]
binding = "MY_KV"
id = "abc123"

[[d1_databases]]
binding = "MY_DB"
database_name = "my-database"
database_id = "def456"

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

[durable_objects]
bindings = [
  { name = "MY_DURABLE_OBJECT", class_name = "MyDurableObject" }
]

[[migrations]]
tag = "v1"
new_classes = ["MyDurableObject"]

KVストレージガイドライン

使用パターン

// KVへの書き込み
await env.MY_KV.put('key', JSON.stringify(data), {
  expirationTtl: 3600, // 1 hour
  metadata: { version: '1.0' },
});

// KVからの読み取り
const value = await env.MY_KV.get('key', { type: 'json' });

// キーのリスト表示
const list = await env.MY_KV.list({ prefix: 'user:' });

ベストプラクティス

• KVを読み取り集約的なワークロード（結果整合性）に使用する
• キャッシュされたデータに適切なTTLを設定する
• メタデータを使用して追加のキー情報を保存する
• キャッシュ無効化戦略を実装する
• KVの結果整合性モデルに注意を払う

D1データベースガイドライン

クエリパターン

// パラメータ化クエリ（SQLインジェクション防止）
const results = await env.MY_DB
  .prepare('SELECT * FROM users WHERE id = ?')
  .bind(userId)
  .all();

// バッチ操作
const batch = await env.MY_DB.batch([
  env.MY_DB.prepare('INSERT INTO logs (message) VALUES (?)').bind('log1'),
  env.MY_DB.prepare('INSERT INTO logs (message) VALUES (?)').bind('log2'),
]);

// 最初の結果のみ取得
const user = await env.MY_DB
  .prepare('SELECT * FROM users WHERE email = ?')
  .bind(email)
  .first();

スキーマ管理

-- migrations/0001_initial.sql
CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);

ベストプラクティス

• 常にパラメータ化クエリを使用する
• 適切なインデックスを作成する
• 複数の書き込みにはバッチ操作を使用する
• クエリをシンプルで効率的に保つ
• スキーマ変更にはマイグレーションを使用する

R2オブジェクトストレージガイドライン

使用パターン

// オブジェクトのアップロード
await env.MY_BUCKET.put('uploads/file.pdf', fileData, {
  httpMetadata: {
    contentType: 'application/pdf',
  },
  customMetadata: {
    uploadedBy: userId,
  },
});

// オブジェクトのダウンロード
const object = await env.MY_BUCKET.get('uploads/file.pdf');
if (object) {
  return new Response(object.body, {
    headers: {
      'Content-Type': object.httpMetadata?.contentType || 'application/octet-stream',
    },
  });
}

// オブジェクトのリスト表示
const list = await env.MY_BUCKET.list({ prefix: 'uploads/' });

// オブジェクトの削除
await env.MY_BUCKET.delete('uploads/file.pdf');

ベストプラクティス

• 適切なコンテンツタイプを設定する
• 大きなファイルにはマルチパートアップロードを使用する
• 適切なアクセス制御を実装する
• クライアント直接アップロードに署名済みURLを使用する
• 論理的なプレフィックスでオブジェクトを整理する

Durable Objectsガイドライン

実装

export class ChatRoom implements DurableObject {
  private state: DurableObjectState;
  private sessions: Map<WebSocket, { id: string }>;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
    this.sessions = new Map();
  }

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/websocket') {
      const pair = new WebSocketPair();
      await this.handleSession(pair[1]);
      return new Response(null, { status: 101, webSocket: pair[0] });
    }

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

  async handleSession(webSocket: WebSocket) {
    webSocket.accept();

    webSocket.addEventListener('message', async (event) => {
      // Handle messages
    });

    webSocket.addEventListener('close', () => {
      this.sessions.delete(webSocket);
    });
  }
}

ベストプラクティス

• 調整と状態的ロジックに使用する
• 適切なWebSocket処理を実装する
• 永続性のためストレージAPIを使用する
• コスト最適化のための休止状態を処理する
• 単一ポイント調整パターン向けに設計する

Cloudflare Pagesガイドライン

プロジェクト構造

my-pages-project/
├── public/           # Static assets
├── functions/        # Pages Functions
│   ├── api/
│   │   └── [endpoint].ts
│   └── _middleware.ts
├── src/              # Application source
└── wrangler.toml     # Configuration

Pages Functions

// functions/api/users.ts
export const onRequestGet: PagesFunction<Env> = async (context) => {
  const users = await context.env.MY_DB
    .prepare('SELECT * FROM users')
    .all();

  return Response.json(users.results);
};

export const onRequestPost: PagesFunction<Env> = async (context) => {
  const body = await context.request.json();
  // Handle POST
  return Response.json({ success: true });
};

エッジセキュリティベストプラクティス

リクエスト検証

function validateRequest(request: Request): boolean {
  // Check content type
  const contentType = request.headers.get('Content-Type');
  if (request.method === 'POST' && !contentType?.includes('application/json')) {
    return false;
  }

  // Check origin (CORS)
  const origin = request.headers.get('Origin');
  if (origin && !ALLOWED_ORIGINS.includes(origin)) {
    return false;
  }

  return true;
}

認証

async function verifyAuth(request: Request, env: Env): Promise<boolean> {
  const authHeader = request.headers.get('Authorization');
  if (!authHeader?.startsWith('Bearer ')) {
    return false;
  }

  const token = authHeader.slice(7);
  // Verify JWT or API key
  return await verifyToken(token, env);
}

レート制限

async function checkRateLimit(ip: string, env: Env): Promise<boolean> {
  const key = `ratelimit:${ip}`;
  const current = await env.MY_KV.get(key, { type: 'json' }) as number || 0;

  if (current >= 100) { // 100 requests per window
    return false;
  }

  await env.MY_KV.put(key, JSON.stringify(current + 1), {
    expirationTtl: 60, // 1 minute window
  });

  return true;
}

パフォーマンス最適化

キャッシング戦略

// Cache API usage
const cache = caches.default;

async function handleRequest(request: Request): Promise<Response> {
  // Check cache
  const cached = await cache.match(request);
  if (cached) {
    return cached;
  }

  // Generate response
  const response = await generateResponse(request);

  // Cache response
  const cacheResponse = new Response(response.body, response);
  cacheResponse.headers.set('Cache-Control', 'public, max-age=3600');
  ctx.waitUntil(cache.put(request, cacheResponse.clone()));

  return cacheResponse;
}

バックグラウンド処理

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Respond immediately
    const response = Response.json({ status: 'accepted' });

    // Process in background
    ctx.waitUntil(processInBackground(request, env));

    return response;
  },
};

テスト

ローカル開発

# Start local development server
wrangler dev

# Run with local persistence
wrangler dev --persist

# Test with specific environment
wrangler dev --env staging

ユニットテスト

import { unstable_dev } from 'wrangler';

describe('Worker', () => {
  let worker: UnstableDevWorker;

  beforeAll(async () => {
    worker = await unstable_dev('src/index.ts', {
      experimental: { disableExperimentalWarning: true },
    });
  });

  afterAll(async () => {
    await worker.stop();
  });

  test('returns 200 for valid request', async () => {
    const response = await worker.fetch('/api/health');
    expect(response.status).toBe(200);
  });
});

デプロイ

本番環境へのデプロイ

# Deploy to production
wrangler deploy

# Deploy to specific environment
wrangler deploy --env production

# Deploy with secrets
wrangler secret put API_KEY

CI/CD統合

# .github/workflows/deploy.yml
name: Deploy Worker

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

避けるべき一般的な落とし穴

1. エッジでのエラーハンドリングが不十分
2. 外部APIコールが多すぎる
3. WorkerのCPUとメモリリミットを無視する
4. ユースケースに適したストレージを使用していない
5. KVの結果整合性を忘れている
6. 適切なレート制限を実装していない
7. シークレットをコードにハードコーディングする
8. コールドスタート最適化を無視する