Windsurf 既知の落とし穴

概要

Windsurf との統合時に発生する一般的な間違いとアンチパターン。

前提条件

• Windsurf コードベースへのレビューアクセス
• async/await パターンの理解
• セキュリティのベストプラクティスに関する知識
• レート制限の概念に関する知識

落とし穴 #1: リクエストパス内の同期的 API 呼び出し

❌ アンチパターン

// ユーザーが Windsurf API 呼び出しを待つ
app.post('/checkout', async (req, res) => {
  const payment = await windsurfClient.processPayment(req.body);  // 2-5s latency
  const notification = await windsurfClient.sendEmail(payment);   // Another 1-2s
  res.json({ success: true });  // User waited 3-7s
});

✅ より良いアプローチ

// 即座に返却し、非同期で処理
app.post('/checkout', async (req, res) => {
  const jobId = await queue.enqueue('process-checkout', req.body);
  res.json({ jobId, status: 'processing' });  // 50ms response
});

// バックグラウンドジョブ
async function processCheckout(data) {
  const payment = await windsurfClient.processPayment(data);
  await windsurfClient.sendEmail(payment);
}

---

落とし穴 #2: レート制限への対応がない

❌ アンチパターン

// リクエストを送信し続け、429 でクラッシュ
for (const item of items) {
  await windsurfClient.process(item);  // Will hit rate limit
}

✅ より良いアプローチ

import pLimit from 'p-limit';

const limit = pLimit(5);  // 最大 5 個の同時実行
const rateLimiter = new RateLimiter({ tokensPerSecond: 10 });

for (const item of items) {
  await rateLimiter.acquire();
  await limit(() => windsurfClient.process(item));
}

---

落とし穴 #3: API キーの漏洩

❌ アンチパターン

// フロントエンドコード内(ユーザーに見える!)
const client = new WindsurfClient({
  apiKey: 'sk_live_ACTUAL_KEY_HERE',  // 誰でも見ることができます
});

// git 履歴内
git commit -m "add API key"  // 永久に公開される

✅ より良いアプローチ

// バックエンド専用、環境変数
const client = new WindsurfClient({
  apiKey: process.env.WINDSURF_API_KEY,
});

// .gitignore を使用
.env
.env.local
.env.*.local

---

落とし穴 #4: べき等性を無視する

❌ アンチパターン

// レスポンス時のネットワークエラー = 二重課金!
try {
  await windsurfClient.charge(order);
} catch (error) {
  if (error.code === 'NETWORK_ERROR') {
    await windsurfClient.charge(order);  // 2 回課金されます!
  }
}

✅ より良いアプローチ

const idempotencyKey = `order-${order.id}-${Date.now()}`;

await windsurfClient.charge(order, {
  idempotencyKey,  // 安全に再試行可能
});

---

落とし穴 #5: ウェブフック検証がない

❌ アンチパターン

// 全てのリクエストを信頼
app.post('/webhook', (req, res) => {
  processWebhook(req.body);  // 攻撃者が偽のイベントを送信可能
  res.sendStatus(200);
});

✅ より良いアプローチ

app.post('/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-windsurf-signature'];
    if (!verifyWindsurfSignature(req.body, signature)) {
      return res.sendStatus(401);
    }
    processWebhook(JSON.parse(req.body));
    res.sendStatus(200);
  }
);

---

落とし穴 #6: エラーハンドリングの欠落

❌ アンチパターン

// エラーでクラッシュ
const result = await windsurfClient.get(id);
console.log(result.data.nested.value);  // 欠落時に TypeError

✅ より良いアプローチ

try {
  const result = await windsurfClient.get(id);
  console.log(result?.data?.nested?.value ?? 'default');
} catch (error) {
  if (error instanceof WindsurfNotFoundError) {
    return null;
  }
  if (error instanceof WindsurfRateLimitError) {
    await sleep(error.retryAfter);
    return this.get(id);  // 再試行
  }
  throw error;  // 不明なエラーを再スロー
}

---

