注文DTOの中に子オブジェクトと明細のリストが入る階層図。子の入力まで検証する

実装・エラー解決

Spring BootでネストしたDTOのバリデーションが効かない原因|Listの中まで検証する方法

注文APIで、注文者名が空なら400になるのに、明細の品番が空でも保存される。コントローラー引数に @Valid があるのを確認しても、原因が見えないことがあります。

私なら最初に見るのは、親から子へ検証を進める指定があるかです。親の検証は、子の中身を自動で全部たどるわけではありません。注文と複数明細を例に、検証する階層を見える形にします。以下は JDK 17、Spring Boot 3.5系と spring-boot-starter-validation の例です。

症状を一つのJSONで再現する

{
  "customerName": "田中",
  "items": [
    {"sku": "A-001", "quantity": 2},
    {"sku": "", "quantity": 0}
  ]
}

この注文では、2件目の品番と数量が不正です。items 自体が存在することと、各明細の項目が正しいことは別の検証です。@NotEmpty をListに付けても、それだけでは明細の sku を調べません。

親、List要素、子をそれぞれ指定する

入れ子のDTOで検証が進む経路。リクエスト:注文DTOを受け取る。子オブジェクト:@Validで検証を伝播。List要素:各明細の制約を見る。結果:項目の位置を特定する
入れ子のDTOで検証が進む経路。@Validが効く経路をたどる

OrderRequest.java の全文

package info.syachiku.auditvalidation;

import jakarta.validation.Valid;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.NotNull;
import java.util.List;

record OrderRequest(
        @NotBlank String customerName,
        @NotEmpty List<@NotNull @Valid OrderItemRequest> items) {
}

record OrderItemRequest(@NotBlank String sku, @Min(1) int quantity) {
}

ここでは三か所に別々の意味があります。

指定検証する内容
@NotEmptyListが null または空ではないか
@NotNullList内の各要素が null ではないか
@Valid各 OrderItemRequest の制約へ進むか

Hibernate Validator 8では、List<@Valid OrderItemRequest> のように要素の型に @Valid を付ける書き方が意図を示しやすい形です。昔の @Valid List<OrderItemRequest> でも動く構成がありますが、これから書くなら何をたどるかが明確な位置へ付けます。

入口にも @Valid が必要です。

OrderController.java の全文

package info.syachiku.auditvalidation;

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.NotNull;
import java.util.List;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
class OrderController {
    @PostMapping("/orders")
    ResponseEntity<Void> create(@Valid @RequestBody OrderRequest request) {
        return ResponseEntity.noContent().build();
    }

    @PostMapping("/orders/no-cascade")
    ResponseEntity<Void> createWithoutCascade(@Valid @RequestBody OrderWithoutCascade request) {
        return ResponseEntity.noContent().build();
    }
}

record OrderWithoutCascade(@NotBlank String customerName,
                           @NotEmpty List<@NotNull OrderItemRequest> items) {
}

この例で @Valid を引数から外すと、DTO内のアノテーションがあってもこの入口では検証されません。また、jakarta.validation.Valid と jakarta.validation.constraints.* を使います。Spring Boot 3系のアプリへ旧 javax.validation の例をそのまま貼り付けると、世代が混ざります。

パスを見れば、どの階層で止まったか分かる

同じ注文JSONで、子への @Valid がない /orders/no-cascade は204、子まで検証する /orders は400です。2件目の品番と数量には items[1].sku、items[1].quantity が出ます。items:[null] は @NotNull により400となり、items[0] を返します。

実行用サンプル

JDK 17とMaven 3.9系で mvn test を実行します。ZIPにはソース全文・テスト・pom.xml・READMEを収録しています。

ValidationContractsTest.java の全文

package info.syachiku.auditvalidation;

import java.util.stream.Stream;
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.test.web.servlet.ResultActions;
import org.springframework.web.bind.MissingServletRequestParameterException;
import org.springframework.web.method.annotation.HandlerMethodValidationException;
import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;

import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@SpringBootTest
@AutoConfigureMockMvc
class ValidationContractsTest {
    @Autowired
    private MockMvc mvc;

    @Test
    void 件名必須と壊れたJSONでは異なるエラーコードになる() throws Exception {
        json("/tasks", "{\"title\":\"確認\"}").andExpect(status().isNoContent());
        json("/tasks", "{\"title\":\"\"}").andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.code").value("VALIDATION_ERROR"))
                .andExpect(jsonPath("$.fields.title").value("件名を入力してください"))
                .andExpect(jsonPath("$.globalErrors").isEmpty());
        json("/tasks", "{\"title\":").andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.code").value("INVALID_JSON"));
    }

