내일 한걸음 더

[CS]권한마다 보안 솔루션이 다르다면? 하이브리드 환경에서 우아하게 파일 보호하기

Anna-Jin — Tue, 7 Jul 2026 21:14:54 +0900

시간이 좀 흘렀지만 작년 말 사내 기술블로그에 투고한 글을 드디어 블로그에 남겨본다.

백오피스를 주로 담당하면서 파일 보호 및 암호화와 관련 레거시 솔루션을 (나름 업계에서는 유명하다고 하는...) 모던 솔루션으로 전환하면서 고민한 내용을 담고 있다.

어떻게 보면 기본적인 패턴과 방식일 수도 있겠지만 누군가에게는 도움이 되지 않을까하여 주제로 다뤄보았다.

레거시 솔루션과 하이브리드로 동작해야하는 환경이었는데 레거시 솔루션이 mac 환경에서는 동작하지 않아서 애를 좀 먹었던 일과 솔루션 전환 과정에서 QA 엔지니어 분들과 밤 늦게까지 수십개의 화면이 정상적으로 동작하는 지 테스트했던 과정들이 기억에 남는다.

누군가에게는 도움이 되기를 바라며...

https://oliveyoung.tech/2025-12-26/protection-switch/

권한마다 보안 솔루션이 다르다면? 하이브리드 환경에서 우아하게 파일 보호하기 | 올리브영 테

전략 패턴과 AOP로 비즈니스 로직과 보안 정책 깔끔하게 분리하기

oliveyoung.tech

아래는 블로그에 투고한 글을 그대로 남긴 내용이므로 링크에서 읽어보는걸 추천드린다.

1. 들어가며: 변화의 지침과 현실적인 제약

올리브영의 오프라인 매장 운영을 책임지는 백오피스 시스템은 매일 수많은 엑셀과 PDF 문서를 생성하고 처리합니다. 그동안 우리는 이 문서들을 보호하기 위해 표준화된 설치형 에이전트(Agent) 보안 솔루션을 사용하여 파일을 암호화해 왔습니다.

최근 전사 보안 정책이 고도화됨에 따라, 문서 보안 체계를 신규 클라우드 기반 보안 시스템으로 전환하게 되었습니다. 이에 따라 백오피스 시스템 내 파일 암호화가 적용된 모든 영역을 새로운 방식으로 전환해야 했습니다.

하지만 분석 단계에서 중요한 현실적 제약에 직면했습니다. 신규 도입된 클라우드 보안 시스템은 라이선스 및 인프라 구조상 '본사 구성원'에게만 지원된다는 점이었습니다.

백오피스 시스템은 본사 구성원뿐만 아니라, 매장에서 근무하는 '매장 구성원'이나 외부 '협력사'들도 빈번하게 사용합니다. 결국, 우리는 두 가지 보안 체계를 동시에 운영해야 하는 상황이 되었습니다.

본사 임직원: 신규 클라우드 기반 보안 (Type A)
그 외 (매장/협력사): 기존 에이전트 기반 보안 (Type B)

즉, "로그인한 사용자의 권한(Role)에 따라 적절한 암호화 솔루션을 동적으로 선택하여 적용"해야 하는 과제가 주어진 것입니다.

2. 해결책 탐색: 왜 전략 패턴인가?

처음부터 전략 패턴을 떠올린 건 아니었습니다. 가장 먼저 떠오른 건 역시 단순한 if-else 분기였습니다.

2.1. 첫 번째 시도: 단순 if-else 분기

"일단 돌아가게 만들자"는 생각으로 빠르게 프로토타입을 작성해봤습니다.

// 첫 번째 시도: 단순 if-else
public byte[] downloadSalesReport(User user) {
    byte[] excelData = excelService.createExcel();

    if (user.isHeadquarters()) {
        // 클라우드 API 호출
        return cloudSecurityApi.encrypt(excelData, user.getId());
    } else {
        // 에이전트 라이브러리 호출
        return agentSecurityLib.protect(excelData);
    }
}

간단해 보이지만, 실제로 적용하려니 문제가 보이기 시작했습니다.

백오피스 시스템에는 파일을 다운로드하는 API가 수십 개에 달했습니다. 매출 리포트, 재고 현황, 발주서, 정산 내역... 이 모든 곳에 동일한 if-else 로직을 복붙해야 했습니다. 그리고 만약 향후 제3의 보안 솔루션이 추가된다면? 수십 개의 파일을 다시 찾아다니며 else if를 추가해야 하는 악몽이 그려졌습니다.

2.2. 두 번째 시도: 별도 서비스 클래스로 분리

그렇다면 암호화 로직을 별도 서비스로 분리하면 어떨까요?

// 두 번째 시도: 서비스 클래스 분리
@Service
public class FileEncryptionService {

    public byte[] encrypt(byte[] data, User user) {
        if (user.isHeadquarters()) {
            return cloudSecurityApi.encrypt(data, user.getId());
        } else {
            return agentSecurityLib.protect(data);
        }
    }
}

// 사용하는 쪽
public byte[] exportExccel(User user) {
    byte[] excelData = excelService.createExcel();
    return fileEncryptionService.encrypt(excelData, user);  // 호출 필요
}

if-else가 한 곳으로 모이긴 했지만, 여전히 두 가지 문제가 남았습니다.

호출 누락 위험: 모든 다운로드 메서드에서 fileEncryptionService.encrypt()를 명시적으로 호출해야 합니다. 신규 API를 만들 때 깜빡하면? 암호화되지 않은 파일이 그대로 내려갑니다.
OCP 위반: 새로운 보안 솔루션이 추가되면 FileEncryptionService 내부를 수정해야 합니다. "확장에는 열려 있고, 수정에는 닫혀 있어야 한다"는 개방-폐쇄 원칙(OCP)에 어긋납니다.

2.3. 세 번째 시도: 팩토리 패턴?

잠깐, 팩토리 패턴은 어떨까요? 사용자 타입에 따라 적절한 암호화 객체를 생성해서 반환하면 되지 않을까요?

// 팩토리 패턴 검토
public class EncryptorFactory {
    public Encryptor create(User user) {
        if (user.isHeadquarters()) {
            return new CloudEncryptor();
        } else {
            return new AgentEncryptor();
        }
    }
}

팩토리 패턴은 객체 생성에 초점을 맞춘 패턴입니다. 반면 우리가 필요한 건 이미 존재하는 암호화 구현체 중 하나를 선택하는 것이었습니다.

매번 new로 객체를 생성하는 방식은 여러 측면에서 적합하지 않았습니다.

Spring 컨테이너 외부의 객체: new로 생성한 객체는 Spring 컨테이너가 관리하지 않습니다. 이 말은 @Autowired를 통한 의존성 주입, AOP 프록시, 트랜잭션 관리 등 Spring이 제공하는 이점을 전혀 활용할 수 없다는 의미입니다. 실제로 우리의 암호화 구현체들은 내부적으로 다른 Spring 빈(API 클라이언트, 설정 정보 등)에 의존하고 있었기에 이는 치명적인 단점이었습니다.
싱글톤 빈의 설계 철학과 불일치: Spring의 기본 빈 스코프는 싱글톤입니다. 애플리케이션 전체에서 하나의 인스턴스만 생성하여 재사용함으로써 메모리 효율성과 일관성을 보장합니다. 팩토리 패턴으로 매번 새 인스턴스를 생성하는 것은 이러한 Spring의 설계 철학에 역행하는 방식이었습니다.

결론적으로, 우리에게 필요한 것은 "객체를 생성"하는 것이 아니라 "이미 Spring 컨테이너가 관리하고 있는 싱글톤 빈 중 적절한 것을 선택"하는 것이었습니다. 이 요구사항에 가장 부합하는 패턴이 바로 전략 패턴이었습니다.

2.4. 결론: 전략 패턴 + AOP 조합

고민 끝에 내린 결론은 전략 패턴과 AOP의 조합이었습니다.

전략 패턴: 암호화 방식을 인터페이스로 추상화하고, 각 구현체를 독립적으로 관리합니다. 새로운 보안 솔루션이 추가되면 기존 코드 수정 없이 구현체만 추가하면 됩니다.
AOP: 개발자가 명시적으로 암호화 메서드를 호출할 필요 없이, 어노테이션 하나로 자동 적용됩니다. 호출 누락의 위험이 사라집니다.

방식중복 제거확장성누락 방지채택

if-else 분기	X	X	X	-
서비스 클래스 분리	O	X	X	-
팩토리 패턴	O	△	X	-
전략 패턴 + AOP	O	O	O	채택

3. 기술적 설계: 전략 패턴을 통한 추상화

전략 패턴이 낯선 분들을 위해 설명드리자면, 전략 패턴은 '게임기'와 '게임 팩'의 관계로 비유할 수 있습니다. 게임기(비즈니스 로직)는 꽂는 팩(전략: 클라우드 보안 또는 에이전트 보안)의 종류에 따라 플레이할 게임(암호화 방식)이 달라지죠. 이와 유사하게 우리는 사용자가 누구냐에 따라 알맞은 전략을 자동으로 반영하는 시스템을 설계했습니다.

3.1. 전략 인터페이스와 구현체

먼저 FileProtectionStrategy라는 인터페이스(규격)를 정의하고, 각각의 보안 방식을 따르는 구현체(게임 팩)를 만들었습니다. 이렇게 하면 향후 또 다른 보안 솔루션이 추가되더라도 기존 코드를 수정할 필요 없이 새로운 구현체만 추가하면 됩니다.

public interface FileProtectionStrategy {

    /** 전략 식별자 (예: "CLOUD", "AGENT") */
    String getType();

    /** 파일 보호(암호화) 처리 */
    byte[] protect(byte[] inputBytes, String fileName);

    /** 파일 보호 해제(복호화) 처리 */
    byte[] unprotect(byte[] protectedBytes);
}

각각의 구현체는 전략에 맞는 API 혹은 라이브러리를 호출하여 실제 암호화를 수행합니다.

/**
 * 전략 A: 신규 클라우드 보안 구현체
 */
@Component
public class CloudFileProtectionStrategy implements FileProtectionStrategy {
    @Override
    public String getType() { return "CLOUD"; }

    @Override
    public byte[] protect(byte[] inputBytes, String fileName) {
        // GW API를 호출하여 클라우드 방식 암호화 수행
        return inputBytes; 
    }
    // ... unprotect 구현 생략
}

/**
 * 전략 B: 기존 에이전트 보안 구현체
 */
@Component
public class AgentFileProtectionStrategy implements FileProtectionStrategy {
    @Override
    public String getType() { return "AGENT"; }

    @Override
    public byte[] protect(byte[] inputBytes, String fileName) {
        // 기존 에이전트 방식 암호화 수행
        return inputBytes;
    }
    // ... unprotect 구현 생략
}

3.2. 전략 선택기 (Resolver)

다음으로, 런타임 시점에 필요한 전략을 빠르게 찾을 수 있도록 Resolver를 구성했습니다.

여기서 주목할 점은 생성자에서 List<FileProtectionStrategy>를 주입받는 부분입니다. 이는 Spring의 다중 빈 자동 주입(Autowiring Collections) 기능을 활용한 것으로, 동일한 인터페이스를 구현한 모든 빈을 한 번에 주입받을 수 있습니다.

전략의 개수가 적을 때는 리스트를 순회해도 문제가 없지만, 호출 빈도가 매우 높은 보안 모듈 특성상 확장 시에도 성능 저하가 없는 구조를 목표로 했습니다. 따라서 주입받은 전략 리스트를 애플리케이션 시작 시점에 단 한 번만 Map으로 변환하여 캐싱해둠으로써, 런타임에는 별도의 조건문(if-else)이나 리스트 순회 없이 O(1) 시간 복잡도로 전략을 즉시 조회할 수 있도록 구현했습니다.

이 접근법의 장점은 새로운 전략 구현체를 추가할 때 Resolver 코드를 전혀 수정할 필요가 없다는 것입니다. @Component로 등록된 새 전략 빈은 애플리케이션 시작 시점에 Spring이 자동으로 감지하여 리스트에 포함시킵니다. 이는 OCP(개방-폐쇄 원칙)를 자연스럽게 만족하는 구조입니다.

참고문서: Spring 공식 문서 - Using @Autowired

@Component
public class FileProtectionStrategyResolver {

    private final Map<String, FileProtectionStrategy> registry;

    // 생성자 주입 시점에 모든 전략 구현체를 Map으로 변환하여 캐싱
    public FileProtectionStrategyResolver(List<FileProtectionStrategy> strategies) {
        this.registry = strategies.stream()
                .collect(Collectors.toMap(FileProtectionStrategy::getType, Function.identity()));
    }

    /**
     * 지정한 전략 식별자(Type)로 구현체를 O(1)로 조회
     */
    public FileProtectionStrategy resolve(String type) {
        FileProtectionStrategy strategy = registry.get(type);
        
        if (strategy == null) {
            throw new IllegalArgumentException("지원하지 않는 보안 타입입니다: " + type);
        }
        
        return strategy;
    }
}

4. AOP를 활용한 자동 적용

마지막 퍼즐은 AOP(Aspect Oriented Programming)입니다.

앞서 전략 패턴을 게임과 게임 팩에 비유했다면, AOP는 공항 보안 검색대에 가깝습니다. 파일을 생성하는 모든 코드마다 resolve()를 호출하고 protect()를 실행하는 방식은 번거로울 뿐 아니라, 호출을 누락할 위험도 있습니다. 이런 반복적이고 빠뜨리기 쉬운 보안 처리를 AOP에 맡기면 훨씬 안정적으로 관리할 수 있습니다. 마치 승객이 비행기를 타기 전에 반드시 보안 검색대를 지나가야 하듯, AOP는 비즈니스 로직으로 진입하기 전에 데이터를 자동으로 검사하고 통과시키는 관문 역할을 합니다.

우리는 @ProtectFile이라는 커스텀 어노테이션만 붙이면, AOP가 자동으로 개입하여 보안 처리를 수행하도록 했습니다.

@Aspect
public class ProtectFileAspect {

    private final FileProtectionStrategyResolver resolver;

    public ProtectFileAspect(FileProtectionStrategyResolver resolver) {
        this.resolver = resolver;
    }

    @Around("@annotation(protectFile)")
    public Object aroundProtect(ProceedingJoinPoint pjp, Object protectFile) throws Throwable {
        // 1. 비즈니스 로직 실행 (파일 생성/다운로드)
        // (예시를 위해 반환 타입이 byte[]라고 가정)
        byte[] raw = (byte[]) pjp.proceed(); 

        // 2. 보안 전략 결정
        // 실제 운영 코드에서는 사용자 세션 정보(SessionUser)를 기반으로
        // "CLOUD" 또는 "AGENT" 타입을 동적으로 결정합니다.
        String securityType = getCurrentUserSecurityType(); 

        // 3. 전략 조회 및 암호화 수행
        FileProtectionStrategy strategy = resolver.resolve(securityType);
        
        // 4. 암호화된 결과 반환
        // (전략 구현체 내부에서 처리)
        return strategy.protect(raw, "sample_report.pdf");
    }

    // 사용자 권한에 따른 보안 타입 결정 로직 (예시)
    private String getCurrentUserSecurityType() {
        // 실제로는 SecurityContextHolder 등에서 사용자 권한을 확인합니다.
        // return userContext.isHeadquarters() ? "CLOUD" : "AGENT";
        return "CLOUD"; // 데모를 위해 고정값 사용
    }
}

이제 비즈니스 로직 개발자는 파일 생성 코드에 집중하고, 아래처럼 @ProtectFile 어노테이션 하나만 붙여주면 됩니다.

@ProtectFile // 이 어노테이션 하나로 암호화 로직이 자동 적용됩니다.
public byte[] downloadSalesReport() {
// 순수 비즈니스 로직 (파일 생성)
return reportService.createPdf(...);
}

5. 삽질기: 실제 적용하면서 마주한 문제들

설계는 깔끔했지만, 실제 적용 과정은 순탄치 않았습니다. 여기서는 개발 중 마주했던 문제들과 해결 과정을 공유합니다.

5.1. 로컬 개발 환경에서 에이전트 솔루션이 동작하지 않는 문제

가장 먼저 부딪힌 벽은 로컬 개발 환경이었습니다.

클라우드 보안 API는 개발 환경에서도 문제없이 동작했지만, 기존 에이전트 기반 솔루션은 상황이 달랐습니다. 에이전트 솔루션은 네이티브 라이브러리에 의존하고 있었는데, 이 라이브러리가 macOS 아키텍처를 지원하지 않았습니다.

