[JAVA] Spring Boot 실행은 되는데 API 호출이 안 되는 이유

Spring Boot는 정상적으로 실행되는데 API 호출이 되지 않는 경우가 있습니다. 처음 보면 서버가 뜬 것처럼 보이기 때문에 더 혼란스럽습니다.

Spring Boot 실행은 되는데 API 호출이 안 되는 이유

Spring Boot에서 서버는 정상적으로 기동되지만 API 요청이 동작하지 않는 상황은 비교적 자주 발생합니다. 단순한 설정 문제부터 요청 경로, 네트워크, 보안 설정까지 원인이 다양하게 섞여 있는 경우가 많습니다.

이 글에서는 실제로 많이 마주치는 원인을 기준으로 하나씩 짚어보겠습니다. 디버깅 순서대로 확인하면 빠르게 원인을 좁힐 수 있습니다.

 

1. 포트와 서버 기동 상태 확인

가장 먼저 확인해야 할 것은 서버가 실제로 요청을 받을 수 있는 상태인지입니다. 콘솔에 "Started Application" 로그가 찍혔다고 해서 요청이 가능한 상태라고 단정하기는 어렵습니다.

확인 포인트

- application.yml 또는 application.properties의 server.port 값
- 실제 요청하는 포트 번호
- 동일 포트를 다른 프로세스가 사용 중인지 여부

server:
  port: 8081

요청을 8080으로 보내고 있는데 서버는 8081에서 떠 있는 경우도 의외로 많습니다. 처음 환경을 세팅할 때 여기서 한 번씩 막히는 경우가 있습니다.

 

2. Controller 매핑 누락 또는 경로 오류

Spring Boot에서 API가 동작하려면 Controller가 정상적으로 등록되어야 합니다. 이 부분은 코드상으로는 문제가 없어 보이는데 실제 요청이 404로 떨어지는 상황에서 많이 확인하게 됩니다.

자주 발생하는 실수

- @RestController 또는 @Controller 누락
- @RequestMapping 경로 오타
- HTTP Method 불일치 (GET / POST)

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

    @GetMapping("/hello")
    public String hello() {
        return "ok";
    }
}

요청은 /hello로 보내고 있는데 실제 매핑은 /api/hello인 경우도 자주 헷갈립니다. 경로 앞뒤를 정확히 맞추는 것이 중요합니다.

 

3. Component Scan 범위 문제

Controller를 작성했는데도 등록이 안 되는 경우라면 Component Scan 범위를 확인해야 합니다. Spring Boot는 기본적으로 메인 클래스 기준 하위 패키지만 스캔합니다.

문제 상황

- Controller가 메인 클래스보다 상위 패키지에 위치
- 다른 모듈에 존재하는 Controller

이 경우에는 명시적으로 스캔 범위를 지정해줘야 합니다.

@SpringBootApplication(scanBasePackages = "com.example")

패키지 구조를 잘못 잡으면 정상 코드인데도 Bean으로 등록되지 않는 상황이 생깁니다. 협업 환경에서는 특히 이 부분이 더 눈에 띄게 나타납니다.

 

4. Spring Security 설정 영향

Spring Security를 사용하는 경우, API가 막혀 있는 상황을 자주 보게 됩니다. 서버는 정상적으로 떠 있지만 요청은 401 또는 403으로 떨어집니다.

확인해야 할 부분

- 인증 없이 접근 가능한 URL 설정 여부
- CSRF 설정
- 기본 로그인 페이지 리다이렉트 여부

http
  .authorizeHttpRequests()
  .requestMatchers("/api/**").permitAll()
  .anyRequest().authenticated();

보안 설정이 들어가면 API가 막힌 것처럼 보이지만 실제로는 인증 정책에 걸린 경우가 많습니다.

 

5. CORS 설정 문제

프론트엔드에서 API를 호출할 때는 CORS 설정이 영향을 줍니다. 서버에서는 정상 응답을 주고 있지만 브라우저에서 요청을 차단하는 경우입니다.

대표적인 증상

- 브라우저 콘솔에 CORS 에러 발생
- 서버 로그에는 요청이 찍히지 않음

@CrossOrigin(origins = "*")

서버 입장에서는 문제 없어 보이기 때문에 원인을 찾는 데 시간이 걸리는 경우가 많습니다.

 

6. 로컬 네트워크 / 바인딩 주소 문제

서버가 localhost에만 바인딩되어 있으면 외부에서 접근이 되지 않습니다. 특히 Docker나 VM 환경에서는 이 부분을 한 번 더 확인하는 것이 좋습니다.

server:
  address: 0.0.0.0

외부에서 호출해야 하는 상황이라면 반드시 확인해야 하는 설정입니다.

 

정리

Spring Boot가 실행되는데 API 호출이 안 되는 경우는 대부분 다음 범주 안에서 해결됩니다.

- 포트 및 서버 상태 문제
- Controller 매핑 오류
- Component Scan 범위
- Security 설정
- CORS 설정
- 네트워크 바인딩

이 순서대로 확인하면 불필요하게 깊게 파고들지 않고도 빠르게 원인을 찾을 수 있습니다. 실제로는 여러 원인이 동시에 겹치는 경우도 있으니, 하나씩 차근히 제거해 나가는 방식이 효율적입니다.