落とし穴 #7: 設定のハードコード

❌ アンチパターン

const client = new WindsurfClient({
  timeout: 5000,  // 一部の操作には短すぎる
  baseUrl: 'https://api.windsurf.com',  // ステージング環境で変更不可
});

✅ より良いアプローチ

const client = new WindsurfClient({
  timeout: parseInt(process.env.WINDSURF_TIMEOUT || '30000'),
  baseUrl: process.env.WINDSURF_BASE_URL || 'https://api.windsurf.com',
});

---

落とし穴 #8: サーキットブレーカーの実装がない

❌ アンチパターン

// Windsurf がダウンしている場合、全てのリクエストがハング
for (const user of users) {
  await windsurfClient.sync(user);  // 全てが順序にタイムアウト
}

✅ より良いアプローチ

import CircuitBreaker from 'opossum';

const breaker = new CircuitBreaker(windsurfClient.sync, {
  timeout: 10000,
  errorThresholdPercentage: 50,
  resetTimeout: 30000,
});

// サーキットがオープン時に高速で失敗
for (const user of users) {
  await breaker.fire(user).catch(handleFailure);
}

---

落とし穴 #9: 機密データのログ出力

❌ アンチパターン

console.log('Request:', JSON.stringify(request));  // API キー、個人識別情報をログ出力
console.log('User:', user);  // メール、電話番号をログ出力

✅ より良いアプローチ

const redacted = {
  ...request,
  apiKey: '[REDACTED]',
  user: { id: user.id },  // 機密でないフィールドのみ
};
console.log('Request:', JSON.stringify(redacted));

---

落とし穴 #10: グレースフルデグラデーションがない

❌ アンチパターン

// Windsurf がダウンしていると機能全体が破損
const recommendations = await windsurfClient.getRecommendations(userId);
return renderPage({ recommendations });  // ページがクラッシュ

✅ より良いアプローチ

let recommendations;
try {
  recommendations = await windsurfClient.getRecommendations(userId);
} catch (error) {
  recommendations = await getFallbackRecommendations(userId);
  reportDegradedService('windsurf', error);
}
return renderPage({ recommendations, degraded: !recommendations });

---

実行手順

ステップ 1: アンチパターンをレビュー

各落とし穴パターンについてコードベースをスキャンします。

ステップ 2: 優先度を付ける

セキュリティの問題を最優先に対応します。

ステップ 3: より良いアプローチを実装

アンチパターンを推奨パターンに置き換えます。

ステップ 4: 再発を防止

リンティングと CI チェックを設定して再発を防止します。

出力

• 特定されたアンチパターン
• 優先度付けされ実装された修正
• 実施された予防措置
• 改善されたコード品質

エラーハンドリング

問題	原因	解決策
検出項目が多すぎる	レガシーコードベース	セキュリティを優先
パターンが検出されない	複雑なコード	手動レビュー
偽陽性	類似コード	例外をホワイトリスト登録
修正がテストを破損	動作変更	テストを更新

例

クイック落とし穴スキャン

# 一般的な落とし穴をチェック
grep -r "sk_live_" --include="*.ts" src/        # キー漏洩
grep -r "console.log" --include="*.ts" src/     # 潜在的な PII ログ

リソース

• Windsurf セキュリティガイド
• Windsurf ベストプラクティス

クイックリファレンスカード

落とし穴	検出方法	予防方法
リクエスト内の同期処理	高レイテンシ	キューを使用
レート制限の無視	429 エラー	バックオフを実装
キー漏洩	git 履歴スキャン	環境変数、.gitignore
べき等性なし	重複レコード	べき等性キー
ウェブフック未検証	セキュリティ監査	署名検証
エラーハンドリング欠落	クラッシュ	try-catch、型
ハードコード設定	コードレビュー	環境変数
サーキットブレーカーなし	カスケード障害	opossum、resilience4j
PII ログ出力	ログ監査	リダクションミドルウェア
デグラデーション機能なし	完全停止	フォールバックシステム