목록
JEMINI CLI API SERVER 대표 이미지

Gemini Relay API 개발자 문서

안녕하세요! Gemini Relay API 프로젝트에 오신 것을 환영합니다. 이 문서는 프로젝트에 새로 합류하는 개발자, 특히 개발 1년차 주니어 개발자분들이 프로젝트를 빠르게 이해하고 개발을 시작할 수 있도록 돕기 위해 작성되었습니다.

1. 프로젝트 개요

이 프로젝트는 Gemini API와의 통신을 중계(Relay)하는 역할을 하는 백엔드 애플리케이션입니다. 클라이언트로부터 요청을 받아 Gemini API로 전달하고, Gemini API의 응답을 다시 클라이언트로 전달하는 핵심 기능을 수행합니다. 이를 통해 클라이언트와 Gemini API 간의 직접적인 의존성을 줄이고, 보안 및 로깅, 추가적인 비즈니스 로직을 중앙에서 관리할 수 있습니다.

2. 기술 스택

이 프로젝트는 다음과 같은 기술 스택을 기반으로 개발되었습니다.

  • 언어: Java 17 (또는 그 이상)
  • 프레임워크: Spring Boot 3.x
    • Spring Web: RESTful API 개발
    • Spring Security: 인증 및 권한 부여
  • 빌드 도구: Gradle
  • 의존성 관리: Gradle
  • 로깅: Logback (Spring Boot 기본 로깅)
  • JSON 처리: Fastjson (또는 Jackson)
  • 기타: Shell Script (애플리케이션 실행/중지)

3. 프로젝트 구조

프로젝트의 주요 디렉토리 및 파일 구조는 다음과 같습니다.

.
├── build.gradle                # Gradle 빌드 설정 파일
├── gradlew                     # Gradle Wrapper 실행 스크립트 (Linux/macOS)
├── gradlew.bat                 # Gradle Wrapper 실행 스크립트 (Windows)
├── settings.gradle             # Gradle 멀티 프로젝트 설정 파일
├── start.sh                    # 애플리케이션 시작 스크립트
├── stop.sh                     # 애플리케이션 중지 스크립트
├── src/
│   └── main/
│       ├── java/
│       │   └── com/
│       │       └── aiready/
│       │           ├── Application.java      # Spring Boot 애플리케이션 진입점
│       │           ├── config/               # 설정 관련 클래스
│       │           │   └── SecurityConfig.java # Spring Security 설정
│       │           ├── controller/           # REST API 컨트롤러
│       │           │   ├── GeminiController.java # Gemini API 관련 요청 처리
│       │           │   └── RootController.java   # 기본 경로 (/) 요청 처리
│       │           ├── exception/            # 커스텀 예외 및 에러 응답 정의
│       │           │   ├── ApiException.java
│       │           │   └── ErrorResponse.java
│       │           ├── service/              # 비즈니스 로직 처리 서비스
│       │           │   └── GeminiService.java  # Gemini 관련 핵심 로직
│       │           ├── shell/                # 쉘 스크립트 관련 유틸리티
│       │           │   └── ProcessManager.java
│       │           └── util/                 # 공통 유틸리티 클래스
│       │               ├── BigEndianByteHandler.java
│       │               ├── FastJsonUtil.java
│       │               ├── JSONValidator.java
│       │               ├── LittleEndianByteHandler.java
│       │               └── ParamValidator.java
│       └── resources/          # 설정 파일 및 리소스
│           ├── application.yml         # 기본 애플리케이션 설정
│           ├── application-dev.yml     # 개발 환경별 설정 (application.properties도 가능)
│           ├── logback-spring.xml      # Logback 로깅 설정
│           └── ...
└── logs/                       # 애플리케이션 로그 파일 저장
  • src/main/java: 모든 Java 소스 코드가 위치합니다. com.aiready 패키지 아래에 기능별로 모듈화되어 있습니다.
    • Application.java: @SpringBootApplication 어노테이션이 붙어 있으며, 애플리케이션이 시작될 때 가장 먼저 실행되는 클래스입니다.
    • controller: 클라이언트의 HTTP 요청을 받아 처리하는 컨트롤러 클래스들이 있습니다. @RestController 어노테이션을 사용하여 RESTful API를 정의합니다.
    • service: 컨트롤러로부터 전달받은 요청을 바탕으로 실제 비즈니스 로직을 수행하는 서비스 클래스들이 있습니다. @Service 어노테이션이 붙습니다.
    • config: 애플리케이션 전반에 걸친 설정(예: 보안, 데이터베이스 연결 등)을 담당하는 클래스들이 있습니다.
    • exception: 애플리케이션에서 발생하는 예외를 처리하고, 클라이언트에게 일관된 에러 응답을 제공하기 위한 클래스들이 정의되어 있습니다.
    • util: 여러 모듈에서 공통적으로 사용될 수 있는 유틸리티(도우미) 클래스들이 모여 있습니다. (예: JSON 처리, 파라미터 검증, 바이트 핸들링 등)
  • src/main/resources: 애플리케이션의 설정 파일, 로깅 설정 파일 등이 위치합니다.
  • build.gradle: 프로젝트의 의존성(라이브러리) 관리, 빌드 스크립트 정의 등 Gradle 관련 설정이 포함되어 있습니다.

