Go Ginrest實現一個RESTful介面

2022-08-18 14:01:54

背景

基於現在微服務或者服務化的思想，我們大部分的業務邏輯處理常式都是長這樣的：

比如grpc伺服器端：

func (s *Service) GetUserInfo(ctx context.Context, req *pb.GetUserInfoReq) (*pb.GetUserInfoRsp, error) {
    // 業務邏輯
    // ...
}

grpc使用者端：

func (s *Service) GetUserInfo(ctx context.Context, req *pb.GetUserInfoReq, opts ...grpc.CallOption) (*pb.GetUserInfoRsp, error) {
    // 業務邏輯
    // ...
}

有些服務我們需要把它包裝為RESTful形式的介面，一般需要經歷以下步驟：

指定HTTP方法、URL
鑑權
引數繫結
處理請求
處理響應

可以發現，引數繫結、處理響應幾乎都是一樣模板程式碼，鑑權也基本上是模板程式碼（當然有些鑑權可能比較複雜）。

而Ginrest庫就是為了消除這些模板程式碼，它不是一個複雜的框架，只是一個簡單的庫，輔助處理這些重複的事情，為了實現這個能力使用了Go1.18的泛型。

倉庫地址：github.com/jiaxwu/ginr…

特性

這個庫提供以下特性：

封裝RESTful請求響應
- 封裝RESTful請求為標準格式服務
- 封裝標準格式服務處理結果為標準RESTful響應格式：Rsp{code, msg, data}
- 預設使用統一數位錯誤碼格式：[0, 4XXXX, 5XXXX]
- 預設使用標準錯誤格式：Error{code, msg}
- 預設統一狀態碼[200, 400, 500]
提供Recovery中介軟體，統一panic時的響應格式
提供SetKey()、GetKey()方法，用於儲存請求上下文（泛型）
提供ReqFunc()，用於設定Req（泛型）

使用例子

範例程式碼在：github.com/jiaxwu/ginr…

首先我們實現兩個簡單的服務：

const (
	ErrCodeUserNotExists = 40100 // 使用者不存在
)
type GetUserInfoReq struct {
	UID int `json:"uid"`
}
type GetUserInfoRsp struct {
	UID      int    `json:"uid"`
	Username string `json:"username"`
	Age      int    `json:"age"`
}
func GetUserInfo(ctx context.Context, req *GetUserInfoReq) (*GetUserInfoRsp, error) {
	if req.UID != 10 {
		return nil, ginrest.NewError(ErrCodeUserNotExists, "user not exists")
	}
	return &GetUserInfoRsp{
		UID:      req.UID,
		Username: "user_10",
		Age:      10,
	}, nil
}
type UpdateUserInfoReq struct {
	UID      int    `json:"uid"`
	Username string `json:"username"`
	Age      int    `json:"age"`
}
type UpdateUserInfoRsp struct{}
func UpdateUserInfo(ctx context.Context, req *UpdateUserInfoReq) (*UpdateUserInfoRsp, error) {
	if req.UID != 10 {
		return nil, ginrest.NewError(ErrCodeUserNotExists, "user not exists")
	}
	return &UpdateUserInfoRsp{}, nil
}

然後使用Gin+Ginrest包裝為RESTful介面：

可以看到Register()裡面每個介面都只需要一行程式碼！

func main() {
	e := gin.New()
	e.Use(ginrest.Recovery())
	Register(e)
	if err := e.Run("127.0.0.1:8000"); err != nil {
		log.Println(err)
	}
}
// 註冊請求
func Register(e *gin.Engine) {
	// 簡單請求，不需要認證
	e.GET("/user/info/get", ginrest.Do(nil, GetUserInfo))
	// 認證，繫結UID，處理
        reqFunc := func(c *gin.Context, req *UpdateUserInfoReq) {
		req.UID = GetUID(c)
	} // 這裡拆多一步是為了顯示第一個引數是ReqFunc
	e.POST("/user/info/update", Verify, ginrest.Do(reqFunc, UpdateUserInfo))
}
const (
	KeyUserID = "KeyUserID"
)
// 簡單包裝方便使用
func GetUID(c *gin.Context) int {
	return ginrest.GetKey[int](c, KeyUserID)
}
// 簡單包裝方便使用
func SetUID(c *gin.Context, uid int) {
	ginrest.SetKey(c, KeyUserID, uid)
}
// 認證
func Verify(c *gin.Context) {
	// 認證處理
	// ...
        // 忽略認證的具體邏輯
	SetUID(c, 10)
}

執行上面程式碼，然後嘗試存取介面，可以看到返回結果：

請求1
GET http://127.0.0.1:8000/user/info/get
{
"uid": 10
}
響應1
{
"code": 0,
"msg": "ok",
"data": {
"uid": 10,
"username": "user_10",
"age": 10
}
}
請求2
GET http://127.0.0.1:8000/user/info/get
{
"uid": 1
}
響應2
{
"code": 40100,
"msg": "user not exists"
}
請求3
POST http://127.0.0.1:8000/user/info/update
{
"username": "jiaxwu",
"age": 10
}
響應3
{
"code": 0,
"msg": "ok",
"data": {}
}