// 문제: macOS 로컬 환경에서 에이전트 솔루션 호출 시
agentSecurityLib.protect(data);
// -> UnsatisfiedLinkError: 네이티브 라이브러리 로드 실패

대부분의 개발자가 macOS 환경에서 개발하고 있었기 때문에, 에이전트 방식 암호화를 테스트하려면 매번 개발 서버에 배포하거나 Docker 환경에서 실행해야 했습니다. 로컬에서 코드 수정 후 즉시 테스트하면 피드백 루프가 1~2분이면 충분하지만, 개발 서버 배포를 거치면 커밋 → CI/CD 파이프라인 → 서버 재시작까지 적지 않은 시간이 소요되어 개발 생산성이 크게 저하되는 문제가 있었습니다.

해결책: 로컬 환경용 Mock 전략 구현체

이 문제를 해결하기 위해 로컬 개발 환경에서만 활성화되는 Mock 전략을 추가하여, 로컬 환경에서는 Mock 전략이 에이전트 전략을 대체하도록 설정했습니다.

@Component
@Profile("local")  // 로컬 환경에서만 활성화
public class MockFileProtectionStrategy implements FileProtectionStrategy {

    @Override
    public String getType() { return "AGENT"; }  // 에이전트 타입을 대체

    @Override
    public byte[] protect(byte[] inputBytes, String fileName) {
        // 실제 암호화 없이 원본 그대로 반환
        log.debug("[Mock] 에이전트 암호화 스킵: {}", fileName);
        return inputBytes;
    }
}

이제 우리는 실제 암호화는 수행하지 않지만, 전략 패턴의 흐름은 그대로 테스트할 수 있게 되었습니다.

실제 암호화 동작 검증이 필요할 때만 개발 서버에 배포하면 되니, 암호화 에이전트를 사용할 수 없는 macOS 환경에서 코드와 흐름에 대한 불확실성을 제거할 수 있었습니다.

이는 인프라의 종속성에서 개발 환경을 완전히 독립시킨 의미 있는 리팩터링었습니다.

5.2. 기존 코드에 어노테이션 일괄 적용

마지막으로, 기존에 존재하는 수십 개의 다운로드 API에 @ProtectFile 어노테이션을 붙이는 작업이 남아있었습니다.

단순 작업이라 생각했지만, 막상 시작하니 까다로운 케이스들이 있었습니다.

파일이 아닌 JSON을 반환하는 API에 실수로 어노테이션을 붙이면?
이미 다른 방식으로 암호화가 적용된 레거시 코드는?
암호화가 필요 없는 공개 문서(약관 등)는?

해결책: API 목록화 + 꼼꼼한 QA 테스트

무작정 적용하기보다, 먼저 모든 파일 다운로드 API를 목록화하고 각각의 특성을 파악했습니다.

[파일 다운로드 API 체크리스트]
✅ /api/report/sales - 매출 리포트 (암호화 필요)
✅ /api/report/inventory - 재고 현황 (암호화 필요)
⬜ /api/template - 양식받기 (공개 문서, 암호화 불필요)

목록화 이후에는 QA 엔지니어분과 함께 꼼꼼한 테스트 과정을 거쳤습니다. 사용자 권한별로 파일을 다운로드하고, 암호화가 정상 적용되는지 하나하나 검증했습니다.

이 자리를 빌려 늦은 시간까지 수십 개의 API를 빠짐없이 테스트해주신 QA팀 여러분께 깊은 감사를 전합니다. ‍♀️

6. 마치며

이번 프로젝트는 전사적인 보안 체계 전환이라는 미션을 수행함과 동시에, 현장의 다양한 사용자 환경을 모두 고려해야 하는 과제였습니다.

전략 패턴과 AOP의 조합으로 본사 구성원에게는 최신 클라우드 보안 환경을, 매장 구성원에게는 익숙한 기존 환경을 제공하면서도 코드의 복잡도는 최소화할 수 있었습니다.

단순히 "돌아가는 코드"를 넘어, 변화에 유연하게 대처할 수 있는 "좋은 구조"를 고민했던 이번 경험이, 복잡한 레거시 환경과 새로운 요구사항 사이에서 고민하는 개발자분들에게 작은 힌트가 되기를 바랍니다.

[AI] #1: Harness Engineering

Anna-Jin — Mon, 1 Jun 2026 12:38:31 +0900

지금껏 Claude를 사용해서 개발을 해오면서도 claude가 어느 단계에서 어떤 Agent를 호출해서 사용하는지, 혹은 어떻게 Agent나 Skill을 구성해야하는 지에 대한 생각을 깊게 해오지 않았다.

정말 아무것도 모를 때에는 Claude.md 파일에 모든 내용과 지침을 때려넣는 것도 해봤으니 말 다했다.

Claude를 '잘' 사용할 수 있게 되면 클로드가 MCP를 직접 호출하거나 Agent가 다른 Agent를 호출해서 여러 역할을 동시에 수행하게 하는 등의 일도 가능하고, 퇴근 시간에도 스스로 계속해서 일을 하는 노예(?)를 만들어 놓을 수도 있다.

이제는 프롬프트를 잘 쓰는 것 뿐만 아니라, "AI가 스스로 일할 작업환경을 얼마나 잘 설계해두는가"가 중요하게 되었다.

이 작업환경을 설계해두는 개념을 "하네스 엔지니어링(Harness Engineering)"이라고 부른다

이번에는 이 하네스 엔지니어링은 무엇이고, Claude를 더 잘 사용하기 위한 하네스를 공부해보고자한다.

1. 언어 모델과 에이전트는 다르다

먼저 두 개념을 구분해야 한다.

언어 모델(Language Model) 은 텍스트를 받아서 텍스트를 돌려주는 엔진이다. 질문을 하면 답을 한다. 코드를 보여주면 설명을 해준다. 하지만 모델 자체는 파일을 열거나, 터미널 명령어를 실행하거나, Slack에 메시지를 보내는 것을 직접 할 수 없다. 텍스트의 세계 안에만 존재한다.

에이전트(Agent) 는 다르다. 에이전트는 목표를 받으면 스스로 계획을 세우고, 필요한 도구를 꺼내 쓴다. 결과를 보고 다시 판단한다. 작업이 끝날 때까지 이 과정을 반복한다. 파일을 실제로 열고, 코드를 실행하고, 에러 메시지를 확인하고, 수정하는 행동을 직접 한다.

핵심 차이를 한 문장으로 정리하면 이렇다.

'말만 잘하는 언어 모델'을 '실제로 행동하는 에이전트'로 만드는 것은 바로 하네스다.

2. 하네스란 무엇인가

하네스(Harness) 는 언어 모델 주위를 감싸서, 모델이 실제 세상과 상호작용할 수 있도록 도구·환경·규칙·안전장치를 제공하는 인프라 골격이다.

아직 감이 잘 오지 않는다면 다음 비유를 생각해보자.

아주 유능한 시니어 개발자가 있다. 10년 경력에 모든 기술 지식을 갖추고 있다. 그런데 오늘 완전히 낯선 회사에 첫 출근을 했다. 이 사람에게 아래의 것들이 없다면 아무것도 할 수 없다.

노트북과 코드 저장소 접근 권한 (도구)
이 회사가 사용하는 코딩 컨벤션 문서 (컨텍스트)
Jira 같은 작업 관리 시스템 (할 일 목록)
실수했을 때 되돌릴 수 있는 Git (안전장치)

이 모든 '업무 인프라'가 곧 하네스다.

중요한 포인트가 있다. 개발자(모델)의 능력은 이미 충분하다. 우리가 설계해야 하는 것은 그 능력이 발휘될 무대, 즉 하네스다.

3. 에이전트 루프

하네스에서 가장 핵심적인 부분은 에이전트 루프(Agent Loop) 다. 이 루프는 에이전트가 작업을 처리하는 반복 구조이다.

사용자 입력
    │
    ▼
┌─────────────────────┐
│   컨텍스트 수집        │  ← 관련 파일, 기억, 규칙 등을 불러온다
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   모델 추론           │  ← Claude가 "다음에 무엇을 해야 할까?"를 판단한다
└──────────┬──────────┘
           │
    도구를 써야 하나?
     예 /       \ 아니오
      /           \
     ▼             ▼
┌─────────┐   ┌──────────┐
│ 도구 실행 │   │  응답 출력 │  ← 작업 완료
│ (파일,   │   └──────────┘
│  명령어, │
│  검색…)  │
└────┬────┘
     │
     ▼
┌─────────────────────┐
│  결과를 컨텍스트에      │  ← "파일을 읽었더니 이런 내용이었다"를 기록
│  추가                │
└──────────┬──────────┘
           │
      작업이 끝났나?
     예 /       \ 아니오
      /           \
     ▼             ▼
┌──────────┐   [모델 추론]으로 돌아가서 반복
│ 응답 출력  │
└──────────┘

이 루프에서 주목해야 할 점이 있다. 루프 자체는 매우 단순하다. "모델에게 보내고 → 결과를 받고 → 도구를 실행하고 → 다시 모델에게 보내고"를 반복하는 구조다. 복잡한 AI가 따로 있는 게 아니다. 아주 뛰어난 모델이 이 단순한 루프 안에서 작동하는 것만으로 복잡한 작업을 해낸다.

그래서 하네스 엔지니어링의 목표는 루프 자체를 복잡하게 만드는 것이 아니라, 루프가 잘 돌아갈 수 있는 환경을 잘 설계하는 것이다.

4. 하네스의 핵심 구성요소

잘 만들어진 하네스에는 공통적으로 등장하는 구성요소들이 있다. Claude Code를 기준으로 살펴보면 다음과 같다.

구성요소	하는 일	쉬운 비유
모델 인터페이스	언어 모델과 통신하는 창구	팀원에게 업무를 지시하는 팀장
도구 레지스트리	모델이 사용할 수 있는 도구 목록과 실행기	사무실 비품 창고 + 사용 설명서
컨텍스트 관리자	모델에게 보낼 정보를 취사선택하고 정리	회의 전에 필요한 자료만 추려 브리핑하는 비서
실행 엔진	도구 호출을 실제로 처리	설계도를 받아 실제로 시공하는 팀
메모리 시스템	단기(현재 대화)·장기(이전 세션) 기억 관리	회의 메모장 + 업무 일지
피드백 루프	도구 실행 결과를 다시 컨텍스트에 입력	실험 결과를 노트에 적고 다음 실험을 설계하는 과정
안전 장치	위험한 작업 차단 및 사용자 승인 게이트	중요 결제 전 상사 결재를 받는 절차
오케스트레이션	여러 에이전트를 조율하는 상위 계층	여러 팀을 동시에 관리하는 프로젝트 매니저

각각의 역할을 조금 더 들여다보자.

도구 레지스트리: 모델에게 '손'을 붙여주는 곳

언어 모델은 텍스트만 주고받는다. 하네스는 도구(Tool) 를 통해 모델이 실제 세계와 상호작용할 수 있게 한다. Claude Code의 내장 도구는 파일 읽기·쓰기·편집, bash 명령어 실행, 웹 검색, 브라우저 제어 등이다. 도구 레지스트리는 이 목록과 각 도구의 사용법 설명을 모델에게 전달한다. 모델은 "read_file과 bash를 쓸 수 있다"는 것을 인식하고 적절한 상황에서 꺼내 쓴다.

여기서 중요한 포인트가 있다. 모델은 파일 시스템을 직접 건드리지 않는다. 모델이 "이 파일을 읽어야겠다"고 판단하면, 하네스의 실행 엔진이 실제로 파일을 열어 그 내용을 컨텍스트에 넣어준다. 모델은 항상 텍스트만 주고받고, 나머지는 하네스가 처리한다.

컨텍스트 관리자: 하네스에서 가장 까다로운 문제

언어 모델에는 컨텍스트 윈도우(Context Window) 라는 한계가 있다. 모델이 한 번에 볼 수 있는 정보의 양이다. 작업이 길어질수록 대화 기록, 파일 내용, 도구 실행 결과가 쌓여서 이 공간이 가득 찬다.

컨텍스트 관리자는 이 공간을 효율적으로 쓰기 위해 무엇을 계속 보여주고, 무엇을 요약하거나 제거할지 끊임없이 판단한다. 컨텍스트를 잘 관리하지 못하면 모델이 이전에 받은 규칙을 잊거나, 작업이 중간에 멈추는 문제가 생긴다. 그래서 컨텍스트 관리는 하네스 품질을 좌우하는 가장 중요한 요소 중 하나다.

안전 장치: "이건 확인받고 하겠습니다"

하네스가 없는 모델은 데모 수준에 머문다. 프로덕션 수준의 하네스에는 반드시 안전 장치가 있어야 한다. Claude Code가 파일을 삭제하거나 중요한 명령어를 실행하려 할 때 사용자에게 승인을 요청하는 것이 바로 이 장치다. 아무리 모델이 자신 있어도, 되돌릴 수 없는 행동 앞에서는 멈추고 확인을 받아야 한다.

5. Claude Code를 하네스로 다시 보기

이제 Claude Code를 하네스 관점으로 다시 본다.

┌─────────────────────────────────────────────────┐
│                   Claude Code                    │
│                                                  │
│  ┌───────────────────────────────────────────┐   │
│  │              하네스 (Harness)              │   │
│  │                                           │   │
│  │   도구 레지스트리     컨텍스트 관리자            │   │
│  │   실행 엔진           안전 장치              │   │
│  │   메모리 시스템       오케스트레이션            │   │
│  │                                          │   │
│  │   ┌───────────────────────────────────┐  │   │
│  │   │         언어 모델 (Claude)          │   │   │
│  │   │      추론과 판단은 여기서 일어남         │   │  │
│  │   └───────────────────────────────────┘   │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

공식 문서는 Claude Code를 이렇게 정의한다. "Claude라는 언어 모델에 도구, 컨텍스트 관리, 실행 환경을 제공해 코딩 에이전트로 만들어주는 에이전트 하네스." claude 명령어를 실행하는 순간, 이미 잘 설계된 하네스를 갖춘 에이전트를 손에 쥔 것이다.

6. 그래서 하네스 설계가 왜 중요한가

"Claude Code가 이미 다 해주는데, 하네스를 내가 왜 알아야 하나?"라는 의문이 생길 수 있다. 두 가지 이유가 있다.

첫째, 같은 모델도 하네스에 따라 성능이 크게 달라진다. Anthropic의 엔지니어링 팀도 "아무리 뛰어난 프론티어 모델이라도 하네스 설계가 나쁘면 성능이 크게 저하된다"고 강조한다. 컨텍스트를 잘못 관리하거나 도구를 어설프게 제공하면, 세계 최고의 모델도 엉뚱한 결과를 낸다.

둘째, Claude Code는 하네스를 직접 확장할 수 있도록 설계되어 있다. 팀의 규칙, 반복 작업, 외부 서비스 연동, 자동화 스크립트를 하네스에 직접 연결할 수 있다. 이 기능들이 하네스의 어느 부분에 연결되는지 이해해야 제대로 활용할 수 있다. 2편에서는 이 확장 기능들을 하나씩 살펴본다.

마치며

이번 편의 핵심을 정리해보자.

개념	한 줄 정리
언어 모델	텍스트를 받아 텍스트를 돌려주는 추론 엔진
에이전트	목표를 받아 스스로 행동을 반복하는 존재
하네스	모델을 에이전트로 만들어주는 인프라 골격
에이전트 루프	추론 → 도구 실행 → 결과 반영을 반복하는 심장부
Claude Code	Claude 모델 + 잘 설계된 하네스

다음 편에서는 Claude Code가 제공하는 하네스 확장 기능 — CLAUDE.md, Skills, MCP, Subagents, Hooks — 을 하나씩 뜯어보도록 하자.

각 기능이 하네스의 어느 구성요소에 연결되는지, 실제로 어떻게 쓰는지를 구체적인 예시와 함께 살펴본다.

참고하면 좋은 자료 링크

https://news.hada.io/topic?id=28232

코딩 에이전트의 구성 요소 | GeekNews

코딩 에이전트는 LLM을 중심으로 코드 작성, 실행, 피드백을 반복 수행하는 제어 루프와 소프트웨어 하니스로 구성된 시스템에이전트 하니스는 컨텍스트 관리, 도구 접근, 프롬프트 구성, 상태

news.hada.io

