@Pattern に正規表現を書いたのに、通るはずの値が弾かれる。かと思えば null や空文字はあっさり通ってしまう。入力チェックを書いていると、一度はハマるところですよね。

この記事では Spring Boot 3.x(jakarta.validation.constraints.Pattern)を前提に、@Pattern だけを扱います。regexp の書き方、null の扱い、flags と message、そのまま使えるパターン集、テストでの確かめ方まで見ていきます。他の標準アノテーションも含めて全体を眺めたい場合は、バリデーションアノテーションの早見表 を見てください。

まずは最小構成で動かす

依存は spring-boot-starter-validation を追加します。Hibernate Validator と Jakarta EL の実装もこれで入ります。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

DTO のフィールドに @Pattern を付けて、Controller 側には @Valid を付けます。import するのは javax ではなく jakarta のほうです。

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Pattern;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

public record UserRequest(
        @NotBlank
        @Pattern(regexp = "\\d{3}-\\d{4}", message = "郵便番号は123-4567の形式で入力してください")
        String zipCode) {
}

@RestController
@RequestMapping("/users")
class UserController {

    @PostMapping
    ResponseEntity<Void> create(@Valid @RequestBody UserRequest request) {
        return ResponseEntity.ok().build();
    }
}

形式が合わないと MethodArgumentNotValidException が投げられて、デフォルトでは 400 Bad Request が返ります。@Valid 自体の仕組みは @Validでバリデーションを実装する方法 で詳しく書いています。以降のコードでは、主要なもの以外の import は省略します。

regexpは文字列全体にマッチする

いちばん誤解されやすいのがここです。Hibernate Validator の PatternValidator は内部で Matcher.matches() を呼んで判定するので、regexp は部分一致ではなく全体一致で評価されます。

@Pattern(regexp = "\\d{3}-\\d{4}")    // "123-4567" は OK、"〒123-4567" は NG
@Pattern(regexp = "^\\d{3}-\\d{4}$")  // 上と同じ挙動。^ と $ は不要だが付けても害はない
@Pattern(regexp = ".*admin.*")        // 「admin を含む」にしたいなら前後を .* で囲む

find() のつもりで admin とだけ書くと、ちょうど “admin” という文字列しか通りません。

もう1つの落とし穴はエスケープです。Java の文字列リテラルなので、正規表現の \d は "\\d"、\. は "\\." と書きます。"\d" ならコンパイルエラーになるので気づけます。厄介なのは \\. のつもりで . とだけ書いたケースで、「任意の1文字」としてエラーなく想定外の値が通ってしまいます。

また、アノテーションの属性値はコンパイル時定数でなければいけません。public static final String の定数にまとめておくと、再利用しやすく読みやすくなります(後述のパターン集でもそうしています)。

nullは通る、空文字はパターン次第

Bean Validation の仕様では、@Pattern は null を「有効」とみなします。null のチェックは @NotNull など別の制約が担当する、という考え方です。

一方で、空文字 "" は普通に正規表現で判定されます。\d{3}-\d{4} なら弾かれますが、[a-z]* のように0文字を許すパターンだと通ってしまいます。

なので、必須項目には @NotBlank を併用するのが基本です。この場合、空文字を送ると @NotBlank と @Pattern の両方に違反するので、エラーメッセージが2つ返る点は覚えておきましょう。

任意項目で「空なら OK、入力があれば形式をチェック」にしたいときは、空文字を選択肢に加えます。

// null は仕様上どのみち通る。^$| を付けると空文字 "" も通るようになる
@Pattern(regexp = "^$|0\\d{9,10}")
String phone;

flags属性とインラインフラグ

大文字と小文字を区別しないなら flags を指定します。複数指定する場合は配列で書きます。

@Pattern(regexp = "[a-z]+", flags = Pattern.Flag.CASE_INSENSITIVE)
String code;

@Pattern(regexp = "[a-z]+",
        flags = {Pattern.Flag.CASE_INSENSITIVE, Pattern.Flag.UNICODE_CASE})
String code2;

// インラインフラグでも同じことができる。一部だけに効かせるなら (?i:...) の形
@Pattern(regexp = "ABC-(?i:[a-z]+)")
String code3;

よく使うフラグはこのあたりです。

フラグ意味
CASE_INSENSITIVE大文字と小文字を区別しない(単独では ASCII のみが対象)
UNICODE_CASE全角英字なども大文字小文字の無視の対象にする(CASE_INSENSITIVE と併用したときだけ効く)
COMMENTSパターン内の空白と # 以降を無視する
DOTALL. が改行にもマッチする

ちなみに Pattern.Flag には UNICODE_CHARACTER_CLASS に相当する値がありません。必要なときはインラインで (?U) と書きます。

message属性でエラーメッセージを指定する

