Gin Validation, อัปโหลดไฟล์ และ Pagination: รับ Input อย่างปลอดภัยใน Go API

type articleURI struct {
	ID uint `uri:"id" binding:"required,min=1"`
}

type listQuery struct {
	Page     int    `form:"page,default=1" binding:"min=1"`
	Limit    int    `form:"limit,default=12" binding:"min=1,max=100"`
	Category uint   `form:"category"`
	Sort     string `form:"sort,default=newest" binding:"oneof=newest oldest title"`
}

type articleRequest struct {
	Title      string `json:"title" binding:"required,notblank,min=5,max=200"`
	Excerpt    string `json:"excerpt" binding:"required,notblank,max=500"`
	Body       string `json:"body" binding:"required,notblank"`
	Image      string `json:"image" binding:"omitempty,max=255"`
	CategoryID uint   `json:"categoryId" binding:"required,gt=0"`
}

package validation

import (
	"reflect"
	"strings"

	"github.com/gin-gonic/gin/binding"
	"github.com/go-playground/validator/v10"
)

func Setup() error {
	v, ok := binding.Validator.Engine().(*validator.Validate)
	if !ok {
		return nil
	}
	// Use json/form/uri tag names in errors instead of Go field names.
	v.RegisterTagNameFunc(func(f reflect.StructField) string {
		for _, key := range []string{"json", "form", "uri"} {
			name := strings.SplitN(f.Tag.Get(key), ",", 2)[0]
			if name != "" && name != "-" {
				return name
			}
		}
		return f.Name
	})
	// "required" accepts "   ". This rule does not.
	return v.RegisterValidation("notblank", func(fl validator.FieldLevel) bool {
		return strings.TrimSpace(fl.Field().String()) != ""
	})
}

func Respond(c *gin.Context, err error) {
	var ve validator.ValidationErrors
	if !errors.As(err, &ve) {
		// Malformed JSON, wrong types, unreadable body.
		c.JSON(http.StatusBadRequest, gin.H{"error": "malformed request"})
		return
	}
	fields := make(map[string]string, len(ve))
	for _, fe := range ve {
		fields[fe.Field()] = message(fe)
	}
	c.JSON(http.StatusUnprocessableEntity, gin.H{"error": "validation failed", "fields": fields})
}

func message(fe validator.FieldError) string {
	unit := ""
	if fe.Kind() == reflect.String {
		unit = " characters"
	}
	switch fe.Tag() {
	case "required", "notblank":
		return "is required"
	case "min":
		return "must be at least " + fe.Param() + unit
	case "max":
		return "must be at most " + fe.Param() + unit
	case "gt":
		return "must be greater than " + fe.Param()
	case "oneof":
		return "must be one of: " + fe.Param()
	}
	return "is invalid"
}

{
  "error": "validation failed",
  "fields": {
    "title": "must be at least 5 characters",
    "categoryId": "is required"
  }
}

const maxImageSize = 5 << 20 // 5 MiB

var allowedImageTypes = map[string]string{
	"image/jpeg": ".jpg",
	"image/png":  ".png",
	"image/webp": ".webp",
}

func (h *UploadHandler) Image(c *gin.Context) {
	// Hard cap on the whole request body, including multipart overhead.
	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxImageSize+(1<<20))

	file, err := c.FormFile("image")
	if err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "image is required and must be under 5 MiB"})
		return
	}
	if file.Size > maxImageSize {
		c.JSON(http.StatusRequestEntityTooLarge, gin.H{"error": "image must be under 5 MiB"})
		return
	}
	ext, err := sniffImage(file)
	if err != nil {
		c.JSON(http.StatusUnsupportedMediaType, gin.H{"error": "only JPEG, PNG and WebP are allowed"})
		return
	}

	name := randomName() + ext
	if err := c.SaveUploadedFile(file, filepath.Join(h.dir, name)); err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not save image"})
		return
	}
	c.JSON(http.StatusCreated, gin.H{"url": "/uploads/" + name})
}