https://news.hada.io/topic?id=28966

하네스 엔지니어링: 모델보다 중요한 작업 환경 설계의 시대 | GeekNews

애디 오스마니(Addy Osmani)가 정리한 “하네스 엔지니어링(Harness Engineering)”에 관한 분석입니다. 그는 지난 2년 동안 업계의 관심이 “어떤 AI 모델이 더 똑똑한가”라는 질문에만 쏠려 있었다고

news.hada.io

[Spring boot] @ModelAttribute에 대한 이해

Anna-Jin — Sat, 20 Jan 2024 17:54:30 +0900

들어가며

일반적으로 Spring boot에서 Get방식(혹은 쿼리파라미터가 필요한) 요청을 받을 때 사용되는 어노테이션에는 @RequestParam, @PathVariable, @ModelAttribute가 있다.

파라미터의 개수가 적은 경우에는 앞의 두개 어노테이션으로 충분하지만 파라미터가 많아질 수록 객체로 요청을 받는게 가독성 측면에도 관리 측면에도 수월해지기 때문에 @ModelAttribute를 사용한다.

종종 @ModelAttribute를 사용하면서 헷갈리거나 잊어버리는 개념이 있어 이번 포스팅에서는 @ModelAttribute 어노테이션에 대해 공부해보고자 한다!

@ModelAttribute

사용 이유

요청을 받을 때 다음과 같이 파라미터의 개수가 적다면 @RequestParam 어노테이션으로도 무리없이 코드 작성이 가능하다.

@GetMapping("/param")
public ApiResponse<StudyResponseDto> requestParam(
        @RequestParam("name") String name,
        @RequestParam("age") int age
) {
    return ApiResponse.success(studyService.requestParam(name, age));
}

하지만 파라미터의 개수가 많아진다면 어떨까?

@GetMapping("/param")
public ApiResponse<StudyResponseDto> requestParam(
        @RequestParam("name") String name,
        @RequestParam("age") int age,
        @RequestParam("email") String email,
        @RequestParam("phone") String phone,
        @RequestParam("nickname") String nickname,
        @RequestParam("hobby") String hobby,
        @RequestParam("job") String job
) {
    return ApiResponse.success(studyService.requestParam(name, age, email, phone, nickname, hobby, job));
}

한 눈에 보더라도 가독성이 떨어질 뿐만 아니라 service로 파라미터를 전달할 때 실수할 가능성이 다분한 코드가 된다.

이때, 파라미터들을 객체로 관리하면 어떨까?

@GetMapping("/model")
public ApiResponse<StudyResponseDto> modelAttribute(
        StudyRequestDto requestDto
        ) {
    return ApiResponse.success(studyService.modelAttribute(requestDto));
}

@Getter
@Setter
public class StudyRequestDto {

    private String name;
    private int age;
    private String email;
    private String phone;
    private String nickname;
    private String hobby;
    private String job;

}

코드가 한결 간결해질 뿐만 아니라 코드를 수정할 때 DTO 객체만 관리하면 되기 때문에 코드 수정도 용이해진다.

자, @ModelAttribute를 사용하는 이유는 이제 알겠는데, 이 어노테이션이 어떻게 동작하기에 요청 파라미터들을 자동으로 바인딩해주는 걸까?

728x90

동작방식

@ModelAttribute는 기본적으로 setter 메소드를 사용하여 데이터를 바인딩한다.

위의 코드를 사용해서 간단하게 테스트코드를 짜서 테스트해보자.

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class StudyControllerTest {

    @LocalServerPort
    private int port;

    @Test
    public void modelAttribute() {
        // given
        RestAssured.baseURI = "http://localhost";
        RestAssured.port = port;

        given()
                .log().params()
                .param("name", "name")
                .param("age", 10)
                .param("email", "email")
                .param("phone", "phone")
                .param("nickname", "nickname")
                .param("hobby", "hobby")
                .param("job", "job")

        // when
                .when()
                .get("/api/v1/study/model")

        // then
                .then()
                .log().all();
    }

}

결과 응답값

// 결과
{
    "code": "200_0",
    "message": "정상 처리 되었습니다.",
    "data": {
        "name": "name",
        "age": 10,
        "email": "email",
        "phone": "phone",
        "nickname": "nickname",
        "hobby": "hobby",
        "job": "job"
    }
}

데이터가 잘 바인딩 되는걸 확인할 수 있다.

하지만 하나 불편한 점이 있다. 나는 개인적으로 꼭 필요한 경우가 아니면 DTO에 setter 사용을 지양하고 있다.

setter 대신 생성자를 사용할 수는 없는걸까?

코드를 다음과 같이 변경하고 테스트해보자.

@Getter
@NoArgsConstructor
@AllArgsConstructor // 편의를 위해 Lombok 사용
public class StudyRequestDto {

    private String name;
    private int age;
    private String email;
    private String phone;
    private String nickname;
    private String hobby;
    private String job;

}

결과 응답값

// 데이터가 바인딩되지 않는다.
{
    "code": "200_0",
    "message": "정상 처리 되었습니다.",
    "data": {
        "name": null,
        "age": 0,
        "email": null,
        "phone": null,
        "nickname": null,
        "hobby": null,
        "job": null
    }
}

setter를 사용할 때와 달리 데이터가 바인딩되지 않는다.

이유가 뭘까?

원인을 찾기 위해 @ModelAttribute의 구현체를 찾아가보도록 하자.

ModelAttributeMethodProcessor

ModelAttribute가 어떻게 동작하는 지 확인하고 싶을 때 디버깅을 찍을 수 있는 구현체이다.

이 클래스에서 주목해야할 부분은 constructAttribute() 메소드이다.

해당 클래스의 resolveArgument() 메소드부터 디버깅을 해서 차근차근 들어가보면 생성자에서 파라미터를 바인딩하는 메소드를 찾을 수 있는데, 이걸 결정하는 메소드가 바로 contructAttribute() 메소드이다.