既定のメッセージには {regexp} が埋め込まれていて、利用者に正規表現がそのまま見えてしまいます。画面や API のレスポンスで返すなら、message は指定しておきたいところです。

{regexp} のように波括弧で属性名を書くと、その値に置き換わります。キーを書いておけば、クラスパス直下の ValidationMessages.properties から文言を引けます。

@Pattern(regexp = Regexps.PHONE, message = "{user.phone.pattern}")
String phone;
# src/main/resources/ValidationMessages.properties
user.phone.pattern=電話番号はハイフンなしの半角数字10〜11桁で入力してください
# 開発者向けのメッセージなら属性値の埋め込みも便利
debug.pattern=値が {regexp} に一致しません

Java 9 以降は properties のリソースバンドルを UTF-8 で読むので、日本語をそのまま書いて大丈夫です。

なお Spring Boot 3.x では、アプリの messages.properties(MessageSource)からもキーが引かれ、同じキーがあればそちらが優先されます。どちらか一方にまとめておくと迷いません。エラーを統一形式の JSON で返す方法は、@RestControllerAdviceで統一的なエラーレスポンスを返す方法 にまとめています。

実用的な正規表現パターン集

ここからはコピーして使えるパターンです。定数クラスにまとめておきます。なお、メールアドレスは自前の正規表現を書かずに @Email を使いましょう。

public final class Regexps {
    // 電話番号(ハイフンなし)
    public static final String PHONE = "0\\d{9,10}";
    // 電話番号(ハイフンあり)
    public static final String PHONE_HYPHEN = "0\\d{1,4}-\\d{1,4}-\\d{4}";
    // 郵便番号(ハイフン任意)
    public static final String ZIP_CODE = "\\d{3}-?\\d{4}";
    // 半角英数字のみ
    public static final String ALNUM = "[a-zA-Z0-9]+";
    // 全角カタカナ(長音記号・中黒を含む)
    public static final String KATAKANA = "[\\u30A0-\\u30FF]+";
    // 英大文字・英小文字・数字・記号を各1文字以上。使える文字は ASCII の印字可能文字だけ
    public static final String PASSWORD =
            "(?=.*[A-Z])(?=.*[a-z])(?=.*\\d)(?=.*[!-/:-@\\[-`{-~])[!-~]*";

    private Regexps() {}
}
パターン通る値弾かれる値
PHONE0312345678、09012345678090-1234-5678、9012345678
PHONE_HYPHEN03-1234-5678、090-1234-567809012345678、03-1234-567
ZIP_CODE123-4567、1234567123-456、123-4567
ALNUMabc123abc_123、abc
KATAKANAスズキ、ジョン・スミスすずき、スズキ
PASSWORDPassw0rd!password1、Passw0rd

電話番号でハイフンの有無をどちらも許すなら、PHONE + "|" + PHONE_HYPHEN とつなげれば済みます。ただ個人的には、保存前にハイフンを取り除いて正規化し、ハイフンなしの形式だけを検証するほうが後々楽だと思います。PHONE_HYPHEN は市外局番の桁数までは見ていないので、“01-2-3456” のような値も通ります。そこまで厳密に見たいなら、カスタム制約や専用ライブラリの出番です。

カタカナの範囲 \u30A0-\u30FF には、長音記号「ー」と中黒「・」も含まれます。半角カナ(\uFF65-\uFF9F)は入っていないので、受け付けるかどうかは仕様として決めておきましょう。

パスワードの (?=.*[A-Z]) は「どこかに英大文字が1文字ある」ことだけを確かめる、文字を消費しない先読みです。これを文字種ごとに並べ、最後の [!-~]* で使える文字を制限しています。長さは正規表現で書かずに @Size に任せるのがおすすめです。ルールごとに別のメッセージを出したいなら、@Pattern を複数付けることもできます。

@NotBlank
@Size(min = 8, max = 64)
@Pattern(regexp = ".*[A-Z].*", message = "英大文字を1文字以上含めてください")
@Pattern(regexp = ".*\\d.*", message = "数字を1文字以上含めてください")
String password;

@ParameterizedTestでOK値とNG値をまとめて検証する

正規表現は、書いた本人が思っているとおりに動くとは限りません。Spring コンテキストを使わずに Validator を直接呼べば、テストを高速に回せます。

import static org.assertj.core.api.Assertions.assertThat;

import jakarta.validation.Validation;
import jakarta.validation.Validator;
import jakarta.validation.constraints.Pattern;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.junit.jupiter.params.provider.ValueSource;

class PhonePatternTest {

    record Form(@Pattern(regexp = "^$|" + Regexps.PHONE) String phone) {}

    private static Validator validator;

    @BeforeAll
    static void setUp() {
        validator = Validation.buildDefaultValidatorFactory().getValidator();
    }

