cloudflare-kv

Cloudflare Workers KV

ステータス：本番環境で利用可能 ✅ | 最終確認日：2025-12-27

---

Workers KV とは？

Cloudflare のエッジ上にあるグローバルなキー・バリューストレージです：

• 結果整合性
• 世界中で低レイテンシー
• 1GB 以上の値に対応
• TTL による有効期限
• メタデータに対応

---

クイックスタート（5 分）

1. KV 名前空間を作成する

bunx wrangler kv namespace create MY_NAMESPACE
bunx wrangler kv namespace create MY_NAMESPACE --preview

2. バインディングを設定する

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "kv_namespaces": [
    {
      "binding": "MY_NAMESPACE",
      "id": "<PRODUCTION_ID>",
      "preview_id": "<PREVIEW_ID>"
    }
  ]
}

3. 基本操作

export default {
  async fetch(request, env, ctx) {
    // Write
    await env.MY_NAMESPACE.put('key', 'value');

    // Read
    const value = await env.MY_NAMESPACE.get('key');

    // Delete
    await env.MY_NAMESPACE.delete('key');

    return new Response(value);
  }
};

セットアップ全般については references/setup-guide.md を読み込んでください。

---

KV API メソッド

put() - 書き込み

// Basic
await env.MY_NAMESPACE.put('key', 'value');

// With TTL (1 hour)
await env.MY_NAMESPACE.put('key', 'value', {
  expirationTtl: 3600
});

// With expiration timestamp
await env.MY_NAMESPACE.put('key', 'value', {
  expiration: Math.floor(Date.now() / 1000) + 3600
});

// With metadata
await env.MY_NAMESPACE.put('key', 'value', {
  metadata: { role: 'admin', created: Date.now() }
});

get() - 読み取り

// Simple get
const value = await env.MY_NAMESPACE.get('key');

// With type
const text = await env.MY_NAMESPACE.get('key', 'text');
const json = await env.MY_NAMESPACE.get('key', 'json');
const buffer = await env.MY_NAMESPACE.get('key', 'arrayBuffer');
const stream = await env.MY_NAMESPACE.get('key', 'stream');

// With metadata
const { value, metadata } = await env.MY_NAMESPACE.getWithMetadata('key');

delete() - 削除

await env.MY_NAMESPACE.delete('key');

list() - キーの一覧表示

// Basic list
const { keys } = await env.MY_NAMESPACE.list();

// With prefix
const { keys } = await env.MY_NAMESPACE.list({
  prefix: 'user:',
  limit: 100
});

// Pagination
const { keys, cursor } = await env.MY_NAMESPACE.list({
  cursor: previousCursor
});

---

重要なルール

必ず行うこと ✅

1. 一時データには必ず TTL を使用する
2. null を処理する（キーが存在しない可能性があります）
3. 小さなデータにはメタデータを使用する
4. リストをページ分割する（キーは最大 1000 件）
5. 整理にはプレフィックスを使用する
6. Worker 内でキャッシュする（KV の呼び出しを複数回行わない）
7. 非同期の書き込みにはwaitUntil() を使用する
8. 結果整合性を考慮する
9. レート制限を監視する
10. オブジェクトにはJSON.stringify を使用する

絶対に行わないこと ❌

1. 整合性が即時に取れると決して想定しない
2. 1 つの値で 25MB を超えない
3. ページ分割せずにすべてのキーを一覧表示しない
4. エラー処理を省略しない
5. リアルタイムデータには決して使用しない
6. レート制限（毎秒 1000 回の書き込み）を決して超えない
7. 暗号化せずにシークレットを保存しない
8. データベースとして使用しない（トランザクションはありません）
9. メタデータの上限（1024 バイト）を無視しない
10. 一時データの TTL を省略しない

---

一般的なユースケース

ユースケース 1：API レスポンスのキャッシュ

const cacheKey = `api:${url}`;
let cached = await env.MY_NAMESPACE.get(cacheKey, 'json');

if (!cached) {
  cached = await fetch(url).then(r => r.json());
  await env.MY_NAMESPACE.put(cacheKey, JSON.stringify(cached), {
    expirationTtl: 300  // 5 minutes
  });
}

return Response.json(cached);

ユースケース 2：ユーザー設定

const userId = '123';
const preferences = {
  theme: 'dark',
  language: 'en'
};

await env.MY_NAMESPACE.put(
  `user:${userId}:preferences`,
  JSON.stringify(preferences),
  {
    metadata: { updated: Date.now() }
  }
);

ユースケース 3：レート制限

const key = `ratelimit:${ip}`;
const count = parseInt(await env.MY_NAMESPACE.get(key) || '0');

if (count >= 100) {
  return new Response('Rate limit exceeded', { status: 429 });
}

await env.MY_NAMESPACE.put(key, String(count + 1), {
  expirationTtl: 60  // 1 minute window
});

ユースケース 4：プレフィックスによる一覧表示

const { keys } = await env.MY_NAMESPACE.list({
  prefix: 'user:',
  limit: 100
});

const users = await Promise.all(
  keys.map(({ name }) => env.MY_NAMESPACE.get(name, 'json'))
);

ユースケース 5：waitUntil() パターン

