Apollo アップグレード移行

概要

Apollo.io API 統合の安全なアップグレードを計画・実行し、破壊的変更と非推奨エンドポイントに対応します。

アップグレード前の評価

現在の API 使用状況を確認

# Find all Apollo API calls in codebase
grep -r "api.apollo.io" --include="*.ts" --include="*.js" -l

# List unique endpoints used
grep -roh "api.apollo.io/v[0-9]*/[a-z_/]*" --include="*.ts" --include="*.js" | sort -u

# Check for deprecated patterns
grep -rn "deprecated\|legacy" --include="*.ts" src/lib/apollo/

監査スクリプト

// scripts/apollo-audit.ts
import { readFileSync, readdirSync } from 'fs';
import { join } from 'path';

interface AuditResult {
  file: string;
  line: number;
  pattern: string;
  severity: 'warning' | 'error';
  message: string;
}

const DEPRECATED_PATTERNS = [
  {
    pattern: /\/v1\/contacts\//,
    message: 'Use /v1/people/ instead of /v1/contacts/',
    severity: 'error' as const,
  },
  {
    pattern: /organization_name/,
    message: 'Use q_organization_domains instead of organization_name',
    severity: 'warning' as const,
  },
  {
    pattern: /\.then\s*\(/,
    message: 'Consider using async/await for cleaner code',
    severity: 'warning' as const,
  },
];

function auditFile(filePath: string): AuditResult[] {
  const content = readFileSync(filePath, 'utf-8');
  const lines = content.split('\n');
  const results: AuditResult[] = [];

  lines.forEach((line, index) => {
    for (const { pattern, message, severity } of DEPRECATED_PATTERNS) {
      if (pattern.test(line)) {
        results.push({
          file: filePath,
          line: index + 1,
          pattern: pattern.source,
          severity,
          message,
        });
      }
    }
  });

  return results;
}

function auditDirectory(dir: string): AuditResult[] {
  const results: AuditResult[] = [];

  function walkDir(currentDir: string) {
    const files = readdirSync(currentDir, { withFileTypes: true });
    for (const file of files) {
      const path = join(currentDir, file.name);
      if (file.isDirectory() && !file.name.includes('node_modules')) {
        walkDir(path);
      } else if (file.name.endsWith('.ts') || file.name.endsWith('.js')) {
        results.push(...auditFile(path));
      }
    }
  }

  walkDir(dir);
  return results;
}

// Run audit
const results = auditDirectory('./src');
console.log('Apollo API Audit Results:\n');

for (const result of results) {
  const icon = result.severity === 'error' ? '[ERR]' : '[WRN]';
  console.log(`${icon} ${result.file}:${result.line}`);
  console.log(`     ${result.message}\n`);
}

console.log(`Total: ${results.length} issues found`);

移行手順

ステップ 1: 互換性レイヤーの作成

// src/lib/apollo/compat.ts
import { apollo } from './client';

/**
 * 非推奨 API パターンの互換性レイヤー。
 * すべてのコードが更新されたら削除します。
 * @deprecated 新しい API を直接使用してください
 */
export const apolloCompat = {
  /**
   * @deprecated apollo.searchPeople() を使用してください
   */
  async searchContacts(params: any) {
    console.warn('searchContacts is deprecated, use searchPeople');
    return apollo.searchPeople(params);
  },

  /**
   * @deprecated q_organization_domains パラメータを使用してください
   */
  async searchByCompanyName(companyName: string) {
    console.warn('searchByCompanyName is deprecated');
    // Try to find domain from company name
    const orgSearch = await apollo.searchOrganizations({
      q_organization_name: companyName,
      per_page: 1,
    });

    if (orgSearch.organizations.length === 0) {
      throw new Error(`Company not found: ${companyName}`);
    }

    const domain = orgSearch.organizations[0].primary_domain;
    return apollo.searchPeople({
      q_organization_domains: [domain],
    });
  },
};

ステップ 2: インポートの段階的な更新

// 移行前
import { searchContacts } from '../lib/apollo/legacy';

// 移行中（互換性レイヤーを使用）
import { apolloCompat } from '../lib/apollo/compat';
const results = await apolloCompat.searchContacts(params);

// 移行後（新しい API を使用）
import { apollo } from '../lib/apollo/client';
const results = await apollo.searchPeople(params);

ステップ 3: 新しい API のフィーチャーフラグ

// src/lib/apollo/feature-flags.ts
export const USE_NEW_APOLLO_API = process.env.APOLLO_USE_NEW_API === 'true';

// src/services/leads.ts
import { apollo } from '../lib/apollo/client';
import { apolloCompat } from '../lib/apollo/compat';
import { USE_NEW_APOLLO_API } from '../lib/apollo/feature-flags';

export async function searchLeads(criteria: SearchCriteria) {
  if (USE_NEW_APOLLO_API) {
    return apollo.searchPeople({
      q_organization_domains: criteria.domains,
      person_titles: criteria.titles,
    });
  } else {
    // Legacy path
    return apolloCompat.searchContacts({
      organization_domains: criteria.domains,
      titles: criteria.titles,
    });
  }
}

ステップ 4: 並列テスト

// scripts/compare-api-results.ts
import { apollo } from '../src/lib/apollo/client';
import { apolloCompat } from '../src/lib/apollo/compat';

async function compareResults() {
  const testCases = [
    { domains: ['stripe.com'], titles: ['Engineer'] },
    { domains: ['apollo.io'], titles: ['Sales'] },
  ];

  for (const testCase of testCases) {
    console.log(`\nTesting: ${JSON.stringify(testCase)}`);

    // New API
    const newResult = await apollo.searchPeople({
      q_organization_domains: testCase.domains,
      person_titles: testCase.titles,
      per_page: 10,
    });

    // Legacy API (through compat)
    const legacyResult = await apolloCompat.searchContacts({
      organization_domains: testCase.domains,
      titles: testCase.titles,
      per_page: 10,
    });

    // Compare
    const newCount = newResult.people.length;
    const legacyCount = legacyResult.people.length;

    console.log(`  New API: ${newCount} results`);
    console.log(`  Legacy:  ${legacyCount} results`);
    console.log(`  Match:   ${newCount === legacyCount ? 'YES' : 'NO'}`);
  }
}

compareResults().catch(console.error);

ロールアウト戦略

フェーズ 1: カナリア（1%）

# kubernetes/apollo-canary.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: apollo-config-canary
data:
  APOLLO_USE_NEW_API: "true"
---
# Deploy to 1% of traffic

フェーズ 2: 段階的なロールアウト

// ユーザー ID に基づく段階的なロールアウト
function shouldUseNewApi(userId: string): boolean {
  const rolloutPercentage = parseInt(process.env.APOLLO_NEW_API_ROLLOUT || '0');
  const hash = hashCode(userId) % 100;
  return hash < rolloutPercentage;
}

function hashCode(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) - hash) + str.charCodeAt(i);
    hash |= 0;
  }
  return Math.abs(hash);
}

