この記事でわかること
@NotEmptyでは半角スペースだけの氏名が通ります。同じnameに7種類の入力を送り、3つの制約の違いを400/200で比較。全角空白とNBSPはProviderの版を固定して確かめ、拒否する仕様をコードとテストへ落とします。
会員登録APIの氏名を必須にしたつもりで、@NotEmptyを付けた。それでも{"name":" "}を送ると200になる。このときは、検証が動いていないと決める前に、空文字と空白だけの文字列を分けて見ます。
この例の仕様は「氏名に空白以外の文字を1つ以上含める」です。既存の3制約がどこまで拒否するかを比べ、最後に全角空白とNBSPも含めた仕様へ揃えます。
テスト対象・テストコード・実POSTの仕様表を全文で取得
JDK 17とMaven 3.9系。Controller、DTO、独自制約、エラー応答、JUnit、7入力のJSON、pom.xml、README、実HTTP確認用スクリプトを同梱します。DB・認証・外部APIは使いません。
@NotEmptyでも、半角スペースだけなら200になる
まず、配布JARを起動して次のPOSTを送ります。nameは空文字ではなく、半角スペース1文字です。
curl -i -X POST http://127.0.0.1:18087/validation/not-empty \
-H 'Content-Type: application/json' --data '{"name":" "}'このサンプルの応答は200で、本文は{"name":" "}です。@NotEmptyはnullと長さ0を拒否します。長さ1のスペースは空ではないため、この制約では拒否しません。
URLだけを/validation/not-blankへ変え、同じJSONを送ると400です。送信値を変えずに比べると、Controllerへ届いたかの問題と、制約が許す値の問題を混同せずに済みます。入力値の前後を先に削ってから試すと、もとの違いが見えなくなります。
{"errors":[{"field":"name","constraint":"NotBlank","message":"氏名を入力してください"}]}ここで確認するのはREST APIの400/200です。フォーム画面を戻り値のView名で再表示するMVCの例とは、応答の契約を分けます。
同じnameを7通り送ると、拒否する範囲が分かる
表の値はJSONのnameへ送る値です。「欠落」は本文そのものがない要求ではなく、空のJSONオブジェクト{}を送るケースです。このrecordと既定のJackson設定では、項目の欠落と明示的なnullはいずれもDTOのname == nullになります。
| nameへの入力 | @NotNull | @NotEmpty | @NotBlank | 修正後 @RequiredName |
|---|---|---|---|---|
{}(nameなし) | 400(拒否) | 400(拒否) | 400(拒否) | 400(拒否) |
{"name":null} | 400(拒否) | 400(拒否) | 400(拒否) | 400(拒否) |
"" | 200(受付) | 400(拒否) | 400(拒否) | 400(拒否) |
" "(U+0020) | 200(受付) | 200(受付) | 400(拒否) | 400(拒否) |
"\u3000"(全角空白) | 200(受付) | 200(受付) | 200(受付) | 400(拒否) |
"\u00A0"(NBSP) | 200(受付) | 200(受付) | 200(受付) | 400(拒否) |
"山田" | 200(受付) | 200(受付) | 200(受付) | 200(受付) |
実測環境はJava 17、Spring Boot 3.5.16、Hibernate Validator 8.0.3.Finalです。標準3制約の21ケースと、修正後7ケースを、原本JARとZIP展開版JARへ実際にPOSTしました。後述のテストも、同じinput-cases.jsonを読みます。
特に注意したいのは全角空白とNBSPの行です。この環境の@NotBlankでも200でした。「NotBlankなら見た目が空白の文字をすべて拒否する」とはせず、使っている実装と版で結果を確認します。
3つの制約は、拒否したい入力から選ぶ
@NotNullを選ぶのは、値が存在することを求め、空文字は許す契約です。空文字を未入力として拒否する仕様には足りません。@NotEmptyはStringなら長さ0も拒否しますが、半角スペースだけでも長さは1です。
@NotBlankは文字列の空白判定まで行う制約です。今回の版ではnull・空文字・半角空白だけの入力を拒否しました。ただし、どの文字を空白として扱ったかは上の表で照合します。氏名の仕様が全角空白やNBSPも拒否するなら、その行も400になる修正が必要です。
次の3つはNameConstraintController.javaからDTOだけを抜いたものです。項目名と型を同じにし、制約だけを変えています。
public record NotNullName(
@NotNull(message = "氏名を入力してください") String name) {}
public record NotEmptyName(
@NotEmpty(message = "氏名を入力してください") String name) {}
public record NotBlankName(
@NotBlank(message = "氏名を入力してください") String name) {}@NotEmptyはCollection・Map・配列の要素数にも使えますが、この比較表はStringが対象です。リストが空でないことと、各要素の文字列が空でないことは別の条件です。制約名だけをそろえる前に、何の型の、どの状態を拒否するのかを決めます。
また、@Validはこれらの制約をたどって検証するための指定です。@Valid自体に「氏名は必須」という条件はありません。受け取るDTOに何も制約がなければ、必須項目の仕様は表せません。
全角空白とNBSPは、Providerの版を固定して確認する
Jakarta Validationのアノテーションは検証の宣言で、実際に判定する実装がProviderです。このサンプルはHibernate Validator 8.0.3.Finalに固定しています。依存を確認せず、別の環境の結果表をそのまま採用しないようにします。
この版のNotBlankValidatorは、nullでない値についてtrim().length() > 0で判定します。全角空白U+3000とNBSP U+00A0は、このtrim()で消えず、長さが残ります。表の200は、検証を呼び忘れた結果ではありません。同じエンドポイントで空文字・半角空白が400になることも確認しています。
Java 17のString.isBlank()と、この版の@NotBlankを同一の判定として扱わないでください。全角空白の扱いは異なります。また、NBSPを拒否する契約までisBlank()だけで満たせるとは限りません。次の修正では、業務で拒否する文字の範囲をコードへ明示します。
依存の版を上げる場合も、単に最新へ変えて終わりにせず、同じ7入力を流して差を確認します。ここで固定しているのは記事の再現条件であり、既存案件のProviderを一律に置き換える指示ではありません。
全角空白とNBSPも拒否する仕様を、RequiredNameへ固定する
この氏名欄では、null、空文字、JavaのCharacter.isWhitespaceまたはCharacter.isSpaceCharがtrueになる文字だけの値を拒否します。この条件なら全角空白とNBSPも拒否対象です。空白以外の文字を1つでも含むかを判定し、受け取った文字列そのものは変更しません。
src/main/java/info/syachiku/constraints/RequiredNameValidator.javaの全文です。
package info.syachiku.constraints;
import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;
public class RequiredNameValidator implements ConstraintValidator<RequiredName, String> {
@Override
public boolean isValid(String value, ConstraintValidatorContext context) {
if (value == null) {
return false;
}
// 業務仕様: Javaが空白またはスペースと判定する文字だけの氏名は受け付けない。
// 値の前後や途中にある空白を削除する処理ではない。
return value.codePoints().anyMatch(codePoint ->
!Character.isWhitespace(codePoint) && !Character.isSpaceChar(codePoint));
}
}nullは最初に拒否します。空文字ではanyMatchがfalseになり、空白だけの場合もfalseです。文字を含む" 山 田 "はtrueになります。前後や途中の空白を削るかどうかは別の保存仕様なので、このValidatorには混ぜません。
Validatorを作るだけではDTOに適用されません。次のアノテーションで対応付け、DTOのnameへ@RequiredNameを付けます。命名を氏名の仕様に寄せておくと、後から別の項目へ使い回す際にも、同じ入力契約でよいかを確認できます。
RequiredName.javaの全文
package info.syachiku.constraints;
import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER,
ElementType.ANNOTATION_TYPE, ElementType.TYPE_USE, ElementType.RECORD_COMPONENT})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = RequiredNameValidator.class)
public @interface RequiredName {
String message() default "氏名には空白以外の文字を入力してください";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}ControllerのrequiredName()が修正後の入口です。比較用の3つも同じクラスにあり、いずれも@Valid @RequestBodyでJSONを受け取ります。4つを本番APIへ追加するための例ではなく、同じ入力で条件の違いを観察するために分けています。
NameConstraintController.javaの全文
package info.syachiku.constraints;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.NotNull;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/validation")
public class NameConstraintController {
@PostMapping("/not-null")
public AcceptedName notNull(@Valid @RequestBody NotNullName request) {
return new AcceptedName(request.name());
}
@PostMapping("/not-empty")
public AcceptedName notEmpty(@Valid @RequestBody NotEmptyName request) {
return new AcceptedName(request.name());
}
@PostMapping("/not-blank")
public AcceptedName notBlank(@Valid @RequestBody NotBlankName request) {
return new AcceptedName(request.name());
}
@PostMapping("/required-name")
public AcceptedName requiredName(@Valid @RequestBody RequiredNameRequest request) {
return new AcceptedName(request.name());
}
public record NotNullName(
@NotNull(message = "氏名を入力してください") String name) {}
public record NotEmptyName(
@NotEmpty(message = "氏名を入力してください") String name) {}
public record NotBlankName(
@NotBlank(message = "氏名を入力してください") String name) {}
public record RequiredNameRequest(@RequiredName String name) {}
public record AcceptedName(String name) {}
}この独自制約が決めているのは、上で合意した空白だけの入力の扱いです。氏名の長さ、禁止文字、表記の正規化まで同時に決めてはいません。新しい要件が増えたら、まず入力と期待結果を仕様表へ加え、それを満たす条件を選びます。
RESTの400はnameに対応させ、画面再表示の200と分ける
このサンプルは検証で失敗したとき、MethodArgumentNotValidExceptionのフィールドエラーを400のJSONへ変換します。検証結果の中にnameがあることと、API利用者へ同じ項目名で返ることを別々に確認します。
ApiErrorHandler.javaの全文
package info.syachiku.constraints;
import java.util.Comparator;
import java.util.List;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class ApiErrorHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorBody> handle(MethodArgumentNotValidException exception) {
List<FieldIssue> errors = exception.getBindingResult().getFieldErrors().stream()
.map(error -> new FieldIssue(error.getField(), error.getCode(), error.getDefaultMessage()))
.sorted(Comparator.comparing(FieldIssue::field).thenComparing(FieldIssue::constraint))
.toList();
return ResponseEntity.badRequest().body(new ErrorBody(errors));
}
public record ErrorBody(List<FieldIssue> errors) {}
public record FieldIssue(String field, String constraint, String message) {}
}テストではステータスだけでなく、errors[0].field == "name"と、constraintが適用した制約名に一致することを確認します。200のケースは、受け取ったnameを変えずに返す契約です。保存は行いません。
MVCでBindingResultを受け取り、入力画面を再表示する設計では、入力エラーがあっても再表示の応答を200にすることがあります。それを根拠に、このREST APIも200へそろえる必要はありません。レスポンスを読む側が何を判断するかを先に決めます。
30テストで、仕様を弱めた修正も検出する
標準3制約×7入力が21件、@RequiredNameの7件で28件です。これにProviderの版の確認と、文字を含む氏名の空白を削らず返す確認を加え、mvn clean testで30件が成功しました。各ケースの入力と期待値は次のファイルに1か所だけ置いています。
input-cases.jsonの全文
[
{"id":"missing","label":"name欠落","body":{},"expected":{"not-null":400,"not-empty":400,"not-blank":400,"required-name":400}},
{"id":"null","label":"null","body":{"name":null},"expected":{"not-null":400,"not-empty":400,"not-blank":400,"required-name":400}},
{"id":"empty","label":"空文字","body":{"name":""},"expected":{"not-null":200,"not-empty":400,"not-blank":400,"required-name":400}},
{"id":"ascii-space","label":"半角空白 U+0020","body":{"name":" "},"expected":{"not-null":200,"not-empty":200,"not-blank":400,"required-name":400}},
{"id":"wide-space","label":"全角空白 U+3000","body":{"name":"\u3000"},"expected":{"not-null":200,"not-empty":200,"not-blank":200,"required-name":400}},
{"id":"nbsp","label":"NBSP U+00A0","body":{"name":"\u00A0"},"expected":{"not-null":200,"not-empty":200,"not-blank":200,"required-name":400}},
{"id":"valid","label":"文字あり","body":{"name":"山田"},"expected":{"not-null":200,"not-empty":200,"not-blank":200,"required-name":200}}
]ConstraintMatrixTest.javaの全文
package info.syachiku.constraints;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Map;
import java.util.stream.Stream;
import org.hibernate.validator.HibernateValidator;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.MethodSource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.web.bind.MethodArgumentNotValidException;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
@SpringBootTest
@AutoConfigureMockMvc
class ConstraintMatrixTest {
private static final Map<String, String> CONSTRAINT_NAMES = Map.of(
"not-null", "NotNull", "not-empty", "NotEmpty",
"not-blank", "NotBlank", "required-name", "RequiredName");
@Autowired
MockMvc mvc;
static Stream<Arguments> inputCases() throws IOException {
var arguments = new ArrayList<Arguments>();
try (var input = ConstraintMatrixTest.class.getResourceAsStream("/input-cases.json")) {
JsonNode cases = new ObjectMapper().readTree(input);
for (JsonNode item : cases) {
for (String endpoint : new String[]{"not-null", "not-empty", "not-blank", "required-name"}) {
arguments.add(Arguments.of(endpoint, item.path("id").asText(),
item.path("body").toString(), item.path("expected").path(endpoint).asInt()));
}
}
}
return arguments.stream();
}
@ParameterizedTest(name = "{0} / {1} -> {3}")
@MethodSource("inputCases")
void 同じnameの入力を制約ごとの仕様と照合する(
String endpoint, String caseId, String body, int expectedStatus) throws Exception {
var response = mvc.perform(post("/validation/" + endpoint)
.contentType(MediaType.APPLICATION_JSON).content(body))
.andExpect(status().is(expectedStatus))
.andExpect(content().contentTypeCompatibleWith(MediaType.APPLICATION_JSON));
if (expectedStatus == 400) {
response.andExpect(jsonPath("$.errors.length()").value(1))
.andExpect(jsonPath("$.errors[0].field").value("name"))
.andExpect(jsonPath("$.errors[0].constraint").value(CONSTRAINT_NAMES.get(endpoint)))
.andExpect(result -> assertInstanceOf(MethodArgumentNotValidException.class,
result.getResolvedException()));
} else {
String original = new ObjectMapper().readTree(body).path("name").asText();
response.andExpect(jsonPath("$.name").value(original));
}
}
@Test
void 記事のProvider版に固定されている() {
assertEquals("8.0.3.Final", HibernateValidator.class.getPackage().getImplementationVersion());
}
@Test
void 文字を含む氏名の前後と途中の空白は勝手に削らない() throws Exception {
mvc.perform(post("/validation/required-name").contentType(MediaType.APPLICATION_JSON)
.content("{\"name\":\" 山 田 \"}"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.name").value(" 山 田 "));
}
}作業用コピーでRequiredNameValidatorの最後の判定だけをreturn !value.isEmpty();へ弱めると、半角空白・全角空白・NBSPの3件が失敗します。期待400に対して200になるためです。null判定は残したままなので、今回見たい空白の受け付けをテストが捕まえたと分かります。
判定を元のcodePoints().anyMatch(...)へ戻すと30件が再び通過しました。配布ZIPは復元したソースを収録しています。成功するテストを並べるだけでなく、仕様を崩す変更が赤になるかまで確認します。
ZIPを展開し、同じ7入力を実JARへPOSTする
ZIPを展開し、pom.xmlのあるフォルダで次を実行します。JDK 17とMaven 3.9系を使います。依存がない環境では初回に取得用のネットワークが必要です。
mvn clean test
mvn package
java -jar target/validation-constraints-sample-1.0.0.jar --server.address=127.0.0.1 --server.port=18087起動した端末はそのままにし、別の端末から最初のcurlを送ります。Python 3があれば、次のスクリプトで同じ期待値ファイルの28ケースを実POSTし、HTTPとJSONの項目名まで照合できます。送信先はローカルのサンプルだけに限定しています。
python3 scripts/verify-http.py http://127.0.0.1:18087原本とZIP展開版の両方で30テストが通り、それぞれの起動JARへ28件、合計56件を実POSTしました。ステータス、拒否する項目名と制約名、受付時の文字列が一致しました。検証後は両方のサーバーを終了しています。手元でも、確認を終えたら起動した端末でCtrl+Cを押します。
pom.xmlの全文
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.5.16</version><relativePath/></parent>
<groupId>info.syachiku.samples</groupId><artifactId>validation-constraints-sample</artifactId><version>1.0.0</version>
<properties>
<java.version>17</java.version><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<hibernate-validator.version>8.0.3.Final</hibernate-validator.version><junit-jupiter.version>5.12.2</junit-jupiter.version>
</properties>
<dependencies>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>
<dependency>
<groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope>
<exclusions>
<exclusion><groupId>org.mockito</groupId><artifactId>mockito-core</artifactId></exclusion>
<exclusion><groupId>org.mockito</groupId><artifactId>mockito-junit-jupiter</artifactId></exclusion>
</exclusions>
</dependency>
</dependencies>
<build><plugins>
<plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin>
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.6</version></plugin>
</plugins></build>
</project>ConstraintApplication.javaの全文
package info.syachiku.constraints;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class ConstraintApplication {
public static void main(String[] args) {
SpringApplication.run(ConstraintApplication.class, args);
}
}このサンプルにはDB、認証、HTML画面、独自のJackson変換を含めていません。実案件へ適用するときは、送信後に受け取ったDTOの値が同じかを先に見ます。画面の空欄をnullへ変える仕組みがある場合などは、JSONで検証した今回と前提が変わります。
レビューには、拒否する入力とその理由を残す
「必須なので@NotBlankです」だけでは、どの空白を拒否するかが伝わりません。私が実装理由を確認するときは、今回の要件、選択肢、採用理由をそろえて説明できる形を重視します。この例なら、次のように仕様と結果を結びます。
氏名はnull・空文字・空白だけを拒否する仕様です。
@NotEmptyでは半角空白が200になり、
このProvider版の@NotBlankでも全角空白とNBSPが200でした。
RequiredNameではその3入力を400にし、errorsの項目名nameまで確認しています。
文字を含む氏名の前後・途中の空白は変更しません。これなら、後任が制約を置き換えようとしたときも、何を守る必要があるかを入力例から追えます。コードを短くするためにisEmpty()へ戻すと、どの仕様を失うかもテストに現れます。
- 拒否したいのはnullだけか、空文字もか、どの空白までかを入力例にしたか。
- 受け取るDTOの型・項目名と、適用する制約を対応させたか。
- 全角空白とNBSPを、使用中のProvider版と同じ環境で確認したか。
- RESTのステータス、エラーの項目名、受付時に保持する値をテストしたか。
- 氏名の判定と、文字列を削る正規化を別の仕様として扱ったか。
フォームとControllerのつながりから学びたい場合に
制約の比較を動かしたあと、入力フォーム、Controller、Formの受け渡しを一つのWebアプリとして作りたいなら『作って学ぶ Spring Boot入門』を案内します。この記事の空白判定の実測とは分けて、画面から送信し、エラーを利用者へ返す流れを練習するための1冊です。
作って学ぶ Spring Boot入門
Spring Bootを、動くWebアプリを作りながら覚える。
Controller、画面、DB連携などを一つのアプリとして実装できます。Java基礎からSpringの現場へ進む橋渡しに向く一冊です。
- Spring Bootを手を動かして学びたい
- Webアプリ開発の流れをつかみたい
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
この記事とあわせて読みたい
制約名より先に、拒否する入力を決める
@NotNullはnull、@NotEmptyはnullと空文字を拒否します。@NotBlankは空白の判定も行いますが、今回のHibernate Validator 8.0.3.Finalでは全角空白とNBSPだけの値は通りました。
氏名の仕様がその入力も拒否するなら、同じ入力を使って修正前後を比べます。今回の@RequiredNameは、拒否する空白の範囲を明示し、400とnameのエラーで確認しました。アノテーションの名前を暗記するより、何を許す契約かを説明できる状態にします。



