어드민 API 7개와 Bearer 인증을 처음부터 제대로 설계한 이유
목차
단계 어드민 API 7개를 한 번에 설계하고 Bearer token 인증까지 붙인 작업이었다.
왜 어드민 API를 별도로 설계했나
서비스 운영이 궤도에 오르면 반드시 맞닥뜨리는 문제가 있다. 일반 사용자 API와 운영자 API가 뒤섞이기 시작하는 시점이다. 초반엔 "어드민도 그냥 같은 엔드포인트 쓰면 되지"라는 유혹이 강하다. 속도가 빠르고 코드 중복도 줄어드니까. 하지만 운영 요구사항이 하나씩 붙기 시작하면 얘기가 달라진다. 일반 사용자에겐 보여선 안 되는 필드, 운영자만 가능한 수정 권한, 감사 로그, 배치 처리 등 — 이게 전부 일반 API에 if 분기로 박히기 시작하면 나중엔 손댈 수가 없어진다.
이번 작업에서 어드민 API를 /controller/admin/ 하위로 물리적으로 분리한 건 그 이유다. 패키지 분리 자체가 일종의 경계선이다. 팀원들이 코드를 볼 때 "이 컨트롤러는 운영자 전용"이라는 걸 별도 설명 없이도 알아챌 수 있어야 한다.
Bearer token 인증 구성
이번에 SecurityConfig.java를 수정하면서 어드민 API 경로에 Bearer token 인증을 붙였다.
// SecurityConfig 일부 패턴 (일반론)
.requestMatchers("/api/admin/**").authenticated()
.requestMatchers("/api/public/**").permitAll()
Bearer token 방식은 세션 기반 인증보다 어드민 도구에 더 잘 맞는다. 이유는 단순한데, 어드민 클라이언트가 꼭 브라우저일 필요가 없기 때문이다. curl, Postman, 내부 스크립트 등 다양한 클라이언트에서 호출할 수 있어야 하고, 세션 관리 오버헤드를 줄이는 게 낫다. 토큰을 Authorization 헤더에 담아 넘기는 방식은 stateless하기 때문에 서버 확장에도 자유롭다.
주의할 점은 SecurityConfig에서 어드민 경로를 명시적으로 선언하지 않으면, 기본 설정에 따라 의도치 않게 퍼블릭으로 열리거나 반대로 다른 경로가 막히는 사이드 이펙트가 생긴다는 거다. 이런 설정 파일은 PR 리뷰 때 항상 한 번 더 들여다보라고 팀에 강조하는 편이다. 로직 버그는 테스트로 잡히는데, 보안 설정 구멍은 테스트가 없으면 잘 안 잡힌다.
7개 API 구성과 DTO 설계
변경된 파일 목록을 보면 구조가 보인다.
| 레이어 | 파일 | 역할 |
|---|---|---|
| Config | SecurityConfig.java |
어드민 경로 인증 규칙 |
| Config | 내부 클래스 | Bean 설정 (필터 체인 등) |
| Controller | admin/내부 클래스 |
어드민 엔드포인트 7개 |
| DTO | DailyPickAdminRequest.java |
운영자 요청 모델 |
| DTO | DailyPickAdminResponse.java |
운영자 응답 모델 |
DTO를 Request/Response로 분리한 건 당연해 보이지만 실제로 이걸 지키지 않는 코드를 많이 봤다. 같은 클래스를 요청/응답에 재사용하면 처음엔 편한데, 나중에 응답에만 필요한 필드나 요청에만 필요한 validation이 같은 클래스 안에서 충돌하기 시작한다. DailyPickAdminRequest와 DailyPickAdminResponse를 처음부터 분리한 건 이런 미래 부채를 줄이기 위한 선택이었다.
어드민 API 7개를 설계할 때 주로 고민하는 건 조회/생성/수정/삭제 이외에 "운영자만 필요한 배치성 액션"을 어떤 형태로 노출할지다.
GET /admin/daily-picks— 목록 조회POST /admin/daily-picks— 새 항목 등록PATCH /admin/daily-picks/{id}— 수정DELETE /admin/daily-picks/{id}— 삭제- 나머지 3개는 상태 변경, 단계 관리, 또는 bulk 처리 류
이런 구성이 대부분 "단계 관리"가 들어가는 어드민에서 반복되는 패턴이다.
회고
어드민 API는 외부에 노출되지 않는다는 이유로 품질 관리에서 뒷전이 되는 경우가 많다. "어차피 운영자만 쓰니까"라는 마인드가 쌓이면 어느 순간 어드민 코드가 서비스에서 가장 허술한 영역이 된다. 인증 구멍, 느슨한 validation, 에러 핸들링 부재 — 이게 실제로 운영 장애로 이어지는 경로가 된다.
이번 작업에서 처음부터 경로 분리, DTO 분리, Bearer 인증을 제대로 잡아놓은 건 팀 코드 품질 기준을 맞추기 위한 기준점 역할이기도 했다. 이후에 어드민 기능이 추가될 때 "기존 패턴 따라가면 된다"는 말이 자연스럽게 나올 수 있도록.
끝.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.