protected Object constructAttribute(Constructor<?> ctor, String attributeName, MethodParameter parameter, WebDataBinderFactory binderFactory, NativeWebRequest webRequest) throws Exception {
    if (ctor.getParameterCount() == 0) {
        return BeanUtils.instantiateClass(ctor, new Object[0]);
    } else {
        String[] paramNames = BeanUtils.getParameterNames(ctor);
        Class<?>[] paramTypes = ctor.getParameterTypes();
        Object[] args = new Object[paramTypes.length];
        WebDataBinder binder = binderFactory.createBinder(webRequest, (Object)null, attributeName);
        String fieldDefaultPrefix = binder.getFieldDefaultPrefix();
        String fieldMarkerPrefix = binder.getFieldMarkerPrefix();
        boolean bindingFailure = false;
        Set<String> failedParams = new HashSet(4);

        //...
        
 }

이 코드에서 ctro.getParaneterCount()를 사용해서 생성자의 파라미터 개수를 가져온다.

만약 그 개수가 0개라면 기본생성자로, 0개가 아니라면 인자가 있는 (우리의 경우에는 AllAgrsConstructor) 생성자를 인식하고 파라미터 바인딩을 처리하게 된다.

따라서 @AllArgsConstructor를 사용하더라도 @NoArgsConstrutor에 의해 기본생성자가 사용되게 되므로, 만약 Setter 메소드를 사용하고 싶지 않다면 기본생성자를 명시하지 않고 특정 파라미터에 대한 생성자만을 명시해주면 된다.

그렇다면 왜 Setter 메소드가 없으면 데이터 바인딩이 되지 않는 걸까?

Setter 메소드가 없으면 안되는 이유

ModelAttributeMethodProcessor의 메소드 중 하나인 resolveArgument() 메소드를 확인해보면 다음과 같이 WebDataBinder 클래스를 사용하여 데이터를 바인딩 한다.

if (bindingResult == null) {
    WebDataBinder binder = binderFactory.createBinder(webRequest, attribute, name);
    if (binder.getTarget() != null) {
        if (!mavContainer.isBindingDisabled(name)) {
            this.bindRequestParameters(binder, webRequest);
        }

        this.validateIfApplicable(binder, parameter);
        if (binder.getBindingResult().hasErrors() && this.isBindExceptionRequired(binder, parameter)) {
            throw new MethodArgumentNotValidException(parameter, binder.getBindingResult());
        }
    }

    if (!parameter.getParameterType().isInstance(attribute)) {
        attribute = binder.convertIfNecessary(binder.getTarget(), parameter.getParameterType(), parameter);
    }

    bindingResult = binder.getBindingResult();
}

WebDataBinder는 요청 파라미터를 객체에 바인딩해주는 역할을 한다.

그리고 이 클래스는 Java Beans 규약을 준수하여 동작하고 있는데, Java Beans 규약은 getter와 setter를 사용하여 프로퍼티에 접근한다.

따라서 setter 메소드를 명시하지 않는다면 WebDataBinder는 데이터를 바인딩할 방법이 없는 것이다.

결론

@ModelAttribute를 사용하여 파라미터를 객체에 바인딩하기 위한 방법은 두가지가 있다.

Setter 메소드를 사용한다.
기본 생성자는 명시하지 않는다면 default로 생성되므로 신경쓰지 않아도 된다.
파라미터가 존재하는 생성자만 사용한다.
이때, 기본생성자와 함께 사용하면 데이터 바인딩이 되지 않으므로 주의한다.

마치며

지금까지 '그냥 되는구나'라고만 생각하고 사용했던 @ModelAttribute 어노테이션에 대해 깊게 알아보는 시간을 가졌다.

내부적으로 동작하는 코드를 까보는게 생각보다 훨씬 공부에 도움이 된다는걸 한번 더 깨닫게 되었다.

앞으로도 그냥 쓰지 말고 동작원리를 알고 개발하는 습관을 가지기로 다짐하면서 이번 포스팅을 마무리한다.

[Spring boot] WebClient 사용해보기 - 비동기 통신 subscribe()

Anna-Jin — Sat, 11 Nov 2023 14:01:01 +0900

들어가며

WebClient는 RestTemplate의 대안으로서 급부상된 WebFlux의 라이브러리이다.

Spring MVC에서도 지원하는 WebClient는 RestTemplate과 비교했을 때 가장 큰 장점이 `비동기 통신을 지원한다`는 점이 아닐까 싶다. 물론 그 외에도 함수형 프로그래밍 스타일을 지원한다는 점, 다양한 설정과 에러처리를 지원한다는 점 등도 장점으로 꼽을 수 있겠다.

WebClient의 최대 장점인 비동기 통신을 지금까지 사용하기 어렵고 쓸 데가 없다는 이유만으로 동기 방식을 고수해왔었는데 이번 회사 프로젝트를 하면서 비동기 통신이 필요해진 시점이 생겼다. 이번 기회에 WebClient의 비동기 통신을 구현해보았고 이번 포스팅의 주제로 삼아보고자 한다.

처음 비동기 통신을 구현해보았기 때문에 다소 부족할 수 있다는 점 참고 바란다.

비동기 vs 동기

비동기와 동기의 차이점은 예전에 글로 정리한 적이 있었다.

2022.05.30 - [Study/CS] - [CS] 동기 & 비동기 vs 블로킹 & 논블로킹

[CS] 동기 & 비동기 vs 블로킹 & 논블로킹

들어가며 예전에 Petpular 프로젝트 때 사용해본 Spring WebClient에서 동기 & 비동기 / 블로킹 & 논블로킹의 개념이 등장했었다. WebClient는 논블로킹방식으로 작동하고 block() 메소드를 이용해서 블로킹

annajin.tistory.com

동기는 한 작업이 완료될 때까지 다음 작업을 기다리는 방식이고

비동기는 한 작업을 실행한 후에도 다음 작업을 기다리지 않고 계속 진행하는 방식이다.

RestTemplate은 동기 방식으로 동작하는 하는 HTTP 클라이언트 라이브러리이고,

WebClient는 비동기 방식으로 동작하는 라이브러리이다.

Subscribe()

아래 포스팅의 ConnectStep 부분을 보면 block() 메소드를 사용하여 응답을 동기로 받는다고 작성해두었다.

2023.08.26 - [Study/Spring boot] - [Spring boot] WebClient 사용해보기 - 모듈화 1-2

[Spring boot] WebClient 사용해보기 - 모듈화 1-2

들어가며 2023.08.25 - [Study/Spring boot] - [Spring boot] WebClient 사용해보기 2-1 이전글에서는 내가 어떻게 웹클라이언트를 사용하고 있는 지에 대해 간단하게 설명했다. 이번 글에서는 코드를 하나씩 보

annajin.tistory.com

728x90

이번에는 위의 게시글 내용을 베이스로 subscribe()를 사용해서 응답을 비동기로 받을 수 있도록 구현해보자.

ConnectStepImpl

@Log4j2
@RequiredArgsConstructor
public class ConnectStepImpl implements ConnectStep {

    private final WebClient.RequestHeadersSpec<?> methodType;
    private Object response;

   
    /**
     * WebClient의 header와 response class 설정 후 subscribe로 호출<br>
     * 헤더와 응답값이 존재할 때 사용. (ex. 일반적인 api 호출)<br>
     * 예외처리 포함
     * @return {@link ResponseStep}
     */
    @Override
    public Mono<?> connectSubscribe(Map<String, String> headers, Class<?> responseType) {
        try {
            return this.methodType
                    .headers(httpHeaders -> httpHeaders.setAll(headers == null || headers.isEmpty() ? new HashMap<>() : headers))
                    .retrieve()
                    .onStatus(HttpStatusCode::isError, clientResponse ->
                            clientResponse.bodyToMono(String.class)
                                    .flatMap(msg -> Mono.error(new ApiException(ResponseCode.INTERNAL_SERVER_ERROR, msg))))
                    .bodyToMono(responseType)
                    .retryWhen(Retry.fixedDelay(3, java.time.Duration.ofSeconds(1))
                            .doBeforeRetry(before -> log.info("Retry: {} | {}", before.totalRetries(), before.failure())));
        } catch (Exception e) {
            throw new ApiException(ResponseCode.INTERNAL_SERVER_ERROR, e.getMessage());
        }
    }

    /**
     * WebClient의 header와 response class 설정 후 subscribe로 호출<br>
     * 헤더와 응답값이 존재하지 않을 때 사용. (ex. Google chat webhook api 호출)<br>
     * 예외처리 포함
     * @return {@link ResponseStep}
     */
    @Override
    public Mono<String> connectSubscribe() {
        try {
            return this.methodType
                    .retrieve()
                    .onStatus(HttpStatusCode::isError, clientResponse ->
                            clientResponse.bodyToMono(String.class)
                                    .flatMap(msg -> Mono.error(new ApiException(ResponseCode.INTERNAL_SERVER_ERROR, msg))))
                    .bodyToMono(String.class)
                    .retryWhen(Retry.fixedDelay(3, java.time.Duration.ofSeconds(1))
                            .doBeforeRetry(before -> log.info("Retry: {} | {}", before.totalRetries(), before.failure())));
        } catch (Exception e) {
            throw new ApiException(ResponseCode.INTERNAL_SERVER_ERROR, e.getMessage());
        }
    }
}

subscribe()는 WebFlux에서 제공하는 객체인 Mono 혹은 Flux를 사용한다. 이번 포스팅에서는 Mono 객체만을 사용하기로 한다.

block()을 사용할 때와 다른 점은 ConnectStepImpl 클래스에서 subscribe()를 호출하지 않는다는 점과 return값이 ResponseStep이 아니라는 점이다.

단순히 데이터의 후가공이나 logging이 필요하지 않다면 이 단계에서 subscribe()를 호출해도 상관 없다.

하지만 예제에서는 메소드의 모듈화를 위해 확장성을 고려해야했으므로 응답 호출을 후 단계로 미뤘다.

이 점에 주의하자.

Mono가 뭐고 Flux가 무엇인지에 대해서 공부하려면 WebFlux의 세계까지 들어가야한다. 이번에는 단순한 api 비동기 호출에 대해 작성하고 있으므로 이 부분은 건너뛰도록 한다.

여담이지만 처음 개발 공부를 시작했을 때 WebFlux를 완벽하게 공부한 다음 WebClient를 사용하려고 2주의 시간을 끙끙댄 적이 있었다. 지금 생각해보면 너무 비효율적인 공부방식이었던 것 같다. 개발은 하면서 공부하는게 최고라고 생각한다!

WebClientConnector

@Component
@RequiredArgsConstructor
public class WebClientConnector {
    private final ApiWebClientBuilder webClientBuilder;
    private final ApiStatics statics;


    /**
     * Google Chat WebHook 메세지 전송
     * @param requestBody {@link WebHook}
     */
    public Mono<String> callGoogleChat(WebHook requestBody) {
        ApiStatics.GoogleChat googleChat = statics.getGoogleChat();

        return webClientBuilder.request()
                .post(googleChat.getUrl(), requestBody)
                .connectSubscribe();
    }
}

WebClientConnector 객체는 API를 호출해주는 역할을 한다. 간단하게 Google Chat에 메시지를 보내는 Webhook API를 호출하는 예제를 작성해보았다.

구현체를 보면 ResponseStep 메소드를 사용하지 않은 것을 확인할 수 있다.

위에서 return값을 ResponseStep 객체로 하지 않은 이유가, .connectSubscribe()메소드 이후 체이닝에서는 ResponseStep의 메소드를 사용할 수 없도록 강제하기 위함이었다.

GoogleChatService

@Log4j2
@Service
@RequiredArgsConstructor
public class GoogleChatService {

    private final WebClientConnector webClientConnector;

    /**
     * 비동기로 Google Chat WebHook 메세지 전송<br>
     * retry 3회 시도
     * @param title         card header 타이틀
     * @param messageHeader card body 상단 메세지
     * @param message       card body 하단 메세지, 복수 메세지 - divider 추가
     */
    public void sendGoogleChatMultipleMessage(String title, String messageHeader, List<String> message) {
        ResponseCode responseCode = ResponseCode.GOOGLE_CHAT_ERROR;

        webClientConnector.callGoogleChat(WebHookMessageBuilder.createGoogleChatMultipleMessage(title, messageHeader, message))
                .flatMap(response -> Mono.just(ResponseEntity.ok().body(ApiResponse.success())))
                .onErrorResume(error -> Mono.just(ResponseEntity.status(responseCode.getStatus()).body(ApiResponse.error(responseCode, "메세지 전송 실패 : " + error.getCause().getMessage()))))
                .subscribe(
                        response -> log.info("메세지 전송 완료 : {}", response),
                        error -> log.error("메세지 전송 실패 : {}", error.getMessage())
                );
    }

    /**
     * 비동기로 Google Chat WebHook 메세지 전송<br>
     * retry 3회 시도
     * @param title         card header 타이틀
     * @param messageHeader card body 상단 메세지
     * @param message       card body 하단 메세지, 단일 메세지
     */
    public void sendGoogleChatMultipleMessage(String title, String messageHeader, String message) {
        ResponseCode responseCode = ResponseCode.GOOGLE_CHAT_ERROR;

        webClientConnector.callGoogleChat(WebHookMessageBuilder.createGoogleChatSingleMessage(title, messageHeader, message))
                .flatMap(response -> Mono.just(ResponseEntity.ok().body(ApiResponse.success())))
                .onErrorResume(error -> Mono.just(ResponseEntity.status(responseCode.getStatus()).body(ApiResponse.error(responseCode, "메세지 전송 실패 : " + error.getCause().getMessage()))))
                .subscribe(
                        response -> log.info("메세지 전송 완료 : {}", response),
                        error -> log.error("메세지 전송 실패 : {}", error.getMessage())
                );
    }
}

앞서 구현한 로직들을 호출하고, 응답을 받아 로깅하는 Service이다. ConnectStepImpl에서 subscribe()를 사용하지 않은 이유는 이 곳에서 확인할 수 있다.

최종 응답 데이터를 비동기 스트림 내에서 가공하고 처리하기 위함이다. 만약 모듈화된 Step 내부에 subscribe()가 존재한다면 각 서비스마다 connectStep을 새롭게 구현해야할 것이다.

flatMap() : 각 입력 요소를 새로운 스트림으로 변환한다음 각각의 스트림을 하나로 합쳐주는 역할을 한다. 쉽게 말하면 각각의 요청을 하나로 모아주는 역할을 한다고 생각하면 된다. 예제에서는 여러개의 스트림이 존재하지 않지만 비동기 응답에 대한 데이터를 처리하기 위하여 사용했다.
onErrorResume() : 스트림 내에서 발생한 에러를 처리한다.
subscribe() : 비동기 응답을 받아 처리한다. 첫번째 인자로는 정상 응답, 두번째 인자로는 에러 응답을 처리할 수 있다.

마치며

이렇게 간단하게 비동기 처리를 구현해보았다.

사실 WebFlux의 세계는 Spring MVC만큼이나 방대하고 알아야할 것, 사용할 수 있는 수단이 많지만 초보 개발자가 단기간에 습득할 수 있는 분야는 아니라고 생각하기에 차근차근 공부하고 포스팅해나가면서 알아가는게 좋지 않을까 싶다.

[ChatGPT] OpenAi API 사용해보기 - 프롬프트 엔지니어링

Anna-Jin — Sat, 21 Oct 2023 17:33:55 +0900

들어가며

이미 많은 개발자들이 알고, 사용해보고 있을 ChatGPT. Open AI에서 만든 ChatGPT는 API로도 사용이 가능하다.

모델마다 토큰 당 가격에 일부 차이가 있지만 단순한 프로젝트에 적용하기에는 부담되는 비용이 아니기 때문에 사이드프로젝트에 도입을 해보면 좋을 것 같다는 생각이 들어 간단하게 사용법을 작성해보고자 한다.

자세한 내용은 OpenAI의 ChatGPT API Docs를 참고하도록 하자

ChatGPT API Docs

OpenAI Platform

Explore developer resources, tutorials, API docs, and dynamic examples to get the most out of OpenAI's platform.

platform.openai.com

ChatGPT API

사전준비

1. OpenAI 회원가입

회원가입은 어렵지 않다. 이미 ChatGPT를 사용해본 사람이라면 로그인을 하고, 사용해본 적 없는 사람이라면 회원가입을 진행하자.

OpenAI Website

OpenAI Platform

Explore developer resources, tutorials, API docs, and dynamic examples to get the most out of OpenAI's platform.

platform.openai.com

728x90

2. 무료 크레딧 확인

OpenAI에서는 신규회원가입 시 3개월 동안 사용할 수 있는 $5 무료크레딧을 제공해준다.

프로필 클릭 > Manage account > Billing

해당 화면으로 이동 시 현재까지 남은 크레딧을 확인할 수 있다.

만약 Playground에서 아래와 같은 문구가 뜬다면 무료 크레딧이 만료된 것이므로 카드 정보 등록 후 크레딧을 구매해주자.

토큰량이 많지 않은 프로젝트라면 $5로도 충분하다고 생각되므로, 최소한의 금액 씩 구매하는걸 추천한다.

3. API Key 등록

크레딧까지 확인했다면 API를 사용하기 위해 API Key를 등록해주어야한다.

프로필 클릭 > USER > API key > Create new secret key

Secret key의 Name은 자유롭게 설정해도 된다. 필자는 [GPT secret key]라고 입력해주었다.

Name을 입력하고 나면 다음과 같이 Secret key가 생성된다. Secret key는 해당 화면에서 딱 한번만 확인가능하기 때문에 안전한 곳에 저장해두고 관리해야한다.

만약 Secret key를 분실했다면 기존 Key를 삭제한 후 새롭게 발급받아야 한다.

4. Playground

OpenAI가 제공하는 Playgound에서 ChatGPT API를 간편하게 테스트해볼 수 있다.

오른쪽 탭에서는 GPT의 Model, Temperature, Maximum Token(Length) 등등을 설정할 수있고, 좌측 탭에서는 SYSTEM과 USER를 설정할 수 있다.

뒤에서 자세히 설명하겠지만 SYSTEM은 GPT의 역할을 정해주는 부분이고, USER는 발화(질문) 내용을 입력하는 부분으로 이해하면 된다.

간단하게 Playground에서 테스트를 해보면 다음과 같이 ChatGPT와 동일하게 응답이 온다.

ASSISTANT 부분은 GPT에 대한 답변인데, API를 이용할 때 이 ASSISTANT를 함께 Request로 보내주면 마치 대화의 맥락을 기억하는 듯이 구현이 가능하다.

이 SYSTEM 부분에 적절한 역할을 부여해주면 해줄 수록 GPT는 개발자가 의도한 바를 명확하게 파악하고 대답을 하게 되고, 이 부분을 작성하는 과정이 바로 프롬프트 엔지니어링이다.

이제 간단히 ChatGPT의 사전준비가 끝났으니 본격적으로 ChatGPT API를 사용해보자.

알아보기

라이브러리

OpenAI의 ChatGPT API 공식문서에서는 Node.js와 Python를 사용하여 가이드를 진행하고, 공식적으로 이 두가지 언어의 라이브러리만을 지원해준다. 하지만 수많은 기업과 개발자들이 각각의 언어로 된 라이브러리를 배포 및 유지보수하고 있으므로 너무 걱정하지는 말자!

라이브러리가 지원되는 언어들은 다음과 같다.

이정도면 거의 모든 언어가 지원되는게 아닌가 할 정도로 많은 언어로 된 라이브러리가 배포되어있다.

라이브러리 언어 목록

C# / .NET

C++

liboai by D7EAD

Clojure

openai-clojure by wkok

Crystal

openai-crystal by sferik

Dart/Flutter

openai by anasfik

Delphi

DelphiOpenAI by HemulGM

Elixir

openai.ex by mgallo

go-gpt3 by sashabaranov

Java

openai-java by Theo Kanning

Julia

OpenAI.jl by rory-linehan

Kotlin

openai-kotlin by Mouaad Aallam

Node.js

PHP

Python

chronology by OthersideAI

rgpt3 by ben-aaron188

Ruby

openai by nileshtrivedi
ruby-openai by alexrudall

Rust

async-openai by 64bit
fieri by lbkolev

Scala

openai-scala-client by cequence-io

Swift

OpenAIKit by dylanshine
OpenAI by MacPaw

Unity

Unreal Engine

OpenAI-Api-Unreal by KellanM

이 예제에서는 OpenAI가 기본으로 라이브러리를 제공해주는 Python 을 사용해서 구현해볼 것이다.

파라미터 요소

https://platform.openai.com/docs/api-reference/chat/create

OpenAI Platform

Explore developer resources, tutorials, API docs, and dynamic examples to get the most out of OpenAI's platform.

platform.openai.com

우리가 사용하게 될 Chat Completion API의 파라미터들 중 주로 사용하는 인자들은 다음과 같다.

model(필수)

사용하게 될 GPT의 모델이다. 사용 가능한 모델은 다음과 같다.

GPT 모델 목록

MODELS	DESCRIPTION
GPT-4	GPT-3.5 업그레이드 버전
GPT-3.5	GPT-3 업그레이드 버전
GPT base	현재 사용하지 않는 베이스 모델
DALL·E	이미지를 생성하고 편집할 수 있는 모델
Whisper	오디오를 텍스트로 변환할 수 있는 모델
Embeddings	임베딩이 가능한 모델
Moderation	민감한 내용이나 안전하지 않은 지 여부를 감지할 수 있는 미세조정 모델
GPT-3 Legacy	가장 기본 모델. 3.5나 4로 대체되었지만 미세조정이 가능한 유일한 모델이다.
Deprecated	deprecated된 모델 목록

messages(필수)

GPT와의 대화를 구성하는 메시지 목록이다. JSON형태로 제공하며 필수 구성요소는 다음과 같다.

role: 메시지 작성자의 역할을 정의한다. 가능한 인자로는 system, user, assistant, function이 있다.
- system: GPT의 동작을 미리 설정할 수 있다. 예를 들어, GPT의 성격을 정한다거나 응답 형태를 지정하는 방식으로 사용할 수 있다.
- user: 사용자가 입력하는 내용이다.
- assistant: GPT가 답변한 내용이다. GPT는 기본적으로 이전 대화내용을 기억하지 못하기 때문에, 이전 내용을 바탕으로 대화를 이어나가기 위해 사용한다.

content: 메시지의 내용을 작성한다.

max_tokens(옵션)

GPT가 응답으로 만들어내는 토큰의 최대 개수이다. 기본값은 inf로 model에 따라 기본값이 달라진다.

temperature(옵션)

답변의 다양성을 설정한다. 0부터 2사이로 설정하도록 권장되며 소수점 첫째자리까지 입력가능하다.

값이 낮을 수록 더 정확하고 일관된 답변을 제공하고, 값이 높을 수록 더 다양한 답변을 제공하게 된다.

일반적으로 가장 안정적인 숫자는 0.5 ~ 1.0 사이라고 하지만 유저의 요구사항에 따라 적절한 temperature를 찾아야한다.

stream(옵션)

ChatGPT처럼 한글자씩 응답이 출력되는 방식을 사용하고 싶다면 true로 지정하면 된다. GPT를 Front end에서 구현한다면 느린 응답에 대한 대안이 될 수 있다.

구현하기

이 예제에서는 개발 면접을 도와주는 AI 멘토를 주제로 간단하게 구현한 코드와 프롬프트이다.

GPT는 영어에 대해 더 정확한 응답을 해주지만 이번 예제에서는 한국어로 구현하기로 한다.

사용한 언어는 OpenAI가 공식적으로 지원하는 라이브러리를 사용하기 위해 Python으로 선택하였다.

최종 코드

import json
import os
from dotenv import load_dotenv

import openai

load_dotenv()

# key와 organization을 환경변수로 관리
openai.organization = os.getenv('OPENAI_ORGANIZATION')
openai.api_key = os.getenv('OPENAI_API_KEY')

lang = "Java"
user_content = "Java는 객체지향 언어이다."

messages = [
    {"role": "system", "content": "너는 개발 면접자야. 오직 " + lang + "에 대해서만 질문을 물어봐."},
    {"role": "system", "content": "유저가 말하는 내용을 1점에서 100점까지 점수로 판단해야해. 문장 가장 처음은 무조건 점수부터 출력해."},
    {"role": "system", "content": "유저가 말하는 내용에 대한 점수는 데이터의 정확도로 판단해. 공백이거나 \"모르겠음\"이라는 의미가 포함되면 0점이야."},
    {"role": "system",
     "content": "유저가 말한 내용에 대해 '답변'과 '키워드'와 '꼬리질문'을 말해. 답변은 틀린 이유에 대해 설명해줘.\n점수 : {점수}점\n답변 : {답변}\n키워드: {키워드}\n꼬리질문: {꼬리질문}"},
    {"role": "system", "content": "어조: 친절하게, 전문적이게"},
    {"role": "assistant", "content": "꼬리질문: JAVA의 특징은 무엇이 있나요?"}, # 첫번째 질문을 미리 세팅해두었다.
    {"role": "user", "content": user_content}
]

# assistant를 저장하는 jsonl 파일을 읽고, message에 추가
with open('gpt_msg_assistant.jsonl', 'r') as file:
    for line in file:
        assistant = json.loads(line)
        messages.append(assistant)


# GPT 호출
completion = openai.ChatCompletion.create(model="gpt-4", messages=messages, temperature=0.2, max_tokens=2048)

# GPT 응답에서 필요한 부분만 추출
assistant_message = completion["choices"][0]["message"].encode("UTF-8").decode()

# 결과값을 확인하기 위해 출력
print(assistant_message)

# user의 답변을 jsonl 파일에 저장하기 위해 변수에 저장
user_message = {"role": "user", "content": user_content}


# 파일에 쓰기
data_path = "gpt_msg_assistant.jsonl"

with open(data_path, 'a', encoding='utf-8') as f:
    json.dump(user_message, f, ensure_ascii=False)
    f.write('\n')

with open(data_path, 'a', encoding='utf-8') as f:
    json.dump(assistant_message, f, ensure_ascii=False)
    f.write('\n')

이번 포스팅에서는 세세한 코드에 대한 설명보다는 GPT 라이브러리를 사용하는 부분에 대해서만 설명하도록 하겠다.

1. key 세팅

import os
from dotenv import load_dotenv

import openai

load_dotenv()

# key와 organization을 환경변수로 관리
openai.organization = os.getenv('OPENAI_ORGANIZATION')
openai.api_key = os.getenv('OPENAI_API_KEY')

openai 라이브러리를 호출하기 위한 기본 key값 설정이다. 여기서는 .env 파일로 관리하고 있다.

여기서 api_key는 위에서 등록해준 secret key를 입력하면 되며,

organization은 프로필 클릭 > ORGANIZATION > Settings > Organization ID에 적혀있는 값을 사용하면 된다.

2. messages 세팅

lang = "Java"
message = "Java는 객체지향 언어이다."

messages = [
    {"role": "system", "content": "너는 개발 면접자야. 오직 " + lang + "에 대해서만 질문을 물어봐."},
    {"role": "system", "content": "유저가 말하는 내용을 1점에서 100점까지 점수로 판단해야해. 문장 가장 처음은 무조건 점수부터 출력해."},
    {"role": "system", "content": "유저가 말하는 내용에 대한 점수는 데이터의 정확도로 판단해. 공백이거나 \"모르겠음\"이라는 의미가 포함되면 0점이야."},
    {"role": "system",
     "content": "유저가 말한 내용에 대해 '답변'과 '키워드'와 '꼬리질문'을 말해. 답변은 틀린 이유에 대해 설명해줘.\n점수 : {점수}점\n답변 : {답변}\n키워드: {키워드}\n꼬리질문: {꼬리질문}"},
    {"role": "system", "content": "어조: 친절하게, 전문적이게"},
    {"role": "assistant", "content": "꼬리질문: JAVA의 특징은 무엇이 있나요?"}, # 첫번째 질문을 미리 세팅해두었다.
    {"role": "user", "content": message}
]

# assistant를 저장하는 jsonl 파일을 읽고, message에 추가
with open('gpt_msg_assistant.jsonl', 'r') as file:
    for line in file:
        assistant = json.loads(line)
        messages.append(assistant)

본격적으로 프롬프트를 작성한다.

코드를 보면 role을 system으로 설정하고 GPT의 역할, 어조, 응답 형태 등등을 지정해주고 있다.

여기서는 assistant를 직접 입력해주어 첫번째 질문을 미리 세팅해두었다.

또, GPT를 호출할 때마다 응답(assistant)을 jsonl(Json line)파일에 저장해둔다음 GPT호출 전에 미리 messages에 그 내용을 append하여 이전 대화 내용을 기억할 수 있도록 해주었다.

3. GPT 호출

# GPT 호출
completion = openai.ChatCompletion.create(model="gpt-4", messages=messages, temperature=0.2, max_tokens=2048)

# GPT 응답에서 필요한 부분만 추출
assistant_message = completion["choices"][0]["message"].encode("UTF-8").decode()

# 결과값을 확인하기 위해 출력
print(assistant_message)

위에서 생성한 messages를 사용하여 GPT를 호출해준다.

예제에서는 가장 최신 모델인 gpt-4를 사용하였고, temperature는 다양한 질문을 받기 위해 0.2로, max_token은 2048으로 설정해주었다.

이 코드를 호출해보면 출력되는 응답값은 다음과 같다.

{
  "id": "chatcmpl-8C1VQeMNq3vFfbCriutG5CC3YvK4i",
  "object": "chat.completion",
  "created": 1697876416,
  "model": "gpt-4-0613",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "\uc810\uc218 : 70\uc810\n\ub2f5\ubcc0 : \ub9de\uc2b5\ub2c8\ub2e4. Java\ub294 \uac1d\uccb4\uc9c0\ud5a5 \uc5b8\uc5b4\uc785\ub2c8\ub2e4. \ud558\uc9c0\ub9cc Java\uc758 \ud2b9\uc9d5\uc740 \uadf8\uac83\ub9cc\uc774 \uc544\ub2d9\ub2c8\ub2e4. Java\ub294 \ud50c\ub7ab\ud3fc \ub3c5\ub9bd\uc801\uc774\uba70, \uba40\ud2f0\uc2a4\ub808\ub4dc\uc640 \ubd84\uc0b0\ud658\uacbd \uc9c0\uc6d0, \uac04\ub2e8\ud55c \uba54\ubaa8\ub9ac \uad00\ub9ac \ub4f1\uc758 \ud2b9\uc9d5\ub3c4 \uc788\uc2b5\ub2c8\ub2e4.\n\ud0a4\uc6cc\ub4dc: \uac1d\uccb4\uc9c0\ud5a5 \uc5b8\uc5b4, \ud50c\ub7ab\ud3fc \ub3c5\ub9bd\uc801, \uba40\ud2f0\uc2a4\ub808\ub4dc, \ubd84\uc0b0\ud658\uacbd \uc9c0\uc6d0, \uba54\ubaa8\ub9ac \uad00\ub9ac\n\uaf2c\ub9ac\uc9c8\ubb38: Java\uc758 \uba54\ubaa8\ub9ac \uad00\ub9ac\uc5d0 \ub300\ud574 \uc880 \ub354 \uc790\uc138\ud788 \uc124\uba85\ud574\uc8fc\uc2e4 \uc218 \uc788\ub098\uc694?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 353,
    "completion_tokens": 204,
    "total_tokens": 557
  }
}