    @Test
    void 相関制約が項目名を持たない場合もJSONへ入る() throws Exception {
        json("/tasks", """
                {"title":"確認","startDate":"2026-11-05","endDate":"2026-11-04"}
                """).andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.fields").isEmpty())
                .andExpect(jsonPath("$.globalErrors[0]").value("開始日と終了日の順序を確認してください"));
    }

    @Test
    void 子へのValidを外すと子の入力値が検証されない() throws Exception {
        String invalid = """
                {"customerName":"田中","items":[{"sku":"A-001","quantity":2},{"sku":"","quantity":0}]}
                """;
        json("/orders/no-cascade", invalid).andExpect(status().isNoContent());
        json("/orders", invalid).andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.fields['items[1].sku']").exists())
                .andExpect(jsonPath("$.fields['items[1].quantity']").exists());
        json("/orders", "{\"customerName\":\"田中\",\"items\":[null]}")
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.fields['items[0]']").exists());
    }

    @Test
    void 同日を許可し逆転と終了日未入力を終了日のエラーへ変換する() throws Exception {
        json("/request-dates", "{\"startDate\":\"2026-11-04\",\"endDate\":\"2026-11-04\"}")
                .andExpect(status().isNoContent());
        json("/request-dates", "{\"startDate\":\"2026-11-04\",\"endDate\":\"2026-11-03\"}")
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.fields.endDate").value("終了日は開始日以降を指定してください"));
        json("/request-dates", "{\"startDate\":\"2026-11-04\"}")
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.fields.endDate").exists());
    }

    @Test
    void クエリの欠落と空白と型変換で例外型が変わる() throws Exception {
        mvc.perform(get("/api/employees").param("keyword", "田中").param("page", "0"))
                .andExpect(status().isOk()).andExpect(content().string("田中:0"));
        mvc.perform(get("/api/employees"))
                .andExpect(status().isBadRequest())
                .andExpect(result -> assertInstanceOf(MissingServletRequestParameterException.class,
                        result.getResolvedException()));
        mvc.perform(get("/api/employees").param("keyword", " "))
                .andExpect(status().isBadRequest())
                .andExpect(result -> assertInstanceOf(HandlerMethodValidationException.class,
                        result.getResolvedException()));
        mvc.perform(get("/api/employees").param("keyword", "田中").param("page", "bad"))
                .andExpect(status().isBadRequest())
                .andExpect(result -> assertInstanceOf(MethodArgumentTypeMismatchException.class,
                        result.getResolvedException()));
    }

    @ParameterizedTest
    @MethodSource("pathLengths")
    void 文字数制約とルーティングを分けて確認する(String path, int code) throws Exception {
        mvc.perform(get(path)).andExpect(status().is(code));
    }

    static Stream<Arguments> pathLengths() {
        return Stream.of(
                Arguments.of("/api/employees/" + "a".repeat(31), 400),
                Arguments.of("/api/employees/" + "a".repeat(32), 200),
                Arguments.of("/api/employees/" + "a".repeat(33), 400),
                Arguments.of("/api/employees/" + "a".repeat(32) + "/extra", 404));
    }

    private ResultActions json(String path, String content) throws Exception {
        return mvc.perform(post(path).contentType(MediaType.APPLICATION_JSON).content(content));
    }
}

テストではエラーメッセージの全文より、問題の場所を先に確かめます。文言は日本語化で変わり得ますが、items[1].sku のようなパスなら、2件目の品番と特定できます。

ここでのインデックスは0始まりです。List内の null も確認するときは List.of(null) を使わないでください。List.of 自体が null を拒否するため、検証処理へ到達しません。Arrays.asList((OrderItemRequest) null) のようなListを作って別に試します。

直しても400にならない場合の確認順

  1. spring-boot-starter-validation が依存関係にあるか。
  2. コントローラーのルートDTO引数に @Valid があるか。
  3. 子が単体項目ならそのフィールド、Listなら要素型に @Valid があるか。
  4. 検証したい値に @NotBlank、@Min など適切な制約があるか。
  5. 保存処理が別の入口から呼ばれ、その入口で検証を省いていないか。

最後の点が実務では大切です。APIからは不正な値を拒否できても、バッチや別サービスが同じ保存処理へ渡せるなら業務上の不変条件は別途守る必要があります。まずこのAPIの入力を確実に止め、それから保存境界を確認します。APIで項目別エラーをJSONとして返す形は、別記事「Spring BootでバリデーションエラーをJSONで返す方法」で扱います。

参考資料

-実装・エラー解決
-,