ginvalidator を使用して Go での Jin 入力検証を簡素化する

概要

ginvalidator は、私の他のオープンソース パッケージ validatorgo が提供するバリデーターとサニタイザーの広範なコレクションをラップする、Gin ミドルウェアのセットです。また、JSON フィールド構文に人気のオープンソース パッケージ gjson を使用し、JSON オブジェクトからのデータの効率的なクエリと抽出を提供します。

Gin リクエストを検証してサニタイズできるように、これらをさまざまな方法で組み合わせることができ、リクエストが有効かどうか、バリデータに従ってどのデータが一致したかを判断するツールを提供します。

人気のある js/express ライブラリの Express-validator に基づいています

サポート

このバージョンの ginvalidator では、アプリケーションが Go 1.16 で実行されている必要があります。
また、Gin 1.x.x で動作することも確認されています。

理論的根拠

なぜ使用しないのでしょうか?

• 手書きバリデータ: 独自の検証ロジックを手動で作成することもできますが、繰り返しが多くなり、すぐに面倒になってしまいます。新しい検証が必要になるたびに、同じ種類のコードを何度も書くことになります。間違いを犯しやすく、それを維持するのは大変です。
• Gin の組み込みモデルのバインディングと検証: Gin には検証機能が組み込まれていますが、すべての人にとって理想的なわけではありません。構造体タグには制限があり、特に複雑なルールが必要な場合、コードが読みにくくなります。さらに、検証はモデルに強く結びつきすぎるため、柔軟性があまり良くありません。
• その他のライブラリ (Galidator など): 他にもライブラリはありますが、機能に対して複雑すぎると感じることがよくあります。特に検証のためのシンプルで単純なソリューションが必要な場合は、予想以上に多くのセットアップと作業が必要です。

インストール

マシンに Go がインストールされていることを確認してください。

ステップ 1: 新しい Go モジュールを作成する

1. 任意の名前で空のフォルダーを作成します。
2. ターミナルを開き、そのフォルダーに移動 (cd) し、新しい Go モジュールを初期化します。

go mod init example.com/learning

ステップ 2: 必要なパッケージをインストールする

go get を使用して、必要なパッケージをインストールします。

1. ジンをインストールします:

go get -u github.com/gin-gonic/gin

1. ginvalidator をインストールします。

go get -u github.com/bube054/ginvalidator

はじめる

何かを学ぶための最良の方法の 1 つは、例を見ることです。それでは、袖をまくってコーディングを始めましょう。

設定

最初に必要なのは、Gin サーバーを実行することです。誰かに挨拶するものを実装してみましょう。このためには、main.go を作成し、次のコードを追加します:

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
}

ターミナルで go run main.go を実行して、このファイルを実行します。

go mod init example.com/learning

HTTP サーバーが実行されているはずです。http://localhost:8080/hello?person=John を開いて、John に挨拶できます。

? ヒント:
Go および Gin で Air を使用してライブ リロードを実装できます。ファイルが変更されるたびにサーバーが自動的に再起動されるため、自分でこれを行う必要はありません!

バリデーターの追加

サーバーは動作していますが、問題があります。最も注目すべきは、名前が設定されていない人に挨拶したくないということです。
たとえば、http://localhost:8080/hello にアクセスすると、「Hello, 」と表示されます。

そこで ginvalidator が役に立ちます。リクエストを検証するために使用されるバリデーター、サニタイザー、およびモディファイアーを提供します。
個人のクエリ文字列が空であってはいけないことをチェックするバリデーターと修飾子を追加しましょう。バリデーターの名前は Empty 、修飾子の名前は Not:
です。

go get -u github.com/gin-gonic/gin

? 注:

簡潔にするために、コード例では gv が ginvalidator のエイリアスとして使用されています。

次に、サーバーを再起動し、再度 http://localhost:8080/hello にアクセスします。うーん、まだ「Hello, !」と表示されます...なぜですか?

検証エラーの処理

ginvalidator 検証チェーンは、検証エラーをユーザーに自動的に報告しません。
その理由は簡単です。バリデーターを追加したり、フィールドを追加したりするときに、どのようにエラーを収集する必要があるでしょうか。すべてのエラーのリスト (フィールドごとに 1 つだけ、全体で 1 つだけ) が必要ですか...?

次の明らかなステップは、上記のコードを再度変更し、今回は ValidationResult 関数を使用して検証結果を検証することです。

go get -u github.com/bube054/ginvalidator

ここで、http://localhost:8080/hello に再度アクセスすると、わかりやすくするためにフォーマットされた次の JSON コンテンツが表示されます。

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
}

さて、これが私たちに伝えていることは、

