給正在跟前端吵架的後端工程師——統一 API 回傳格式，從此不用再解釋「這個 API 的 response 長什麼樣子」。
先講結論
所有 Controller 繼承同一個 Base Controller，裡面放一個 returnJsonFormatter，強制每個 API 都回傳 { success, message, data } 的結構。前端只要寫一套處理邏輯就夠了。
就這麼簡單，但你不信有多少專案連這個都沒做。
問題在哪？
你有沒有遇過這種情況：前端同事跑來問你「欸，這支 API 成功的時候回 { data: ... }，那支 API 成功的時候回 { result: ... }，到底哪個才是對的？」
答案是——兩個都對，但兩個都爛。
沒有統一格式的 API，前端每串一支都要去翻文件（如果有文件的話），然後寫不同的 error handling。久了大家都很累，bug 也特別多。
直接看 code
在 Laravel 裡，Base Controller 就是 app/Http/Controllers/Controller.php：
<?php
namespace App\Http\Controllers;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Routing\Controller as BaseController;
class Controller extends BaseController
{
use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
public function returnJsonFormatter($success, $message, $data, $statusCode) {
return response()->json([
'success' => $success,
'message' => $message,
'data' => $data
], $statusCode);
}
}這樣你的每個 Controller 在回傳的時候就是：
return $this->returnJsonFormatter(true, '取得成功', $users, 200);
return $this->returnJsonFormatter(false, '找不到資料', null, 404);前端拿到的永遠是同一種結構，success 判斷成功失敗、message 拿來顯示提示、data 拿來用。不用猜，不用翻文件。
回傳格式長這樣
| 欄位 | 說明 |
|---|---|
success | 布林值，成功 true 失敗 false |
message | 給人看的訊息 |
data | 實際資料，沒有就給 null |
statusCode | HTTP 狀態碼，照 MDN 規範走 |
我知道有人會想加更多欄位，像 error_code、timestamp 之類的。可以，但先把基本的搞定再說。過度設計是另一種 bug。
在 Django 也是一樣的道理
如果你用 Django REST Framework，ViewSet 本質上就是 Base Controller 的概念。差別在於 DRF 已經幫你做了很多，但統一回傳格式這件事你還是得自己來。
我在做 Proto 專案的時候，用自定義的 Response class 把 { success, message, data } 包起來，前端的 Axios interceptor 只要看 success 就知道該怎麼處理。
不管你用什麼框架，Base Controller 是前後端分離架構中第一個該建的基礎設施。對吧？
API 格式統一不難，難的是讓每個人都乖乖遵守。