NGINXおよびNGINX Plus向け正規表現テスター

NGINX | 2019年6月11日

Rick Nelsonソリューションエンジニアリング担当リージョナルバイスプレジデント

NGINXで使用する正規表現（regex）を作成していたとき、実際のNGINX設定内から正規表現を簡単にテストする方法を思いつきました。（この正規表現テスターは、NGINX Open SourceとNGINX Plusのどちらでも同じように機能します。読みやすくするため、この記事では単に「NGINX」と表記します。）

正規表現のサポートはNGINXの強力な機能の1つですが、正規表現は複雑で、特に日常的に扱っていない場合は正しく記述するのが困難です。NGINXでは、location、map、rewrite、サーバー名など、設定の複数の箇所で正規表現を使用できます。ここで説明するテスターは、locationとmapで使用する正規表現を対象としています。

ほとんどの正規表現に対応できる無料のオンライン正規表現テスターはほかにもありますが、NGINXではWebアプリケーション向けに最適化された、標準とは異なる省略記法がいくつか使用されています。たとえば、標準的な正規表現とは異なり、URI内のスラッシュ（/）をエスケープする必要はありません。また、mapで正規表現を使用する場合は、一致した内容に基づいて設定する値を指定します。ほかの正規表現テスターでは、正規表現を変更したり、mapの場合は設定される値を推測したりする必要が生じることがあります。さらに、実際の環境で実際の正規表現エンジンを使用して正規表現をテストできることも重要です。

注：

NGINXでは、Perl互換正規表現（PCRE）を使用します。この記事は、NGINXと正規表現の両方について基本的な知識があることを前提としています。正規表現の作成方法についての説明はこの記事の範囲外であり、コメント欄での追加のご質問には回答できません。正規表現の作成に役立つツールやドキュメントを提供するWebサイトは数多くあります。F5が有用だと考えるサイトを2つご紹介します。
- regex101.com
- Regular-expressions.info
このテスターは、正規表現を2つのコンテキスト（map{}ブロックとHTTP location{}ブロック）で処理します。以下では、それぞれのコンテキストで正規表現がどのように機能するかを簡単に説明します。NGINXがすべてのコンテキストで正規表現を処理する仕組みについては、この記事では扱いません。詳しくは、ドキュメントをご覧ください：
- ヘルスチェック：
  - HTTP – nginx.orgおよびNGINX Plus管理者ガイド
  - TCP – nginx.orgおよびNGINX Plus管理者ガイド
  - UDP – nginx.orgおよびNGINX Plus管理者ガイド
- location{}ブロック – nginx.orgおよびNGINX Plus管理者ガイド
- map{}ブロック – nginx.org
- URIの書き換え – nginx.orgおよびNGINX Plus管理者ガイド
- 仮想サーバー名 – nginx.orgおよびNGINX Plus管理者ガイド
このテスターは、可能な限りシンプルにし、ユーザーが記述した正規表現を、mapおよびHTTP location用の実際のNGINX正規表現エンジンでテストするという1つの目的に特化して設計されています。そのため、動作するNGINX設定を作成するために必要な情報は最小限で済みます。シンプルさという基本原則に反するため、テスト前の正規表現の検証などの機能を追加する予定はありません。もちろん、バグには対応します。報告するには、Issuesタブ（GitHubリポジトリ）をご利用ください。

概要

正規表現テスターの詳細に入る前に、まずNGINXのlocationとmapで正規表現を使用する方法について説明します。

ロケーション

NGINXのlocation{}ブロックで使用する正規表現は、次の形式です。

location regex {
    #...
}

たとえば、次の正規表現を指定したlocation{}ブロックは、URIの末尾がmyapp/filename.phpとなるすべてのPHPリクエストを処理します。たとえば、/test/myapp/hello.phpや/myapp/hello.phpなどです。チルダの後のアスタリスク（~*）により、大文字と小文字を区別せずに照合されます。

location ~* /myapp/.+\.php$ {
    #...
}