• このリクエストには 1 つだけエラーがありました;
• このフィールドは person と呼ばれます;
• クエリ文字列内にあります (場所: "queries");
• 表示されたエラー メッセージは「無効な値」でした。

これはより良いシナリオですが、まだ改善の余地があります。続けてみましょう。

より適切なエラー メッセージの作成

すべてのリクエスト位置バリデータは、オプションの 2 番目の引数を受け入れます。これは、エラー メッセージのフォーマットに使用される関数です。 nil が指定された場合、上記の例に示すように、デフォルトの汎用エラー メッセージが使用されます。

go run main.go

ここで http://localhost:8080/hello に再度アクセスすると、次の JSON コンテンツと新しいエラー メッセージが表示されます。

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()
}

検証/サニタイズされたデータへのアクセス

GetMatchedData を使用すると、ginvalidator が検証および/またはサニタイズしたすべてのデータが自動的に収集されます。このデータは、MatchedData:
の Get メソッドを使用してアクセスできます。

go mod init example.com/learning

http://localhost:8080/hello?person=John を開いて、ジョンに敬意を表します!

使用可能な場所は、BodyLocation、CookieLocation、QueryLocation、ParamLocation、および HeaderLocation です。
これらの各場所には、検証/サニタイズされたデータが保存されている場所を返す String メソッドが含まれています。

入力のサニタイズ

ユーザーは空の人名を送信できなくなりましたが、HTML をページに挿入することはできます。これは、クロスサイト スクリプティングの脆弱性 (XSS) として知られています。
どのように機能するかを見てみましょう。 http://localhost:8080/hello?person=John にアクセスすると、「こんにちは、ジョン!」と表示されるはずです。
この例は問題ありませんが、攻撃者は人物のクエリ文字列を <script> に変更する可能性があります。有害な可能性がある独自の JavaScript をロードするタグ。<br> このシナリオでは、ginvalidator の問題を軽減する 1 つの方法は、サニタイザー、特に特殊な HTML 文字をテキストとして表現できる他の文字に変換する Escape を使用することです。<br> </script>

go get -u github.com/gin-gonic/gin

ここでサーバーを再起動してページを更新すると、「Hello, John!」というメッセージが表示されます。私たちのサンプル ページは XSS に対して脆弱ではなくなりました!

⚠️ 注意:

ginvalidator は、サニタイズ中に http.Request 値を変更しません。サニタイズされたデータにアクセスするには、常に GetMatchedData 関数を使用してください。

検証チェーン

検証チェーンは ginvalidator の主要な概念の 1 つであるため、効果的に使用できるように、検証チェーンについて学習すると役立ちます。

しかし、心配しないでください。入門ガイドを最後まで読んだことがある方は、気付かないうちにすでに検証チェーンを使用していることになります。

検証チェーンとは何ですか?

検証チェーンは次の関数を使用して作成され、それぞれが HTTP リクエスト内の特定の場所をターゲットとします。

• NewBody: http.Request 本文からのデータを検証します。その場所は BodyLocation です。
• NewCookie: http.Request Cookie からのデータを検証します。その場所は CookieLocation です。
• NewHeader: http.Request ヘッダーからのデータを検証します。その場所は HeaderLocation です。
• NewParam: Jin ルート パラメーターからのデータを検証します。その場所は ParamLocation です。
• NewQuery: http.Request クエリ パラメーターからのデータを検証します。その場所は QueryLocation です。

フィールドの値を検証 (またはサニタイズ) でラップし、その各メソッドがそれ自体を返すため、この名前が付けられています。
このパターンは通常メソッド チェーンと呼ばれるため、検証チェーンという名前が付けられています。

検証チェーンには、検証、サニタイズ、変更を定義するための便利なメソッドが多数あるだけでなく、Gin ミドルウェア ハンドラー関数を返す Validate メソッドもあります。

これは、検証チェーンが通常どのように使用されるか、および検証チェーンを読み取る方法の例です。

go mod init example.com/learning

特徴

検証チェーンには、バリデーター、サニタイザー、モディファイアーの 3 種類のメソッドがあります。

バリデータは、リクエストフィールドの値が有効かどうかを判断します。これは、フィールドが期待どおりの形式になっているかどうかを確認することを意味します。たとえば、サインアップ フォームを作成している場合、ユーザー名は電子メール アドレスである必要があり、パスワードは 8 文字以上である必要があるという要件が考えられます。

値が無効な場合は、エラー メッセージを使用してそのフィールドのエラーが記録されます。この検証エラーは、Gin ルート ハンドラーの後の時点で取得され、ユーザーに返されます。

それらは次のとおりです:

