JavaScript | 配列→オブジェクトにリファクタリングする手順とAPI設計視点での戻り値設計のベストプラクティス

API設計視点での戻り値設計のベストプラクティス

API設計では「戻り値＝オブジェクトで意味付き」がほぼ標準です。
理由は以下のとおりです。

1. 結果の意味が明確になる

{
  "success": true,
  "data": {
    "userId": 123,
    "name": "Taro"
  },
  "errors": []
}

{
  "success": true,
  "data": {
    "userId": 123,
    "name": "Taro"
  },
  "errors": []
}

• success, data, errors の役割が一目で分かる。
• 順番に依存しないため、拡張や改修が簡単。

2. 拡張性が高い

• 後からフィールドを追加しても、古いクライアントコードを壊さない。
• 例："warnings": [...] を追加しても既存の呼び出しコードはそのまま。

3. エラーやステータス管理がしやすい

// JavaScript側の受け取り例
const response = await fetch("/api/user").then(res => res.json());

if (!response.success) {
  console.log(response.errors);
} else {
  const { userId, name } = response.data;
}

// JavaScript側の受け取り例
const response = await fetch("/api/user").then(res => res.json());

if (!response.success) {
  console.log(response.errors);
} else {
  const { userId, name } = response.data;
}

• 配列で返す場合、response[0] が何を意味するか分からず、直感的でない。
• オブジェクトなら「ラベルでアクセス」でき、ミスが減る。

4. 現場でのルール例（REST API）

• 基本はオブジェクトで返す。
• 配列は「データのリスト」の場合だけ使う：

{
  "users": [
    { "id": 1, "name": "Taro" },
    { "id": 2, "name": "Hanako" }
  ],
  "total": 2
}

{
  "users": [
    { "id": 1, "name": "Taro" },
    { "id": 2, "name": "Hanako" }
  ],
  "total": 2
}

• users は配列、その他はオブジェクトで意味を付ける。