devex-sdk-design

開発者エクスペリエンスと SDK 設計

SDK 設計の原則

API の使いやすさ

// Bad: too many required params, unclear ordering
createUser(name, email, role, true, false, null, 'active');

// Good: builder pattern with named properties
const user = await sdk.users.create({
  name: 'Alice',
  email: '[email protected]',
  role: 'admin',
});

// Good: fluent API for complex operations
const results = await sdk.query('users')
  .where('role', '=', 'admin')
  .orderBy('createdAt', 'desc')
  .limit(10)
  .execute();

段階的な情報開示

// Simple case: just works with defaults
const client = new MySDK('api-key');
const result = await client.doThing();

// Advanced case: full control available
const client = new MySDK({
  apiKey: 'api-key',
  baseUrl: 'https://custom.endpoint.com',
  timeout: 30000,
  retries: { maxAttempts: 3, backoff: 'exponential' },
  middleware: [loggingMiddleware, authRefreshMiddleware],
});

エラー設計

// SDK errors should be structured and actionable
class SDKError extends Error {
  constructor(
    message: string,
    public readonly code: string,        // machine-readable
    public readonly statusCode?: number,  // HTTP status if applicable
    public readonly retryable: boolean = false,
    public readonly docs?: string,        // link to relevant docs
  ) {
    super(message);
  }
}

// User sees:
// SDKError: Rate limit exceeded (rate_limit_exceeded)
//   Retryable: true, retry after 2.3s
//   Docs: https://docs.example.com/rate-limits

CLI 設計

コマンド構成

mycli <command> <subcommand> [flags]

mycli init                    # Interactive setup
mycli deploy --env production # Explicit flags
mycli logs --follow           # Streaming output
mycli config set key value    # Noun-verb pattern

CLI のベストプラクティス

• 適切なデフォルト設定： そのまま動作し、カスタマイズには --flag を使用します
• 段階的な出力： 時間のかかる処理にはスピナー、デバッグには --verbose、機械処理には --json を使用します
• 確認プロンプト： 破壊的な操作には --yes または対話形式の確認を必須とします
• シェル補完： bash/zsh/fish/PowerShell 用の補完を生成します
• 終了コード： 0 = 成功、1 = エラー、2 = 使用方法のエラー

ドキュメント主導の開発

README の構成（SDK 向け）

1. 一文での説明： 何をするものかを一文で説明します
2. クイックスタート： コピーして貼り付ければ動作する例（10 行未満）
3. インストール： パッケージマネージャーのコマンド
4. 使い方： コード例を使った一般的なパターン
5. API リファレンス： 型や docstring から自動生成
6. エラー処理： よくあるエラーと解決策
7. 移行ガイド： バージョン間の破壊的変更

コード例

• 公開メソッドすべてに使用例を用意します
• 例はコンパイルまたは実行できる必要があります。CI でテストしてください
• まず正常系を示し、その後にエッジケースを示します
• コメントに想定される出力を含めます

開発者オンボーディングの指標

• Hello World までの時間： ドキュメントを読んでから動作するコードを書くまで 5 分未満
• 最初の API 呼び出しまでの時間： 認証設定を含めて 10 分未満
• コピー＆ペーストの成功率： クイックスタートの例が初回で動作する
• エラー解決までの時間： エラーメッセージから直接修正方法がわかる

バージョン管理と破壊的変更

• セマンティックバージョニングを厳守します
• 削除の 2 つ前のマイナーバージョンから非推奨の警告を出します
• メジャーバージョンのアップグレード向けに移行用 codemod を用意します
• リリースごとに変更履歴を記載します（keep-a-changelog 形式）