メインコンテンツまでスキップ

詳細仕様サンプル - 顧客一覧取得API

tip
  1. DocusaurusにPlantUMLのテーマを作ったのはこういう仕様を書きたかったから♪
  2. テキストベースなのでChatGPTなどでほぼすべて書ける。楽ちん

概要​

  1. 顧客情報を一覧で取得するAPIである
  2. gRPCを使用し、connect-goに基づいて実装する

前提条件​

  1. 認証が必要
  2. ユーザーが顧客情報の閲覧権限を持つ必要がある

CRUD​

操作: 読み取り(Read)​

  1. 参照テーブル: customers

パラメーター仕様​

{
  "userId": "string" // ユーザーID
  "filter": "string" // 検索条件(オプション)
  "limit": "number" // 最大取得件数(オプション)
  "offset": "number" // 取得開始位置(オプション)
}

Result仕様​

{
  "customers": [
    {
      "id": "string" // 顧客ID
      "name": "string" // 顧客名
      "email": "string" // メールアドレス
      "createdAt": "string" // 作成日時
    }
  ],
  "total": "number" // 総件数
}

シーケンス図​

PlantUML diagram

処理詳細​

[02]: 認証​

  1. リクエストの認証情報を検証
  2. 認証失敗時はエラーを返却し処理を終了

[03]: パラメーターのバリデーション​

  1. userId が必須であることを確認
  2. limit や offset の値が適切であることを確認
  3. バリデーションエラー時はエラーを返却し処理を終了

[04]: DBで権限確認​

  1. userId を元に権限を取得
  2. 権限がない場合はエラーを返却し処理を終了

[06]: DBから一覧の取得​

  1. filter, limit, offset に基づき customers テーブルを検索
  2. 検索結果を取得

Result形式に変換​

  1. 顧客情報を customers 配列に格納
  2. total を設定

[08]: クライアントへresultを返却​

に最終更新