Overview
ginvalidator is a set of Gin middlewares that wraps the extensive collection of validators and sanitizers offered by my other open source package validatorgo. It also uses the popular open-source package gjson for JSON field syntax, providing efficient querying and extraction of data from JSON objects.
It allows you to combine them in many ways so that you can validate and sanitize your Gin requests, and offers tools to determine if the request is valid or not, which data was matched according to your validators.
It is based on the popular js/express library express-validator
Support
This version of ginvalidator requires that your application is running on Go 1.16 .
It's also verified to work with Gin 1.x.x.
Rationale
Why not use?
- Handwritten Validators: You could write your own validation logic manually, but that gets repetitive and messy fast. Every time you need a new validation, you’re writing the same kind of code over and over. It’s easy to make mistakes, and it’s a pain to maintain.
- Gin's Built-in Model Binding and Validation: Gin has validation built in, but it’s not ideal for everyone. Struct tags are limiting and make your code harder to read, especially when you need complex rules. Plus, the validation gets tied too tightly to your models, which isn't great for flexibility.
- Other Libraries (like Galidator): There are other libraries out there, but they often feel too complex for what they do. They require more setup and work than you’d expect, especially when you just want a simple, straightforward solution for validation.
Installation
Make sure you have Go installed on your machine.
Step 1: Create a New Go Module
- Create an empty folder with a name of your choice.
- Open a terminal, navigate (cd) into that folder, and initialize a new Go module:
go mod init example.com/learning
Step 2: Install Required Packages
Use go get to install the necessary packages.
- Install Gin:
go get -u github.com/gin-gonic/gin
- Install ginvalidator:
go get -u github.com/bube054/ginvalidator
Getting Started
One of the best ways to learn something is by example! So let's roll the sleeves up and get some coding happening.
Setup
The first thing that one needs is a Gin server running. Let's implement one that says hi to someone; for this, create a main.go then add the following code:
package main import ( "net/http" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() r.GET("/hello", func(ctx *gin.Context) { person := ctx.Query("person") ctx.String(http.StatusOK, "Hello, %s!", person) }) r.Run() // listen and serve on 0.0.0.0:8080 }
Now run this file by executing go run main.go on your terminal.
go mod init example.com/learning
The HTTP server should be running, and you can open http://localhost:8080/hello?person=John to salute John!
? Tip:
You can use Air with Go and Gin to implement live reload. These automatically restart the server whenever a file is changed, so you don't have to do this yourself!
Adding a validator
So the server is working, but there are problems with it. Most notably, you don't want to say hello to someone when the person's name is not set.
For example, going to http://localhost:8080/hello will print "Hello, ".
That's where ginvalidator comes in handy. It provides validators, sanitizers and modifiers that are used to validate your request.
Let's add a validator and a modifier that checks that the person query string cannot be empty, with the validator named Empty and modifier named Not:
go get -u github.com/gin-gonic/gin
? Note:
For brevity, gv is used as an alias for ginvalidator in the code examples.
Now, restart your server, and go to http://localhost:8080/hello again. Hmm, it still prints "Hello, !"... why?
Handling validation errors
ginvalidator validation chain does not report validation errors to users automatically.
The reason for this is simple: as you add more validators, or for more fields, how do you want to collect the errors? Do you want a list of all errors, only one per field, only one overall...?
So the next obvious step is to change the above code again, this time verifying the validation result with the ValidationResult function:
go get -u github.com/bube054/ginvalidator
Now, if you access http://localhost:8080/hello again, you’ll see the following JSON content, formatted for clarity:
package main import ( "net/http" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() r.GET("/hello", func(ctx *gin.Context) { person := ctx.Query("person") ctx.String(http.StatusOK, "Hello, %s!", person) }) r.Run() // listen and serve on 0.0.0.0:8080 }
Now, what this is telling us is that
- there's been exactly one error in this request;
- this field is called person;
- it's located in the query string (location: "queries");
- the error message that was given was "Invalid value".
This is a better scenario, but it can still be improved. Let's continue.
Creating better error messages
All request location validators accept an optional second argument, which is a function used to format the error message. If nil is provided, a default, generic error message will be used, as shown in the example above.
go run main.go
Now if you access http://localhost:8080/hello again, what you'll see is the following JSON content, with the new error message:
package main import ( "net/http" gv "github.com/bube054/ginvalidator" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() r.GET("/hello", gv.NewQuery("person", nil). Chain(). Not(). Empty(nil). Validate(), func(ctx *gin.Context) { person := ctx.Query("person") ctx.String(http.StatusOK, "Hello, %s!", person) }) r.Run() }
Accessing validated/sanitized data
You can use GetMatchedData, which automatically collects all data that ginvalidator has validated and/or sanitized. This data can then be accessed using the Get method of MatchedData:
go mod init example.com/learning
open http://localhost:8080/hello?person=John to salute John!
The available locations are BodyLocation, CookieLocation QueryLocation, ParamLocation and HeaderLocation.
Each of these locations includes a String method that returns the location where validated/sanitized data is being stored.
Sanitizing inputs
While the user can no longer send empty person names, it can still inject HTML into your page! This is known as the Cross-Site Scripting vulnerability (XSS).
Let's see how it works. Go to http://localhost:8080/hello?person=John, and you should see "Hello, John!".
While this example is fine, an attacker could change the person query string to a <script> tag which loads its own JavaScript that could be harmful.<br>
In this scenario, one way to mitigate the issue with ginvalidator is to use a sanitizer, most specifically Escape, which transforms special HTML characters with others that can be represented as text.<br>
</script>
go get -u github.com/gin-gonic/gin
Now, if you restart the server and refresh the page, what you'll see is "Hello, John!". Our example page is no longer vulnerable to XSS!
⚠️ Caution:
ginvalidator does not modify http.Request values during sanitization. To access sanitized data, always use the GetMatchedData function.
The Validation Chain
The validation chain is one of the main concepts in ginvalidator, therefore it's useful to learn about it, so that you can use it effectively.
But don't worry: if you've read through the Getting Started guide, you have already used validation chains without even noticing!
What are validation chains?
Validation chains are created using the following functions, each targeting a specific location in the HTTP request:
- NewBody: Validates data from the http.Request body. Its location is BodyLocation.
- NewCookie: Validates data from the http.Request cookies. Its location is CookieLocation.
- NewHeader: Validates data from the http.Request headers. Its location is HeaderLocation.
- NewParam: Validates data from the Gin route parameters. Its location is ParamLocation.
- NewQuery: Validates data from the http.Request query parameters. Its location is QueryLocation.
They have this name because they wrap the value of a field with validations (or sanitizations), and each of its methods returns itself.
This pattern is usually called method chaining, hence why the name validation chain.
Validation chains not only have a number of useful methods for defining validations, sanitizations and modifications but they also have methods Validate which returns the Gin middleware handler function.
This is an example of how validation chains are usually used, and how you can read one:
go mod init example.com/learning
Features
A validation chain has three kinds of methods: validators, sanitizers and modifiers.
Validators determine if the value of a request field is valid. This means checking if the field is in the format that you expect it to be. For example, if you're building a sign up form, your requirements could be that the username must be an e-mail address, and that passwords must be at least 8 characters long.
If the value is invalid, an error is recorded for that field using some error message. This validation error can then be retrieved at a later point in the Gin route handler and returned to the user.
They are:
- CustomValidator
- Contains
- Equals
- AbaRouting
- After
- Alpha
- Alphanumeric
- Ascii
- Base32
- Base58
- Base64
- Before
- Bic
- Boolean
- BTCAddress
- ByteLength
- CreditCard
- Currency
- DataURI
- Date
- Decimal
- DivisibleBy
- EAN
- Empty
- EthereumAddress
- Float
- FQDN
- FreightContainerID
- FullWidth
- HalfWidth
- Hash
- Hexadecimal
- HexColor
- HSL
- IBAN
- IdentityCard
- IMEI
- In
- Int
- IP
- IPRange
- ISIN
- ISO4217
- ISO6346
- ISO6391
- ISO8601
- ISO31661Alpha2
- ISO31661Alpha3
- ISO31661Numeric
- ISRC
- ISSN
- JSON
- LatLong
- LicensePlate
- Locale
- LowerCase
- LuhnNumber
- MacAddress
- MagnetURI
- MailtoURI
- MD5
- MimeType
- MobilePhone
- MongoID
- Multibyte
- Numeric
- Octal
- PassportNumber
- Port
- PostalCode
- RFC3339
- RgbColor
- SemVer
- Slug
- StrongPassword
- TaxID
- SurrogatePair
- Time
- ULID
- UpperCase
- URL
- UUID
- VariableWidth
- VAT
- Whitelisted
- Matches
Sanitizers transform the field value. They are useful to remove noise from the value and perhaps even to provide some basic line of defense against threats.
Sanitizers persist the updated fields value back into the Gin Contexts, so that it's usable by other ginvalidator functions, your own route handler code, and even other middlewares.
They are:
- CustomSanitizer
- Blacklist
- Escape
- LTrim
- NormalizeEmail
- RTrim
- StripLow
- ToBoolean
- ToDate
- ToFloat
- ToInt
- Trim
- Unescape
- Whitelist
Modifiers define how validation chains behave when they are run.
They are:
- Bail
- If
- Not
- Skip
- Optional
? Note:
These methods are thoroughly documented using GoDoc within the pkg.go.dev ginvalidator documentation. If any details are unclear, you may also want to refer to related functions within the validatorgo package for additional context, which I’ll be explaining below.
Standard validators/sanitizers
All of the functionality exposed by the validation chain actually comes from validatorgo, one of my other open source go packages which specializes in string validation/sanitation. Please check it out, star and share ???, Thank You.
This includes all of validatorgo validators and sanitizers, from commonly used IsEmail, IsLength, and Trim to the more niche IsISBN, IsMultibyte and StripLow!
These are called standard validators and standard sanitizers in ginvalidator. But without the Is prefix from validatorgo.
Chaining order
The order in which you call methods on a validation chain usually matters.
They are almost always run in the order that they are specified, therefore you can tell what a validation chain will do just by reading its definition, from first chained method to last.
Take the following snippet as an example:
go mod init example.com/learning
In this case, if the user passes a "search_query" value that is composed of whitespaces only, it won't be empty, therefore the validation passes. But since the .Trim() sanitizer is there, the whitespace's will be removed, and the field will become empty, so you actually end up with a false positive.
Now, compare it with the below snippet:
go get -u github.com/gin-gonic/gin
This chain will more sensibly remove whitespace's, and then validate if the value is not empty.
One exception to this rule is .Optional(): It can be placed at any point in the chain and it will mark the chain as optional.
Reusing validation chains
If you wish to reuse the same chain, it's a good idea to return them from functions:
go get -u github.com/bube054/ginvalidator
Field Selection
In ginvalidator, a field is any value that is either validated or sanitized and it is string.
Pretty much every function or value returned by ginvalidator reference fields in some way. For this reason, it's important to understand the field path syntax both for when selecting fields for validation, and when accessing the validation errors or validated data.
Syntax
-
Body fields are only valid for the following Content-Types:
- application/json: This uses GJSON path syntax for extracting values. Please refer to the linked documentation for details.
- Example:
go mod init example.com/learning
With path user.name, the extracted value would be "John".
- application/x-www-form-urlencoded: Typically used for HTML form submissions. Fields are submitted as key-value pairs in the body.
- Example:
go get -u github.com/gin-gonic/gin
Body:
go get -u github.com/bube054/ginvalidator
Field "name" would have the value "John", and "email" would have the value "john.doe@example.com".
- multipart/form-data: Commonly used for file uploads or when submitting form data with files.
- Example:
package main import ( "net/http" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() r.GET("/hello", func(ctx *gin.Context) { person := ctx.Query("person") ctx.String(http.StatusOK, "Hello, %s!", person) }) r.Run() // listen and serve on 0.0.0.0:8080 }
Body:
go run main.go
Field "name" would have the value "John", and "file" would be the uploaded file.
-
Query fields correspond to URL search parameters, and their values are automatically url unescaped by Gin.
Examples:- Field: "name", Value: "John"
package main import ( "net/http" gv "github.com/bube054/ginvalidator" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() r.GET("/hello", gv.NewQuery("person", nil). Chain(). Not(). Empty(nil). Validate(), func(ctx *gin.Context) { person := ctx.Query("person") ctx.String(http.StatusOK, "Hello, %s!", person) }) r.Run() }
- Field: "full_name", Value: "John Doe"
package main import ( "net/http" gv "github.com/bube054/ginvalidator" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() r.GET("/hello", gv.NewQuery("person", nil). Chain(). Not(). Empty(nil). Validate(), func(ctx *gin.Context) { result, err := gv.ValidationResult(ctx) if err != nil { ctx.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{ "message": "The server encountered an unexpected error.", }) return } if len(result) != 0 { ctx.AbortWithStatusJSON(http.StatusUnprocessableEntity, gin.H{ "errors": result, }) return } person := ctx.Query("person") ctx.String(http.StatusOK, "Hello, %s!", person) }) r.Run() }
-
Param fields represent URL path parameters, and their values are automatically unescaped by ginvalidator.
Example:- Field: "id", Value: "123"
{ "errors": [ { "location": "queries", "message": "Invalid value", "field": "person", "value": "" } ] }
-
Header fields are HTTP request headers, and their values are not unescaped. A log warning will appear if you provide a non-canonical header key.
Example:- Field: "User-Agent", Value: "Mozilla/5.0"
package main import ( "net/http" gv "github.com/bube054/ginvalidator" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() r.GET("/hello", gv.NewQuery("person", func(initialValue, sanitizedValue, validatorName string) string { return "Please enter your name." }, ).Chain(). Not(). Empty(nil). Validate(), func(ctx *gin.Context) { result, err := gv.ValidationResult(ctx) if err != nil { ctx.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{ "message": "The server encountered an unexpected error.", }) return } if len(result) != 0 { ctx.AbortWithStatusJSON(http.StatusUnprocessableEntity, gin.H{ "errors": result, }) return } person := ctx.Query("person") ctx.String(http.StatusOK, "Hello, %s!", person) }) r.Run() }
-
Cookies fields are HTTP cookies, and their values are automatically url unescaped by Gin.
Example:- Field: "session_id", Value: "abc 123"
{ "errors": [ { "location": "queries", "message": "Please enter your name.", "field": "person", "value": "" } ] }
Customizing express-validator
If the server you're building is anything but a very simple one, you'll need validators, sanitizers and error messages beyond the ones built into ginvalidator sooner or later.
Custom Validators and Sanitizers
A classic need that ginvalidator can't fulfill for you, and that you might run into, is validating whether an e-mail address is in use or not when a user signing up.
It's possible to do this in ginvalidator by implementing a custom validator.
A CustomValidator is a method available on the validation chain, that receives a special function CustomValidatorFunc, and have to returns a boolean that will determine if the field is valid or not.
A CustomSanitizer is also a method available on the validation chain, that receives a special function CustomSanitizerFunc, and have to returns the new sanitized value.
Implementing a custom validator
A CustomValidator can be asynchronous by using goroutines and a sync.WaitGroup to handle concurrent operations. Within the validator, you can spin up goroutines for each asynchronous task, adding each task to the WaitGroup. Once all tasks complete, the validator should return a boolean.
For example, in order to check that an e-mail is not in use:
go mod init example.com/learning
Or maybe you could also verify that the password matches the repeat:
go get -u github.com/gin-gonic/gin
⚠️ Caution:
If the request body will be accessed multiple times—whether in the same validation chain, in another validation chain for the same request context, or in subsequent handlers—ensure you reset the request body after each read. Failing to do so can lead to errors or missing data when the body is read again.
Implementing a custom sanitizer
CustomSanitizer don't have many rules. Whatever the value that they return, is the new value that the field will acquire.
Custom sanitizers can also be asynchronous by using goroutines and a sync.WaitGroup to handle concurrent operations.
go get -u github.com/bube054/ginvalidator
Error Messages
Whenever a field value is invalid, an error message is recorded for it.
The default error message is "Invalid value", which is not descriptive at all of what the error is, so you might need to customize it. You can customize by
package main import ( "net/http" "github.com/gin-gonic/gin" ) func main() { r := gin.Default() r.GET("/hello", func(ctx *gin.Context) { person := ctx.Query("person") ctx.String(http.StatusOK, "Hello, %s!", person) }) r.Run() // listen and serve on 0.0.0.0:8080 }
- initialValue is the original value extracted from the request (before any sanitization).
- sanitizedValue is the value after it has been sanitized (if applicable).
- validatorName is the name of the validator that failed, which helps identify the validation rule that did not pass.
For a complete list of validator names, refer to the ginvalidator constants.
Maintainers
- bube054 - Attah Gbubemi David (author)
The above is the detailed content of Simplify Gin Input Validation in Go with ginvalidator. For more information, please follow other related articles on the PHP Chinese website!

This article explains Go's package import mechanisms: named imports (e.g., import "fmt") and blank imports (e.g., import _ "fmt"). Named imports make package contents accessible, while blank imports only execute t

This article explains Beego's NewFlash() function for inter-page data transfer in web applications. It focuses on using NewFlash() to display temporary messages (success, error, warning) between controllers, leveraging the session mechanism. Limita

This article details efficient conversion of MySQL query results into Go struct slices. It emphasizes using database/sql's Scan method for optimal performance, avoiding manual parsing. Best practices for struct field mapping using db tags and robus

This article demonstrates creating mocks and stubs in Go for unit testing. It emphasizes using interfaces, provides examples of mock implementations, and discusses best practices like keeping mocks focused and using assertion libraries. The articl

This article explores Go's custom type constraints for generics. It details how interfaces define minimum type requirements for generic functions, improving type safety and code reusability. The article also discusses limitations and best practices

This article details efficient file writing in Go, comparing os.WriteFile (suitable for small files) with os.OpenFile and buffered writes (optimal for large files). It emphasizes robust error handling, using defer, and checking for specific errors.

The article discusses writing unit tests in Go, covering best practices, mocking techniques, and tools for efficient test management.

This article explores using tracing tools to analyze Go application execution flow. It discusses manual and automatic instrumentation techniques, comparing tools like Jaeger, Zipkin, and OpenTelemetry, and highlighting effective data visualization


Hot AI Tools

Undresser.AI Undress
AI-powered app for creating realistic nude photos

AI Clothes Remover
Online AI tool for removing clothes from photos.

Undress AI Tool
Undress images for free

Clothoff.io
AI clothes remover

AI Hentai Generator
Generate AI Hentai for free.

Hot Article

Hot Tools

SAP NetWeaver Server Adapter for Eclipse
Integrate Eclipse with SAP NetWeaver application server.

EditPlus Chinese cracked version
Small size, syntax highlighting, does not support code prompt function

Dreamweaver Mac version
Visual web development tools

Notepad++7.3.1
Easy-to-use and free code editor

VSCode Windows 64-bit Download
A free and powerful IDE editor launched by Microsoft
