如何設計 API 介面，實現統一格式返回？

文章目錄：

目錄

• 前後端介面互動
• 介面返回值約定
  • 返回值規範
  • 正確返回
  • 錯誤返回
• 統一定義錯誤碼
  • 錯誤碼規範
• Controller 層如何用？
  • 正確返回
  • 錯誤返回
• 詳細程式碼實現
  • 錯誤碼
  • Controller
• 總結
  • 問題思考

前後端介面互動

我們都知道，前端通常會通過後臺提供的介面來獲取資料來完成前端頁面的渲染，前端可以為 PC 端、M 端、小程式、APP 等。

在這廢話就不多說了，這不是重點。

介面返回值約定

返回值規範

• 設定返回的 HTTP 響應狀態碼；
• 發生錯誤時，需設定 Response Body 的錯誤碼和描述資訊；

正確返回

HTTP 響應狀態碼，設定成 200，Response Body 結構為返回的資料結構。

錯誤返回

HTTP 響應狀態碼，不要設定成 200！需遵循 RFC 標準。

// Failure 錯誤時返回結構
type Failure struct {
	Code    int    `json:"code"`    // 業務碼
	Message string `json:"message"` // 描述資訊
}

統一定義錯誤碼

錯誤碼規範

• 統一在一個檔案中定義錯誤碼；
• 錯誤碼長度為 5 位；

第 1 位表示錯誤是哪種級別？例如：1 為系統級錯誤，2 為業務模組錯誤，可標記 9 種錯誤級別。

第 2 位和第 3 位表示錯誤是哪個模組？例如：01 為使用者模組，02 為訂單模組，可標記 99 個模組。

第 4 位和第 5 為表示具體是什麼錯誤？例如：01 為手機號不合法，02 為驗證碼輸入錯誤，可標記 99 個錯誤。

Controller 層如何用？

正確返回

res := new(createResponse)
res.Id = 1
ctx.Payload(res)

錯誤返回

c.AbortWithError(errno.NewError(
	http.StatusBadRequest,
	code.AdminCreateError,
	code.Text(code.AdminCreateError)).WithErr(err),
)

return 

詳細程式碼實現

錯誤碼

• 錯誤碼封裝：https://github.com/xinliangnote/go-gin-api/blob/master/pkg/errno/errno.go
• 定義錯誤碼：https://github.com/xinliangnote/go-gin-api/blob/master/internal/api/code/code.go

Controller

• https://github.com/xinliangnote/go-gin-api/blob/master/internal/api/controller/admin_handler/func_create.go

總結

以上程式碼供大家參考，還有優化的空間，歡迎大家使用並提出寶貴意見。

問題思考

• 1、提供對外介面時，如何進行安全的簽名驗證？
• 2、介面的冪等性如何設計？
• 3、如何統一對返回資料進行敏感資料脫敏？
• 4、如何設計介面日誌，便於介面聯調時快速進行錯誤定位？
• 5、關於介面文件，如何進行自動生成？聽說過 swagger 還不知道如何使用？

如果你對以上問題又疑惑或拿捏不準，快來我的星球交流討論吧，https://t.zsxq.com/iIUVVnA。