    @ParameterizedTest
    @ValueSource(strings = {"0312345678", "09012345678", ""})
    void 通る値(String phone) {
        assertThat(validator.validateProperty(new Form(phone), "phone")).isEmpty();
    }

    @ParameterizedTest
    @CsvSource({
            "090-1234-5678, ハイフンあり",
            "9012345678, 先頭が0でない",
            "012345678, 桁不足",
            "09012345678, 全角数字"
    })
    void 弾かれる値(String phone, String reason) {
        assertThat(validator.validateProperty(new Form(phone), "phone"))
                .as(reason).isNotEmpty();
    }

    @Test
    void nullは通る() {
        assertThat(validator.validateProperty(new Form(null), "phone")).isEmpty();
    }
}

spring-boot-starter-validation が入っていれば、テストのクラスパスにも Hibernate Validator と EL 実装がそろうので、このまま動きます。validateProperty で対象のフィールドだけを検証でき、null と空文字のケースも入れておけば本文の挙動をそのまま確かめられます。@CsvSource の使い方は JUnit 5の基本と@ParameterizedTest も参考にしてください。

日本語入力で起きやすい落とし穴

Java の \d は、既定では ASCII の 0-9 にしかマッチしません。上のテストのとおり、全角数字は弾かれます((?U) を付けると全角数字もマッチするようになります)。

もう1つよくあるのが、見た目の似た文字です。全角ハイフン「-」やマイナス記号「−」、長音記号「ー」が混ざると、ハイフンありのパターンで弾かれてしまいます。

全角での入力も受け付けたいなら、検証の前に Normalizer.normalize(value, Normalizer.Form.NFKC) で正規化しておくのが手軽です。全角数字や全角ハイフンは半角になりますが、長音記号やマイナス記号は変換されないので、別途置き換えが必要です。

壊滅的バックトラック(ReDoS)を避ける

@Pattern はリクエストの値をそのまま正規表現にかけるので、パターンによっては細工された入力で CPU を占有されてしまいます。

// 危険:繰り返しの中の選択肢どうしが同じ文字にマッチする
// "aaaa...a!" のような入力でバックトラックが爆発し得る
"(a|aa)+"
"(\\w|\\d)+"

// 安全:選択肢が重ならないように書き直す
"a+"
"\\w+"

JDK 9 以降は (a+)+ のような典型的な入れ子に最適化が入っていて、すぐ終わる場合もあります。ただ、選択肢が重なるパターンや複雑な入れ子は今でも危険になり得るので、量指定子を入れ子にしない、選択肢どうしを重ねない、を基本にしておきましょう。

注意したいのは @Size の扱いです。@Size を付けても、それだけでは @Pattern の評価は止まりません。Default グループではすべての制約が評価されるので、長すぎる入力にもそのまま正規表現が走ります。長さチェックを先に通したいなら、@GroupSequenceで実行順序を制御する方法 で順序を固定するか、リクエストサイズ自体を制限しておきましょう。グループの基本は @Validatedでグループ別バリデーションを実装する方法 にまとめています。

@Patternで書くか、カスタム制約にするか

判断の目安はシンプルです。

  • 1つのフィールドで完結し、形式だけを見るチェックなら @Pattern
  • 複数フィールドの相関チェック、DB の参照、チェックディジットの計算などロジックを伴うものはカスタム制約
  • 同じ @Pattern と message の組み合わせをあちこちに書いているなら、アノテーションにまとめどき

3つ目のケースは、ConstraintValidator を書かなくても既存の制約を束ねるだけで済みます。これを合成制約と呼びます。

@NotBlank
@Pattern(regexp = Regexps.PHONE)
@ReportAsSingleViolation
@Constraint(validatedBy = {})
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface PhoneNumber {
    String message() default "{user.phone.pattern}";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

@ReportAsSingleViolation を付けると、中のどれに違反してもメッセージは @PhoneNumber のもの1つにまとまります。さきほどの「エラーが2つ返る」問題もこれで解消できます。ロジックを伴う本格的なカスタム制約の作り方は、カスタムバリデーションアノテーションを作る方法 で紹介しています。

まとめ

  • regexp は matches() による全体一致なので、^ と $ は不要です。部分一致にしたいなら .* で囲みます
  • Java の文字列なので \\d のようにエスケープします。パターンは定数にまとめておくと便利です
  • null は仕様上通るので、必須項目には @NotBlank を併用します。任意項目で空文字も許すなら ^$|... の形にします
  • flags や (?i)、message と ValidationMessages.properties で挙動と文言を調整できます
  • 長さは @Size に任せ、正規表現は形式のチェックだけに絞ります。ReDoS 対策で長さを先に見るなら順序の固定が必要です

正規表現は、通る値と弾かれる値をテストに並べておくと安心です。まずは手元のパターンを1つ、@ParameterizedTest で確かめてみてください。