NGINXと正規表現テスターは、キャプチャグループの位置指定をlocation{}ブロック内でサポートしています。次の例では、最初のグループがPHPファイル名より前のすべてをキャプチャし、2番目のグループがPHPファイル名をキャプチャします。

location ~* (.*/myapp)/(.+\.php)$ {
    #...
}

URI /myapp/hello.phpの場合、変数$1には/myappが設定され、$2にはhello.phpが設定されます。

NGINXは名前付きキャプチャグループにも対応しています。

location ~* (?<begin>.*myapp)/(?<end>.+\.php)$ {
    #...
}

この場合、変数「$begin」には「/myapp」が設定され、変数「$end」には「hello.php」が設定されます。

正規表現テスターは名前付きキャプチャグループをサポートしていますが、出力では位置指定キャプチャグループとして扱い、名前ではなく通し番号を表示します。

マップ

NGINXの正規表現を使用するmap{}ブロックは、次の形式です。

map variable-to-test variable-to-set {
    regex1 value-to-set-if-match;
    regex2 value-to-set-if-match;
    #...
    regexN value-to-set-if-match;
    default value-to-set-if-no-match;
}

たとえば、この「map{}」ブロックは、URI（変数「$isphp」に記録）が「1」で終わる場合、変数「$uri」を「.php」に設定し、そうでない場合は「0」に設定します（大文字と小文字は区別されます）。

map $uri $isphp {
    ~\.php$ 1;
    default 0;
}

mapでは、NGINXと正規表現テスターの両方が、位置指定キャプチャグループと名前付きキャプチャグループをサポートしています。

たとえば、次のどちらのmapでも、変数「$fileext」にファイル拡張子の値を設定します。この例では、この値は「$1」としてもキャプチャされます。

map $uri $fileext {
    ~*.+\.(.+)$  $1;
    default      '';
}

この例では、$extとして使用します。

map $uri $fileext {
    ~*.+\.(?<ext>.+)$  $ext;
    default            '';
}

正規表現テスターは、map{}ブロックがどちらのコンテキストでも同じ構文と動作を使用するため、http{}とstream{}の両方のコンテキストで使用できます。ただし、マップがstream{}コンテキストにある場合、テスターの出力のうち使用できるのはmap{}ブロックのみです。詳しくは、以下の注記を参照してください。

正規表現テスター

正規表現テスターは、NGINXとNGINX UnitをインストールしたDockerコンテナに実装されています。NGINX Unitは2種類のPHPページを提供します。一方はlocation{}ブロック内の正規表現用、もう一方はmap{}ブロック内の正規表現用です。各ページでは、それぞれ異なる入力を求められます。

Locationページ：
- 正規表現
- 大文字と小文字の区別
- URI
マップページ：
- 正規表現
- 大文字と小文字の区別
- テストする値（mapディレクティブの第1パラメーターである変数の値）
- The value to set in the variable specified as the second parameter to the mapディレクティブの第2パラメーターとして指定された変数に設定する値

情報を入力したら、［Test］ボタンをクリックします。テスターによって必要なNGINX設定ファイルが生成され、設定が再読み込みされた後、正規表現をテストするためのリクエストが送信されます。続いて結果が表示され、一致が見つかったかどうかを確認できます。一致した場合、［Location Tester］ページにはキャプチャグループの値が表示され、［Map Tester］ページにはmapによって設定された値が表示されます。

Locationページの例

この例は、正規表現「(.*myapp)/(.+\.php)$」をURI「/myapp/hello.php」に対して大文字と小文字を区別せずにテストした結果を示しています：

マップページの例

この例では、正規表現「.+\.(?<ext>.*)$」を値「/myapp/hello.php」に対して大文字と小文字を区別せずにテストし、名前付きキャプチャグループ「$ext」を設定する値として使用した結果を示します。

注：マップがstream{}コンテキストにある場合、出力のうち構成で使用できるのはmap{}ブロックのみです。server{}ブロックには、location{}ブロックが含まれています。このブロックはstream{}コンテキストではサポートされていないため、server{}ブロックは無効です。