實現原理

Do()和DoOpt()都會轉發到do()，它其實是一個模板函數，把髒活累活給處理了：

// 處理請求
func do[Req any, Rsp any, Opt any](reqFunc ReqFunc[Req],
	serviceFunc ServiceFunc[Req, Rsp], serviceOptFunc ServiceOptFunc[Req, Rsp, Opt], opts ...Opt) gin.HandlerFunc {
	return func(c *gin.Context) {
		// 引數繫結
		req, err := BindJSON[Req](c)
		if err != nil {
			return
		}
		// 進一步處理請求結構體
		if reqFunc != nil {
			reqFunc(c, req)
		}
		var rsp *Rsp
		// 業務邏輯函數呼叫
		if serviceFunc != nil {
			rsp, err = serviceFunc(c, req)
		} else if serviceOptFunc != nil {
			rsp, err = serviceOptFunc(c, req, opts...)
		} else {
			panic("must one of ServiceFunc and ServiceFuncOpt")
		}
		// 處理響應
		ProcessRsp(c, rsp, err)
	}
}

功能列表

處理請求

用於把一個標準服務封裝為一個RESTfulgin.HandlerFunc，對應Do()、DoOpt()函數。

DoOpt()相比於Do()多了一個opts引數，因為很多rpc框架使用者端都有一個opts引數作為結尾。

還有一個BindJSON()，用於把請求體包裝為一個Req結構體：

// 引數繫結
func BindJSON[T any](c *gin.Context) (*T, error) {
	var req T
	if err := c.ShouldBindJSON(&amp;req); err != nil {
		FailureCodeMsg(c, ErrCodeInvalidReq, "invalid param")
		return nil, err
	}
	return &amp;req, nil
}

如果無法使用Do()和DoOpt()則可以使用此方法。

處理響應

用於把rsp、error、errcode、errmsg等資料封裝為一個JSON格式響應體，對應ProcessRsp()、Success()、Failure()、FailureCodeMsg()函數。

比如ProcessRsp()需要帶上rsp和error，這樣業務裡面就不需要再寫如下模板程式碼了：

// 處理簡單響應
func ProcessRsp(c *gin.Context, rsp any, err error) {
	if err != nil {
		Failure(c, err)
		return
	}
	Success(c, rsp)
}

響應格式統一為：

// 響應
type Rsp struct {
	Code int    `json:"code"`
	Msg  string `json:"msg"`
	Data any    `json:"data,omitempty"`
}

Success()用於處理成功情況：

// 請求成功
func Success(c *gin.Context, data any) {
	ginRsp(c, http.StatusOK, &amp;Rsp{
		Code: ErrCodeOK,
		Msg:  "ok",
		Data: data,
	})
}

其餘同理。

如果無法使用Do()和DoOpt()則可以使用這些方法。

處理錯誤

一般我們都需要在出錯時帶上一個業務錯誤碼，方便使用者端處理。因此我們需要提供一個合適的error型別：

// 錯誤
type Error struct {
	Code int    `json:"code"`
	Msg  string `json:"msg"`
}

我們提供了一些函數方便使用Error，對應NewError()、ToError()、ErrCode()、ErrMsg()、ErrEqual()函數。

比如NewError()生成一個Error型別error：

// 通過code和msg產生一個錯誤
func NewError(code int, msg string) error {
	return &amp;Error{
		Code: code,
		Msg:  msg,
	}
}

請求上下文操作

Gin的請求是鏈式處理的，也就是多個handler順序的處理一個請求，比如：

        reqFunc := func(c *gin.Context, req *UpdateUserInfoReq) {
		req.UID = ginrest.GetKey[int](c, KeyUserID)
	}
        // 認證，繫結UID，處理
	e.POST("/user/info/update", Verify, ginrest.Do(reqFunc, UpdateUserInfo))

這個介面經歷了Verify和ginrest.Do兩個handler，其中我們在Verify的時候通過認證知道了使用者的身份資訊（比如uid），我們希望把這個uid存起來，這樣可以在業務邏輯裡使用。

因此我們提供了SetKey()、GetKey()兩個函數，用於儲存請求上下文：

比如認證通過後我們可以設定UID到上下文，然後在reqFunc()裡讀取設定到req裡面（下面介紹）。

// 認證
func Verify(c *gin.Context) {
	// 認證處理
	// ...
	// 忽略認證的具體邏輯
	ginrest.SetKey(c, KeyUserID, uid)
}

請求結構體處理

上面我們設定了請求上下文，比如UID，但是其實我們並不知道具體這個UID是需要設定到req裡的哪個欄位，因此我們提供了一個回撥函數ReqFunc()，用於設定Req：

	// 這裡↓
        reqFunc := func(c *gin.Context, req *UpdateUserInfoReq) {
		req.UID = ginrest.GetKey[int](c, KeyUserID)
	}
        // 認證，繫結UID，處理
	e.POST("/user/info/update", Verify, ginrest.Do(reqFunc, UpdateUserInfo))