概要

これまではエラーをそのまま返却しており SpringBoot 側はハンドリングされていないエラーはすべて 500 エラーで返します

今回は特定のエラーをハンドリングしエラーレスポンスをカスタムする方法を紹介します

環境

macOS 26.4.1
openjdk 26.0.1
SpringBoot 4.0.6
- jasypt-spring-boot 4.0.4
- jackson-databind 2.21.2
gradle 9.5.1
VSCode 1.121.0
MySQL 9.6.0
Redis 8.6.3

カスタムエラーの作成

まずはカスタムエラーを作成します
独自の Exception になります

vim src/main/java/com/example/demo/exception/BusinessException.java

package com.example.demo.exception;

public class BusinessException extends RuntimeException {

	private final String code;

	public BusinessException(String code, String message) {
		super(message);
		this.code = code;
	}

	public String getCode() {
		return code;
	}
}

エラーレスポンス用の DTO の作成

レスポンス用の DTO を作成します
エラーレスポンスとして返却したい情報を管理します

vim src/main/java/com/example/demo/exception/dto/ErrorResponse.java

package com.example.demo.exception.dto;

import java.time.LocalDateTime;

public class ErrorResponse {

	private String code;
	private String message;
	private LocalDateTime timestamp;

	public ErrorResponse(String code, String message, LocalDateTime timestamp) {
		this.code = code;
		this.message = message;
		this.timestamp = timestamp;
	}

	public String getCode() {
		return code;
	}

	public String getMessage() {
		return message;
	}

	public LocalDateTime getTimestamp() {
		return timestamp;
	}
}

エラーハンドラの作成

これがメイン部分です
SpringBoot では @RestControllerAdvice を基本的に使います
このアノテーションがあるクラスを自動的に読み込みエラーハンドリングしてくれます

vim src/main/java/com/example/demo/exception/GlobalExceptionHandler.java

package com.example.demo.exception;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import com.example.demo.exception.dto.ErrorResponse;

import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;

import java.time.LocalDateTime;

@RestControllerAdvice
public class GlobalExceptionHandler {

	@ExceptionHandler(BusinessException.class)
	@ResponseStatus(HttpStatus.BAD_REQUEST)
	public ErrorResponse handleBusinessException(BusinessException ex) {
		return new ErrorResponse(ex.getCode(), ex.getMessage(), LocalDateTime.now());
	}

	@ExceptionHandler(Exception.class)
	@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
	public ErrorResponse handleException(Exception ex) {
		return new ErrorResponse("INTERNAL_SERVER_ERROR", "予期しないエラーが発生しました", LocalDateTime.now());
	}
}

サービス側修正

サービス側は作成したカスタム Exception を返却するようにします

vim src/main/java/com/example/demo/service/UserService.java

package com.example.demo.service;

import java.util.ArrayList;
import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Service;

import com.example.demo.dto.RedisMessageRequest;
import com.example.demo.dto.UserRequest;
import com.example.demo.dto.UserResponse;
import com.example.demo.entity.User;
import com.example.demo.exception.BusinessException;
import com.example.demo.repository.UserRepository;
import com.fasterxml.jackson.databind.ObjectMapper;

@Service
public class UserService {

	@Autowired
	private UserRepository userRepository;

	@Autowired
	private StringRedisTemplate redisTemplate;

	@Autowired
	private ObjectMapper objectMapper;

	public void createUser(UserRequest req) {

		// 例：ビジネスルール
		if (userRepository.existsByEmail(req.getEmail())) {
			throw new BusinessException("USER_ALREADY_EXISTS", "既に登録されています");
		}

		User user = new User();
		user.setName(req.getName());
		user.setEmail(req.getEmail());

		userRepository.save(user);

		// Redis キューにメッセージを JSON 形式で送信
		try {
			RedisMessageRequest message = new RedisMessageRequest();
			message.setName(req.getName());
			message.setEmail(req.getEmail());

			String jsonMessage = objectMapper.writeValueAsString(message);
			redisTemplate.convertAndSend("chat", jsonMessage);
		} catch (Exception e) {
			throw new RuntimeException("Failed to send Redis message", e);
		}
	}

	public List<UserResponse> getAllUsers() {
		List<User> users = new ArrayList<>();
		userRepository.findAll().forEach(users::add);

		return users.stream().map(this::toResponse).toList();
	}

	private UserResponse toResponse(User user) {
		UserResponse response = new UserResponse();
		response.setName(user.getName());
		return response;
	}
}

動作確認

./gradlew clean && ./gradlew bootRun --args='--jasypt.encryptor.password=xxx'
curl -XPOST http://localhost:8080/demo/add -d '{"name": "First", "email": "someemail5@someemailprovider.com"}' -H 'content-type: application/json'

{"code":"USER_ALREADY_EXISTS","message":"既に登録されています","timestamp":"2026-05-25T13:32:16.13214"}

最後に

SpringBoot でエラーハンドリングする方法を紹介しました
@RestControllerAdvice を使いましょう