이 중에서 우리는 message의 value를 가져와서 파일에 저장하기만 하면 되는데, content부분이 Unicode로 인코딩되어 출력되기 때문에 디코딩을 하는 과정이 필수이다.

결과값을 디코딩해보면 다음과 같이 출력된다.

점수 : 70점\n답변 : 맞습니다. Java는 객체지향 언어입니다. 하지만 Java의 특징은 그것만이 아닙니다. Java는 플랫폼 독립적이며, 멀티스레드와 분산환경 지원, 간단한 메모리 관리 등의 특징도 있습니다.\n키워드: 객체지향 언어, 플랫폼 독립적, 멀티스레드, 분산환경 지원, 메모리 관리\n꼬리질문: Java의 메모리 관리에 대해 좀 더 자세히 설명해주실 수 있나요?

4. 응답값 jsonl 파일에 쓰기

# 파일에 쓰기
data_path = "gpt_msg_assistant.jsonl"

with open(data_path, 'a', encoding='utf-8') as f:
    json.dump(user_message, f, ensure_ascii=False)
    f.write('\n')

with open(data_path, 'a', encoding='utf-8') as f:
    json.dump(assistant_message, f, ensure_ascii=False)
    f.write('\n')

GPT가 대화 맥락을 기억할 수 있도록 하기 위해 위에서 jsonl파일을 읽어 messages에 추가해주었다.

이 마지막 부분에서 사용자의 메시지와 GPT의 응답을 파일에 쓰게 된다.

마치며

간단하게 OpenAI의 라이브러리를 사용하는 과정에 대해 적어보았다.

GPT API에는 이렇게 간단한 대화 뿐만 아니라 직접 학습을 시키거나, 오디오를 인식하거나, 이미지를 만드는 등등의 파워풀한 기능이 굉장히 많아서 어떻게 사용하느냐에 따라 ChatGPT보다 더 좋은 서비스를 개발할 수 있을 것 같다.

앞으로는 이 예제 코드에 여러가지 기능을 추가해서 직접 화면을 띄워놓고 면접을 보는 서비스를 개발해 볼 예정이다.

[Spring boot] SSH 터널링 구현하기

Anna-Jin — Fri, 13 Oct 2023 12:05:01 +0900

들어가며

회사에서 개발 중인 서비스가 통신하기 위한 서버가 특정 서버에서만 접근 가능한 상황이었다.

백그라운드에서 동작하는 (유저가 접근하지 않아도 되는) 어플리케이션은 그 특정 서버에 서비스를 띄워서 서로 통신이 가능한 방식을 사용하고 있었지만 개발 중인 서비스가 동작 중인 서버는 별도의 서버로 분리가 되어있었고, 이 서버는 정책상 특정 서버에서 인바운드가 막혀있는 상태였다.

조금 복잡한데 아무튼 개발 중 서비스 -> 타겟 서버로의 직접 접근이 안된다는 말이다.

이 문제를 해결하기 위해서는 타겟 서버로의 접속을 우회하는 방식을 사용해야하는데 이걸 SSH 터널링이라고 한다.

이번에는 SSH 터널링의 개념과 필요성, 구현 예시에 대해 작성해보고자 한다.

SSH (Secure Shell)

시큐어 셸(Secure SHell, SSH)은 네트워크 상의 다른 컴퓨터에 로그인하거나 원격 시스템에서 명령을 실행하고 다른 시스템으로파일을 복사할 수 있도록 해 주는 응용 프로그램 또는 그 프로토콜을 가리킨다.
출처 - 위키백과

쉽게 말하면 원격 서버에 접속하기 위한 도구 라고 생각하면 된다. 사이드 프로젝트의 서버를 담당해본 사람이라면 아마 대부분 알고있지 않을까 싶다.

ssh 명령어는 아래처럼 사용 가능하다. -i 옵션은 key 파일로 서버에 접근해야하는 경우 사용하고, password를 사용한다면 옵션 없이 입력해도 된다.

ssh {user}@{host} -i {idendtity_file}

SSH의 Default Port는 22번이다. 따라서 telnet을 사용해서 22번 포트가 열려있는 지 확인하려면 아래처럼 작성하면 된다.

telnet {host} 22

접근이 제한되어있는 서버에 접속하려면?

현재 서버인 A 서버와 원격 서버인 B 서버가 있다고 가정하자.

A 서버 -> B 서버로의 통신은 불가능한데, 또 다른 서버인 C 서버 -> B 서버로의 접근이 가능하다. 또, A 서버 -> C 서버로의 접근 또한 가능하다.

이런 경우에 A 서버는 C 서버에 접속한 다음 B 서버로의 접속이 가능하다.

물론 직접 ssh 명령어를 하나하나 입력해서 B 서버까지 도달하는 방법도 있지만 보다 간단하게 A 서버에서 B 서버로의 접근이 가능한 방법이 있다.

이를 SSH 터널링 혹은 SSH 포트 포워딩이라고 한다.

일반적으로 이 C 서버를 '점프 서버(Jump Server)' 혹은 '배스쳔 서버(Bastion Server)'라고 부르고,

B 서버를 '리모트 서버(Remote Server)' 혹은 '타겟 서버(Target Server)'라고 부른다.

SSH 터널링 / SSH 포트 포워딩

둘은 비슷한 개념이지만 사실 개념에서 약간의 차이가 있다.

SSH 터널링 (SSH Tunneling)

SSH 터널링은 보안이 강화된 특별한 '터널'을 만들어서, 두 서버 사이에 안전하게 정보를 주고받을 수 있게 해주는 기술이다.

SSH 포트 포워딩 (SSH Port Forwarding)

SSH 포트 포워딩은 이런 '터널'을 통해서 특정 포트를 열어주는 기술이다. 포트 포워딩을 통해 서버와 클라이언트 사이의 통신을 안전하게 하거나, 보안 정책으로 인해 직접 접근이 불가능한 서버에 접근할 수 있다.

포트 포워딩은 로컬 포트 포워딩(Local Port Forwarding)과 리모트 포트 포워딩(Remote Port Forwarding), 그리고 다이나믹 포트 포워딩(Dynamic Port Forwarding, SOCKS Proxy)으로 나뉜다.

로컬 포트 포워딩

로컬 시스템(127.0.0.1 or localhost)의 특정 포트(LOCAL_PORT)를 리모트 서버의 특정 포트(REMOTE_PORT)와 연결한다.

클라이언트가 localhost:{LOCAL_PORT} 로 요청을 보내면, 그 요청은 SSH 터널을 통해서 {REMOTE_HOST}:{REMOTE_PORT} 로 전달된다.

리모트 포트 포워딩

리모트 서버의 특정 포트(REMOTE_PORT)를 로컬의 특정 포트(LOCAL_PORT)와 연결한다.

리모트 서버에서 localhost:{REMOTE_PORT} 로 요청을 보내면, 그 요청은 SSH 터널을 통해서 localhost:{LOCAL_PORT}로 전달된다.

다이나믹 포트 포워딩

로컬에서 설정한 동적 포트를 사용하여 SOCKS 프록시 서버를 구성한다. 이 SOCKS 프록시를 통해 여러 리모트 호스트와 포트로의 동적인 연결이 가능해진다.

결국 간단하게 말하면 SSH 터널링은 안전한 '도로'를 만드는 거고, SSH 포트 포워딩은 그 '도로' 위에서 특정 '출입구'를 열어주는 방식이다.

구현 예제

Spring boot에서 SSH를 사용하기 위한 몇가지 라이브러리가 존재하는데 이 예제에서는 JSch 라이브러리를 사용하였다.

Dependency

Maven

<!-- JSch for ssh -->
<dependency>
    <groupId>com.jcraft</groupId>
    <artifactId>jsch</artifactId>
    <version>0.1.55</version>
</dependency>

Gradle

// JSch for ssh
implementation 'com.jcraft:jsch:0.1.55'

최종 코드

최종 코드는 다음과 같다.

import com.jcraft.jsch.*;
import com.roomio.linkapiserver.exception.CustomException;
import com.roomio.linkapiserver.exception.errorCode.CommonErrorCode;
import lombok.extern.log4j.Log4j2;

import java.io.IOException;
import java.io.InputStream;

@Log4j2
class SshServiceExample {

    public static void main(String[] args) throws IOException {
        String jumpServerHost = "점프 서버 IP";
        String jumpServerUser = "점프 서버 USER";
        String jumpServerIdentityPath = "점프 서버 key file path";

        String remoteServerHost = "리모트 서버 IP";
        String remoteServerUser = "리모트 서버 USER";
        String remoteServerPassword = "리모트 서버 PASSWORD";

        String request = "실행할 명령어";

        StringBuilder response = new StringBuilder();

        Session jumpSession = null;
        Session remoteSession = null;
        ChannelExec channel = null;


        try {

            // JSch 로그 설정
            JSch.setLogger(new Logger() {
                @Override
                public boolean isEnabled(int level) {
                    return true;
                }

                @Override
                public void log(int level, String message) {
                    log.debug("========== JSch Logger==========\n==========Level: {}, Message: {} ===========", level, message);
                }
            });

            // JSch 객체 생성
            JSch jsch = new JSch();

            // First SSH session: application server -> jump server
            jumpSession = jsch.getSession(jumpServerUser, jumpServerHost, 22);


            // Private Key 설정
            jsch.addIdentity(jumpServerIdentityPath);

            // SSH에 처음 연결할 때, 리모트 호스트의 공개키가 자신의 known_hosts 파일에 저장된 것과 일치하는 지 검사하고 저장할 지 확인
            // no로 설정하면 보안에 취약해지므로 신뢰할 수 없는 네트워크에서는 사용을 지양해야함.
            jumpSession.setConfig("StrictHostKeyChecking", "no");

            // SSH 연결
            jumpSession.connect();


            log.info("SSH session1 connected");


            // Second SSH session: jump server -> remote server

            // 포트포워딩 설정을 해준다. Lport를 0으로 설정하면 자동으로 남는 포트에 바인딩 된다.
            /* 중요 */
            // jump server에는 사용 중이 아닌 포트가 (남는 포트)가 존재해야한다.
            int assigned_port = jumpSession.setPortForwardingL(0, remoteServerHost, 22); // 자동으로 바인딩된 포트번호
            // remote 서버를 열 때는 localhost로 열어야 한다.
            remoteSession = jsch.getSession(remoteServerUser, "localhost", assigned_port);
            remoteSession.setPassword(remoteServerPassword);

            remoteSession.setConfig("StrictHostKeyChecking", "no");

            remoteSession.connect();

            log.info("SSH session2 connected");

            // exec 타입의 채널 오픈. 이 채널에서 Command 사용 가능
            channel = (ChannelExec) remoteSession.openChannel("exec");

            // 실행할 Command 세팅
            channel.setCommand(request);

            // 채널 입력 스트림 설정
            // 입력 스트림 : 데이터가 프로그램으로 들어오는 통로. 여기서는 SSH 채널에서 명령어의 실행 결과를 읽어 오는 데 사용됨

            // 입력 스트림을 null로 설정하는 이유?
            // 단방향 통신: 이 예제에서는 서버에 명령을 내리고 그 결과만 읽어오면 된다. 즉, 명령 실행 후에 추가적으로 서버에 보낼 데이가 없고, 이런 경우 입력 스트림이 필요 없으므로 null로 설정한다.
            // 명령어 독립성: 명령어가 실행되는 동안에는 다른 입력을 받을 필요가 없음. 명령어는 이미 setCommand(command);로 설정되었기 때문에 추가적인 입력 스트림은 필요하지 않다..
            // 리소스 절약: 불필요한 스트림을 열지 않음으로써 리소스를 절약할 수 있다.
            // setInputStream(null);을 호출함으로써, JSch는 서버로부터 데이터를 읽어올 때만 스트림을 사용하고, 서버에 데이터를 보낼 때는 스트림을 사용하지 않게 된다. 이렇게 하면 명령어 실행과 결과 수집에만 집중할 수 있음.
            channel.setInputStream(null);
            channel.setErrStream(System.err);

            // 명령어의 출력을 받을 스트림을 가져옴
            InputStream input = channel.getInputStream();

            // 채널을 연결하여 명령어 실행
            channel.connect();

            log.info("channel.isConnected() : {}", channel.isConnected());

            // 결과값 가져오기
            byte[] buffer = new byte[1024];
            while (true) {
                int bytesRead = input.read(buffer, 0, buffer.length);
                if (bytesRead < 0) {
                    break;
                }
                response.append(new String(buffer, 0, bytesRead));
            }


        } catch (JSchException e) {

            throw new CustomException(CommonErrorCode.SSH_CONNECTION_FAILED.getCode(), CommonErrorCode.SSH_CONNECTION_FAILED.getMsg(), e.getMessage());

        } finally {
        
            // 채널과 세션 닫기
            // session은 자동으로 연결이 끊어지지 않기 때문에 finally 키워드로 직접 연결을 끊어줘야한다.
            if (channel != null && channel.isConnected()) {
                channel.disconnect();
            }
            if (remoteSession != null && remoteSession.isConnected()) {
                remoteSession.disconnect();
            }
            if (jumpSession != null && jumpSession.isConnected()) {
                jumpSession.disconnect();
            }
        }

        // 응답값 출력
        System.out.println(response);
    }
}

