feat: commit at 20241227165559

Author: colin404

pkg/core/core.go

@@ -1,56 +1,74 @@
 package core
 
 import (
+	"context"
 	"net/http"
 
 	"github.com/gin-gonic/gin"
-
 	"github.com/superproj/onex/pkg/errorsx"
 )
 
-// ErrorResponse 定义了一个错误响应结构体.
+// ValidatorFn 定义验证函数类型。用于对绑定的数据结构进行验证。  
+type ValidatorFn[T any] func(context.Context, T) error
+
+// BindFn 定义绑定函数类型，接收通用类型参数并返回错误。  
+type BindFn func(any) error
+
+// ErrorResponse 定义错误响应结构体。  
+// 用于 API 请求中发生错误时，按照统一格式返回给客户端。  
 type ErrorResponse struct {
-	// 理由
-	Reason string `json:"reason,omitempty"`
-	// 信息
-	Message string `json:"message,omitempty"`
-	// 元数据
-	Metadata map[string]string `json:"metadata,omitempty"`
+	Reason   string            `json:"reason,omitempty"`   // 错误原因，标识错误类型  
+	Message  string            `json:"message,omitempty"`  // 错误的具体描述信息  
+	Metadata map[string]string `json:"metadata,omitempty"` // 元数据，包含额外的上下文信息  
 }
 
-func ShouldBindJSON(c *gin.Context, rq any) error {
-	return ReadRequest(c, rq, c.ShouldBindJSON)
+// ShouldBindJSON 使用 JSON 格式的绑定函数绑定请求参数并执行验证。  
+func ShouldBindJSON[T any](c *gin.Context, rq T, validators ...ValidatorFn[T]) error {
+	return ReadRequest(c, rq, c.ShouldBindJSON, validators...)
 }
 
-func ShouldBindQuery(c *gin.Context, rq any) error {
-	return ReadRequest(c, rq, c.ShouldBindQuery)
+// ShouldBindQuery 使用 Query 格式的绑定函数绑定请求参数并执行验证。
+func ShouldBindQuery[T any](c *gin.Context, rq T, validators ...ValidatorFn[T]) error {
+	return ReadRequest(c, rq, c.ShouldBindQuery, validators...)
 }
 
-func ShouldBindUri(c *gin.Context, rq any) error {
-	return ReadRequest(c, rq, c.ShouldBindUri)
+// ShouldBindUri 使用 URI 格式的绑定函数绑定请求参数并执行验证。
+func ShouldBindUri[T any](c *gin.Context, rq T, validators ...ValidatorFn[T]) error {
+	return ReadRequest(c, rq, c.ShouldBindUri, validators...)
 }
 
-// ReadRequest 绑定参数、调用 Default() 初始化，并处理错误.
-func ReadRequest(c *gin.Context, rq any, bindFn func(any) error) error {
-	// 使用特定参数绑定函数
+// ReadRequest 是通用的请求绑定和验证工具函数。
+// 它会对请求进行参数绑定，初始化默认值（如果目标结构体实现了 Default 接口），并执行验证函数（可选）。
+func ReadRequest[T any](c *gin.Context, rq T, bindFn BindFn, validators ...ValidatorFn[T]) error {
+	// 调用绑定函数绑定请求数据
 	if err := bindFn(rq); err != nil {
 		return err
 	}
 
-	// 调用 Default() 方法（如果存在）
-	if defaulter, ok := rq.(interface{ Default() }); ok {
+	// 如果目标结构体实现了 Default 接口，则调用其 Default 方法设置默认值
+	if defaulter, ok := any(rq).(interface{ Default() }); ok {
 		defaulter.Default()
 	}
 
+	// 遍历所有验证函数并执行它们
+	for _, validator := range validators {
+		if validator == nil { // 跳过 nil 的验证函数  
+			continue
+		}
+		if err := validator(c.Request.Context(), rq); err != nil {
+			return err
+		}
+	}
+
 	return nil
 }
 
-// WriteResponse 处理响应的函数.
+// WriteResponse 是统一的响应处理函数。  
+// 根据返回值是否发生错误，返回成功响应或错误响应。  
 func WriteResponse(c *gin.Context, result any, err error) {
-	// 判断错误是否存在
+	// 如果发生错误，生成错误响应  
 	if err != nil {
-		errx := errorsx.FromError(err) // 从错误中获取详细信息
-		// 返回错误响应
+		errx := errorsx.FromError(err) // 从错误对象中解析详细错误信息  
 		c.JSON(errx.Code, &ErrorResponse{
 			Reason:   errx.Reason,
 			Message:  errx.Message,
@@ -59,6 +77,6 @@ func WriteResponse(c *gin.Context, result any, err error) {
 		return
 	}
 
-	// 返回正常响应
+	// 如果没有错误，生成成功响应  
 	c.JSON(http.StatusOK, result)
 }