// sniffImage checks the real content, not the client-supplied header or extension.
func sniffImage(fh *multipart.FileHeader) (string, error) {
	f, err := fh.Open()
	if err != nil {
		return "", err
	}
	defer f.Close()

	head := make([]byte, 512)
	n, err := io.ReadFull(f, head)
	if err != nil && !errors.Is(err, io.ErrUnexpectedEOF) {
		return "", err
	}
	ext, ok := allowedImageTypes[http.DetectContentType(head[:n])]
	if !ok {
		return "", errors.New("unsupported file type")
	}
	return ext, nil
}

func randomName() string {
	b := make([]byte, 16)
	_, _ = rand.Read(b) // crypto/rand
	return hex.EncodeToString(b)
}

if err := os.MkdirAll("uploads", 0o755); err != nil {
	log.Fatal(err)
}
r.Static("/uploads", "./uploads") // no directory listing
protected.POST("/uploads/images", uploads.Image)

?page=1&limit=12  ->  OFFSET 0   LIMIT 12
?page=2&limit=12  ->  OFFSET 12  LIMIT 12
offset     = (page - 1) * limit
totalPages = ceil(total / limit)

package pagination

import (
	"context"

	"golang.org/x/sync/errgroup"
	"gorm.io/gorm"
)

type Params struct{ Page, Limit int }

type Meta struct {
	Page       int   `json:"page"`
	Limit      int   `json:"limit"`
	Total      int64 `json:"total"`
	TotalPages int   `json:"totalPages"`
	PrevPage   *int  `json:"prevPage"`
	NextPage   *int  `json:"nextPage"`
}

type Page[T any] struct {
	Data []T  `json:"data"`
	Meta Meta `json:"meta"`
}

// Paginate runs the COUNT and the page query concurrently. base holds the
// filters; list adds page-only options such as Preload and Order.
func Paginate[T any](ctx context.Context, base *gorm.DB, p Params,
	list func(*gorm.DB) *gorm.DB) (Page[T], error) {

	q := base.Session(&gorm.Session{}) // safe to reuse from two goroutines
	var (
		total int64
		items []T
	)
	g, ctx := errgroup.WithContext(ctx)
	g.Go(func() error {
		return q.WithContext(ctx).Model(new(T)).Count(&total).Error
	})
	g.Go(func() error {
		offset := (p.Page - 1) * p.Limit
		return list(q.WithContext(ctx)).Limit(p.Limit).Offset(offset).Find(&items).Error
	})
	if err := g.Wait(); err != nil {
		return Page[T]{}, err
	}

	totalPages := int((total + int64(p.Limit) - 1) / int64(p.Limit))
	meta := Meta{Page: p.Page, Limit: p.Limit, Total: total, TotalPages: totalPages}
	if p.Page > 1 {
		prev := p.Page - 1
		meta.PrevPage = &prev
	}
	if p.Page < totalPages {
		next := p.Page + 1
		meta.NextPage = &next
	}
	if items == nil {
		items = []T{} // encode as [] rather than null
	}
	return Page[T]{Data: items, Meta: meta}, nil
}

var sortOrders = map[string]string{
	"newest": "created_at DESC, id DESC",
	"oldest": "created_at ASC, id ASC",
	"title":  "title ASC, id ASC",
}

func (h *ArticleHandler) List(c *gin.Context) {
	var q listQuery
	if err := c.ShouldBindQuery(&q); err != nil {
		validation.Respond(c, err)
		return
	}
	base := h.db.Model(&models.Article{})
	if q.Category != 0 {
		base = base.Where("category_id = ?", q.Category)
	}
	page, err := pagination.Paginate[models.Article](c.Request.Context(), base,
		pagination.Params{Page: q.Page, Limit: q.Limit},
		func(tx *gorm.DB) *gorm.DB { return tx.Preload("Category").Order(sortOrders[q.Sort]) })
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not load articles"})
		return
	}
	c.JSON(http.StatusOK, page)
}