각 단계별로 코드를 살펴보도록 하자. 기본 변수 세팅 부분은 넘어가도록 한다.

JSch 로그 설정 및 객체 생성

// JSch 로그 설정
JSch.setLogger(new Logger() {
    @Override
    public boolean isEnabled(int level) {
        return true;
    }

    @Override
    public void log(int level, String message) {
        log.debug("========== JSch Logger==========\n==========Level: {}, Message: {} ===========", level, message);
    }
});

// JSch 객체 생성
JSch jsch = new JSch();

JSch는 자체적으로 Logger 인터페이스를 제공한다.

이 인터페이스를 상속 받아서 구현을 해도 되지만, 이번에는 익명클래스를 사용해서 간단하게 Logger를 구현했다.

boolean isEnabled(int level) : 인자로 받은 로그 레벨에 대한 로깅이 활성화 되어있는 지 확인
다음과 같이도 사용 가능하다.
가능한 로그 레벨은 DEBUG, INFO, WARN, ERROR, FATAL이 있다.

@Override
public boolean isEnabled(int level) {
    return level == Logger.DEBUG;
}

void log(int level, String message) : 로그 메세지 출력. level의 실제 값은 아래를 참고하자.

int DEBUG = 0;
int INFO = 1;
int WARN = 2;
int ERROR = 3;
int FATAL = 4;

로깅을 설정한 다음에는 new JSch();로 객체를 생성해주면 JSch를 사용할 준비가 끝났다.

다음에는 ssh에 접속해서 터널링까지 진행해보자.

SSH Session 연결 및 포트 포워딩(터널링)

// First SSH session: application server -> jump server
jumpSession = jsch.getSession(jumpServerUser, jumpServerHost, 22);
jsch.addIdentity(jumpServerIdentityPath); // Private Key 설정
jumpSession.setConfig("StrictHostKeyChecking", "no");
jumpSession.connect(); // SSH 연결


log.info("SSH Jump session connected");


// Second SSH session: jump server -> remote server
int assigned_port = jumpSession.setPortForwardingL(0, remoteServerHost, 22); // 자동으로 바인딩된 포트번호
remoteSession = jsch.getSession(remoteServerUser, "localhost", assigned_port);
remoteSession.setPassword(remoteServerPassword);
remoteSession.setConfig("StrictHostKeyChecking", "no");
remoteSession.connect();


log.info("SSH Remote session connected");

SSH를 사용하기 위한 Session 객체를 만들어 connect하는 부분이다.

해당 코드는 현재 서버 구조상 local -> jump -> remote -> target 형태이기 때문에 Session을 두번 생성하고 있지만 일반적인 경우라면 Second SSH session 부분 하나로도 터널링이 가능하다.

이 코드에서 주목해야할 부분은 setPortForwardingL() 부분인데, 차근차근 따라가면서 이해해보자.

Application Server -> Jump Server

jumpSession = jsch.getSession(jumpServerUser, jumpServerHost, 22);

로컬 서버(Spring application server)에서 점프 서버로 접속하기 위한 Session을 연다. 일반적인 경우, 점프 서버가 로컬 서버가 된다. 이점에 유의하고 헷갈리지 말자.

jsch.addIdentity(jumpServerIdentityPath);

점프 서버는 Password 대신 key.pem 파일을 사용하여 서버에 접속한다. 따라서 setIdentity()를 사용하여 pem 파일이 저장되어있는 경로를 입력해준다.

jumpSession.setConfig("StrictHostKeyChecking", "no");

StrickHostKeyChecking은 SSH에 처음 연결할 때, 접속하려는 서버의 공개키가 자신의 known_hosts 파일에 저장된 것과 일치하는 지 검사하고 저장할 지 확인하는 옵션이다.

이 옵션을 no로 설정하면 보안에 취약해지므로 신뢰할 수 없는 네트워크에서는 사용을 지양해야한다.

이 예제에서는 각각의 서버가 특정 IP로 제한되어 있기 때문에 해당 옵션을 비활성화 해주었다.

jumpSession.connect();

마지막 코드를 실행시키면 최종적으로 점프 서버로의 SSH 접속이 완료된다.

Jump Server -> Remote Server

진짜 SSH 터널링을 하는 작업을 진행해보자.

SSH 터널링 / 포트포워딩을 하기 위해 선행되어야하는 작업이 있는데, 바로 사용하지 않는 포트를 확보하는 것이다.

SSH 터널링은 사용되지 않는 포트를 잡아서 localhost:{포트} 로 요청을 받고, 리모트 서버의 특정 포트(여기서는 22)로 포트 포워딩 시키는 방식을 사용하고 있기 때문에 서버 내의 모든 포트가 사용 중이라면 터널링 기능을 사용할 수 없다.

int assigned_port = jumpSession.setPortForwardingL(0, remoteServerHost, 22);

포트 포워딩을 위한 설정 부분이다.

첫번째 인자(Lport)에는 사용 가능한 포트 번호를 적어주면 되는데, "0"을 사용하면 자동으로 서버 내의 남아있는 포트를 찾아 바인딩해준다.

두번째 인자와 세번째 인자에는 터널링을 하고자하는 서버의 host와 port를 작성해주면 된다.

remoteSession = jsch.getSession(remoteServerUser, "localhost", assigned_port);

위에서와 똑같이 리모트 서버로 접속하기 위한 세션을 연다. 이때, 주의할 점은 위에서 포트포워딩 설정을 해주었기 때문에 localhost:{assigned_port} 를 Host에 적어주어야 정상적으로 접속이 가능하다.

remoteSession.setPassword(remoteServerPassword);

이 예제에서 리모트 서버는 Password를 사용하기 때문에 setPassword()를 사용해주었다.

Remote Server에서 Command 실행

// 명령어 실행을 위한 Channel 열기
channel = (ChannelExec) remoteSession.openChannel("exec");
channel.setCommand(request);

channel.setInputStream(null);
InputStream input = channel.getInputStream();

channel.connect();

log.info("channel.isConnected() : {}", channel.isConnected());

// 결과값 가져오기
byte[] buffer = new byte[1024];
while (true) {
    int bytesRead = input.read(buffer, 0, buffer.length);
    if (bytesRead < 0) {
        break;
    }
    response.append(new String(buffer, 0, bytesRead));
}

이제 접속한 리모트 서버에서 Command를 보낼 수 있게 되었다.

channel = (ChannelExec) remoteSession.openChannel("exec");
channel.setCommand(request);

서버에서 직접 Command를 보내기 위해서는 Channel을 열어주어야한다. 이를 위해 리모트 서버의 세션에서 openChannel()을 해주어야하는데, 이 메소드의 인자로 들어갈 수 있는 타입 중 주로 사용하는 타입은 다음과 같다.

session: 기본 세션 채널, 특별한 동작 없음
shell: 원격 쉘을 열어 명령어 실행. 일반적으로 대화식 작업에 사용
exec: 단일 명령어 실행. 명령 실행이 완료되면 채널이 자동으로 닫힘.
sftp: 파일 전송을 위해 사용

이 예제에서는 단순히 커맨드를 실행하기만 하면 되므로 exec타입을 사용했다.

channel.setInputStream(null);

다음으로는 채널 입력 스트림을 설정해주어야한다.

다음과 같은 이유로 입력 스트림은 null로 설정해준다.

단방향 통신: 이 예제에서는 서버에 명령을 내리고 그 결과만 읽어오면 된다. 즉, 명령 실행 후에 추가적으로 서버에 보낼 데이터가 없고, 이런 경우 입력 스트림이 필요하지 않다.
명령어 독립성: 명령어가 실행되는 동안에는 다른 입력을 받을 필요가 없다. 명령어는 이미 setCommand(request);로 설정되었기 때문에 추가적인 입력 스트림은 필요하지 않다.
리소스 절약: 불필요한 스트림을 열지 않음으로써 리소스를 절약할 수 있다.

InputStream input = channel.getInputStream();
channel.connect();

마지막으로 명령어의 출력을 받을 스트림을 가져온 후 채널을 연결하여 명령어를 실행하면 inputStream에서 결과값을 가져와 가공할 수 있는 단계가 된다.

입력 스트림(Input Stream)?
데이터가 프로그램으로 들어오는 통로. 여기서는 SSH 채널에서 명령어의 실행 결과를 읽어오는 데 사용된다.

Session 닫기

finally {
    if (channel != null && channel.isConnected()) {
        channel.disconnect();
    }
    if (remoteSession != null && remoteSession.isConnected()) {
        remoteSession.disconnect();
    }
    if (jumpSession != null && jumpSession.isConnected()) {
        jumpSession.disconnect();
    }
}

위의 코드들이 try-catch로 묶여있었는데, 마지막 finally 키워드를 이용하여 채널과 세션을 모두 닫아준다.

Session은 모든 과정이 끝나더라도 자동으로 연결이 끊어지지 않기 때문에 작업 중간에 에러가 나더라도 세션이 유지된다.

따라서 꼭 세션을 닫아주도록 하자.

마치며

보안이 철저한 서버의 구조가 많은 우리 회사의 특성상 이렇게 SSH 터널링을 한번 구현해두니 다방면으로 사용할 수 있게 되었다. 앞으로는 어플리케이션 서버에서 여러 서버로의 접근이 가능해진 셈이니 말이다.

보안이 중요한 회사 도메인 특성상 여러 단계의 서버를 거칠일이 많기 때문에 기록해두고 자주 꺼내볼듯 싶다.

[Spring boot] WebClient 사용해보기 - 모듈화 1-2

Anna-Jin — Sat, 26 Aug 2023 17:34:16 +0900

들어가며

2023.08.25 - [Study/Spring boot] - [Spring boot] WebClient 사용해보기 2-1

이전글에서는 내가 어떻게 웹클라이언트를 사용하고 있는 지에 대해 간단하게 설명했다.

이번 글에서는 코드를 하나씩 보면서 내가 짠 코드가 어떻게 작동하는 지에 대해 설명해보고자 한다.

메서드 체이닝 방식 구현

지난 글에서 위의 그림과 같이 메서드 체이닝 방식을 직접 구현했었다.

위의 그림 순서에 따라서 차근차근 코드를 보자.

ApiWebClientBuilder

@Component
@RequiredArgsConstructor
public class ApiWebClientBuilder {

    private final WebClient.Builder webClientBuilder;

    // 체이닝 시작점
    public <T> MethodStep<T> request() {
        return new MethodStepImpl<>(this.webClientBuilder);
    }
}

메서드 체이닝의 시작점이다.

일반적으로 WebClient를 Bean으로 등록할 때 WebClient 객체 자체를 등록해서 사용하는데, 여기서는 WebClient.Builder를 @Component어노테이션을 이용하여 Bean으로 등록한 후 이후 Build 과정을 동적으로 받을 수 있게 하였다.

이 클래스를 의존성 주입을 한 다음 request()메서드를 호출하게 되면 다음 순서인 MethodStepImpl객체를 리턴하게 된다.

request 메서드는 시작점이기 때문에 이 메서드가 호출되기 전에는 다음 과정을 수행할 수 없고, 다른 메서드를 먼저 호출하려고 하면 컴파일 에러가 뜨게 된다.

MethodStepImpl

@RequiredArgsConstructor
@Slf4j
public class MethodStepImpl<T> implements MethodStep<T> {

    private final WebClient.Builder webClientBuilder;
    private WebClient.RequestHeadersSpec<?> methodType;


    /**
     * WebClient의 baseUrl과 defaultHeader, encoding 설정
     *
     * @return {@link WebClient}
     */
    private WebClient setBase(String baseUrl) {
        // 인코딩 설정
        DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
        factory.setEncodingMode(DefaultUriBuilderFactory.EncodingMode.VALUES_ONLY);

        // memory size 설정
        ExchangeStrategies exchangeStrategies = ExchangeStrategies.builder()
                .codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(50 * 1024 * 1024)) // to unlimited memory size
                .build();

        // timeout 설정
        ReactorClientHttpConnector httpConnector = new ReactorClientHttpConnector(
                HttpClient.create()
                        .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 120000)
                        .responseTimeout(Duration.ofSeconds(120)));


        return this.webClientBuilder
                .exchangeStrategies(exchangeStrategies)
                .clientConnector(httpConnector)
                .uriBuilderFactory(factory)
                .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
                .baseUrl(baseUrl)
                .build();
    }

    /**
     * WebClient의 HttpMethod를 POST로 설정.<br>
     * Path 사용
     *
     * @return {@link ConnectStep}
     */
    @Override
    public ConnectStep post(String baseUrl, String path, T requestBody) {
        this.methodType = this.setBaseUrl(!StringUtils.hasText(baseUrl) ? "" : baseUrl)
                .post()
                .uri(uriBuilder -> uriBuilder
                        .path(path)
                        .build())
                .bodyValue(requestBody);
        return new ConnectStepImpl(this.methodType);
    }

    /**
     * WebClient의 HttpMethod를 POST로 설정.<br>
     * queryParam 사용
     *
     * @return {@link ConnectStep}
     */
    @Override
    public ConnectStep post(String baseUrl, MultiValueMap<String, String> params, T requestBody) {
        this.methodType = this.setBaseUrl(baseUrl)
                .post()
                .uri(uriBuilder -> uriBuilder
                        .queryParams(params)
                        .build())
                .bodyValue(requestBody);
        return new ConnectStepImpl(this.methodType);
    }

    /**
     * WebClient의 HttpMethod를 GET으로 설정.<br>
     *
     * @return {@link ConnectStep}
     */
    @Override
    public ConnectStep get(String baseUrl, MultiValueMap<String, String> params) {
        this.methodType = this.setBaseUrl(baseUrl)
                .get()
                .uri(uriBuilder -> uriBuilder
                        .queryParams(params == null || params.isEmpty() ? new LinkedMultiValueMap<>() : params)
                        .build());
        return new ConnectStepImpl(this.methodType);
    }
}

MethodStep Interface

public interface MethodStep<T> {
    ConnectStep post(String baseUrl, String path, T requestBody);
    ConnectStep post(String baseUrl, MultiValueMap<String, String> params, T requestBody);
    ConnectStep get(String baseUrl, MultiValueMap<String, String> params);
}

MethodStep부터는 본격적으로 동적으로 값을 세팅하기 시작한다.

이 곳에서 baseUrl을 세팅하고, Api를 어떤 Http method로 호출할 것인지 선택하게 된다.

기본적으로 Interface를 상속받게 함으로써 기본적으로 사용하게 될 메서드 구현을 강제하게 만들었다.

각각의 메소드는 개발자에 따라 다르겠지만 우선 가장 많이 사용하는 post와 get를 몇가지 방식으로 구현해두었다.

메소드를 하나씩 보면서 따라가보자.

setBase()

