[CHORE] 전역 프리픽스 추가

[catomat0]

📌 PR 개요

• 프리픽스 추가

---

🔗 관련 이슈

• Closes [CHORE] 엔드포인트 프리픽스 추가 #201

---

🛠 변경 사항

• WebConfig - 컨트롤러에 프리픽스 추가
• SecurityConfig - 프리픽스 추가한 경로로 수정

---

⚠️ 리뷰 시 참고 사항

• 프론트에 경로 수정했다고 배포 이후에 전달하겠습니다.

---

✅ 체크리스트

• 로컬에서 정상 실행됨
• 로그 / 네이밍 정리
• main / develop 직접 커밋 아님

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: c5b063fd-1555-4b0a-9147-947f3c6e29fa

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/#201-prefix

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[catomat0]

@CodeRabbit 전역 프리픽스 이렇게 설정하는지 알려줘 그리고 사이드이펙트 고려해줘

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Find WebConfig and SecurityConfig files
fd -e java "WebConfig|SecurityConfig" --exec cat {}

Length of output: 5502

---

🏁 Script executed:

#!/bin/bash
echo "=== Controllers with `@RequestMapping` containing /api/v1 (double-prefix risk) ==="
rg -n --type java 'RequestMapping.*api/v1' -A2 -B2

echo ""
echo "=== All `@RestController` classes and their packages ==="
rg -n --type java '@RestController' -A3 -B1

echo ""
echo "=== springdoc / swagger config ==="
fd -e yaml -e properties -e yml . | xargs grep -l "springdoc\|swagger" 2>/dev/null | xargs cat 2>/dev/null

echo ""
echo "=== Controllers NOT in com.deare.backend.api package ==="
rg -n --type java '@RestController' -l | xargs grep -L 'package com.deare.backend.api'

Length of output: 9155

---

@catomat0 코드 분석 결과를 정리했습니다.

---

✅ 전역 프리픽스 설정 방식 분석

현재 설정 방식

WebConfig 에서 PathMatchConfigurer.addPathPrefix() 를 사용하는 방식입니다.

configurer.addPathPrefix(
    "/api/v1",
    c -> c.isAnnotationPresent(RestController.class)
            && c.getPackageName().startsWith("com.deare.backend.api")
);

적용 조건: @RestController 어노테이션이 있고, 패키지가 com.deare.backend.api로 시작하는 클래스에만 적용됩니다.

현재 설정이 잘 된 부분 ✅

항목	상태
더블 프리픽스 위험	없음 — 컨트롤러에 /api/v1 하드코딩 없음
모든 컨트롤러 패키지	com.deare.backend.api 하위에 존재 → 조건 정상 작동
GlobalExceptionHandler	@RestControllerAdvice (global 패키지) → 프리픽스 미적용 (정상)
@RestControllerAdvice (UserExceptionHandler 등)	@RestController 아님 → 프리픽스 미적용 (정상)
/actuator/**, /oauth2/**	com.deare.backend.api 패키지 아님 → 프리픽스 미적용 (정상)

---

⚠️ 사이드이펙트 및 주의사항

1. Swagger UI 경로 표시 문제 (가장 중요)

springdoc-openapi 관련 설정 파일이 없습니다. addPathPrefix를 쓰면 springdoc가 자동으로 반영하긴 하지만, 버전에 따라 Swagger UI에서 서버 URL이 잘못 표시될 수 있습니다. 아래 설정 추가를 권장합니다:

# application.yml
springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
  default-flat-param-object: true

또는 OpenAPI 빈으로 서버 URL 명시:

`@Bean`
public OpenAPI openAPI() {
    return new OpenAPI()
        .addServersItem(new Server().url("/api/v1"));
}

2. WebConfig ↔ SecurityConfig 수동 동기화 필요

현재 SecurityConfig에 경로가 하드코딩되어 있어, 프리픽스가 변경될 경우 두 파일 모두 수정해야 합니다. 상수로 분리하면 유지보수가 편해집니다:

// 공통 상수로 분리
public class ApiConstants {
    public static final String API_PREFIX = "/api/v1";
}

3. 테스트 코드 경로 깨짐

MockMvc 또는 @WebMvcTest 기반의 통합 테스트가 있다면, 기존에 /users, /auth 등으로 테스트하던 코드가 전부 /api/v1/users, /api/v1/auth로 수정되어야 합니다.

4. ImageController 조건부 등록

ImageController는 @ConditionalOnProperty(name = "aws.s3.enabled", havingValue = "true")가 붙어있어, S3가 비활성화 환경에서는 빈이 등록되지 않습니다. 그러나 SecurityConfig에는 항상 /api/v1/images/**가 permit되어 있습니다 — 보안상 큰 문제는 아니지만, S3 미사용 환경에서는 해당 경로가 404를 반환합니다.

5. LetterOcrController와 LetterController 경로 충돌 (기존 이슈)

두 컨트롤러가 모두 /letters를 매핑하고 있어, 메서드 레벨 경로가 겹칠 경우 AmbiguousRequestMappingException 이 발생할 수 있습니다. (이번 PR 도입 이슈는 아니지만 확인 필요)

---

대안 비교

방식	장점	단점
현재: addPathPrefix (WebConfig)	선택적 적용 가능, 컨트롤러 코드 수정 불필요	SecurityConfig와 수동 동기화 필요
server.servlet.context-path=/api/v1	설정 한 줄로 끝	Actuator, Swagger에도 적용되어 별도 처리 필요
각 컨트롤러 @RequestMapping("/api/v1/...")	명시적	반복 코드, 리팩토링 어려움

현재 방식은 합리적인 선택입니다. 위의 Swagger 설정과 상수 분리만 추가로 챙겨주시면 더 안정적인 구조가 될 것입니다. 🙂