この記事の要点
@RequestBody はHTTP リクエストボディを Java オブジェクトに変換するアノテーション Jackson が JSON / XML を自動で POJO にバインド POST / PUT / PATCH の API で必須 バリデーション: @Valid と組み合わせて入力チェック GET メソッドでは通常使わない（ボディなし）

 

基本的な使い方

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

    @PostMapping
    public User create(@RequestBody UserCreateRequest req) {
        return userService.create(req);
    }
}

// リクエスト例
// POST /api/users
// Content-Type: application/json
// {
//   "name": "Alice",
//   "email": "alice@example.com"
// }

// UserCreateRequest
public class UserCreateRequest {
    private String name;
    private String email;
    // getters/setters
}

バリデーション (@Valid)

@PostMapping
public User create(@RequestBody @Valid UserCreateRequest req) {
    return userService.create(req);
}

// DTO に Bean Validation アノテーション
public class UserCreateRequest {

    @NotBlank(message = "名前は必須です")
    @Size(max = 100, message = "名前は 100 文字以内")
    private String name;

    @NotBlank
    @Email(message = "有効なメールアドレスを入力してください")
    private String email;

    @Min(value = 18, message = "18 歳以上である必要があります")
    private int age;

    @Pattern(regexp = "^[0-9]{10,11}$", message = "電話番号は数字 10-11 桁")
    private String phone;
}

// バリデーション失敗時の例外ハンドラ
@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler(MethodArgumentNotValidException.class)
public Map handleValidation(MethodArgumentNotValidException ex) {
    Map errors = new HashMap<>();
    ex.getBindingResult().getFieldErrors().forEach(err ->
        errors.put(err.getField(), err.getDefaultMessage())
    );
    return errors;
}

主要な Bean Validation アノテーション

アノテーション	用途
@NotNull	null 不可
@NotBlank	文字列：null / 空 / 空白のみ 不可
@NotEmpty	コレクション / 文字列：null / 空 不可
@Size(min, max)	長さ範囲
@Min / @Max	数値の最小・最大
@Email	メール形式
@Pattern	正規表現
@Past / @Future	日付の過去・未来
@Positive / @Negative	正の数 / 負の数
@Digits(integer, fraction)	整数部・小数部の桁数
@AssertTrue / @AssertFalse	boolean フィールドの値
@Valid	ネストされたオブジェクトを再帰的にバリデート

JSON 受信のカスタマイズ

① プロパティ名のマッピング

public class UserCreateRequest {
    @JsonProperty("user_name")  // JSON 側は user_name
    private String name;        // Java 側は name
}

// または application.properties で一括
spring.jackson.property-naming-strategy=SNAKE_CASE

② 不要なフィールドの無視

@JsonIgnoreProperties(ignoreUnknown = true)
public class UserCreateRequest {
    private String name;
    private String email;
    // JSON に余分なフィールドがあっても無視
}

// または application.properties
spring.jackson.deserialization.fail-on-unknown-properties=false

③ 日付フォーマット

public class EventRequest {
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "Asia/Tokyo")
    private LocalDateTime scheduledAt;
}

④ enum の柔軟受信

public enum UserStatus {
    ACTIVE, INACTIVE, SUSPENDED;

    @JsonCreator
    public static UserStatus fromString(String s) {
        return UserStatus.valueOf(s.toUpperCase());  // "active" → ACTIVE
    }
}

# または application.properties
spring.jackson.deserialization.accept-case-insensitive-enums=true

ネストしたオブジェクト

public class OrderRequest {
    @NotBlank
    private String customer;

    @Valid  // ← ネストしたリストも再帰バリデーション
    @NotEmpty
    private List items;
}

public class OrderItemRequest {
    @NotNull
    private Long productId;

    @Min(1)
    private int quantity;
}

// JSON
// {
//   "customer": "Alice",
//   "items": [
//     {"productId": 1, "quantity": 2},
//     {"productId": 3, "quantity": 1}
//   ]
// }

@RequestBody と @RequestParam の使い分け

シナリオ	アノテーション
JSON / XML のボディ	@RequestBody
フォームデータ（application/x-www-form-urlencoded）	@RequestParam または @ModelAttribute
multipart/form-data（ファイルアップロード）	@RequestParam("file") MultipartFile file
クエリパラメータ	@RequestParam

よくあるトラブル

Q. リクエストが 400 Bad Request になる

• Content-Type が application/json でない: クライアント側のヘッダ確認
• JSON 構文エラー: カンマ・引用符の確認
• DTO のフィールド型不一致: 数値を文字列で送る等
• setter がない: Jackson は setter 経由でセット（または public フィールド）

Q. すべてのフィールドが null になる

• JSON のキー名と Java のフィールド名（または setter 名）が一致していない
• Lombok の @Data や @Setter 忘れ
• jackson-databind が依存に含まれていない

関連記事

• @ResponseBody
• @RestController
• @PathVariable
• アノテーション一覧