4. 주요 로직 흐름 (Request Flow)

클라이언트의 요청이 Gemini Relay API를 통해 처리되는 일반적인 흐름은 다음과 같습니다.

  1. 클라이언트 요청: 웹 브라우저, 모바일 앱 등 클라이언트가 특정 API 엔드포인트로 HTTP 요청(GET, POST 등)을 보냅니다.
  2. 컨트롤러 (Controller): GeminiController와 같은 컨트롤러 클래스가 요청을 받습니다.
    • 요청 URL과 HTTP 메서드에 매핑되는 컨트롤러 메서드가 실행됩니다.
    • 요청 파라미터나 본문(Body)의 유효성을 검증합니다. (ParamValidator 등 활용)
    • 필요한 경우, 요청 데이터를 가공하여 서비스 계층으로 전달합니다.
  3. 서비스 (Service): GeminiService와 같은 서비스 클래스가 컨트롤러로부터 전달받은 데이터를 바탕으로 핵심 비즈니스 로직을 수행합니다.
    • Gemini API와 통신하여 데이터를 요청하거나 전송합니다.
    • 응답 데이터를 가공하거나 추가적인 처리를 수행합니다.
    • 데이터베이스 연동이 필요한 경우, 해당 로직을 수행합니다 (현재 프로젝트에는 명시적인 DB 연동은 보이지 않으나, 확장 시 서비스 계층에서 담당).
  4. 응답 반환: 서비스 계층에서 처리된 결과는 다시 컨트롤러로 전달되고, 컨트롤러는 이 결과를 HTTP 응답 형태로 클라이언트에게 반환합니다.
    • JSON 형식의 데이터를 반환하는 것이 일반적입니다. (FastJsonUtil 등 활용)

5. 빌드 및 실행 방법

5.1. 프로젝트 빌드

프로젝트를 빌드하여 실행 가능한 JAR 파일을 생성합니다.

  1. 터미널 열기: 프로젝트의 루트 디렉토리(/home/devcosmos/current/2025_jeminicli_relay_api/)에서 터미널을 엽니다.

  2. 빌드 명령 실행: 다음 Gradle 명령어를 실행합니다.

    ./gradlew clean build
    • clean: 이전에 빌드된 파일들을 삭제합니다.
    • build: 프로젝트를 컴파일하고 테스트를 실행하며, 최종적으로 build/libs 디렉토리에 api-0.0.1.jar와 같은 실행 가능한 JAR 파일을 생성합니다.

5.2. 애플리케이션 실행

빌드된 JAR 파일을 직접 실행하거나, 제공된 쉘 스크립트를 사용하여 애플리케이션을 실행할 수 있습니다.

5.2.1. start.sh 스크립트 사용 (권장)

프로젝트 루트에 있는 start.sh 스크립트는 애플리케이션을 편리하게 시작하도록 도와줍니다.

  1. 터미널 열기: 프로젝트의 루트 디렉토리에서 터미널을 엽니다.

  2. 실행 스크립트 실행:

    sh start.sh
    • 이 스크립트는 일반적으로 java -jar 명령어를 사용하여 빌드된 JAR 파일을 실행합니다.
    • application-dev.yml과 같은 개발 환경 설정을 자동으로 로드하도록 구성되어 있을 수 있습니다.

5.2.2. JAR 파일 직접 실행

start.sh 스크립트가 없는 경우, 빌드된 JAR 파일을 직접 실행할 수 있습니다.

  1. JAR 파일 경로 확인: build/libs 디렉토리에서 생성된 JAR 파일(예: api-0.0.1.jar)의 정확한 이름을 확인합니다.

  2. 실행 명령 실행:

    java -jar build/libs/api-0.0.1.jar
    • 특정 프로파일(예: 개발 환경)로 실행하려면 다음과 같이 -Dspring.profiles.active 옵션을 추가합니다.
      java -jar -Dspring.profiles.active=dev build/libs/api-0.0.1.jar

5.3. 애플리케이션 중지

stop.sh 스크립트를 사용하여 실행 중인 애플리케이션을 중지할 수 있습니다.

  1. 터미널 열기: 프로젝트의 루트 디렉토리에서 터미널을 엽니다.

  2. 중지 스크립트 실행:

    sh stop.sh
    • 이 스크립트는 실행 중인 Java 프로세스를 찾아 종료합니다.

