Spring AI를 배우기 전에 정리할 것

프론트엔드도 알아야 하지만, 백엔드는 조금 더 깊게 파고들고 싶다. 기술을 한 가지만 고르기보다 여러 기술을 경험하되, 결국에는 내가 잘 아는 도메인 하나를 만들어야 한다.

그 전에 객체 지향, Spring Boot의 계층 구조, 그리고 AI 기능이 어디에 들어가는지를 한 흐름으로 정리해 본다.

객체 지향: 캡, 추, 다, 상

객체 지향의 핵심은 클래스로 만든 객체가 자기 역할을 가지고 협력하게 하는 것이다. 외우기 쉽게 캡, 추, 다, 상이라고 정리할 수 있다.

interface Payment {
    void pay(int amount);
}

class CardPayment implements Payment {
    @Override
    public void pay(int amount) {
        System.out.println("카드로 " + amount + "원 결제");
    }
}

class TransferPayment implements Payment {
    @Override
    public void pay(int amount) {
        System.out.println("계좌이체로 " + amount + "원 결제");
    }
}

Payment payment = new CardPayment();
payment.pay(10_000); // 같은 pay(), 다른 동작

LLM 기본 용어

AI를 붙이기 전에 모델이 무엇을 기준으로 동작하는지 알아야 한다.

임베딩, 벡터 검색, RAG

임베딩이란?

임베딩은 문장을 의미를 담은 숫자 배열, 즉 벡터로 바꾸는 것이다. 뜻이 비슷한 문장은 벡터 공간에서도 가까워진다.

예를 들어 사용자가 휴가 내는 법이라고 물어도, 문서에 연차 신청 규정이라고 적혀 있으면 의미가 가까워서 찾을 수 있다. 단어가 정확히 같지 않아도 검색할 수 있다는 점이 핵심이다.

RAG란?

RAG, Retrieval-Augmented Generation는 질문과 관련된 문서를 먼저 찾고, 그 근거를 모델에게 함께 주어 답하게 하는 방식이다. 모델을 다시 학습하지 않아도 문서를 교체하거나 추가해서 지식을 갱신할 수 있다.

문서 파일
  → 읽기
  → 청킹
  → 임베딩
  → VectorStore에 저장

사용자 질문
  → 질문 임베딩
  → 유사한 문서 검색
  → 검색 결과를 프롬프트에 추가
  → 모델 답변 + 출처 반환

도구와 에이전트

모델은 직접 DB를 수정하거나 이메일을 보내지 않는다. 모델은 어떤 도구를 호출할지 판단하고, 실제 실행은 우리 코드가 담당한다.

Spring Boot 기초: 계층 구조와 어노테이션

왜 계층을 나눌까?

계층을 나누는 이유는 문제가 생겼을 때 바꿔야 할 부분만 고치기 위해서다. 화면 요구가 바뀌면 Controller, 업무 규칙이 바뀌면 Service, 저장 방식이 바뀌면 Repository나 Mapper를 중심으로 수정한다.

HTTP 요청
  → Controller: 받고, 검증하고, DTO로 응답한다
  → Service: 업무 흐름과 트랜잭션을 결정한다
  → Repository 또는 Mapper: DB와 외부 시스템에 접근한다
  → DB / 외부 API

요청 하나가 지나가는 흐름

GET /ch02/orders/12345?userId=user1 요청을 예로 들면 다음과 같다.

1. OrderController가 @PathVariable, @RequestParam, @Valid로 값을 받는다.
2. OrderService에 주문 번호와 사용자 ID처럼 필요한 값만 전달한다.
3. OrderRepository 또는 OrderMapper가 권한 조건을 포함해 데이터를 조회한다.
4. 엔티티나 조회 결과를 응답 DTO로 변환한다. 원가나 소유자 ID처럼 외부에 보이면 안 되는 값은 제외한다.
5. Controller가 DTO를 JSON으로 반환한다.

400은 주로 입력 검증, 404는 업무상 대상 없음, 500은 DB 연결이나 예상하지 못한 오류에서 많이 발생한다. 하지만 실제 상태 코드는 서비스의 정책과 예외 처리 방식에 따라 정해야 한다.

자주 쓰는 어노테이션

@SpringBootApplication은 설정 클래스, 컴포넌트 스캔, 자동 구성을 묶어 둔 시작점이다. Spring AI 스타터를 추가했을 때 관련 Bean이 자동으로 준비되는 것도 이 자동 구성 흐름에 올라탄다.

@Service, @Repository, @Controller는 모두 @Component의 구체적인 표현이다. 이름만 봐도 역할을 알 수 있게 해 주며, @Repository는 DB 접근 예외를 Spring의 예외 체계로 변환하는 의미도 가진다.

Bean과 의존성 주입

Bean은 Spring이 만들어 관리하는 객체다. 기본 스코프는 singleton이라서 애플리케이션 전체에서 보통 하나만 만든다. 그래서 Service의 필드에 사용자별 값이나 요청별 상태를 저장하면 안 된다.

@Service
public class OrderService {

    private final OrderRepository repository;

    public OrderService(OrderRepository repository) {
        this.repository = repository;
    }

    public OrderResponse findOrder(String orderId, String userId) {
        return repository.findByIdAndOwnerId(orderId, userId)
                .map(OrderResponse::from)
                .orElseThrow(() -> new OrderNotFoundException(orderId));
    }
}

