実務設計レビューチェックリスト

実務設計レビューチェックリスト

実務で設計レビューを行う際のチェックリストです。すべての項目を確認してください。

リソース管理

• タイムアウト: すべての外部通信(DB/API/Cache)に現実的な上限を設定

  • DB接続: 3秒
  • HTTP API: 5秒
  • キャッシュ: 1秒

• リソース解放: 例外時でも確実に破棄・閉鎖される

  • try-finallyブロックでリソースを解放
  • ファイルを適切にクローズ
  • DB接続を適切にクローズ

• 接続プール: 適切なサイズとタイムアウトを設定

  • 最大接続数: サーバーリソースに応じて設定（pool_size=5）
  • 接続タイムアウト: 30秒
  • アイドルタイムアウト: 10分

• イベントループのブロック: 同期I/O操作を避ける

  • requestsではなくhttpxを使用
  • open()ではなくaiofiles.open()を使用
  • 長時間実行される処理はCeleryを使用

エラーハンドリングとリトライ

• リトライ戦略: バックオフ＋冪等性がセットで動作している

  • Exponential Backoff + Jitter
  • 最大リトライ回数: 3回
  • リトライ可能なエラーと不可能なエラーを区別

• 冪等性: 再送・再起動時も二重登録されない

  • Idempotency Keyを使用
  • データベースの一意制約で重複を防止
  • 再実行時に既存データを返す

トランザクション管理

• トランザクション境界: DB取引中に外部APIを呼ばない

  • Outboxパターンを使用
  • トランザクションの範囲を最小限に
  • トランザクションコミット後に外部APIを呼ぶ

• デッドロック対策: ロックの順序を統一

  • IDの小さい順にロックを取得
  • タイムアウトを設定
  • デッドロック検出時のロールバック

観測可能性

• ログ: コード改修なしで原因追跡ができる

  • トレースIDを通す
  • 構造化ログ（JSON形式）を出力
  • 入出力境界ごとにログを出力

• メトリクス: 成功率・レイテンシ・リトライ回数・プール使用率を監視

  • Prometheusを使用
  • Grafanaで可視化
  • アラートを設定

• トレース: 分散トレース可能にする

  • OpenTelemetryを使用
  • 外部API・DBアクセス単位にSpanを埋める
  • Jaeger/Zipkinで可視化

セキュリティ

• 認可と認証の分離: あらゆるAPIが認可境界を明示

  • 依存性注入で認可を実装
  • ロールベースアクセス制御（RBAC）
  • リソースレベルの認可

• 最小権限の原則: アクセスキーやトークンはスコープ最小限に限定

  • 必要な権限のみを付与
  • トークンの有効期限を設定
  • 権限の定期的な見直し

• 暗号化: 通信(TLS)・保存時(At Rest)を問わず暗号化

  • HTTPSを使用
  • 機密データは暗号化して保存
  • 暗号化キーの適切な管理

• 入力検証: SQL・JSON・正規表現などすべての入力を検査

  • Pydanticを使用
  • SQLインジェクション対策
  • XSS対策

環境とスケーラビリティ

• 環境分離: ステートレス設計で複数インスタンス安全に動作

  • セッションを外部ストア（Redis）に保存
  • ファイルアップロードを外部ストレージ（S3）に保存
  • ステートフルな処理を避ける

• スケーラビリティ: 水平スケール可能な設計

  • ステートレスな設計
  • 共有リソース（DB、キャッシュ）への依存を最小化
  • ロードバランサーで分散可能

過剰設計の回避

• YAGNI原則: 今必要な複雑さに収まっているか？

  • 将来必要かもしれない抽象化を避ける
  • シンプルな実装から始める
  • 必要になったらリファクタリング

• 整合性トレードオフ: すべてをACIDで守る必要はない

  • 厳密整合性が必要なデータと結果整合性で良いデータを分類
  • イベント駆動アーキテクチャを検討
  • 最終的整合性で十分な場合は、それを明示

• 抽象化の節度: インターフェース化は目的を明確に

  • 交換容易性が必要な場合のみ抽象化
  • テスト容易性が必要な場合のみ抽象化
  • 過剰な抽象化を避ける

復旧性

• Graceful Degradation: 外部依存が落ちたらキャッシュ・スタブで縮退運転

  • キャッシュからのフォールバック
  • スタブデータの返却
  • エラーメッセージの適切な表示

• 再起動安全性: 失敗から自動/手動で安全に戻れる設計があるか？

  • Outboxパターンで再処理可能
  • 中途状態のデータをリカバリ可能
  • 手動対応が必要な状態をマーク

• 手動オペ対応: フラグ切替・一時停止がコード修正なしで可能

  • 機能フラグによる制御
  • 管理画面での設定変更
  • ロールバック可能なデプロイ

まとめ

このチェックリストを確認することで、堅牢なシステムを構築できます。

重要な原則: すべての関数、API、ジョブが独立に倒れてもシステム全体は立ち続ける。そのための原則を、このチェックリストは「再現」より「予防」としてまとめている。