フェーズ 3: 完全な移行

# カナリアが成功した後
export APOLLO_USE_NEW_API=true

# 互換性レイヤーを削除
rm src/lib/apollo/compat.ts

# すべてのインポートを更新
find src -name "*.ts" -exec sed -i 's/apolloCompat/apollo/g' {} \;

移行後のクリーンアップ

# 非推奨のコードを削除
grep -rl "deprecated" --include="*.ts" src/lib/apollo/ | xargs rm -v

# ドキュメントを更新
# 互換性レイヤーのドキュメントを削除
# API の例を新しい形式に更新

# 最終監査
npm run audit:apollo

ロールバック手順

# 問題が検出された場合、すぐにロールバック
export APOLLO_USE_NEW_API=false

# またはデプロイメントをロールバック
kubectl rollout undo deployment/api-server

出力

• アップグレード前の監査結果
• 段階的な移行のための互換性レイヤー
• フィーチャーフラグで制御されたロールアウト
• 並列テスト検証
• クリーンアップ手順

エラー処理

問題	解決策
監査がエラーを検出	進める前に修正
互換性レイヤーが失敗	マッピングロジックを確認
結果が異なる	API の変更を調査
カナリアに問題がある	即座にロールバック

リソース

• Apollo API Changelog
• Apollo Migration Guides
• Feature Flag Best Practices

次のステップ

CI/CD セットアップについては、apollo-ci-integration に進んでください。