스프링 405 에러: 원인과 해결 방법 총정리

IT관련정보

스프링 405 에러: 원인과 해결 방법 총정리

heokebi 2025. 1. 4. 01:13

스프링(Spring)으로 웹 애플리케이션을 개발하다 보면 HTTP 405 에러(Method Not Allowed)를 마주할 때가 있습니다. 이 에러는 주로 요청된 HTTP 메서드(GET, POST 등)가 서버에서 허용되지 않을 때 발생합니다. 특히 REST API 설계나 컨트롤러 매핑 오류에서 자주 나타나는데요. 초보 개발자뿐만 아니라 숙련된 개발자도 헷갈릴 수 있는 문제입니다. 이 글에서는 스프링 405 에러의 원인을 구체적으로 분석하고, 이를 해결하는 다양한 방법을 소개합니다.

1. 405 에러란? 기본 개념과 발생 원인

"405 에러는 서버와 클라이언트 간의 요청-응답 불일치에서 발생합니다."
HTTP 상태 코드 405는 Method Not Allowed를 의미합니다. 이는 클라이언트가 요청한 HTTP 메서드가 서버에서 허용되지 않거나 지원하지 않는 경우 발생합니다.

더 자세히

1. 405 에러의 발생 조건:

클라이언트가 특정 메서드(GET, POST, PUT 등)로 요청했지만, 서버가 해당 메서드를 처리할 수 없는 경우.
예를 들어, 클라이언트가 POST 요청을 보냈는데 서버가 GET만 허용할 때 발생.

2. 405 에러의 주요 원인:

컨트롤러 매핑 오류: 컨트롤러 메서드가 잘못 매핑되거나 HTTP 메서드와 맞지 않는 경우.
HTTP 메서드 미설정: 요청에 필요한 메서드가 제대로 정의되지 않은 경우.
Spring Security 설정 충돌: 보안 설정이 HTTP 메서드를 차단하는 경우.

제가 처음 405 에러를 접했을 때, GET 요청과 POST 요청을 혼동해서 헤맸던 기억이 있어요. 기본 개념만 이해해도 문제를 더 빨리 해결할 수 있었을 텐데 말이죠.

2. 스프링에서 405 에러가 발생하는 주요 상황

"스프링에서는 주로 컨트롤러와 HTTP 메서드 설정에서 문제가 발생합니다."
스프링에서 405 에러는 대부분 RequestMapping, RestController, Spring Security 설정이 올바르게 동작하지 않을 때 발생합니다.

더 자세히

1. 컨트롤러 매핑 문제:

컨트롤러의 메서드에 지정된 HTTP 메서드가 요청과 일치하지 않을 때 발생.
```
@PostMapping("/api/data")
public String postData() {
    return "Data posted";
}
```
- 위 코드에서 GET /api/data로 요청하면 405 에러 발생.

2. Spring Security 설정 문제:

Spring Security가 특정 HTTP 메서드를 차단하거나 인증되지 않은 요청을 거부할 때.
```
http.csrf().disable()
    .authorizeRequests()
    .antMatchers(HttpMethod.POST, "/api/**").permitAll();
```
- 위와 같이 설정하지 않으면 POST 요청이 차단될 수 있음.

3. DispatcherServlet 동작 문제:

스프링의 DispatcherServlet이 올바르게 요청을 매핑하지 못할 경우.

3. 컨트롤러 매핑 문제 해결하기

"올바른 매핑 설정이 가장 기본적인 해결 방법입니다."
스프링 컨트롤러에서 405 에러를 방지하려면 @GetMapping, @PostMapping 등의 매핑 어노테이션을 올바르게 사용해야 합니다.

더 자세히

1. 매핑 어노테이션 사용:

요청과 매핑되는 HTTP 메서드를 명확히 지정.

@RestController
@RequestMapping("/api")
public class MyController {

    @GetMapping("/data")
    public String getData() {
        return "Data fetched";
    }

    @PostMapping("/data")
    public String postData() {
        return "Data posted";
    }
}

위 코드에서는 GET과 POST 요청을 명확히 분리하여 에러를 방지.

2. 메서드 매핑 확인 체크리스트:

클라이언트 요청과 서버 매핑 메서드가 일치하는지 확인.
@RequestMapping 어노테이션에서 메서드를 명시하지 않으면 모든 요청을 수용.
```
@RequestMapping(value = "/data", method = RequestMethod.GET)
```

3. 테스트 팁:

Postman과 같은 툴을 사용해 요청을 테스트하고 에러 발생 상황 재현.
서버 로그를 확인해 어떤 메서드가 호출되었는지 추적.

한 번은 컨트롤러 매핑 실수로 405 에러가 발생해 고생했어요. Postman으로 요청을 디버깅하며 해결했답니다.

4. HTTP 메서드 설정 확인하기

"HTTP 메서드 설정은 명확해야 합니다."
스프링에서 HTTP 메서드는 클라이언트와의 소통 방식입니다. 적절한 메서드 설정은 405 에러를 예방하는 핵심입니다.

더 자세히

1. HTTP 메서드 기본 개념:

GET: 데이터 조회.
POST: 데이터 생성.
PUT: 데이터 수정.
DELETE: 데이터 삭제.

2. 올바른 메서드 매핑:

요청 메서드와 서버 메서드가 일치하도록 설정.