private WebClient setBase(String baseUrl) {
        // 1. 인코딩 설정
        DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
        factory.setEncodingMode(DefaultUriBuilderFactory.EncodingMode.VALUES_ONLY);

        // 2. memory size 설정
        ExchangeStrategies exchangeStrategies = ExchangeStrategies.builder()
                .codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(50 * 1024 * 1024)) // to unlimited memory size
                .build();

        // 3. timeout 설정
        ReactorClientHttpConnector httpConnector = new ReactorClientHttpConnector(
                HttpClient.create()
                        .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 120000)
                        .responseTimeout(Duration.ofSeconds(120)));


        return this.webClientBuilder
                .exchangeStrategies(exchangeStrategies)
                .clientConnector(httpConnector)
                .uriBuilderFactory(factory)
                .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
                .baseUrl(baseUrl)
                .build();
    }

이 메소드에서는 baseUrl 세팅과 Api 호출에 필요한 여러가지 설정을 세팅한다.

각 설정을 동적으로 받지 않은 이유는, 프로젝트 구조상 굳이 뺄 필요가 없는 설정들이라고 판단했기 때문에 자칫해서 개발자가 놓칠 수도 있는 부분을 고려하지 않아도 될 수 있게 하기 위함이다.

각 설정을 살펴보자

인코딩 설정 : 다음글을 참고해서 인코딩 모드를 설정해주었다. 각 EncodingMode에 대한 설명은 링크에 설명되어있긴 하지만 간단하게 설명을 적어본다.
- TEMPLATE_AND_VALUES : URI의 문자열과 변수가 모두 인코딩된댜. 이때 URI Template(고정된 문자열들 ex. host, 변수명 등) 가 먼저 인코딩 되고 이후 변수가 특정 기준에 맞춰 인코딩된다.
- VALUES_ONLY : URI Template를 인코딩하지 않고 URI 변수만 인코딩한다.
- URI_COMPONENT : URI 변수가 대입된 후에 각 구성요소들을 인코딩한다. 이때 path에 허용된 예약어들은 인코딩하지 않는다.
- NONE : 인코딩을 적용하지 않는다.
Memory size 설정 : 응답값의 최대 메모리 사이즈를 결정해주었다.
Timeout 설정 : 현재 사용 중인 Api의 권장 timeout시간이 120초였기에 다음과 같이 설정했다. tcpConfiguration()은 deprecated 되었으므로 Option()을 사용하여 Connection timeout 설정을 해준다.

설정이 끝났다면 의존성 주입으로 받은 WebCliet.Builder 객체를 이용하여 본격적으로 WebClient 객체 빌드를 하고 이후 객체 사용을 위해서 리턴해준다.

post(), get()

/**
 * WebClient의 HttpMethod를 POST로 설정.<br>
 * Path 사용
 *
 * @return {@link ConnectStep}
 */
@Override
public ConnectStep post(String baseUrl, String path, T requestBody) {

    if (!StringUtils.hasText(baseUrl)) {
        throw new ApiException(ErrorCode.ETC_ERROR, "[WebClient] baseUrl은 비어있을 수 없습니다.");
    }

    this.methodType = this.setBaseUrl(baseUrl)
            .post()
            .uri(uriBuilder -> uriBuilder
                    .path(path)
                    .build())
            .bodyValue(requestBody);
    return new ConnectStepImpl(this.methodType);
}

/**
 * WebClient의 HttpMethod를 POST로 설정.<br>
 * queryParam 사용
 *
 * @return {@link ConnectStep}
 */
@Override
public ConnectStep post(String baseUrl, MultiValueMap<String, String> params, T requestBody) {
    if (!StringUtils.hasText(baseUrl)) {
        throw new ApiException(ErrorCode.ETC_ERROR, "[WebClient] baseUrl은 비어있을 수 없습니다.");
    }

    this.methodType = this.setBaseUrl(baseUrl)
            .post()
            .uri(uriBuilder -> uriBuilder
                    .queryParams(params)
                    .build())
            .bodyValue(requestBody);
    return new ConnectStepImpl(this.methodType);
}

/**
 * WebClient의 HttpMethod를 GET으로 설정.<br>
 *
 * @return {@link ConnectStep}
 */
@Override
public ConnectStep get(String baseUrl, MultiValueMap<String, String> params) {
    if (!StringUtils.hasText(baseUrl)) {
        throw new ApiException(ErrorCode.ETC_ERROR, "[WebClient] baseUrl은 비어있을 수 없습니다.");
    }

    this.methodType = this.setBaseUrl(baseUrl)
            .get()
            .uri(uriBuilder -> uriBuilder
                    .queryParams(params == null || params.isEmpty() ? new LinkedMultiValueMap<>() : params)
                    .build());
    return new ConnectStepImpl(this.methodType);
}

WebClient가 호출하게 될 HttpMethod를 선택하고, RequestBody 혹은 RequestParam을 설정하는 부분이다.

프로젝트 요구사항에서 POST나 GET 이외의 방식은 사용할 일이 없었기 때문에 두가지 메소드만 선언을 해두었지만, 개인의 요구사항에 맞게 세팅하면 된다.

WebClient의 각 메소드를 간단하게 설명해보면 다음과 같다.

get(), post() : Http Method
uri() : UriBuilder를 이용하여 호출하려는 uri의 scheme, host, path, param... 등등을 설정할 수 있다.
bodyValue() : 객체 자체를 RequestBody로 담아 보낼 수 있다. WebFlux에서는 비동기 타입인 Mono나 Flux를 사용하지만 bodyValue를 사용하면 실제 값을 담을 수 있다.

Method 선택 및 RequestBody(Param)의 세팅이 끝났다면 다음 단계인 ConnectStepImpl을 return해주어 다음 체이닝 단계를 사용할 수 있게 해준다.

위의 코드처럼 호출 URL을 WebClient 객체를 build하기 전 baseUrl로 설정해주는 방식도 존재하지만, UriBuilder의 sheme(), host() 메소드를 사용해서 지정할 수도 있다. 하지만 이렇게 하게 되면 URL을 설정하는 코드가 중복되기 때문에 하나의 메소드로 분리하여 구현하였다.

UriBuilder를 사용하여 URL을 지정하는 방법은 아래와 같다.

this.setBaseUrl(baseUrl)
                .post()
                .uri(uriBuilder -> uriBuilder
                        .scheme("https")
                        .host("example.com")
                        .queryParams(params)
                        .build())
                .bodyValue(requestBody);

ConnectStepImpl

@Slf4j
@RequiredArgsConstructor
public class ConnectStepImpl implements ConnectStep {

    private final WebClient.RequestHeadersSpec<?> methodType;
    private Object response;


    /**
     * WebClient의 header와 response class 설정 후 block으로 호출<br>
     * 헤더와 응답값이 존재할 때 사용. (ex. 일반적인 api 호출)<br>
     * 예외처리 포함
     *
     * @return {@link ResponseStep}
     */
    @Override
    public ResponseStep connectBlock(Map<String, String> headers, Class<?> responseType) {
        try {
            this.response = this.methodType
                    .headers(httpHeaders -> {
                        httpHeaders.setAll(headers == null || headers.isEmpty() ? new HashMap<>() : headers);
                    })
                    .retrieve()
                    .onStatus(HttpStatus::isError, clientResponse ->
                            clientResponse.bodyToMono(String.class)
                                    .flatMap(msg -> Mono.error(new APIException(ResponseCode.INTERFACE_ERROR, msg))))
                    .bodyToMono(responseType)
                    .retryWhen(Retry.fixedDelay(3, java.time.Duration.ofSeconds(1))
                            .doBeforeRetry(before -> log.info("Retry: {} | {}", before.totalRetries(), before.failure())))
                    .block();
            return new ResponseStepImpl(this.response);
        } catch (Exception e) {
            log.error("Exception : {}", e.getMessage());
            throw new ApiException(ErrorCode.INTERFACE_ERROR, e.getMessage());
        }
    }


    @Override
    public ResponseStep connectBlock(Map<String, String> headers) {
        try {
            this.response = this.methodType
                    .headers(httpHeaders -> {
                        httpHeaders.setAll(headers == null || headers.isEmpty() ? new HashMap<>() : headers);
                    })
                    .retrieve()
                    .onStatus(HttpStatus::isError, clientResponse ->
                            clientResponse.bodyToMono(String.class)
                                    .flatMap(msg -> Mono.error(new APIException(ResponseCode.INTERFACE_ERROR, msg))))
                    .bodyToMono(Object.class)
                    .retryWhen(Retry.fixedDelay(3, java.time.Duration.ofSeconds(1))
                            .doBeforeRetry(before -> log.info("Retry: {} | {}", before.totalRetries(), before.failure())))
                    .block();
            return new ResponseStepImpl(this.response);
        } catch (Exception e) {
            log.error("Exception : {} | {}", e.getMessage(), e.getStackTrace()[0].toString());
            throw new ApiException(ErrorCode.INTERFACE_ERROR, e.getMessage());
        }
    }


    /**
     * WebClient의 header와 response class 설정 후 block으로 호출<br>
     * 헤더와 응답값이 존재하지 않을 때 사용. (ex. Google chat webhook api 호출)<br>
     * 예외처리 포함
     *
     * @return {@link ResponseStep}
     */
    @Override
    public ResponseStep connectBlock() {
        try {
            this.response = this.methodType
                    .retrieve()
                    .onStatus(HttpStatus::isError, clientResponse ->
                            clientResponse.bodyToMono(String.class)
                                    .flatMap(msg -> Mono.error(new APIException(ResponseCode.INTERFACE_ERROR, msg))))
                    .bodyToMono(Object.class)
                    .retryWhen(Retry.fixedDelay(3, java.time.Duration.ofSeconds(1))
                            .doBeforeRetry(before -> log.info("Retry: {} | {}", before.totalRetries(), before.failure())))
                    .block();
            return new ResponseStepImpl(this.response);
        } catch (Exception e) {
            log.error("Exception : {} | {}", e.getMessage(), e.getStackTrace()[0].toString());
            throw new ApiException(ErrorCode.INTERFACE_ERROR, e.getMessage());
        }
    }
}

ConnectStep은 본격적으로 API를 URL로 호출하여 응답을 받는 부분이다.

이번에도 각 메소드를 하나씩 살펴보자

retrieve() : WebClient에서 응답을 받는 방식은 exchange()와 retrieve() 두가지가 있다. exchange()는 deprecated되었으므로 만약 exchange를 사용하고 싶다면 exchangeToMono() 나 exchangeToFlux()를 사용하자.
onStatue() : 상태코드를 캐치한다. 특정 상태코드 (404, 500 등등)나 4xx, 5xx 등 세분화하여 응답을 받을 수 있다.
- 여기서는 isError를 사용하여 모든 에러를 캐치하여 Exception을 throw할 수 있도록 구현하였다.
bodyToMono() : ResponseBody를 원하는 객체로 변환한다. Mono 타입이므로 0 ~ 1개의 응답만 받을 수 있다.
- 만약 2개 이상의 응답을 받고 싶다면 bodyToFlux()를, ResponseEntity를 받고 싶다면 toEntity()를 사용할 수 있다.
retryWhen() : 에러가 발생했을 경우 재시도 한다. Retry 객체로 재시도 횟수와 대기 시간, 재시도하기 전에 수행할 동작을 정의할 수 있다.
block() : 응답을 동기 방식으로 받는다. block를 사용하면 비동기 타입인 Mono<Object>가 아닌 Object 객체를 가져올 수 있지만 WebClient의 장점인 비동기 방식이 아닌 동기 방식을 사용한다는 부분에 유의하자.
- 내 경우에는 비동기 통신을 이용할 일이 없기 때문에 모든 메소드를 block()을 사용하여 동기 방식을 사용하였다. 이 역시 개인의 요구사항에 맞춰 사용하자.

코드를 살펴보면 오버로딩을 통해 여러가지 파라미터를 받는 걸 확인할 수 있다. 이는, 요청으로 header가 필요한 경우, 특정 응답 객체로 받는 경우, 아무 응답도 받지 않는 경우를 모두 구현해 놓았기 때문이다.

이렇게 API 호출 및 응답을 받는 과정을 마치면 최종적으로 객체를 원하는 형태로 만드는 ResponseStepImpl을 리턴하여 최종 단계로 넘어갈 수 있다.

ResponseStepImpl

@Slf4j
@RequiredArgsConstructor
public class ResponseStepImpl implements ResponseStep {

    private final Object response;

    /**
     * WebClient의 response를 Object로 리턴<br>
     * 응답값을 response type class로 파싱 후 사용<br>
     * <br>
     * Example)<br>
     * TestDto test = (TestDto) webClientConnectorTest.post(url, path, requestBody)
     *                 .connectBlock(headers, TestDto.class)
     *                 .toObjectCall();
     * @return {@link Object}
     */
    @Override
    public Object toObjectCall() {
        return this.response;
    }

    /**
     * WebClient의 response를 JsonNode로 파싱하여 리턴
     * @return {@link JsonNode}
     */
    @Override
    public JsonNode toJsonNodeCall() {
        try {
            ObjectMapper om = new ObjectMapper();

            return om.readTree(this.response.toString());
        } catch (JsonProcessingException e) {
            log.error("JsonProcessingException : {}", e.getMessage());
            throw new ApiException(ErrorCode.INTERFACE_ERROR, e.getMessage());
        }
    }

    /**
     * WebClient의 response를 리턴하지 않음
     */
    @Override
    public void toVoidCall() {}
}

마지막 step은 간단하다. 어떤 형태의 객체를 return할 지를 결정하는 부분이다.

사실 toJsonNodeCall()은 굳이 필요하지 않지만 팀원의 요청으로 넣어두었기 때문에 무시해도 된다.

크게 설명할 부분이 없으므로 이 부분은 코드만 보여주고 넘어가도록 하겠다.

Result

이 모든 과정을 마치면 이전 글에서 작성한 것처럼 아래와 같이 코드를 사용할 수 있다.

public Object callApi(String baseUrl, String path, T request, Class<?> response) {
    return apiWebClientBuilder.request()
            .post(baseUrl, path, request)
            .connectBlock(this.getHeader(), response)
            .toObjectCall();
}

public ExampleResponseDto exampleCallApi(ExampleRequestDto request) {
	String baseUrl = "https://example.com";
    String path = "/api/test";
    
    return (ExampleResponseDto) this.callApi(baseUrl, path, request, ExampleResponseDto.class);
}

최종 코드는 아래 Github 링크에서 확인할 수 있다

https://github.com/Anna-Jin/spring-boot

GitHub - Anna-Jin/spring-boot: spring boot 코드 정리 및 공부용 레파지토리

spring boot 코드 정리 및 공부용 레파지토리. Contribute to Anna-Jin/spring-boot development by creating an account on GitHub.

github.com

마치며

어떻게 WebClient를 더 쉽게 라이브러리처럼 bean등록하여 사용할 수 있을까 고심하여 코드를 짜보았다.

긴 내용이지만 WebClient에 대한 약간의 이해가 있는 상태에서 차근차근 따라가면 크게 어려울 것 없는 코드라고 생각한다.

아직 초보 개발자로서 완벽한 코드라고 말하기는 어렵지만, 계속 코드를 업데이트하면서 더 완벽하게 만들어 모듈화시킬 예정이다!

[Spring boot] WebClient 사용해보기 - 모듈화 1-1

Anna-Jin — Fri, 25 Aug 2023 18:44:27 +0900

들어가며

무려 1년도 더 된 이전글이 항상 내 블로그 인기글 1위인걸 볼 때마다 마음에 걸렸다.

누가봐도 개발 갓 시작한 초보가 쓴 티가 나는 글..ㅜㅜ

막 개발 공부하기 시작했을 즈음 webClient에 대한 자료가 별로 없어서 정리할 겸 작성했던 글인데 관련 키워드로 검색하면 저 글이 뜨는 걸 보고... 새롭게 알게된 내용들을 조금 더 추가하고, 현재는 어떻게 사용하고 있는 지에 대해 정리를 해보고자 한다.

기본 개념이나 RestTemplate과의 차이점 등등은 공식문서나 구글에 검색하면 깔끔하게 정리된 자료가 많기에 넘어가기로 하고, 내가 사용하면서 알게 된 개념들만 적어내려가보겠다!

WebClient

최종적으로 완성될 구조는 위와 같다. 각 step 이 뭐고 어떻게 사용하는 지는 천천히 설명하기로 하겠다.

이 구조를 사용하면 아래와 같이 코드를 사용할 수 있다.

/**
 * API 호출
 *
 * @param baseUrl  특정 API 마다 baseUrl이 다를 수 있음.
 * @param path     path parameter
 * @param request  requestBody
 * @param response responseBody의 class
 * @return 응답 객체
 */
