[Java/Spring Boot] Spring Boot + MyBatis 환경에서 쿼리 조회용 API를 만들기 전에 꼭 고려해야 할 5가지

회사 내부 시스템에서 데이터를 빠르게 조회하기 위한 목적으로 Spring Boot + MyBatis + PostgreSQL 기반 백엔드 앱에 간단한 쿼리 조회용 API를 추가하고자 했습니다.
하지만 단순히 API를 만드는 것만으로 끝나지 않고, 실무에서는 몇 가지 중요한 점들을 반드시 고려해야 한다는 사실을 알게 되었습니다. 이 글에서는 조회용 API를 만들기 전 꼭 고민해야 할 사항들을 정리해봅니다.

1. 보안 이슈

가장 주의해야 할 부분입니다.
조회 전용이라고 해도 다음과 같은 보안 취약점에 노출될 수 있습니다.

• SQL 인젝션 위험: 입력받은 쿼리를 그대로 실행하면 악의적인 요청이 DB를 손상시킬 수 있습니다.
• 인증/인가 없이 데이터 노출: 내부용이라도 인증 없이 공개되면 사용자 정보, 로그 등 민감한 데이터가 쉽게 유출될 수 있습니다.
• API 문서 공개 위험: Swagger나 Postman에 등록된 내부 API가 외부에 노출되면 의도치 않게 내부 구조가 공개될 수 있습니다.

2. 성능 저하

• 복잡한 JOIN이나 대용량 조회 쿼리가 무분별하게 호출되면 DB 성능에 큰 영향을 줄 수 있습니다.
• WHERE 조건 없는 전체 조회 쿼리도 주의가 필요합니다.
• 페이징 처리가 없는 API는 더욱 위험합니다.

3. 유지보수 어려움

• API에서 쿼리를 직접 작성하다 보면 SQL이 난립하고, 도메인 로직과의 경계가 모호해집니다.
• MyBatis XML Mapper가 늘어나면 전체 코드 흐름 파악이 어려워지고 변경 시 영향도가 커집니다.

4. 도메인 무시로 인한 데이터 정합성 문제

• 빠르게 데이터를 조회하고자 도메인 검증 없이 쿼리를 실행하면 정합성이 깨질 가능성이 높습니다.
• 서비스 레이어를 우회한 API 사용은 장기적으로 오류의 원인이 됩니다.

5. 오남용 가능성

• 조회 전용 API가 점점 내부 도구처럼 사용되다 보면, 외부 시스템에서도 연결되어 실서비스처럼 쓰이게 되는 경우가 있습니다.
• 통제가 되지 않는 쿼리 호출은 점점 기술부채가 됩니다.

그럼 어떻게 해야 할까?

실무에서는 아래와 같은 방식으로 쿼리용 API를 설계 및 운영하는 것이 권장됩니다.

1. 사내 전용 인증체계를 갖춘 API로 분리 운영
   → VPN 내부에서만 접근 가능하거나, 인증 토큰을 통한 제어 권장
2. 입력된 SQL을 그대로 실행하지 말고, 사전 정의된 쿼리만 사용
   → 파라미터만 바꿀 수 있도록 제한된 형태로 Mapper 구성
3. 쿼리 사용량 로깅 및 모니터링 적용
   → DB 부하를 사전에 예측하고 이슈 대응 가능
4. Swagger, 문서화 도구는 접근 제한 설정 필수
   → 개발 환경이나 운영툴 별도로 구분
5. BI 도구(예: Metabase, Superset, Redash) 등으로 역할 분리 고려
   → 백엔드 앱이 모든 역할을 떠안기보다는 적절히 분리해서 운영 효율성 확보

마무리하며

편의성과 효율성을 위한 조회용 API는 실무에서 꽤 유용하지만, 잘못 설계되면 보안 취약점이나 시스템 부하, 관리 포인트 증가 등 다양한 문제를 유발할 수 있습니다.
단기적인 편리함보다 장기적인 유지보수성과 보안을 고려한 설계가 무엇보다 중요합니다.
앞으로 유사한 API를 설계할 때 위 내용을 기준 삼아 점검해보시길 추천드립니다.