필드에는 Repository처럼 바뀌지 않는 협력 객체를 두고, 주문 번호나 사용자 ID 같은 요청별 값은 메서드 파라미터로 받는다.

DTO와 엔티티는 분리한다

엔티티는 DB 구조와 연결된 내부 모델이고, DTO는 API에서 주고받는 데이터 모양이다. 엔티티를 그대로 반환하면 DB 구조가 API 규격이 되고, 원가나 소유자 ID 같은 내부 정보가 실수로 노출될 수 있다.

public record CreateOrderRequest(
        @NotBlank String productId,
        @Min(1) @Max(99) int quantity,
        @Size(max = 200) String memo
) {
}

public record OrderResponse(
        String orderId,
        String item,
        String status,
        LocalDate eta
) {
    public static OrderResponse from(Order order) {
        return new OrderResponse(
                order.getId(),
                order.getItem().getName(),
                order.getStatus().name(),
                order.getEta()
        );
    }
}

@Entity
class Order {
    @Id
    private String id;
    private String ownerId;      // 내부 전용
    private BigDecimal cost;     // 외부에 노출하면 안 되는 원가
}

DTO 변환 위치는 팀 규칙에 따라 다를 수 있지만, 중요한 것은 한 방향으로 일관되게 두는 것이다. 위 예시는 응답 DTO의 from() 메서드에 변환을 모았다.

JPA Repository와 MyBatis Mapper

둘 다 데이터를 다루지만 기준은 다르다. 객체와 엔티티의 상태 변경이 중심이면 JPA가 편하고, 복잡한 SQL을 직접 제어해야 하면 MyBatis Mapper가 편하다. 한 프로젝트에서 함께 써도 된다.

// JPA
@Entity
public class User {
    @Id
    @GeneratedValue
    private Long id;
    private String name;
}

public interface UserRepository extends JpaRepository<User, Long> {
}

userRepository.save(user);
userRepository.findById(1L);

// MyBatis
@Mapper
public interface UserMapper {

    @Select("SELECT id, name FROM users WHERE id = #{id}")
    User findById(Long id);

    @Insert("INSERT INTO users(name) VALUES(#{name})")
    void save(User user);
}

userMapper.save(user);
userMapper.findById(1L);

Service 입장에서는 둘 다 저장소 역할을 하는 협력자다. 다만 실제 권한 조건은 조회한 뒤 자바에서 거르는 것보다, 쿼리 조건에 포함해서 처음부터 가져오지 않게 하는 편이 안전하다.

Spring AI는 어디에 둘까?

AI를 Controller에 바로 붙이면 처음에는 빨라 보이지만, 프롬프트, 도구, 보안, 메모리, 검색 정책이 섞여 나중에 관리하기 어려워진다.

Controller
  → Service
    → ChatClient
      → Advisor 체인
        → 필요하면 RAG 검색, Tool 호출

• Controller는 질문과 세션 ID를 받고 서비스만 호출한다.
• Service는 업무 규칙에 맞게 프롬프트와 도구 사용 여부를 결정한다.
• Config와 Advisor는 모델 설정, 메모리, 보안, 감사처럼 공통으로 필요한 일을 맡는다.
• RAG는 문서 인제스트, 검색, 근거 조립을 맡는다.

/api/chat 요청 한 번의 흐름

POST /api/chat
  → ChatController: 인증 확인, 질문과 세션 ID 전달
  → AuditAdvisor: 감사 기록 시작
  → SafetyAdvisor: 위험 입력 차단
  → MemoryAdvisor: 같은 세션의 대화 이력 추가
  → RetrievalService: 관련 문서 검색, 근거 추가
  → HelpDeskService: 프롬프트 조립, 모델 호출
  → OrderTools: 모델이 필요할 때만 주문 정보 조회
  → TokenMeter: 토큰과 지연 시간 기록
  → AnswerDto: 답변, 출처, 도구 사용 여부를 반환

여기서 순서가 중요하다. 안전 검사는 메모리 저장이나 외부 도구 호출보다 먼저 실행해야 한다. 그리고 주문 정보의 권한 검증은 프롬프트가 아니라 Repository 쿼리나 Tool의 실제 코드에서 다시 확인해야 한다.

Spring AI의 세 가지 핵심 추상화

Spring AI는 특정 AI 공급자의 SDK에 바로 묶이지 않도록 공통 인터페이스를 제공한다. 중심에는 ChatModel, EmbeddingModel, VectorStore가 있다. 실무에서는 저수준 ChatModel을 직접 쓰기보다 ChatClient로 감싸 사용하는 경우가 많다.

@Service
public class EmbedService {

    private final EmbeddingModel embeddingModel;

    public EmbedService(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    public float[] embed(String text) {
        return embeddingModel.embed(text);
    }
}

이 세 가지를 조합하면 챗봇, 문서 검색, RAG, 도구를 사용하는 에이전트까지 확장할 수 있다.

공급자 독립성과 옵션

내 코드는 ChatClient, ChatModel 같은 Spring AI 추상화에 의존하고, 실제 모델 선택은 스타터 의존성과 application.yml에서 한다. 그래서 공통 기능만 쓴다면 개발 환경은 가벼운 모델, 운영 환경은 더 성능 좋은 모델로 비교적 쉽게 바꿀 수 있다.

공급자 고유 옵션은 필요한 경우에만 쓴다. 그 옵션을 쓰는 코드만큼은 해당 공급자에 의존하게 된다는 점을 알고 경계를 나누면 된다.

핵심만 다시 정리