APIで空の件名を送ると400になる。ところが画面側では、どの欄を直せばよいか分からない。ステータスコードだけ合っていても、入力画面を作る側には足りません。
私なら、エラー応答を利用者が修正できる項目名とメッセージだけに絞った契約にします。スタックトレース、例外クラス名、送信された秘密値を返す必要はありません。ここでは JDK 17、Spring Boot 3.5系、Spring MVC の @Valid @RequestBody を例にします。
応答形式を先に決める

件名を必須にした、架空のタスク登録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のリンクにはアフィリエイトを含みます。
