Replit リファレンスアーキテクチャ

概要

Replitインテグレーション向けの本番環境対応アーキテクチャパターンです。

前提条件

• レイヤーアーキテクチャの理解
• Replit SDKの知識
• TypeScriptプロジェクトのセットアップ
• テストフレームワークの設定

プロジェクト構成

my-replit-project/
├── src/
│   ├── replit/
│   │   ├── client.ts           # Singleton クライアントラッパー
│   │   ├── config.ts           # 環境設定
│   │   ├── types.ts            # TypeScript 型
│   │   ├── errors.ts           # カスタムエラークラス
│   │   └── handlers/
│   │       ├── webhooks.ts     # Webhook ハンドラー
│   │       └── events.ts       # イベント処理
│   ├── services/
│   │   └── replit/
│   │       ├── index.ts        # サービスファサード
│   │       ├── sync.ts         # データ同期
│   │       └── cache.ts        # キャッシング層
│   ├── api/
│   │   └── replit/
│   │       └── webhook.ts      # Webhook エンドポイント
│   └── jobs/
│       └── replit/
│           └── sync.ts         # バックグラウンド同期ジョブ
├── tests/
│   ├── unit/
│   │   └── replit/
│   └── integration/
│       └── replit/
├── config/
│   ├── replit.development.json
│   ├── replit.staging.json
│   └── replit.production.json
└── docs/
    └── replit/
        ├── SETUP.md
        └── RUNBOOK.md

レイヤーアーキテクチャ

┌─────────────────────────────────────────┐
│             API レイヤー                  │
│   (コントローラー、ルート、Webhook)      │
├─────────────────────────────────────────┤
│           サービスレイヤー                │
│  (ビジネスロジック、オーケストレーション) │
├─────────────────────────────────────────┤
│          Replit レイヤー                 │
│   (クライアント、型、エラーハンドリング) │
├─────────────────────────────────────────┤
│         インフラストラクチャレイヤー      │
│    (キャッシュ、キュー、モニタリング)    │
└─────────────────────────────────────────┘

主要コンポーネント

ステップ 1: クライアントラッパー

// src/replit/client.ts
export class ReplitService {
  private client: ReplitClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: ReplitConfig) {
    this.client = new ReplitClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('replit');
  }

  async get(id: string): Promise<Resource> {
    return this.cache.getOrFetch(id, () =>
      this.monitor.track('get', () => this.client.get(id))
    );
  }
}

ステップ 2: エラーバウンダリー

// src/replit/errors.ts
export class ReplitServiceError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly originalError?: Error
  ) {
    super(message);
    this.name = 'ReplitServiceError';
  }
}

export function wrapReplitError(error: unknown): ReplitServiceError {
  // SDK エラーをアプリケーションエラーに変換
}

ステップ 3: ヘルスチェック

// src/replit/health.ts
export async function checkReplitHealth(): Promise<HealthStatus> {
  try {
    const start = Date.now();
    await replitClient.ping();
    return {
      status: 'healthy',
      latencyMs: Date.now() - start,
    };
  } catch (error) {
    return { status: 'unhealthy', error: error.message };
  }
}

データフロー図

ユーザーリクエスト
     │
     ▼
┌─────────────┐
│   API       │
│   ゲートウェイ│
└──────┬──────┘
       │
       ▼
┌─────────────┐    ┌─────────────┐
│   サービス   │───▶│   キャッシュ  │
│   レイヤー   │    │  (Redis)    │
└──────┬──────┘    └─────────────┘
       │
       ▼
┌─────────────┐
│   Replit    │
│   クライアント│
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Replit    │
│   API       │
└─────────────┘

設定管理

// config/replit.ts
export interface ReplitConfig {
  apiKey: string;
  environment: 'development' | 'staging' | 'production';
  timeout: number;
  retries: number;
  cache: {
    enabled: boolean;
    ttlSeconds: number;
  };
}

export function loadReplitConfig(): ReplitConfig {
  const env = process.env.NODE_ENV || 'development';
  return require(`./replit.${env}.json`);
}

手順

ステップ 1: ディレクトリ構造の作成

上記のリファレンス構成に従ってプロジェクトレイアウトをセットアップします。

ステップ 2: クライアントラッパーの実装

キャッシングとモニタリング機能を備えたシングルトンクライアントを作成します。

ステップ 3: エラーハンドリングの追加

Replit操作のカスタムエラークラスを実装します。

ステップ 4: ヘルスチェックの設定

Replit接続性用のヘルスチェックエンドポイントを追加します。

出力

• 構造化されたプロジェクトレイアウト
• キャッシング機能付きクライアントラッパー
• 実装されたエラーバウンダリー
• 設定されたヘルスチェック

エラーハンドリング

問題	原因	解決方法
循環依存	不適切なレイヤー構成	レイヤーごとに関心事を分離
設定が読み込まれない	パス指定が誤り	設定ファイルの場所を確認
型エラー	型定義が不足	Replit 型を追加
テスト分離の失敗	状態の共有	依存性注入を使用

例

クイックセットアップスクリプト

# リファレンス構造を作成
mkdir -p src/replit/{handlers} src/services/replit src/api/replit
touch src/replit/{client,config,types,errors}.ts
touch src/services/replit/{index,sync,cache}.ts

リソース

• Replit SDK ドキュメント
• Replit ベストプラクティス

関連スキル

マルチ環境セットアップの場合は、replit-multi-env-setup を参照してください。