6. 설정 (Configuration)

Spring Boot 애플리케이션의 설정은 주로 src/main/resources 디렉토리의 application.yml (또는 application.properties) 파일을 통해 관리됩니다.

  • application.yml: 모든 환경에 공통적으로 적용되는 기본 설정을 정의합니다.
  • application-{profile}.yml: 특정 환경(예: dev, prod, test)에만 적용되는 설정을 정의합니다. 예를 들어, application-dev.yml은 개발 환경에서만 로드되며, application.yml의 설정을 덮어쓸 수 있습니다.
    • 개발 환경에서 애플리케이션을 실행할 때는 start.sh 스크립트가 자동으로 dev 프로파일을 활성화하거나, 위에서 설명한 java -jar -Dspring.profiles.active=dev 명령어를 사용할 수 있습니다.

주요 설정 예시:

# application.yml 예시
server:
  port: 8080 # 애플리케이션이 실행될 포트 번호

spring:
  application:
    name: gemini-relay-api # 애플리케이션 이름
  # ... 기타 Spring 관련 설정

팁: 민감한 정보(예: API 키)는 application.yml에 직접 하드코딩하기보다는 환경 변수나 Spring Cloud Config와 같은 외부 설정 관리 도구를 사용하는 것이 좋습니다.

7. API 엔드포인트

controller 패키지에 정의된 주요 API 엔드포인트는 다음과 같습니다.

7.1. RootController.java

  • GET /: 애플리케이션의 상태를 확인하거나 간단한 환영 메시지를 반환하는 엔드포인트입니다. 주로 헬스 체크 용도로 사용될 수 있습니다.

7.2. GeminiController.java

이 컨트롤러는 Gemini API와의 상호작용을 위한 핵심 엔드포인트를 제공합니다.

  • POST /gemini/prompt:
    • 설명: 클라이언트로부터 Gemini 모델에 전달할 프롬프트(질문)를 받아 Gemini API로 전달하고, 그 응답을 클라이언트에게 반환합니다.
    • 요청 본문 (Request Body):
      {
  "prompt": "Gemini 모델에게 질문할 내용"
}
    • 응답 본문 (Response Body):
      {
  "response": "Gemini 모델의 응답 내용",
  "timestamp": "2025-10-22T10:00:00Z"
}
    • 오류 처리: Gemini API 통신 중 오류가 발생하거나 요청 데이터가 유효하지 않을 경우, exception 패키지에 정의된 ErrorResponse 형식으로 오류 메시지를 반환합니다.

8. 유틸리티 클래스 (util 패키지)

src/main/java/com/aiready/util 패키지에는 여러 곳에서 재사용될 수 있는 유용한 도우미 클래스들이 포함되어 있습니다.

  • FastJsonUtil.java: JSON 직렬화(객체를 JSON 문자열로 변환) 및 역직렬화(JSON 문자열을 객체로 변환)를 위한 유틸리티입니다.
  • JSONValidator.java: JSON 데이터의 유효성을 검증하는 기능을 제공합니다.
  • ParamValidator.java: API 요청 시 전달되는 파라미터들의 유효성을 검증하는 데 사용됩니다. (예: 필수 값 누락 여부, 형식 검증 등)
  • BigEndianByteHandler.java, LittleEndianByteHandler.java: 바이트 배열을 다룰 때 빅 엔디안(Big-Endian) 또는 리틀 엔디안(Little-Endian) 방식으로 데이터를 처리하는 유틸리티입니다. 특정 프로토콜이나 데이터 형식 처리 시 유용합니다.

9. 개발 가이드라인

  • 코드 컨벤션: 기존 코드의 스타일(들여쓰기, 변수명, 주석 등)을 따르세요. 일관된 코드 스타일은 가독성을 높입니다.
  • 테스트 코드: 새로운 기능을 추가하거나 버그를 수정할 때는 관련 테스트 코드를 작성하거나 업데이트하는 것을 권장합니다.
  • 로깅: 디버깅 및 운영 시 문제 파악을 위해 적절한 위치에 로깅을 추가하세요. logback-spring.xml 설정을 참고하여 로깅 레벨을 조절할 수 있습니다.
  • 보안: API 키나 민감한 정보는 코드에 직접 노출하지 않도록 주의하고, 환경 변수 등을 통해 관리하세요.
  • 문서 업데이트: 기능 변경이나 새로운 기능 추가 시, 이 개발자 문서를 포함하여 관련 문서를 최신 상태로 유지해 주세요.

이 문서가 프로젝트 이해에 도움이 되기를 바랍니다. 궁금한 점이 있다면 언제든지 동료 개발자에게 질문해 주세요!

#JEMINI #API 서버 #AI 채팅