HTTP 400と項目名・理由を示すJSON応答の図。入力エラーを契約として返す

実装・エラー解決

Spring BootでバリデーションエラーをJSONで返す方法|RestControllerAdviceの実装例

APIで空の件名を送ると400になる。ところが画面側では、どの欄を直せばよいか分からない。ステータスコードだけ合っていても、入力画面を作る側には足りません。

私なら、エラー応答を利用者が修正できる項目名とメッセージだけに絞った契約にします。スタックトレース、例外クラス名、送信された秘密値を返す必要はありません。ここでは JDK 17、Spring Boot 3.5系、Spring MVC の @Valid @RequestBody を例にします。

応答形式を先に決める

APIのエラー応答に必要な要素。HTTP 400:入力の問題と示す。項目名:どこを直すか示す。理由:利用者向けに簡潔に。テスト:応答形を固定する
APIのエラー応答に必要な要素。APIの応答も契約として設計

件名を必須にした、架空のタスク登録APIです。空文字なら次の応答にします。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": "VALIDATION_ERROR",
  "fields": {
    "title": "件名を入力してください"
  },
  "globalErrors": []
}

code は画面側が処理を分けるための固定値です。fields のキーは入力項目の名前で、今回の例では title です。日本語メッセージは表示用であり、プログラムの分岐条件には使いません。同じ項目に複数制約が違反したときは、ここでは最初に取得した1件を表示します。どの制約が先になるかへ依存せず、表示の優先順位が必要なら明示的に決めてください。全件必要なAPIなら Map<String, List<String>> に契約を変えます。

DTOとコントローラーを作る

spring-boot-starter-validation を依存関係に入れます。@NotBlank は null・空文字・空白だけの文字列を拒否します。

TaskInput.java の全文

package info.syachiku.auditvalidation;

import jakarta.validation.constraints.NotBlank;
import java.time.LocalDate;

@ValidTaskWindow
record TaskInput(
        @NotBlank(message = "件名を入力してください") String title,
        LocalDate startDate,
        LocalDate endDate) {
}

TaskController.java の全文

package info.syachiku.auditvalidation;

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

@RestController
class TaskController {
    @PostMapping("/tasks")
    ResponseEntity<Void> create(@Valid @RequestBody TaskInput input) {
        return ResponseEntity.noContent().build();
    }
}

この形の引数検証に失敗すると MethodArgumentNotValidException が発生し、Spring MVCは標準で400を返します。ここから自分たちのJSON形式へ変換する部分を追加します。

RestControllerAdviceで項目別エラーへ変換する

ValidationErrorAdvice.java の全文

package info.syachiku.auditvalidation;

import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.HttpMessageNotReadableException;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
class ValidationErrorAdvice {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    ResponseEntity<ApiError> handleValidation(MethodArgumentNotValidException exception) {
        var result = exception.getBindingResult();
        Map<String, String> fields = new LinkedHashMap<>();
        result.getFieldErrors().forEach(error ->
                fields.putIfAbsent(error.getField(), error.getDefaultMessage()));
        var globalErrors = result.getGlobalErrors().stream()
                .map(error -> error.getDefaultMessage())
                .toList();
        return ResponseEntity.badRequest().body(new ApiError("VALIDATION_ERROR", fields, globalErrors));
    }

    @ExceptionHandler(HttpMessageNotReadableException.class)
    ResponseEntity<ApiError> handleMalformedJson() {
        return ResponseEntity.badRequest().body(new ApiError("INVALID_JSON", Map.of(), List.of()));
    }
}

record ApiError(String code, Map<String, String> fields, List<String> globalErrors) {
}

getRejectedValue() や ex.getMessage() をそのまま返していないのがポイントです。パスワードや個人情報の入力値、内部実装をレスポンスへ混ぜないためです。クラス単位の相関チェックも扱うAPIなら、getGlobalErrors() を別の errors 配列へ変換するか、制約側で修正すべき項目へ違反を紐付けます。

MockMvcで契約を確かめる

同じ /tasks で、正常なら204、件名が空なら400と fields.title、壊れたJSONなら400と INVALID_JSON を確認します。開始日と終了日の逆転は、項目に属さない制約として globalErrors に入ります。

実行用サンプル

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

ValidTaskWindow.java の全文

package info.syachiku.auditvalidation;

import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.*;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = TaskWindowValidator.class)
@interface ValidTaskWindow {
    String message() default "開始日と終了日の順序を確認してください";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

TaskWindowValidator.java の全文

package info.syachiku.auditvalidation;

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

public class TaskWindowValidator implements ConstraintValidator<ValidTaskWindow, TaskInput> {
    @Override
    public boolean isValid(TaskInput input, ConstraintValidatorContext context) {
        return input == null || input.startDate() == null || input.endDate() == null
                || !input.endDate().isBefore(input.startDate());
    }
}

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

このテストは「エラーになった」だけでなく、利用側が頼るフィールド名とコードを固定します。メッセージを多言語化するなら、文言そのもののテストは言語を指定して分けます。

この例が扱わないエラーを混同しない

不正なJSON、日付への変換失敗、認証失敗、業務上の重複は、同じ MethodArgumentNotValidException とは限りません。またコントローラー引数に @Min などの制約を直接付けた場合、Spring MVC 6.1以降のメソッド検証では HandlerMethodValidationException が発生し得ます。そこまで共通形式にするなら、別途その例外の応答も設計してテストします。

まずは自分たちのAPIが受け取るDTOで、どの失敗を400として返すかを一つずつ固定してください。例外を何でもまとめて400にすると、サーバー側の不具合まで「入力のせい」に見えてしまいます。

Spring BootのController、入力、Serviceのつながりを通して学び直すなら『作って学ぶ Spring Boot入門』が候補です。Java、HTML/CSS、基本SQLの知識が前提で、この記事のJSON形式の出典として紹介しているわけではありません。出版社の内容紹介を確認し、必要なら脱初心者の本棚(Amazon)から探せます。Amazonのリンクにはアフィリエイトを含みます。

参考資料

-実装・エラー解決
-, ,