@DeleteMapping("/data")
public String deleteData() {
    return "Data deleted";
}

3. HTTP 헤더 설정:

클라이언트에서 올바른 HTTP 헤더를 사용했는지 확인.
```
POST /api/data HTTP/1.1
Content-Type: application/json
```

4. 예상 시나리오 테스트:

클라이언트가 올바른 메서드로 요청하는지 반복 확인.
잘못된 요청은 서버에서 적절히 차단.

5. Spring Security와의 연관성

"405 에러, 보안 설정 때문일 수도 있습니다."
스프링 애플리케이션에서 Spring Security는 요청의 흐름을 제어합니다. 특정 HTTP 메서드를 차단하거나 인증이 필요하도록 설정했을 때, 예상치 못한 405 에러가 발생할 수 있습니다. 이런 경우, 보안 설정을 검토하여 문제가 되는 부분을 해결해야 합니다.

더 자세히

1. Spring Security에서의 주요 역할:

특정 URL 경로에 대해 HTTP 메서드를 제한.
인증되지 않은 요청을 거부.
CSRF(Cross-Site Request Forgery) 보호로 인해 POST/PUT 요청 차단.

2. Spring Security와 405 에러의 관계:

POST 요청이 허용되지 않은 경우:
- CSRF 보호가 활성화된 경우, POST 요청이 차단될 수 있음. 이를 csrf().disable()로 비활성화하거나 토큰 기반 인증을 구현해야 합니다.
http.csrf().disable() .authorizeRequests() .antMatchers(HttpMethod.POST, "/api/**").permitAll();
특정 HTTP 메서드 제한:
- 위 코드에서 /admin/** 경로는 GET 요청만 허용하며, 인증이 필요합니다. POST 요청이 이 경로로 들어오면 405 에러가 발생.
http.authorizeRequests() .antMatchers(HttpMethod.GET, "/admin/**").authenticated() .anyRequest().permitAll();

3. 해결 방법:

보안 설정을 확인하고 허용된 HTTP 메서드와 경로를 명확히 정의.
CSRF 보호를 사용하는 경우, 관련 토큰을 요청에 포함하도록 클라이언트를 수정.

저도 처음 Spring Security를 사용할 때, POST 요청이 계속 405 에러를 반환해 이유를 몰랐는데, CSRF 설정 때문이었어요. CSRF를 비활성화하니 문제가 해결되었답니다.

6. 에러를 예방하는 코드 작성 팁

"코드를 미리 점검하여 405 에러를 예방하세요."
405 에러를 사전에 방지하려면 코딩 단계에서부터 매핑, HTTP 메서드, 보안 설정 등을 꼼꼼히 작성해야 합니다. 다음은 이를 위한 팁입니다.

더 자세히

1. 컨트롤러 매핑 점검:

@GetMapping, @PostMapping 등 어노테이션을 사용해 명확히 HTTP 메서드를 정의하세요.

매핑된 URL 경로와 HTTP 메서드가 클라이언트 요청과 일치하는지 확인.

@RestController
@RequestMapping("/api")
public class MyController {
    @PostMapping("/submit")
    public String submitData() {
        return "Data submitted!";
    }
}

2. 공통적인 에러 상황 사전 예방:

잘못된 HTTP 메서드 사용: 서버에서 정의되지 않은 메서드 요청을 거부하도록 예외 처리를 추가.
필수 헤더 확인: 요청에 필요한 헤더(Content-Type, Authorization 등)가 누락되지 않도록 확인.

3. 에러 로깅 및 디버깅:

로깅을 활용하여 문제를 빠르게 추적.

@ExceptionHandler(Exception.class)
public ResponseEntity<String> handleException(Exception e) {
    return new ResponseEntity<>("Error: " + e.getMessage(), HttpStatus.BAD_REQUEST);
}

4. 테스트 자동화:

JUnit 또는 Postman을 사용해 여러 HTTP 메서드로 요청을 테스트하고 예상 시나리오를 확인하세요.

문제 상황 예방 방법

잘못된 HTTP 메서드 요청	매핑된 HTTP 메서드 확인 및 요청 메서드 일치
CSRF 문제	CSRF 비활성화 또는 클라이언트에서 CSRF 토큰 전달
URL 매핑 불일치	컨트롤러의 매핑 경로와 클라이언트 요청 경로 검토

제 경험상, 로깅과 테스트를 꾸준히 병행하면 예상치 못한 405 에러를 대부분 예방할 수 있었습니다. 특히 Postman으로 다양한 요청을 미리 테스트하는 것이 큰 도움이 되더라고요.

405 에러는 스프링 애플리케이션에서 자주 발생하지만, 발생 원인을 이해하고 예방하면 충분히 방지할 수 있는 문제입니다. 컨트롤러와 보안 설정, 그리고 클라이언트 요청을 꼼꼼히 검토하여 문제를 사전에 차단하세요. 문제 해결보다 예방이 훨씬 효율적입니다.

스프링에서 405 에러는 간단한 실수에서 발생할 수 있지만, 해결책도 간단합니다. 정확한 매핑과 HTTP 메서드 설정, Spring Security와의 연계를 꼼꼼히 점검하여 오류를 방지하세요. 코드 품질을 높이면 405 에러는 더 이상 문제가 되지 않을 것입니다.

저작자표시

티스토리