public Object callApi(String baseUrl, String path, T request, Class<?> response) {
    return apiWebClientBuilder.request()
            .post(baseUrl, path, request)
            .connectBlock(this.getHeader(), response)
            .toObjectCall();
}

이런 구조를 사용한 이유?

이런 각 step 구조로 만들게 된 이유는 회사 내의 OpenApi에서 범용적으로 사용할 수 있도록하고, 메서드 체이닝 방식을 사용해서 마치 라이브러리를 사용하는 것처럼 간편하게 사용할 수 있게 하기 위해서이다.

WebClient를 각 요청마다 매번 새롭게 생성해서 사용하기에는 반복되는 코드가 많아지는 문제가 있었고, bean에 등록해서 사용하기에는 WebClient는 Immutable하기 때문에 한번 Build를 하고나면 기존 객체를 mutate해서 사용해야했기 때문에 번거롭다는 생각이 들었다.

Webclient 공식문서에는 다음과 같은 내용이 기술되어있다.
Once built, a WebClient is immutable. However, you can clone it and build a modified copy as follows:
WebClient client1 = WebClient.builder()
		.filter(filterA).filter(filterB).build();

WebClient client2 = client1.mutate()
		.filter(filterC).filter(filterD).build();

// client1 has filterA, filterB

// client2 has filterA, filterB, filterC, filterD
출처 : WebClient 공식문서

따라서 최종 목표는 bean등록을 함으로써 중복되는 코드를 줄이면서도 baseUrl은 동적으로 변경할 수 있도록 구현하는 것이었다. 또, 메서드 체이닝을 할 때 메서드 호출 순서를 강제하게 함으로써 예상치 못한 문제 또한 제거하고자 했다.

구현 예제

메서드 체이닝은 각 체이닝 단계별로 Interface와 구현체를 만들고, 순차적으로 다음 단계의 구현체를 리턴하는 방식으로 구현된다.

이미지로 표현한 메서드 체이닝 구조

기존에는 Builder 패턴처럼 구현하려고 했었다. 위와 같은 방식을 사용하면 각 호출마다 새로운 객체를 생성하게 되어서 메모리 낭비가 될 우려가 있었기 때문이다. 하지만 Builder 패턴처럼 구현하게 되면 메서드 호출 순서를 강제할 수 없기 때문에 문제가 발생 가능성이 있었다.

마치며

지금까지 간단하게 내가 어떻게 WebClient를 사용하고 있는지 설명해보았다.

다음 글에서는 코드를 하나씩 살펴보면서 어떻게 구현했는 지를 설명해보려고 한다.

2023.08.26 - [Study/Spring boot] - [Spring boot] WebClient 사용해보기 2-2

출처 및 참고

WebClient 공식문서

[Intellij] 인텔리제이 TODO 코드태그(Code Tag) 커스텀

Anna-Jin — Tue, 24 Jan 2023 17:35:29 +0900

들어가며

인텔리제이 TODO

개발을 하다보면 사진처럼 주석을 하이라이팅 하거나 한눈에 모아보고 싶은 경우가 있다.

Intellij에서 제공하는 테마를 살짝 손봐서 주석 색상을 변경하는 방법도 있고, Javadoc 주석(/** content */)을 사용는 방법도 있 지만 Intellij 자체에서 주석을 모아보는 TODO 기능이 존재한다.

오늘은 Intellij에서 제공하는 TODO 코드 태그(Code Tag)기능을 알아보자!

TODO 기능 사용하기

기본 사용법

TODO 기능의 사용방법은 간단하다.

주석 코드와 함께 대문자로 TODO를 입력하면 자동으로 주석이 하이라이팅이 된다. (!)

이때 TODO와 작성하고자하는 내용은 한칸의 공백(space)가 있어야 한다.

이렇게 멀티라인으로도 사용할 수 있다!

멀티라인 TODO는 TODO 태그 다음 줄에 한칸의 공백(space)을 입력 후 작성하면 된다.

TODO 모아보기

TODO 탭은 상단바에서 View > Tool Windows > TODO 를 클릴하면 다음과 같이 작성한 TODO들을 한 눈에 볼 수 있다.

TODO 탭 기능

Icon	Name	Shortcut	Description
	Previous TODO	Mac : option + cmd + up	이전 TODO
	Next TODO	Mac : option + cmd + down	다음 TODO
	Filter TODO Items		필터 선택, 필터 편집
	Navigate with Sigle Click		활성화 시 싱글클릭으로 TODO 표시
	Expand All	Mac : cmd + '+'	탭 모두 펼치기
	Collapse All	Mac : cmd + '-'	탭 모두 닫기
	Group By		TODO 항목 그룹화
	Preview Source		TODO 미리보기

코드태그 추가하기

기본으로 사용할 수 있는 TODO와 FIXME 외에도 코드 태그를 커스텀하여 사용할 수도 있다.

Preferences > Editor > TODO

Patterns 아래의 + 버튼을 클릭한 후, 아래의 정규식을 사용하여 새로운 태그를 추가할 수 있다.

\b{TODO이름}\b.*


ex) \bwaring\b.*

Case sensitive 버튼을 클릭하면 대소문자를 구분할 수 있다. 이 버튼을 클릭하지 않으면 기본으로 '대문자'로만 사용할 수 있다!

또, Use color scheme TODO default colors 버튼 체크박스를 해제하면 원하는 형태의 TODO를 만들 수도 있으니 입맛에 맞게 사용해보자.

[후기] 항해99 수료 후기 - 항해99 과정 및 솔직 후기

Anna-Jin — Thu, 18 Aug 2022 18:26:38 +0900

항해99에 승선한 5월부터 8월까지. 총 99일 +a간의 여정이 막을 내렸다.

미니 프로젝트부터 알고리즘, 주특기, 실전프로젝트까지 다사다난했던 지난 날들을 회고하며 항해의 끝과 앞으로의 개발자로서의 여정의 첫 문장을 이렇게 시작하고 싶다.

전직 호텔리어가 개발자로 전직하게 된 썰 푼다

호텔리어가 개발자를 한다고?

국내 5성급 호텔에 취업해서 일을 하다가 갑자기 개발자가 되기로 마음을 먹었을 때, 사실 주위의 반대는 없었다. 어렸을 때부터 기계를 다루길 좋아했고, 취미가 여행경비 엑셀에 정리하기였기 때문이다.

코딩을 접하게 된 계기는 사소했다. 떠오르는 IT 시대에 발맞춰 학교에서 코딩 교양을 열어줬고, 흥미가 생겨 수업을 듣게 되었다.

교양에서 사용한 프로그램은 스크래치였는데, 블럭 몇 개 가지고 고양이랑 춤추는 그 과정이 흥분되었다. 당연하게도 해당 수업은 A+를 받았고 그렇게 마음 속에 코딩의 싹을 틔웠다.

스크래치 고양이

대학을 졸업하고 나서 아무튼 호텔경영학과를 졸업했으니 호텔리어는 되어보자!라는 생각에 무작정 호텔에 취업을 하긴 했지만 마음 한 켠에는 여전히 채워지지 않는 무언가가 있었다.

그 후에 우연한 계기로 접하게 된 언어가 파이썬이었다. 점프투파이썬을 보면서 차근차근 코딩을 공부하고 있으니 휴무의 1/4을 다 써도 지치지 않을 정도로 재미가 있었다. 지금까지 공부를 하면서 이렇게 몰입을 했던 적이 있었던가? 하는 생각에 과감하게 일을 그만두고 개발 공부를 시작하게 되었다.

학원 수료 후, 항해99

퇴사하자마자 학원에 등록해 6개월 간의 과정을 수료했음에도 불구하고 여전히 개발자가 되기에는 많이 부족하다고 느꼈다. 1인프로젝트로 서비스를 하나 만들어보는 경험도 했지만 협업 경험이 중요하다고 느꼈고, 아직 모르는게 많았기에 부트캠프를 다니자!라는 생각이 들어 파워 구글링에 들어갔다.

정말 많은 부트캠프가 있었다.

국내 코딩 부트캠프 가격 비교 (2021년 11월 기준)

본 포스팅은 블로그들마다 혹은 연도마다 부트캠프들의 수강기간과 가격이 정확하지 않아 제가 보기 위해서 정리한 글입니다. 부트캠프 사이트에 직접 들어가서 메인 페이지나 QnA 페이지에

cocoon1787.tistory.com

728x90

여러 부트캠프 중에서 항해99를 선택한 이유는 물론 가격도 있었지만 99일 동안 9 to 9으로 최대 몰입 경험을 제공한다는 점이었다.

조금이라도 여유시간이 생기면 헤이해지거나 스트레스를 받는 내 성격상 하루종일 앉아있어야하는 강제력이 필요했기 때문에 나랑 가장 잘 맞는 부트캠프라는 생각이 들어 지원하게 되었고, 좋은 기회로 합격 후 항해99에 승선하게 되었다.

나만의 공부방법 찾기

항해99의 커리큘럼을 따라가면서 많은 우여곡절이 있었다. 특히 처음해본 알고리즘 공부는 이렇게 가다간 무너진다라는 생각밖에 들지 않았다. 고민 끝에 내린 결론은 "나만의 공부방법을 찾자" 였다.

예전에 TIL에 적은 적이 있었는데, 나만의 알고리즘 공부방식을 정립하고 차근차근 따라가다보니 어렵더라도 차근차근 커리큘럼을 따라가고 있는 나를 발견할 수 있었다.

https://annajin.tistory.com/114

실전프로젝트

배슐랭 포트폴리오

배슐랭 (Bae-Chelin)

“사회적 교통약자도 편하게 식사하세요”

planet-punishment-427.notion.site

배슐랭 서비스 링크

배슐랭

사회적 교통 약자도 편하게 식사하세요

bae-chelin.com

항해99 커리큘럼을 따라가면서 배운 모든걸 적용하는 최종 기간이었다.

배슐랭은 사회적 교통약자를 위한 배리어 프리 가게 검색 플랫폼을 주제로 "사회적 교통약자도 편하게 식사하세요"를 슬로건으로 삼고있는 프로젝트였다.

내가 담당한 부분은 Spring Security와 JWT, OAuth2.0을 사용한 소셜로그인이었는데 처음에 만만하게 생각했던 것과는 달리 굉장히 어려웠다. 더불어 팀 리더도 맡고 있었기 때문에 생각해야할게 많아서 고생이 많았다. Spring Security와 JWT의 플로우를 이해하는 데에 많은 시간이 걸렸고, 지금도 완벽하게 이해하고 있다고는 말할 수 없지만 그래도 어느정도 다룰 수 있을 정도는 되었다고 자신할 수 있다.

항해99 추천? 비추천?

약 4개월간의 여정은 좋은 점도 아쉬운 점도 많았다.

좋은 점은 국비학원에서는 배우기 힘든 기술들을 다양하게 접할 수 있다는 점, 계속해서 팀을 꾸려서 공부를 했다는 점, 디자이너 + 프론트엔드 + 백엔드 간의 협업을 할 수 있었다는 점이다.

팀 협업 경험은 개인적으로 꾸리고 프로젝트를 진행하면서 가능한 경험이지만, 다양한 사람을 만나볼 수 있고 이미 열정이 가득한 사람들과 함께할 수 없다는 게 차별점인 것 같다.

아쉬운 점은 다소 부족한 커리큘럼과 짧은 기간, 학습 자료의 부족이었다.

알고리즘 주차가 진행된 3주동안 1년동안 공부해야할 만큼의 내용을 공부하고 테스트를 봤어야 했는데 항해99가 지향하는 비전공자도 가능한 부트캠프가 아니라 전공자 혹은 그에 준하는 공부를 해본 사람을 위한 부트캠프 같았다.

당연하게도 알고리즘 주차 커리큘럼을 따라가는건 쉽지 않았다. 오히려 이 기간동안 항해99를 그만둔 사람이 단 한명도 없다는 게 신기할 정도였다.

그렇다면 항해99를 추천하는가 비추천하는가?

만약 개발 공부를 단 한번도 해본 적이 없는 사람들 중 자기주도학습에 적응할 자신이 없는 사람이라면 비추천한다. 다른 부트캠프는 모르겠지만 항해99는 개발 공부 경험이 전무한 사람에게 친절한 부트캠프는 아니다. 모든걸 '스스로' 찾아서 학습해야하기 때문에 자기주도학습이 익숙하지 않은 사람은 어지간한 열정을 갖고있지 않다면 득보단 실이 많을거라고 생각한다.

실제로 중도포기한 타 반의 사람들의 이야기를 들어봤을 때, 개발이 처음인 사람이 대다수였고 국비지원학원에서처럼 A to Z로 하나하나 알려주면서 끌고가주기를 바랐으나 항해99는 그렇지 않아 불친절하다는 말이 많았다.

그 분들을 나쁘게 말하려는 게 아니라 부트캠프는 생각했던 것 보다 더 '자기주도학습'에 초점이 맞춰져있다고 말하는 의도이다.

3개월이라는 짧은 시간동안 한가지 언어를 배우고, CRUD와 그 외 처음 사용해보는 기술들을 습득하기는 웬만한 열정이 아니고서는 쉽지 않기 때문에 항해99의 커리큘럼을 따라가려면 정말 쉬지않고!! 공부해야한다. 전공자가 4년동안 공부해온 내용 중 핵심만 쏙쏙 뽑아서 단기간에 머리에 집어넣는 과정이기 때문에 당연하지만 참 어렵다.

다시 한번 강조하지만 개발 공부를 단 한번이라도 '스스로' 해본 적이 없는 사람이라면 부트캠프보단 국비지원이든 독학이든 그 외의 경로를 통해서든 기초를 습득하고 오는 걸 추천한다!

이와 반대로 개발 공부를 조금이라도 해봐서 스스로 검색하고 알아내는 데에 경험이 있고 개발에 대한 열정이 있다면 추천한다. 오전 9시부터 오후 9시까지 혼자서 앉아서 공부하기는 어려운 일이기 때문에 약간의 강제력이 있는 건 몰입하기에 아주 좋은 환경이다.

또, 국비지원학원에서는 알려주지 않는, 요즘 많이 사용하는 기술들의 존재를 알게 되는 경험을 할 수 있다. (위에서도 계속 말하지만 공부는 셀프이다)

추가로 항해99의 협력사에 대해 궁금해하는 사람들도 많을 것 같아 조금 얘기를 풀어보겠다.

결론부터 말하자면 스타트업 ~ 중소 기업은 절대 싫다! 하면 기대하지 말자.

최종 발표회 때부터 계속해서 '스타트업' 협력사들의 채용 세션을 접할 기회가 종종 생긴다. 7기의 경우에는 삼성 사외벤처 프로그램에 선정된 스타트업도 있었고, 퀄리티 있어보이는 스타트업도 채용 세션을 진행했다.

적어도 주마다 한 개 이상의 채용 세션을 진행하면서 항해99 출신 개발자에게 관심이 있는 회사들을 접할 기회가 많다는건 좋지만 계속 언급하는 것처럼 '스타트업' 한정이기 때문에 중견 ~ 대기업 수준의 협력사를 바란다면... 항해99가 더 성장해서 유명해지기를 기도하거나 직접 발품팔아서 이력서를 넣고 다니는게 낫다.

항해99에서 서비스 중인 포트99에도 다양한 회사들이 채용공고를 올려두고 있는데, 이곳 역시 스타트업이 대부분이다.

포트99를 이용하면 좋은 점은 항해99 출신을 좋게 보는 회사들을 골라서 이력서를 넣어볼 수 있다는 정도? 그렇다고 협력사 서류 합격률이 높다고는 말하기 어렵다. 당연한 말이지만 서류 합격은 온전히 본인에게 달렸다.

총평

지금까지 말했던 것처럼 우여곡절이 많은 기간이었지만 확실히 전보다는 성장했음을 느낄 수 있다. 몰랐던 기술들도 많이 알았고 배운 점도 많았다.

21년 10월부터 22년 8월까지의 개발 공부. 이제 취준에 들어가지만 공부는 끝나지 않았다.

내일 한 걸음 더 나아가는 개발자가 되기 위해 나는 열심히 달린다!

+추가

바이럴이라는 분들이 계셔서 3줄 요약 해드립니다.

1. 국비 나오는 것보다 배울 점은 많음

2. 개발 처음 시작하는 사람은 오지 마라. 개발 처음하는 사람에게 친절하지 않음.

3. 개발 공부 독학이든 뭐든 해봤으면 나쁘지 않음