• カスタムバリデータ
• が含まれます
• 等しい
• AbaRouting
• その後
• アルファ
• 英数字
• アスキー
• Base32
• Base58
• Base64
• 前
• ビック
• ブール値
• BTCアドレス
• バイト長
• クレジットカード
• 通貨
• データURI
• 日付
• 10 進数
• 割り切れる数
• アン
• メール
• 空
• イーサリアムアドレス
• フロート
• FQDN
• 貨物コンテナID
• 全幅
• 半角
• ハッシュ
• 16 進数
• HexColor
• HSL
• IBAN
• 身分証明書
• IMEI
• で
• 整数
• IP
• IP範囲
• ISIN
• ISO4217
• ISO6346
• ISO6391
• ISO8601
• ISO31661Alpha2
• ISO31661Alpha3
• ISO31661数値
• ISRC
• ISSN
• JSON
• 緯度経度
• ナンバープレート
• ロケール
• 小文字
• ルーン番号
• Macアドレス
• MagnetURI
• MailtoURI
• MD5
• MimeType
• 携帯電話
• MongoID
• マルチバイト
• 数値
• 8 進数
• パスポート番号
• ポート
• 郵便番号
• RFC3339
• RgbColor
• SemVer
• ナメクジ
• 強力なパスワード
• 納税者番号
• サロゲートペア
• 時間
• ユリド
• 大文字
• URL
• UUID
• 変数幅
• 付加価値税
• ホワイトリストに登録されました
• 一致

サニタイザーはフィールド値を変換します。これらは値からノイズを除去するのに役立ち、場合によっては脅威に対する基本的な防御線を提供することにも役立ちます。

サニタイザーは、更新されたフィールド値を Gin コンテキストに保持して戻すため、他の ginvalidator 関数、独自のルート ハンドラー コード、さらには他のミドルウェアでも使用できるようになります。

それらは次のとおりです:

• カスタムサニタイザー
• ブラックリスト
• 逃げる
• LTrim
• メールを正規化する
• RTrim
• ストリップロー
• ToBoolean
• 今日まで
• フロート
• ToInt
• トリム
• 脱出
• ホワイトリスト

修飾子は、検証チェーンの実行時の動作を定義します。

それらは次のとおりです:

• 保釈金
• 場合
• そうではありません
• スキップ
• オプション

? 注:

これらのメソッドは、pkg.go.dev ginvalidator ドキュメント内の GoDoc を使用して詳細に文書化されています。詳細が不明な場合は、追加のコンテキストについて、validatorgo パッケージ内の関連関数を参照することもできます。これについては、以下で説明します。

標準バリデーター/サニタイザー

検証チェーンによって公開されるすべての機能は、実際には、文字列の検証/サニテーションに特化した、私の他のオープンソース go パッケージの 1 つである validatorgo から来ています。ぜひチェックして、スターを付けてシェアしてください???、ありがとうございます。

これには、一般的に使用される IsEmail、IsLength、Trim からよりニッチな IsISBN、IsMultibyte、StripLow まで、validatorgo バリデーターとサニタイザーがすべて含まれます!

これらは、ginvalidator では標準バリデーターおよび標準サニタイザーと呼ばれます。ただし、validatorgo の Is プレフィックスはありません。

連鎖順序

通常、検証チェーンでメソッドを呼び出す順序が重要です。
これらはほとんどの場合、指定された順序で実行されるため、最初にチェーンされたメソッドから最後まで、その定義を読むだけで、検証チェーンが何を行うかを知ることができます。

次のスニペットを例として挙げます:

go mod init example.com/learning

この場合、ユーザーが空白のみで構成される「search_query」値を渡した場合、値は空にならないため、検証は合格します。しかし、.Trim() サニタイザーがあるため、空白が削除され、フィールドが空になるため、実際には誤検知が発生します。

次に、以下のスニペットと比較してください:

go get -u github.com/gin-gonic/gin

このチェーンは、より賢明に空白を削除し、値が空でないかどうかを検証します。

このルールの 1 つの例外は .Optional() です。これはチェーン内の任意の点に配置でき、チェーンをオプションとしてマークします。

検証チェーンの再利用

同じチェーンを再利用したい場合は、関数からそれらを返すことをお勧めします。

go get -u github.com/bube054/ginvalidator

フィールドの選択

ginvalidator では、フィールドは検証またはサニタイズされた任意の値であり、文字列です。

ginvalidator によって返されるほぼすべての関数または値は、何らかの方法でフィールドを参照します。このため、検証するフィールドを選択するときと、検証エラーまたは検証されたデータにアクセスするときの両方において、フィールド パス構文を理解することが重要です。

構文