export default {
  async fetch(request, env, ctx) {
    // Don't wait for KV write
    ctx.waitUntil(
      env.MY_NAMESPACE.put('analytics', JSON.stringify(data))
    );

    return new Response('OK');
  }
};

---

制限（概要）

キーの制限：

• キーのサイズ：最大 512 バイト
• 値のサイズ：最大 25 MB
• メタデータ：最大 1024 バイト

レート制限：

• 書き込み：キーごとに毎秒 1000 回
• 一覧表示：名前空間ごとに毎秒 100 回
• 読み取り：無制限

制限、料金、最適化戦略の詳細については、references/limits-quotas.md を読み込んでください。

---

結果整合性

KV は結果整合性です：

• 書き込みはグローバルに反映されます（約 60 秒）
• リアルタイムデータには適していません
• 強い整合性が必要な場合は D1 を使用してください

パターン：

// Write
await env.MY_NAMESPACE.put('key', 'value');

// May not be visible immediately in other regions
const value = await env.MY_NAMESPACE.get('key');  // Might be null

---

リファレンスを読み込むタイミング

タスクの内容に応じて、適切なリファレンスファイルを読み込んでください：

セットアップと設定の場合：

• 名前空間の作成やバインディングの設定時は、references/setup-guide.md を読み込みます

パフォーマンスの最適化の場合：

• キャッシュの実装やパフォーマンスの最適化時は、references/best-practices.md を読み込みます
• 高度な最適化、cacheTtl 戦略、ベンチマークを行う場合は、references/performance-tuning.md を読み込みます

API の使用方法について：

• KV 操作を実装する場合やメソッドのシグネチャが必要な場合は、references/workers-api.md を読み込みます

トラブルシューティングの場合：

• エラーや整合性の問題をデバッグする場合は、references/troubleshooting.md を読み込みます

制限とクォータについて：

• 容量を計画する場合やクォータエラーが発生した場合は、references/limits-quotas.md を読み込みます

移行の場合：

• localStorage、Redis、D1、R2、その他のストレージソリューションから移行する場合は、references/migration-guide.md を読み込みます

---

リソース

リファレンス（references/）：

• best-practices.md - 本番環境でのパターン、キャッシュ戦略、レート制限への対応、エラー復旧
• setup-guide.md - Wrangler CLI コマンド、名前空間の作成、バインディングの設定を含む完全なセットアップ手順
• workers-api.md - API の完全なリファレンス、一貫性モデル（結果整合性）、制限とクォータ、パフォーマンスの最適化
• troubleshooting.md - 解決策を含む包括的なエラーカタログ
• limits-quotas.md - 制限、クォータ、料金、最適化のヒントの詳細
• migration-guide.md - localStorage、Redis、D1、R2、その他のストレージソリューションからの完全な移行ガイド
• performance-tuning.md - 高度な cacheTtl 戦略、一括操作、キー設計、ベンチマーク手法

テンプレート（templates/）：

• kv-basic-operations.ts - 基本的な KV 操作（取得、書き込み、削除、一覧表示）
• kv-caching-pattern.ts - KV を使った HTTP キャッシュ
• kv-list-pagination.ts - カーソルページネーションを使った一覧表示
• kv-metadata-pattern.ts - メタデータの使用パターン
• wrangler-kv-config.jsonc - KV 名前空間のバインディング

スクリプト（scripts/）：

• check-versions.sh - KV API エンドポイントとパッケージバージョンの検証
• test-kv-connection.sh - KV 名前空間への接続と操作のテスト
• setup-kv-namespace.sh - 対話型の名前空間セットアップウィザード
• validate-kv-config.sh - wrangler.jsonc 設定の検証
• analyze-kv-usage.sh - KV の使用パターンと最適化のためのコード分析

コマンド：

• /cloudflare-kv:setup - 対話型の KV 名前空間セットアップウィザード
• /cloudflare-kv:test - KV 操作と接続のテスト
• /cloudflare-kv:optimize - KV の使用状況を分析して最適化

エージェント：

• kv-optimizer - KV の使用状況を分析し、パフォーマンス最適化を提案します
• kv-debugger - KV のエラーや一貫性の問題のデバッグを支援します

サンプル（examples/）：

• rate-limiting/ - 完全なレート制限の実装（固定ウィンドウ、スライディングウィンドウ、トークンバケット、マルチティア）
• session-management/ - TTL による有効期限、メタデータの追跡、管理者向けコントロールを備えた本番環境向けセッションストア
• api-caching/ - HTTP レスポンスのキャッシュパターン（キャッシュ・アサイド、stale-while-revalidate、条件付きキャッシュ、ETag）
• config-management/ - フラグ、A/B テスト、環境設定、バージョン追跡、ホットリロード

---

公式ドキュメント

• KV の概要：https://developers.cloudflare.com/kv/
• KV API：https://developers.cloudflare.com/kv/api/
• ベストプラクティス：https://developers.cloudflare.com/kv/best-practices/

---

ご質問や問題がありますか？

1. 完全なセットアップ手順については、references/setup-guide.md を確認してください
2. 名前空間のバインディングが設定されていることを確認してください
3. 結果整合性に対応してください
4. レート制限を確認してください