feat(binding): Support custom BindUnmarshaler for binding.

[dkkb]

Feature

Add binding.BindUnmarshaler interface to support custom unmarshaling (from the suggestion in #2673)

Description

This PR is inspired by the information provided on the following page: labstack/echo/v4#BindUnmarshaler and PR-3045.

As ssoroka (the author of PR-3045) mentioned:

This is way off my radar (it's been 2 years and I've switched to huma). Feel free to take over the change and apply it in a new PR."

Therefore, I would like to open a new pull request to implement this feature. However, I have identified two potential issues with PR-3045:

1. PR-3045 also introduces support for the encoding.TextUnmarshaler interface. I believe there might be compatibility issues with this approach. Instead, I suggest that users implement the new interface binding.BindUnmarshaler to achieve the desired custom unmarshaler functionality.

2. In order to support arrays and slices, PR-3045 uses vs[0] to retrieve the first item. This approach may be susceptible to boundary issues. Upon closer examination of the implementation, I found that addressing this complexity might be challenging. As a temporary solution, I have decided not to support this functionality for arrays and slices. If there is a future demand from other users, we can consider implementing it at that time.

if ok, err := trySetCustom(vs[0], value); ok || err != nil {
    return ok, err
}

Usage

package main

import (
  "github.com/gin-gonic/gin"
  "strings"
)

type Birthday string

func (b *Birthday) UnmarshalParam(param string) error {
  *b = Birthday(strings.Replace(param, "-", "/", -1))
  return nil
}

func main() {
  route := gin.Default()
  var request struct {
    Birthday Birthday `form:"birthday"`
  }
  route.GET("/test", func(ctx *gin.Context) {
    _ = ctx.BindQuery(&request)
    ctx.JSON(200, request.Birthday)
  })
  route.Run(":8088")
}

Test it with:

curl 'localhost:8088/test?birthday=2000-01-01'

Result

"2000/01/01"

Testing

1. Unit testing, see binding/form_mapping_test.go
2. Integration testing, see gin_test.go

References

• Close Use UnmarshalText in URI binding #2673
• Close BindQuery to custom type #2631
• Related to TextUnmarshaler support for binding #3045

[dkkb]

@appleboy Hi, Boyi, could you take a look at this PR. Any help would be greatly appreciated.

[appleboy]

Testing error:

[dkkb]

I forgot the build tags, I'll fix it.

[dkkb]

I move the newly added interface to form_mapping.go, it works now.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.18%. Comparing base (3dc1cd6) to head (9dc4b6e).
Report is 38 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3933      +/-   ##
==========================================
- Coverage   99.21%   99.18%   -0.03%     
==========================================
  Files          42       43       +1     
  Lines        3182     2716     -466     
==========================================
- Hits         3157     2694     -463     
+ Misses         17       12       -5     
- Partials        8       10       +2     

Flag	Coverage Δ
	?
-tags "sonic avx"	99.18% <100.00%> (?)
-tags go_json	99.18% <100.00%> (?)
-tags nomsgpack	99.17% <100.00%> (?)
go-1.18	99.11% <100.00%> (-0.01%)	⬇️
go-1.19	99.18% <100.00%> (-0.03%)	⬇️
go-1.20	99.18% <100.00%> (-0.03%)	⬇️
go-1.21	99.18% <100.00%> (-0.03%)	⬇️
go-1.22	99.18% <100.00%> (?)
macos-latest	99.18% <100.00%> (-0.03%)	⬇️
ubuntu-latest	99.18% <100.00%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.