• 本文フィールド は、次の Content-Type に対してのみ有効です:

  • application/json: これは、値の抽出に GJSON パス構文を使用します。詳細については、リンク先のドキュメントを参照してください。
  • 例:

  go mod init example.com/learning
  

  パス user.name の場合、抽出される値は「John」になります。

  • application/x-www-form-urlencoded: 通常、HTML フォームの送信に使用されます。フィールドは、本文内のキーと値のペアとして送信されます。
  • 例:

  go get -u github.com/gin-gonic/gin
  

  本体:
  

  go get -u github.com/bube054/ginvalidator
  

  フィールド「name」の値は「John」となり、「email」の値は「john.doe@example.com」になります。

  • multipart/form-data: ファイルのアップロードまたはファイルとともにフォーム データを送信する場合に一般的に使用されます。
  • 例:

  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
  }
  

  本体:
  

  go run main.go
  

  フィールド「name」の値は「John」となり、「file」はアップロードされたファイルになります。

• クエリ フィールド は URL 検索パラメータに対応し、それらの値は、Gin によって自動的に URL エスケープ解除されます。
  
  例:

  • フィールド: "名前"、値: "ジョン"

  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()
  }
  

  • フィールド: "full_name"、値: "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 フィールド は URL パス パラメーターを表し、その値は ginvalidator によって自動的にエスケープ解除されます。
  
  例:

  • フィールド: "id"、値: "123"

  {
    "errors": [
      {
        "location": "queries",
        "message": "Invalid value",
        "field": "person",
        "value": ""
      }
    ]
  }
  

• ヘッダー フィールド は HTTP リクエスト ヘッダーであり、その値はエスケープ解除されていません。非正規のヘッダー キーを指定すると、ログ警告が表示されます。
  
  例:

  • フィールド: "ユーザーエージェント"、値: "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()
  }
  

• Cookie フィールド は HTTP Cookie であり、その値は、Gin によって自動的にエスケープ解除された URL になります。
  
  例:

  • フィールド: "session_id"、値: "abc 123"

  {
    "errors": [
      {
        "location": "queries",
        "message": "Please enter your name.",
        "field": "person",
        "value": ""
      }
    ]
  }
  

Express-Validator のカスタマイズ

構築しているサーバーが非常に単純なものではない場合、遅かれ早かれ ginvalidator に組み込まれているもの以外のバリデーター、サニタイザー、およびエラー メッセージが必要になります。

カスタムバリデーターとサニタイザー

ginvalidator では満たすことができず、遭遇する可能性がある典型的なニーズは、ユーザーのサインアップ時に電子メール アドレスが使用されているかどうかを検証することです。

カスタムバリデーターを実装することで、ginvalidator でこれを行うことができます。

CustomValidator は検証チェーンで使用できるメソッドで、特別な関数 CustomValidatorFunc を受け取り、フィールドが有効かどうかを決定するブール値を返す必要があります。

CustomSanitizer は検証チェーンで使用できるメソッドでもあり、特別な関数 CustomSanitizerFunc を受け取り、新しいサニタイズされた値を返す必要があります。

カスタムバリデーターの実装

CustomValidator は、ゴルーチンと sync.WaitGroup を使用して同時操作を処理することで非同期にすることができます。バリデーター内で、各非同期タスクのゴルーチンをスピンアップし、各タスクを WaitGroup に追加できます。すべてのタスクが完了すると、バリデーターはブール値を返す必要があります。

たとえば、電子メールが使用されていないことを確認するには:

go mod init example.com/learning

または、パスワードが繰り返しと一致することを確認することもできます:

go get -u github.com/gin-gonic/gin

⚠️ 注意:
同じ検証チェーン内、同じリクエスト コンテキストの別の検証チェーン内、または後続のハンドラー内でリクエスト本文に複数回アクセスする場合は、読み取りのたびに必ずリクエスト本文をリセットしてください。そうしないと、本文を再度読み取るときにエラーやデータの欠落が発生する可能性があります。

カスタムサニタイザーの実装

CustomSanitizer には多くのルールはありません。返される値が何であれ、フィールドが取得する新しい値です。
カスタム サニタイザーは、ゴルーチンと sync.WaitGroup を使用して同時操作を処理することで非同期にすることもできます。

go get -u github.com/bube054/ginvalidator

エラーメッセージ

フィールド値が無効な場合は常に、エラー メッセージが記録されます。
デフォルトのエラー メッセージは「値が無効です」ですが、これではエラーの内容がまったく説明されていないため、カスタマイズが必要になる場合があります。
でカスタマイズできます

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 は、リクエストから抽出された元の値 (サニタイズ前) です。
• sanitizedValue は、サニタイズされた後の値です (該当する場合)。
• validatorName は失敗したバリデーターの名前であり、合格しなかった検証ルールを識別するのに役立ちます。

バリデーター名の完全なリストについては、ginvalidator 定数を参照してください。

メンテナー

• bube054 - Attah Gbubemi David (著者)

以上がginvalidator を使用して Go での Jin 入力検証を簡素化するの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。