lucky-jun.log

Local LLM with LangChain

Wed, 06 Nov 2024 04:54:25 GMT

LLM API를 이용해 원하는 기능을 만들고 사용해보고 싶지만 항상 비용이 걱정됩니다.

비용 문제도 해결하고 직접 학습도 할 수 있는 매력적인 Local LLM(LLaMa3)과 함께 LangChain의 주요 내용들을 알아보겠습니다.

LangChain

ChatGPT를 필두로 한 LLM은 굉장히 유용한 툴입니다.

하지만, 아직은 사용자가 수많은 정보들을 정확하게 입력해줘야 원하는 결과를 얻을 수 있습니다.

context와 입출력 format을 더 자세히 제공할 수록 더 빠르게 구체적이고 좋은 결과를 줍니다.

또한, 얻은 결과는 사람들이 직접 가공하여 사용하여야 합니다.

여기서 LangChain이라는 툴이 유용하게 사용될 수 있습니다. LLM이 뇌라면 LangChain은 LLM의 손, 발, 눈, 코, 입이 되어줍니다.

LangChain

Local LLM 실행 (w.Ollama)

LangChain 사용에 앞서 로컬에서도 LLM을 사용할 수 있는 방법을 알아보겠습니다.

Ollama

LLM을 로컬에서 실행할 수 있도록 도와주는 툴입니다. cli 툴로 개발자들에게 특히 유용하게 사용될 수 있는 툴입니다.

Ollama

Ollama에 등록된 LLM을 로컬에 pull 받습니다.

$ ollama pull llama3

Ollama를 실행합니다.

default로 http://127.0.0.1:11434에 ollama와 통신할 수 있는 API가 열립니다.

$ ollama serve

curl로 ollama와 통신, LLM과 대화

open된 ollama 서버에 요청을 보내고, 결과를 받습니다.

요청시 ollama가 가지고 있는 LLM model을 지정해줘야 합니다.

$ curl http://localhost:11434/api/generate -d '{
   "model": "llama3",
   "prompt": "Hello LLaMA!"
}'

혹은 langchain_ollama를 활용해 통신, LLM과 대화

curl이외에 LangChain에서 제공하는 ollama 통신 모듈을 활용해 통신할 수도 있습니다.

# Python
from langchain_ollama.llms import OllamaLLM

# Ollama 통신 객체 생성 및 초기화
llm = OllamaLLM(model="llama3")

# prompt와 함께 Ollama의 LLM과 통신
prompt = "Hello LLaMA!"
response = llm.invoke(prompt)
# 결과 출력
print(f'{response=}')

Template & Parser

기본적으로 LLM의 입력과 출력은 Text 혹은 Image와 같이 컴퓨터가 온전히 이해할 수 있는 형태의 정보들을 받거나 출력할 수 있습니다.

즉, Python의 Dictionary나 Array같은 프로그래밍 언어 만의 자료구조 형태로는 입력과 출력을 할 수 없다는 뜻입니다.

따라서, LLM이 이해할 수 있는 형태로 입력을 변환하여 주고, LLM이 출력한 결과를 다시 활용하기 좋은 형태로 변환해주는 작업이 필요합니다.

LangChain에선 입력은 Prompt Template, 출력은 Output parser의 형태로 이를 제공합니다.

(현 포스팅에선 Text 형태의 LLM 입,출력만 다룹니다.)

Prompt Template

LLM 입력으로 제공할 prompt Template를 만들 수 있습니다.

특히, 입력 설명, 출력 format 설정 및 설명, 역할 설정 그리고 출력 예시들(shots)과 같이 개별 대화마다 필요한 설명들(System Prompt)처럼 반복되는 부분을 템플릿화하여 사용할 수 있습니다.

from langchain_community.llms import Ollama
from langchain_core.prompts import PromptTemplate

prompt_template = PromptTemplate.from_template("""
You are a software assistant, especially dealt with python and TypeScript(+ node.js).
Answer the following questions with the best of your knowledge and explanation in readable format like indented bullet points with clean codes.

{question}
""")
# prompt 완성
prompt = prompt_template.invoke({ "question": "What is the difference between Python and TypeScript?" })

# LLM에 prompt 전달
llm = Ollama(model="llama3")
llm.invoke(prompt)
print(f'{response=}')

LangChain에는 PromptTemplate이외에도 ChatPromptTemplate, FewShotPromptTemplate 등이 다양한 prompt template이 있습니다.

목적에 맞게 사용해주시면 됩니다.

Output parser

LLM의 출력을 런타임에서도 다루기 쉬운 형태로 변환해주는 작업이 필요합니다.

이번 포스팅에선 PydanticOutputParser를 사용해보겠습니다.

# string 형태의 LLM 출력을 파싱하기 위한 OutputParser
from langchain_core.output_parsers import PydanticOutputParser

class Joke(BaseModel):
    setup: str = Field(description="The setup to the joke")
    punchline: str = Field(description="The punchline to the joke")

parser = PydanticOutputParser(pydantic_object=Joke)

template = "Answer the user query.\n{format_instructions}\n{query}"
system_message_prompt = SystemMessagePromptTemplate.from_template(template)
chat_prompt = ChatPromptTemplate.from_messages([system_message_prompt])

prompt = chat_prompt.invoke({
    "query": "What is a really funny joke about Python programming?",
    "format_instructions": parser.get_format_instructions()
})
print(f'{prompt=}')

프롬프트가 아래와 같이 준비됩니다.

Answer the user query.
The output should be formatted as a JSON instance that conforms to the JSON schema below.

As an example, for the schema {"properties": {"foo": {"title": "Foo", "description": "a list of strings", "type": "array", "items": {"type": "string"}}}, "required": ["foo"]}
the object {"foo": ["bar", "baz"]} is a well-formatted instance of the schema. The object {"properties": {"foo": ["bar", "baz"]}} is not well-formatted.

Here is the output schema:

{"properties": {"setup": {"description": "The setup to the joke", "title": "Setup", "type": "string"}, "punchline": {"description": "The punchline to the joke", "title": "Punchline", "type": "string"}}, "required": ["setup", "punchline"]}

What is a really funny joke about Python programming?

프롬프트를 LLM에 전달하고, 결과를 파싱합니다.

result = llm.invoke(prompt)
print(f'{result=}')

try:
    joke_object = parser.parse(result)
    print(joke_object.setup)
    print(joke_object.punchline)
except Exception as e:
    print(e)

LLM이 준 결과가 아래와같이 나옵니다.

Here's the output:

```json
{
    "properties": {
      "setup": {
        "description": "The setup to the joke",
      "title": "Setup",
      "type": "string"
    },
    "punchline": {
        "description": "The punchline to the joke",
      "title": "Punchline",
      "type": "string"
    }
  },
  "required": ["setup", "punchline"],
  "setup": "Why do programmers prefer dark mode so much?",
  "punchline": "Because light attracts bugs."
}


아래와같이 파싱되어 나옵니다.

```python
print(joke_object.setup)
print(joke_object.punchline)

# Why do programmers prefer dark mode so much?
# Because light attracts bugs.

LCEL(LangChain Expression Language)

프롬프트, 모델, 출력 파서 등의 구성 요소를 파이프 연산자( | )를 사용해서 단일 체인으로 구성하는 LangChain에서 지원하는 표현 방식입니다.

연속적인 함수 실행엔 메소드 체이닝 방법도 있지만, 그보다 훨씬 가독성이 좋은 방법이라고 할 수 있습니다.

주의할 점으로 LCEL 파이프라인 시작시 랭체인에서 제공하는 함수 중, 파이프라인에 사용할 수 있는 함수를 사용해 시작해야합니다.

from langchain_core.runnables import RunnableLambda

# 단일 파이프라인, + 1 -> * 2 순서로 실행
sequence = RunnableLambda(lambda x: x + 1) | (lambda x: x * 2)
print(sequence.invoke(1)) # 4

# 병렬 파이프라인, + 1 -> * 2, * 5 순서로 실행
sequence2 = RunnableLambda(lambda x: x + 1) | {
  'mul_2': RunnableLambda(lambda x: x * 2),
  'mul_5': RunnableLambda(lambda x: x * 5)
}
res = sequence2.invoke(1) # { 'mul_2': 4, 'mul_5': 10 }

# 파이프라인끼리 연결
sequence3 = sequence2 | RunnableLambda(lambda x: x['mul_2'] + x['mul_5'])
res = sequence3.invoke(1) # 14

prompt 생성부터 출력까지의 과정을 LCEL로 표현해보겠습니다.

LCEL scope

LCEL 파이프라인 구현시 주의해야할 점은 파이프라인 바로 전 단계의 출력의 결과만을 사용할 수 있다는 것 입니다.

대표적으로 itemgetter 함수와 RunnablePassthrough가 있습니다.

from langchain_core.runnables import RunnableLambda, RunnablePassthrough
from operator import itemgetter

def prompt_lambda(prompt: str) -> str: # Fake LLM for the example
    return {"prompt": prompt, "with_system_prompt": f'Answer the user query. query : {prompt}'}

chain = RunnableLambda(prompt_lambda) | {
    # RunnablePassthrough는 앞 pipeline의 output을 그대로 받을 수 있다.
    'original': RunnablePassthrough(), # Original LLM output
    'system_prompt': itemgetter('with_system_prompt') # 'Answer the user query. query : {prompt}'
} | RunnablePassthrough()

res = chain.invoke("What is the difference between Python and TypeScript?")
print(f'{res=}')
# RunnablePassthrough는 바로 앞 pipeline의 output을 그대로 받아 출력한다.
# res=
# { 'original': {
#     'prompt': 'What is the difference between Python and TypeScript?',
#     'with_system_prompt': 'Answer the user query. query : What is the difference between Python and TypeScript?'
#   },
#   'system_prompt': 'Answer the user query.\nWhat is the difference between Python and TypeScript?'
# }

LCEL with LLM

LLM과 함께 파이프라인을 구현해보겠습니다.

prompt1 = ChatPromptTemplate.from_template("what is the city {person} is from?")
prompt2 = ChatPromptTemplate.from_template(
    "what country is the city {city} in? respond in {language}"
)

model = OllamaLLM(model="llama3.1")

# LLM에서 받은 응답을 Parser로 변환해줘야 pipeline에서 사용할 수 있다.
chain1 = prompt1 | model | StrOutputParser()

chain2 = (
    # chain2 내부에 chain1을 이었다. 일종의 chain depth
    {"city": chain1, "language": itemgetter("language")}
    | prompt2
    | model
    | StrOutputParser()
)

res = chain2.invoke({"person": "obama", "language": "korean"})
print(f'{res=}')
# res=
# 오바마(Barrack Obama) 대통령의 생모지국은? 그것은 하와이(Hawaii)입니다.
# 그는 1961년 8월 4일 Honolulu, Hawaii에서 Kapi'olani Medical Center for Women and Children에서 태어났습니다.
# 하지만 그의 고향 또는 성장한 곳은 일리노이주 시카고(Cicago, Illinois)입니다! 오바마는 대부분의 인생을 시카고에서 보냈으며, 그는 하와이 생모지국보다 시카고에 더 많은 친감을 느꼈습니다.

etc...

그 외 RemoteRunnable, RunnableParallel 등등... LCEL 파이프라인에서 사용가능한 다양한 Runnable이 있습니다.

ref

Finite State Machine (with XState)

Mon, 16 Sep 2024 08:58:57 GMT

애플리케이션이 발전하다보면 수많은 state가 생기게 됩니다. 그러다보면 여러 state간의 관계가 생기고 복잡해집니다. 단순히 로직으로 이를 관리하다보면 코드가 복잡해지고 유지보수가 어려워집니다.

상태 하나가 추가되면 다른 상태들과의 관계를 고려해야하고, 그럼 상태 하나가 추가될 때마다 복잡도가 기하급수적으로 증가합니다.

이런 복잡한 문제를 깔끔하게 해결하기 위해, Finite State Machine을 사용해 보았습니다.

State Machine

State machine(상태 머신)은 시스템이 가질 수 있는 모든 상태와 상태 간의 전환을 명확하게 모델링하는 개념입니다. 시스템은 주어진 순간에 하나의 상태만 가질 수 있으며, 특정 이벤트가 발생할 때 정의된 전환에 따라 다른 상태로 변경됩니다.

정리하면 상태 머신은 다음과 같은 특징을 가집니다.

한번에 하나의 상태만 가질 수 있습니다.
상태(state): 시스템이 가질 수 있는 모든 상태들을 정의합니다.
이벤트(event): 상태 전이를 일으키는 트리거, 즉 상태 변화를 유도하는 조건입니다.
전이(transition): 이벤트가 발생했을 때 시스템이 현재 상태에서 다른 상태로 이동하는 과정을 말합니다.

상태 머신은 일종의 프레임워크처럼 이벤트에 따른 상태를 명확하고 예측 가능하게 만들어, 복잡한 상태 관리를 단순화하는 데 유용합니다.

Finite State Machine

이번에 사용하는 state machine은 정확히는 Finite State Machine입니다.

여기서 Finite는 유한한 이라는 뜻으로, 상태가 유한하다는 것을 의미합니다.

위키에 FSM의 정의가 잘 정리돼있지만, 간단히 요약하면 제한된 구조와 제한된 상태들을 몇가지 제약으로 복잡하게 얽힌 흐름을 단순하고 직관적으로 표현하는 방법입니다.

반대로 Infinite라면 무한한 상태를 가지게 되는데, 현실적으로 무한한 상태를 단순하고 직관적으로 표현하는 것은 불가능합니다. 예시로 Finite State Machine을 쓰지 않은 날 것 그대로의 로직이 Infinite State Machine이라고 할 수 있을 것 같습니다.

때문에 애플리케이션에서는 보다 직관적이고 단순하게 상태의 흐름을 표현할 수 있는 Finite State Machine가 더 적합하다고 할 수 있습니다.

XState

state machine을 구현하는 방법엔 여라가지가 있지만, 이번엔 TypeScript 환경에서 XState라는 라이브러리를 사용했습니다. (V.5 버전을 기준으로 합니다.)

XState는 JS / TS로 작성된 라이브러리로 State Machine을 정의하고, 상태 전이를 관리하는 데 도움을 주는 라이브러리입니다.

굉장히 장점이 많은 라이브러리라고 생각합니다. 편리한 디버깅 툴(Inspector, XState VS Code extension), 정의한 상태 머신을 시각적으로 보여주고 테스트 해볼 수 있는 툴 Stately Visualizer, 풍부한 예시(Stately Studio)들이 있어 개발 편의성이 높습니다.

또한, React, Vue, Svelte 등의 UI 라이브러리 혹은 프레임워크들과도 쉽게 연동할 수 있습니다.

Example

XState로 간단한 Finite State Machine을 구현해보기 위해 간단한 예시를 만들어 구현해보았습니다.

예시 시나리오

예시는 결제 진행으로 크게 1. 결제 준비 2. 결제 진행 단계로 나뉩니다.

결제 준비 단계에선 비회원, 회원 상태를 가지고 있고, 비회원과 회원 상태에 따라 결제 준비 단계가 약간 다르게 진행됩니다.

그리고 결제 진행 단계에선 비동기 처리 상태에 따라 상태와 UI가 변경되고 결제가 완료되면 종료됩니다.

Demo

간단히 어떤 예시인지 완성된 데모를 살펴보겠습니다.

non-member	member

상태 머신이 없을 때

먼저 상태 머신이 없을 때의 코드를 살펴보겠습니다.

상태 머신이 상태를 관리하지 않기 때문에, 우선 상태를 선언해야 합니다. 필요한 상태는 다음과 같습니다.

  // 회원인가 아닌가?
  const [isMember, setIsMember] = useState(false);

  // 동의절차는 정의된 순서 그대로 순차적으로 진행됩니다.
  type AgreeProcess = 'user-info-input' | 'user-info-consent' | 'payment-consent' | 'payment';
  // 동의 절차를 하나씩 순차적으로 하나씩 추가해서 보여줘야 함.
  const [agreeProcess, setAgreeProcess] = useState();

비회원이면 정보 입력을 위한 입력창을 띄워줍니다. 입력이 완료되면 회원과 동일한 동의 절차를 시작합니다.

여기서 현재 state에 따라서 다음 절차를 파악하는 등, 동의 절차 state를 컴포넌트에서 모두 수동으로 관리해야합니다.

  // 회원인 경우와 아닌 경우 시작하는 동의 절차 상태가 다름

  // 상태에 따른 동의 절차 컴포넌트 추가
  const agreeComponents: ReactNode[] = [];

  if (!isMember) {
    agreeComponents.push(
       {
          setAgreeProcess('user-info-consent');
        }}
      />
    );
  }

  if (agreeProcess === 'user-info-consent') {
    agreeComponents.push(
      
         {
              const { checked } = e.target;
              if (checked) {
                setAgreeProcess('payment-consent');
              }
            }}
            color="primary"
          />
        }
        label="사용자 정보에 동의하시겠습니까?"
        />
      
    );
  }

  // 동일하게 진행...

결제 동의 절차가 끝나고 본격적으로 결제 요청이 시작되는 비동기 작업의 경우 아래와 같은 코드로 관리됩니다.

// 결제 요청 여부
  const [isFetched, setIsFetched] = useState(false);
  // 비동기 결제를 요청하고 3초를 client에서 스스로 측정해서 보여줘야 함.
  const [isLoading, setIsLoading] = useState(false);

동일하게 모든 상태 변화를 native 로직을 통해 관리합니다.

  const handlePaymentButtonClick = useCallback(async () => {
    // 모든 상태 변화를 수동으로 관리
    setIsFetched(true);

    const loadingTimer = setTimeout(() => {
      setIsLoading(true);
    }, 3000);

    try {
      await mockPaymentFetching(() => {
        clearTimeout(loadingTimer);
        setIsFetched(false);
        setIsLoading(false);
      });
    } catch {
      clearTimeout(loadingTimer);
      setIsFetched(false);
      setIsLoading(false);
    }
  }, []);

  // 결제 시작 버튼
  

  // 결제 진행 상태 표시 모달
  
    
      
      {isLoading ? 잠시만 기다려 주세요...
 : 결제중...}

상위 코드는 모든 상태관리 로직과 View가 한 곳에 모여있어 가독성 및 관리가 어렵습니다.

또한, 엄격한 규칙없이 native 로직으로 느슨하게 관리하다보면, 코드의 의도를 알기도 어렵고 이로인해 잘못된 코드 수정으로 버그가 발생할 여지가 많아져 유지보수가 어려워집니다. (협업의 어려움 가중)

상태 머신을 사용할 때

이제 XState를 사용하여 상태 머신을 구현하고 상위 코드를 리팩토링해보겠습니다.

먼저 결제 동의 절차를 위한 상태 머신을 정의합니다.

export const paymentMachine = createMachine({
  id: 'payment',
  initial: 'Init',
  context: {
    // 이 사람이 회원인지 아닌지 기억한다.
    isMember: false,
  },
  states: {
    // !! : 명확한 상태 순서 정의
    Init: {
      on: {
        next: [
          {
            // 회원일 때만 유저 동의 절차로 이동
            guard: (context) => context.context.isMember,
            target: 'UserInfoConsent',
          },
          {
            // 비회원일 땐 유저 정보 입력으로 이동
            guard: (context) => !context.context.isMember,
            target: 'UserInfoInput',
          },
        ],
        stay: {
          target: 'Init',
        },
        setMember: {
          actions: assign({
            isMember: ({ context, event }) => event?.isMember ?? context.isMember
          }),
        }
      },
    },
    UserInfoInput: {
      on: { next: 'UserInfoConsent' },
    },
    UserInfoConsent: {
      on: { next: 'PaymentConsent' },
    },
    PaymentConsent: {
      on: { next: 'Payment' },
    },
    Payment: {
      type: 'final',
    },
  },
});

이제 상태 머신을 컴포넌트에 적용해보겠습니다.

  import { useMachine } from '@xstate/react';

  // !! : 필요한 여러 상태들이 컴포넌트에서 보이지 않음.
  const [snapshot, send] = useMachine(paymentMachine, {});

  const curState = snapshot.value;
  const isMember = snapshot.context.isMember;

  // 상태에 따른 동의 절차 컴포넌트 추가
  const agreeComponents: ReactNode[] = [];

  if (!isMember) {
    agreeComponents.push(
       {
          console.log('click')
          send({ type: 'next' })
        }}
      />
    );
  }

  if (curState === 'UserInfoConsent') {
    agreeComponents.push(
      
         {
              const { checked } = e.target;
              if (checked) {
                // !!: 추상화 된 상태 머신 변환 메소드
                send({ type: 'next' });
              }
            }}
          />
        }
        label="사용자 정보에 동의하시겠습니까?"
        />
      
    );
  }

  // 동일하게 진행...

결제 요청 비동기 작업의 경우는 아래와 같이 변경됩니다.

// 로딩표시를 위한 상태 머신으로 항상 재사용할 수 있도록 설계
// 머신 종료 상태인 type: final을 적용하면 상태 머신 재사용이 힘듦.
export const paymentLoadingMachine = createMachine({
  id: 'payment',
  initial: 'Init',
  states: {
    Init: {
      on: { next: 'PaymentSend' },
    },
    PaymentSend: {
      on: { next: 'Init' },
      after: {
        // !! : 내부적인 상태 전환을 컴포넌트에서 해줄 필요가 없음.
        3000: 'Loading' // 3000ms (3초) 후 Loading으로 자동 전환
      },
    },
    Loading: {
      on: { next: 'Init' },
    }
  }
});

상태 머신을 컴포넌트에 적용합니다.

  // 결제 요청 했다고 가정하는 비동기 함수
  async function mockPaymentFetching() {
    return new Promise((resolve) => {
      setTimeout(() => {
        console.log('done');
        resolve('done');
      }, 5000);
    });
  }

  const [paymentLoadingSnapshot, paymentLoadingSend] = useMachine(paymentLoadingMachine, {});

  const isFetched = paymentLoadingSnapshot.value !== 'Init';
  const isLoading = paymentLoadingSnapshot.value === 'Loading';
  const isDialogOpen = isFetched;

  const handlePaymentButtonClick = useCallback(async () => {
    if (isFetched) return;

    // !! : 훨씬 간결해진 코드
    paymentLoadingSend({ type: 'next' });
    try {
      await mockPaymentFetching();
      paymentLoadingSend({ type: 'next' });
    } catch {
      paymentLoadingSend({ type: 'next' });
    }
  }, [isFetched, paymentLoadingSend]);

  

  
    
      
      {isLoading ? 잠시만 기다려 주세요...
 : 결제중...}

상태 머신을 적용했을 때, 상태 머신의 엄격한 규칙으로 인해 코드의 의도가 더 명확해지고, 컴포넌트에서 상태를 다루는 여러 복잡한 로직들이 많이 사라졌습니다.

Finite State Machine(w. XState) 후기

이번에 간단한 예시 상황을 만들고 XState로 코드를 리팩토링 해보면서 상태 머신의 장점과 단점을 경험했습니다.

장점

제가 느낀 장점은 꽤 컷으며, 상태 머신만으로도 웹 애플리케이션의 모든 상태를 관리할 수 있을 정도로 장점이 강력한 도구였다고 느꼈습니다.

명확한 상태 표현으로 협업에도 큰 도움이 될 것 같다고 생각했습니다.

명확한 상태의 흐름과 상태간의 관계 표현으로 인한 가독성 향상.
불가능한 상황을 방지하는 엄격한 규칙으로 인한 버그 방지.

단점

처음 경험해 본 FSM을 설계함에도 고려해야될 것이 많아 복잡했고, XState를 처음 사용할 때 쉽지 않았습니다.

FSM을 구현하기 위한 메소드와 제약 사항 같은 옵션들이 정말 많아서, 이를 확인하고 익히는 데만 시간이 좀 걸렸습니다.

이런 학습 비용은 FSM과 XState의 단점이라고 생각합니다.

또한 마치 리덕스처럼 간단한 상태 머신을 만드는데도 필요한 코드가 많아 처음 상태 머신을 만들 때 조금 번거로웠습니다.

필요한 코드가 많고 적용할 수 있는 옵션들이 만큼 설계가 잘못되어 여러 context가 얽히게 되면 상태 머신을 사용하지 않을 때보다 더 복잡해질 수 있다고 느꼈습니다.

따라서 상태 머신은 Visualizer 툴등을 이용해 디버깅 및 관리하면서 간결하게 유지하는 것이 중요하다고 생각했습니다.

상태 머신과 XState를 잘 활용하기 위해선 어느정도 학습 시간이 필요. (학습 비용 있음)
- 팀 간 노하후 공유로 어느정도 완화 가능.
redux처럼 상태 머신만을 위한 boilerplate 코드가 꽤 많이 필요하다.
- 스니펫 활용으로 생산성 향상 가능.
상태 머신을 사용할 때는 상태 머신의 상태를 최대한 직관적이고 간결하게 유지하고, 상태 머신에 불필요한 context가 서로 얽히지 않도록 주의해야한다.
- Visualizer를 잘 활용하면 복잡한 상태 머신을 시각적으로 확인할 수 있어 디버깅과 리팩토링에 도움이 될 수 있다.

Conclusion

XState에선 FSM 구현을 위해 제공하는 메소드와 기능들이 정말 많지만, 이번 포스팅에선 정말 기본적인 기능들만 사용해보았습니다.

아직 잘 모르는 기능과 옵션들도 많아 앞으로 계속해서 사용해보며 익혀나가야겠습니다. (필요하다면 후속 포스팅에서 이어나가보겠습니다.)

처음에 익숙해지기는 어렵지만, 장점이 뚜렷하여 적절히 활용하면 점점 더 성장하고 복잡해지는 프로덕트 유지보수에 큰 도움이 될 것 같습니다.

감사합니다. 🙏

ref

SSE(Server-Sent events) with EventSource

Thu, 22 Feb 2024 08:11:11 GMT

SSE(Server-Sent events) with EventSource

보통 HTTP 통신은 요청 1번에 응답 1번을 받습니다.

하지만 SSE(Server-Sent events) 한번의 연결로 여러번의 응답을 실시간으로 받을 수 있습니다.

이번 글에선 EventSource Web API를 활용해 SSE를 이용하는 방법을 알아보겠습니다.

SSE(Server-Sent events)란?

SSE(Server-Sent events)는 HTTP 기반으로, 서버의 데이터를 실시간으로 streaming하는 기술입니다.

실시간 통신의 대명사인 webSocket과 다른 점은 서버에서 클라이언트로의 단방향 스트리밍이라는 점입니다.

ref. SSE의 HTTP spec

polling과 webSocket

SSE이외에 지속 통신 방법은 두가지가 있습니다. polling과 webSocket입니다.

vs polling

poling은 client가 직접 일정 주기로 요청해서 서버 data를 pull하는 방식으로 주기적인 HTTP 통신 요청을 해줘야 하기 때문에 리소스가 낭비됩니다.

반면, SSE는 한번의 요청 및 연결 성립으로 실시간 통신이 가능합니다.

vs webSocket

webSocket은 SSE와는 다르게 양방향 통신이 가능하고, 한번의 연결로 여러번의 요청과 응답이 가능합니다. (정확히는, webSocket은 연결후에도 계속 handshake를 주고받습니다.)

하지만, webSocket만의 protocol이 따로 있으며, 양방향 통신이 반드시 필요한 경우가 아니라면, SSE를 사용하는 것이 더 간단하고 효율적입니다.

또한, webSocket은 fireWall에 의한 통신 issue가 있을 수 있는 반면, SSE는 그렇지 않습니다.

Open connection 제한과 HTTP/2

EventSource - mdn 문서에선 SSE를 사용하기 전에, 브라우저의 연결 제한을 확인하라고 합니다.

크롬 및 파이어폭스 브라우저는 "한 브라우저 + domain" 당 open connection을 최대 6개까지만 유지할 수 있도록 제한하고 있습니다.

즉, SSE를 연결하는 동일한 주소의 페이지가 있을 경우 6개 탭까지만 연결되고 그 이후엔 추가적인 연결이 제한된다는 것입니다.

하지만, HTTP/2를 사용하면, default 100개까지 open connection을 유지할 수 있습니다.

EventSource

EventSource는 SSE 연결을 편리하게 할 수 있도록 해주는 Web API입니다.

클라이언트에서 SSE를 연결을 위해 여러가지를 알아보면 바로 나오는 것이 MDN에서 소개하는 Using_server-sent_events입니다.

EventSource로 서버와 SSE 연결을 하는 방법을 알려줍니다.

ref. EventSource HTML spec

EventSource의 특징

EventSource API는 고유한 특징과 한계가 있습니다.

사용할 때, 이러한 특징과 한계를 고려해야 합니다!

GET 요청입니다.
연결이 끊기면 자동으로 다시 연결합니다.
withCredentials 옵션을 통해 CORS 정책을 준수할 수 있습니다.
SSE 연결 요청시, header를 수정할 수 없습니다. 🤯 (Setting headers for EventSource discussion에 의하면 앞으로도 header 수정 기능을 추가할 생각은 없는 것 같습니다. 😇)

SSE example

간단한 예시와 함께 SSE를 사용하는 방법을 알아보겠습니다. (feat. EventSource)

Server

express.js로 예시 서버를 만들어 봤습니다.

SSE 연결을 위해 줘야하는 응답은 간단합니다.

res.setHeader("Content-Type", "text/event-stream");
res.setHeader("Cache-Control", "no-cache");
res.setHeader("Connection", "keep-alive");
res.flushHeaders();

이렇게 header를 달아 응답을 주면, client와 event stream 연결이 성립됩니다.

이 후, 같은 API에서 원하는 데이터와 함께 응답을 보내면 실시간으로 client에 전송이 됩니다.

// send server sent events
let counter = 0;
const interValID = setInterval(() => {
  counter++;
  if (counter > 5) {
    clearInterval(interValID);
    // if connection is closed, retry after 10s
    res.write("retry: 10000\n");
    res.end();
    return;
  }

  ///// real-time sent data /////
  res.write(`id: ${counter}\n`);
  res.write(`data: ${JSON.stringify({ num: counter })}\n\n`);
  ///////////////////////////////

}, 1000);

// If client closes connection, stop sending events
res.on("close", () => {
  console.log("client dropped me");
  clearInterval(interValID);
  res.end();
});

Client

EventSource를 통해 서버와 SSE 연결을 맺고, 실시간으로 전송되는 이벤트를 listen하는 코드입니다.

let closeTime = 0;
const sseDataElement = document.getElementById('sse');
const eventSource = new EventSource(`https://localhost:3000/slack/sse`, {
  withCredentials: true,
});

eventSource.addEventListener('message', (event) => {
  sseDataElement.innerHTML += event.data + '
';
});

eventSource.addEventListener('open', (event) => {
  const openTime = Date.now().getTime();
  console.log('open sse connection', openTime);
  if (closeTime > 0) console.log('reopen At : ', closeTime - openTime);
});

// we can use custom event!
eventSource.addEventListener('custom', (event) => {
  console.log('custom event', event);
});

eventSource.onerror = (error) => {
  console.error('SSE Error:', error);
  closeTime = Date.now().getTime();
  console.log('close sse connection At : ', closeTime);
};

Demo

사실 EventSource 문서만 봐선 어떻게 사용해야할지 명확하게 알기 힘들어, 간단한 예시로 직접 해봤습니다.

network 탭을 보면, 한번의 요청으로 여러번의 응답을 받는 것을 확인할 수 있습니다.

retry

서버에서 ms과 함께 retry 메세지를 전달하면, 연결이 끊겼을 때 재요청하는 시간을 조정할 수 있습니다.

// retry in 1s
res.write("retry: 1000\n");

이번엔 3초로 설정해보겠습니다.

// retry in 3s
res.write("retry: 3000\n");

Custom Event

default인 message event 외에도 직접 추가한 custom event를 사용할 수 있습니다.

event가 명시돼있지 않는 경우는 모두 message event입니다.

///// real-time sent data /////
res.write("event: custom\n");
res.write(`id: ${counter}\n`);
res.write(`data: ${JSON.stringify({ num: counter })}\n\n`);
///////////////////////////////

network 탭에서 event type이 custom으로 바뀐 것을 확인할 수 있습니다.

EventSource의 한계와 polyfills

Web API로 주어지는 EventSource는 편리하지만, GET 요청 밖에 안되는 점, header 수정이 안되는 점 등의 한계가 있습니다.

polyfill 라이브러리를 통해 이 한계를 극복할 수 있습니다.

event-source-polyfill

@microsoft/fetch-event-source

혹은, ReadableStream 혹은 xhr.onprogress로 직접 구현할 수도 있습니다. 👍

아래 코드는 fetch와 ReadableStream을 활용한 SSE 구현 예시입니다. ref

const fetchSSE = () => {
    fetch(url, {
      method: 'POST',
      headers: {
        token: authToken,
        'Content-Type': 'application/json; charset=utf-8',
      },
      body: {
         // ...
      },
     })
      .then((response) => {
        const reader = response.body!.getReader();
        const decoder = new TextDecoder();

        const readChunk = () => {
          return reader.read().then(appendChunks);
        };

        const appendChunks = (result) => {
          const chunk = decoder.decode(result.value || new Uint8Array(), {
            stream: !result.done,
          });
          const parseData = JSON.parse(chunk);
          // do something with parseData

          if (!result.done) {
            return readChunk();
          }
        };

        return readChunk();
      })
      .then(() => {
        // when it's done
      })
      .catch((e) => {
        // error
      });
};

Conclusion

SSE의 개념과 EventSource를 통해 실시간 통신을 하는 방법을 알아보았습니다.

EventSource API가 모든 것을 해결해주기 보단 이를 보완한 여러 해결책들이 많은 것으로 보아 앞으로도 여러가지 해결할 문제들이 많을 것 같아 관심있게 지켜보고 해결해야할 문제가 있다면 적극적으로 해결해보려고 합니다. 😁

Ref.

https://developer.mozilla.org/en-US/docs/Web/API/EventSource

https://blog.logrocket.com/using-fetch-event-source-server-sent-events-react/

https://kwseo.github.io/2017/03/25/sse/

https://surviveasdev.tistory.com/entry/%EC%9B%B9%EC%86%8C%EC%BC%93-%EA%B3%BC-SSEServer-Sent-Event-%EC%B0%A8%EC%9D%B4%EC%A0%90-%EC%95%8C%EC%95%84%EB%B3%B4%EA%B3%A0-%EC%82%AC%EC%9A%A9%ED%95%B4%EB%B3%B4%EA%B8%B0

Next.js의 Proxy

Tue, 23 Jan 2024 14:34:11 GMT

Next.js의 proxy 기능

Next.js는 기본적으로 웹 프론트도 가능하지만, 서버까지 함께있는 풀스택 프레임워크 입니다.

여기서 Next.js가 제공하는 서버의 여러가지 proxy 기능을 활용하여 다양한 것을 할 수 있습니다.

Proxy란?

Proxy는 클라이언트와 서버 사이에 위치하여, 클라이언트의 요청을 받아서 서버에 전달하고, 서버의 응답을 받아서 클라이언트에 전달하는 중계자 서버 역할을 합니다.

Proxy 서버는 그 위치에 따라 2가지로 나뉩니다.

Forward vs Reverse Proxy

Forward는 클라이언트 바로 뒤에 위치합니다.

반면 Reverse Proxy는 서버 바로 앞에 위치합니다. (여기서 Reverse는 "반대"라는 의미가 아닌, "배후, 뒤쪽"라는 의미입니다.)

Next.js가 제공하는 Proxy는 서버 바로 앞에 위치하기 때문에 Reverse Proxy입니다.

redirect vs rewrite

Next.js에서 제공하는 proxy 기능은 redirect와 rewrite가 있습니다.

redirect는 말 그대로 redirect, rewrite는 forwarding과 대응한다고 할 수 있겠네요!

redirect vs forwarding

redirect와 forwarding은 백엔드에서 자주 사용되는 용어입니다.

간단히 이렇게 설명할 수 있습니다.

Redirect : 요청 -> 다른 곳으로 요청하라고 응답 (code: 3xx) -> 클라이언트에서 다시 요청 -> 응답
Forwarding : 요청 -> 서버내에서 다른 곳에 요청하고 응답 받아옴 -> 그대로 결과 응답

Example

적용 예시를 보시겠습니다. 😎

redirect

redirect를 적용한 코드와 페이지 스샷입니다.

여기서! permanent 옵션에 따라 307, 308로 응답코드가 나눠집니다.

이는, 웹표준을 준수한 것으로 자세한 내용은 MDN, 300 Multiple Choices를 참고해주세요.

rewrite

rewrite를 적용한 코드와 페이지 스샷입니다.

dynamic path & 외부 url

고정 url뿐만 아니라, dynamic path와 외부 url도 적용할 수 있습니다.

Other options

위에서 보셨듯이 source로 proxy할 요청 url을 지정했는데요.

추가 조건을 주어 proxy 대상을 더 세세히 판단할 수 있습니다.

has로 must have를 missing으로 must not have를 지정할 수 있습니다.

v.14.1 기준 4가지 타입을 적용할 수 있습니다.

header
cookie
query
host

자세한 건 -> Next.js, rewrite header-cookie-and-query-matching

beforeFiles, afterFiles, fallback

rewrite에만 있는 옵션으로, 좀 더 세세하게 rewrite를 적용할 수 있습니다.

Next.js의 요청 및 응답 순서

Next.js에 어떤 요청이 오면, 다음과 같은 순서로 처리됩니다.

Header check/response
redirect check/response
beforeFiles check/response
static files check/response
afterFiles check/response
Dynamic route page check/response
fallback check/response

이 순서를 잘 파악해서 사용하면 좋을 것 같습니다.

beforeFiles

정적 파일들이 등록된 api를 확인하기 전에 proxy가 적용됩니다.

아래와 같이 설정했다고 가정해보겠습니다.

rewrites: async ()  => ({
  beforeFiles: [{
    source: '/test/:path*',
    destination: '/proxy/:path*',
  }],
})

/test는 정적 컴포넌트가 있는 경로입니다.

여기서 ${url}/test에 요청하면 /test에 등록된 정적 컴포넌트가 아닌 /proxy로 요청이 proxy됩니다.

afterFiles

정적 파일들이 등록된 api를 확인한 후에 proxy가 적용됩니다.

rewrites: async ()  => ({
  afterFiles: [{
    source: '/test/:path*',
    destination: '/proxy/:path*',
  }],
})

동일하게 /test는 정적 컴포넌트가 있는 경로고,${url}/test에 요청하면, /proxy로 요청이 proxy되지 않고, /test에 등록된 정적 컴포넌트가 응답됩니다.

여기서 /test/[id]와 같이 동적 경로가 등록되어 있다면, /test/1에 대한 요청은 /proxy/1로 proxy됩니다.

fallback

fallback은 정적 파일과 동적 경로가 등록된 api를 확인한 후에 proxy가 적용됩니다.

rewrites: async ()  => ({
  fallback: [{
    source: '/test/:path*',
    destination: '/proxy/:path*',
  }],
})

위와 동일한 가정하에, {url}/test, {url}/test/[id]로 요청하면, proxy되지 않습니다.

오로지, 아무것도 등록되지 않은 api에 접근했을 떄만, fallback에 등록한 proxy가 적용됩니다.

rewrite 활용

Next.js 공식 홈페이지에서 여러가지 활용 방안을 소개하고 있습니다.

CORS 해결
점진적인 페이지 마이그레이션
Multi zone이라는 이름으로 Micro frontend를 지원하네요. 이것 또한 rewrite를 응용한 것 입니다.

Ref

너와 나와 우리를 위한 클린코드 (feat. NextStep, TDD 클린코드 with React)

Sun, 23 Apr 2023 11:41:48 GMT

NextStep, TDD 클린코드 with React

2월 ~ 4월까지 약 2달 동안 NextStep의 TDD 클린코드 with React 과정을 진행했습니다.

과정을 진행하면서 여러모로 배운 점들이 정말 많지만, 이번엔 리액트 클린코드 과정 진행과 클린코드에 대해 배우고 느꼈던 점들에 대해 나누어보려고 합니다. 😁

글이 좀 길어져, 목차를 추가했습니다! 📜

TDD 클린코드 with React 과정 소개
미션 요구사항에 따른 첫 설계
리뷰를 통한 코드 수정, 기존 코드를 클린하게 수정하기.
클린코드에 대해서

TDD 클린코드 with React 과정 소개

간단하게 제가 진행했던 TDD 클린코드 with React 2기 과정에 대해 설명하겠습니다.

미션은 크게 2가지로 구성되어있습니다.

페이먼츠 미션

다수의 input이 있는 복잡한 form을 다루는 미션입니다.

CDD 방법론을 적용해 Bottom-up 방식으로 컴포넌트를 개발하고 Storybook으로 단위 컴포넌트를 테스트하는 것을 중점으로 합니다.

(이 미션에선 상태 관리 라이브러리를 사용할 수 없습니다. ㅎㅎ 😯)

페이먼츠 과제 결과물 Repo와 PR -> Payments Github Repo, Pull Request

장바구니 페이지

Api가 없는 상황에서도 안정적으로 개발환경을 구축하고 복수의 페이지에서도 복잡한 state를 안정적으로 관리하는 방법을 중점으로 진행합니다.

전 MSW와 react-query를 적용해 개발했습니다.

장바구니 PR -> 장바구니 1차 장바구니 2차

이번 포스트는 페이먼츠 미션을 중심으로 진행됩니다.

두가지 미션 중에선 개인적으로 페이먼츠가 더 어려웠고 그만큼 배운 점도 더 많았다고 생각합니다.

따라서, 페이먼츠 미션을 위주로 이번 포스트를 진행하도록 하겠습니다!

페이먼츠 설계

페이먼츠 미션을 보고 처음에 생각했던 설계입니다.

이번 미션에선 상태 관리 라이브러리를 사용할 수 없어 전역 상태 공유는 모두 Context Api를 활용했습니다.

크게 2가지를 생각했습니다.

어디에서든 손쉽게 사용할 수 있도록 input Element와 동기화 된 객체를 state로 가져보자.
여러겹의 추상화 계층으로 재사용성을 높여보자.

어디에서든 손쉽게 사용할 수 있도록 input Element와 동기화 된 객체를 state로 가져보자.

각 input Element에 대응하는 State 객체를 만들어 사용하고 메소드로 필요한 데이터를 가져올 수 있도록 했습니다.

페이먼츠 과제의 요구사항 중에 다음과 같은 사항이 있었고,

각 input들의 조건에 따라 validation 체크
유효한 값 입력시 다음 필드로 Input Focusing

페이먼츠 미션의 요구사항을 보고 생각했을 때, 각 input에 대응하는 state를 객체의 형태로 다룬 이유는 다음과 같습니다.

스스로 validation하는 state 객체

각 Input마다 각자의 validation 로직이 필요합니다.

따라서 객체로 함께 관리하면 컴포넌트에서 별도의 실행로직 없이 새롭게 값이 갱신될 때마다, 자동으로 validation 할 수 있어 컴포넌트의 로직을 한층 깔끔하게 할 수 있을 것이라고 생각했습니다.
invalid에 곧바로 대응해 focus할 수 있는 state 객체

Auto focus를 설계할 당시 invalid한 input을 찾아, focus하는 방법을 생각했습니다.

따라서, invalid한 state 객체를 찾으면 해당 input Element에 곧바로 focus할 수 있도록 HTMLInputElement를 포함시켜두면 좋을 것 이라고 생각했습니다.
컴포넌트의 로직을 깔끔하게 할 수 있을 것으로 기대했습니다.

input의 UI들은 비슷했기에, 구체적인 비즈니스 로직을 state 객체에 넣어두면 공통 컴포넌트에 UI를 정의하고 객체를 주입해 간편하게 재사용할 수 있을 것으로 기대했습니다.

state 객체 구현

직접 구현한 input에 대응하는 state 객체와 이를 컴포넌트에 제공하고 적용하는 로직입니다.

(원래 코드를 조금 수정했습니다.. 추상화단계가 더 있지만, 글의 가독성을 위해 로직을 좀 더 직관적으로 수정했습니다. ㅎㅎ)

// input Element에 대응하는 객체 생성
type TCardNumber = string;

export class CardNumberInputElement {
  value?: TCardNumber;
  errorMessage?: string;
  ref?: HTMLInputElement | null;

  setRef(ref?: HTMLInputElement | null) {
    this.ref = ref;
  }

  // validate 로직, invalidate case에 따른 errorMessage와 함께 관리합니다.
  validateValue(value?: string) {
    if (isNil(value)) return;
    if (!value || value.length !== 4) {
      return '카드 번호 4자리를 입력해주세요.';
    }
  }

  isAllowToFocusNext() {
    return this.value?.length === 4;
  }

  checkWhetherThisUserInputCanBeSet(inputValue: TCardNumber) {
    return !inputValue || inputValue.length <= 4;
  }

  constructor({ value, ref }: Partial) {
    this.value = value;
    this.errorMessage = this.validateValue(value);
    this.ref = ref;
  }
}

// cardStore에 합쳐서 Context로 제공합니다.
const cardStore = {
  cardNumbers: createArray(4, () => new CardNumberInputElement({})),
  cardOwners: createArray(1, () => new CardOwnerInputElement({})),
};

컴포넌트에서 아래와같이 적용됩니다.

interface CardNumbersInputListProps {
  cardNumbers?: TCardStore['cardNumbers'];
}

export const CardNumbersInputList = memo(function CardNumbersInputList({ cardNumbers }: CardNumbersInputListProps) {
  const errorMessage = cardNumbers?.find((cardNumber) => !!cardNumber.errorMessage)?.errorMessage;

  return (
    
      
        {cardNumbers?.map((cardNumber, i) => {
          const isLast = checkIsArrayLast(cardNumbers, i);
          const isPasswordType = i >= cardNumbers.length - 2;
          return (
            
          );
        })}
      
    
  );
});

interface CardNumberProps {
  type?: HTMLInputTypeAttribute;
  cardNumber: CardNumberInputElement;
  index: number;
  needDividerRender: boolean;
}

export const CardNumberInput = memo(function CardNumberInput({
  type = 'text',
  cardNumber,
  index,
  needDividerRender,
}: CardNumberProps) {
  const { checkWhetherThisUserInputCanBeSet, value, setRef, errorMessage } = cardNumber;
  const isError = !!errorMessage;

  const cardContextApis = useCardContextApis();

  const onInputChange = {
    if (checkWhetherThisUserInputCanBeSet(e.currentTarget.value)) {
      const newValue = filterNumber(e.currentTarget.value);
      cardContextApis?.dispatch({ type: 'cardNumbers', payload: { index, value: newValue } });
    }
  };

  // CardInfoInputElement는 input Element를 한번 추상화한 컴포넌트입니다.
  // 내부적으로 Error를 판단해 UI로 표현해줍니다.
  return (
    
  );
});

Auto focusing 기능 구현

아래는 AutoFocus를 위해 만든 custom Hook입니다.

cardStore가 갱신될 때마다 실행됩니다.

// auto focusing 기능을 책임지는 custom hook
// 현재 active인 ref의 state가 isValid인 것을 확인하고 처음부터 끝까지 valid를 확인하고 처음 invalid한 곳을 바라보게한다.
export function useSequentialAutoFocus(cardStore?: TCardState[][] | null) {
  useEffect(() => {
    if (!cardStore) return;

    const activeState = findActiveState(cardStore);
    if (activeState && !activeState.errorMessage && activeState.isAllowToFocusNext()) {
      findInvalidStoreAndFocus(cardStore);
    }
  }, [cardStore]);
}

// 현재 active한 Element를 찾는다.
export function findActiveState(cardStore: TCardState[][]): TCardState | null {
  let activeState: TCardState | null = null;

  cardStore.some((cardStateList) =>
    cardStateList.some((cardState) => {
      const isActiveElement = cardState.ref === document.activeElement;
      if (isActiveElement) activeState = cardState;
      return isActiveElement;
    })
  );

  return activeState;
}

// value가 없거나 errorMessage가 있는 state를 focus한다.
export function findInvalidStoreAndFocus(cardStore: TCardState[][]): TCardState | null {
  let invalidState: TCardState | null = null;

  cardStore.some((cardStateList) =>
    cardStateList.some((cardState) => {
      const isInvalid = !cardState.value || !!cardState.errorMessage;
      if (isInvalid) {
        invalidState = cardState;
        // Focus를 이곳에서 실행합니다!!
        cardState.ref?.focus();
      }
      return isInvalid;
    })
  );

  return invalidState;
}

여러겹의 추상화 계층으로 재사용성을 높여보자.

OOP에선 여러번의 상속을 통한 상속 계층을 통해 객체의 재사용성을 높일 수 있습니다.

함수의 세계에선 추상함수를 구체화 함수에 포함하여 사용하는 방법으로 여러 layer를 두어 재사용성을 높일 수 있습니다.

그 예시로 외부 storage와 소통을 위한 useFetch와 service 객체가 있습니다.

useFetch와 service 객체 구현

아래는 저의 구현입니다. 단계별로 구현됩니다.

1단계: General Type을 통해 그 어떤 Service든 받아들일 수 있는 useFetch hook

import { useCallback, useEffect, useState } from 'react';

export interface Service {
  get(): Promise;
  post(newStore?: T | null): Promise;
}

// Generic Type을 2가지 경우의 수로 setting할 수 있도록 제공
// 스스로 externalStore를 GET하고 POST해줄 수 있는 객체 넣고, 그 결과를 React lifecycle에 맞춰서 제공해줄 수 있는 hook
export function useFetch(service?: Service): {
  fetchedData?: T | null;
  fetch: (key: keyof Service, newStore?: T | null) => void;
};
export function useFetch }>(
  service?: Service & K
): { fetchedData?: T | null; fetch: (key: keyof Service & keyof K, newStore?: T | null) => void } {
  const [fetchedData, setFetchedData] = useState();

  useEffect(() => {
    service?.get().then((res) => {
      setFetchedData(res);
    });
  }, [service]);

  const fetch = useCallback(
    (key: keyof Service & keyof K, newStore?: T | null) => {
      service?.[key](newStore).then((res) => {
        setFetchedData(res);
      });
    },
    [service]
  );

  return { fetchedData, fetch };
}

2단계: 외부 storage와 연결해주는 service 객체 생성

const LOCAL_STORAGE_CARD_LIST_KEY = 'cardList';

const get = async () => {
  const item = window.localStorage.getItem(LOCAL_STORAGE_CARD_LIST_KEY);
  return item ? (JSON.parse(item) as TCardList) : null;
};

export const localStorageService: TCardListService = {
  get,
  post: async (cardList: TCardList) => {
    window.localStorage.setItem(LOCAL_STORAGE_CARD_LIST_KEY, JSON.stringify(cardList));
    return get();
  },
};

3단계: useFetch를 이용해 cardStore만을 다루는 useFetchCardList hook 생성

export function useFetchCardList() {
  const appContext = useApplicationContext();
  const { fetch, fetchedData } = useFetch(localStorageService);

  const postCard = useCallback(
    (card: TCard, givenCardId?: string) => {
      const cardId = givenCardId || new Date().getTime();

      if (!fetchedData) {
        fetch('post', { [cardId]: card });
        return;
      }

      fetchedData[cardId] = card;
      fetch('post', fetchedData);
    },
    [fetch, fetchedData]
  );

  const deleteCard = useCallback(
    (cardId: string) => {
      if (!fetchedData) return;

      delete fetchedData[cardId];
      fetch('post', fetchedData);
    },
    [fetch, fetchedData]
  );

  return { cardList: fetchedData, postCard, deleteCard };
}

페이먼츠 PR 리뷰

구현을 마치고 PR을 올리면 리뷰어님이 제 구현 코드를 보고 리뷰를 주십니다.

현재 코드에서 좀 더 확장성 있고 읽기 쉬운 코드가 되기 위해 놓친 부분들을 많이 지적해 주셨고,

참고하여 더 깨끗하고 좋은 코드로 수정할 수 있었습니다. 😁

~~(수십개가 넘는 Comment로 두들겨 맞은건 비밀 😇)~~

input Element와 동기화 된 state 객체의 문제점 -> DOM 의존성 문제, 로직 책임 문제

로버트 C. 마틴이 쓴 클린코드 책에 따르면, 객체의 재사용성을 위해선 객체끼리의 낮은 결합도와 한가지의 역할만을 맡을 것을 강조했습니다.

하지만, 제가 설계한 객체는

HTMLElement와 강하게 결합되어 있고,
component의 onChange 이벤트를 조작하는 로직 또한 가지고 있어, 여러 역할을 맡고 있었습니다.

좀 더 자세히 알아보도록 하겠습니다.

DOM에 직접적인 의존성을 가지고 있음

위에 구현한 코드를 보시면 HTMLInputElement를 그대로 들고있는 것을 알 수 있습니다.

// 간략화한 코드
export class CardNumberInputElement {
  ref?: HTMLInputElement | null;

  setRef(ref?: HTMLInputElement | null) {
    this.ref = ref;
  }
}

state가 DOM을 직접 가지고 있으면, DOM이 없는 환경에서 바로 문제가 발생할 수 밖에 없습니다.

당장 Server 환경에선 문제가 발생할 것입니다.

코드 변경 또한, 직접 class를 바꿔주고, ref를 사용하는 모든 코드를 바꿔야하므로 굉장한 자원이 소모 됩니다. 😇

로직의 사용처와 선언부가 너무 떨어져 있다. 즉, 책임이 잘못 배정돼있음

두번째로 문제가 되는 것은 state 객체에 책임이 너무 많다는 것이었습니다.

UI 이벤트에 관여하는 로직을, state 객체가 가지고 있어 사용처와 선언부가 매우 멀어 가독성도 떨어질 뿐더러 객체의 책임 소재가 조금 잘못되었다고 생각했습니다.

이렇게 되면 컴포넌트를 이용하기 위해 매번 복잡한 객체를 만들어 제공해줘야합니다. (state 객체가 구체적인 로직을 가지고 있기 때문)

또한, 컴포넌트는 로직이 자주 변경되는 부분 중 하나인데, 만약 새로운 요구사항으로 추상화 컴포넌트를 수정하게 되면, state 객체까지 수정해야합니다.

유지보수가 굉장히 번거로워집니다.

아래는 문제가 되는 부분들만 모아놨습니다.

// 간략화한 state 객체 코드
export class CardNumberInputElement {
  value?: TCardNumber;

  isAllowToFocusNext() {
    return this.value?.length === 4;
  }

  checkWhetherThisUserInputCanBeSet(inputValue: TCardNumber) {
    return !inputValue || inputValue.length <= 4;
  }
}

// 간략화한 컴포넌트 코드
export const CardNumberInput = memo(function CardNumberInput({
  cardNumber,
}: CardNumberProps) {
  const { checkWhetherThisUserInputCanBeSet, value, setRef, errorMessage } = cardNumber;
  const isError = !!errorMessage;

  const cardContextApis = useCardContextApis();

  const onInputChange = {
    // !!: state 객체가 onChange 로직에 관여!
    if (checkWhetherThisUserInputCanBeSet(e.currentTarget.value)) {
      const newValue = filterNumber(e.currentTarget.value);
      cardContextApis?.dispatch({ type: 'cardNumbers', payload: { index, value: newValue } });
    }
  };

  return (
    
  );
});

// auto focus custom hook 로직의 일부분입니다.
const isInvalid = !cardState.value || !!cardState.errorMessage;
if (isInvalid) {
  invalidState = cardState;
  // !!: state 객체가 custom hook 로직에 관여합니다!
  cardState.ref?.focus();
}

-> Jbee님의 클린코드 포스팅과 soso님의 클린코드 포스팅을 참고했습니다.

이렇게 수정!

따라서, state에 모든 메소드를 분리하고 DOM의 의존하는 property를 없애 최대한 단순화 하였고, 컴포넌트에서 비즈니스 로직이 수행되도록 수정했습니다.

// ?!?! 엄청나게 가벼워졌습니다.
export interface CardNumberState {
  value?: CardNumber;
  errorMessage?: string;
}

// validator라는 Directory를 새로 만들어 검증 로직을 별도로 관리했습니다.
export function validateCardNumber(cardNumber?: CardNumber) {
  if (!cardNumber || cardNumber.length !== 4) {
    return '카드 번호 4자리를 입력해주세요.';
  }
}

export function checkIsCardNumberFulfilled(cardNumberState: CardNumberState) {
  const { errorMessage, value } = cardNumberState;
  return !errorMessage && value?.length === 4;
}

아래는 컴포넌트 입니다.

import {
  CardNumberState,
  useCardContextApis,
} from '@/contexts/CardContext';
import {
  validateCardNumber,
} from '@/contexts/CardContext/validator';

interface CardNumberProps {
  type?: HTMLInputTypeAttribute;
  cardNumber: CardNumberState;
  index: number;
}

export const CardNumberInput = memo(function CardNumberInput({
  type = 'text',
  cardNumber,
  index,
}: CardNumberProps) {
  const { value, errorMessage } = cardNumber;
  const isError = !!errorMessage;

  const cardContextApis = useCardContextApis();

  const onInputChange = (e: ChangeEvent) => {
    const filteredNumber = filterNumber(e.currentTarget.value);

    // 메소드가 아니라 직접 컴포넌트에서 로직을 수행합니다.
    if (!filteredNumber || filteredNumber.length <= 4) {
      const newValue = filteredNumber;
      // 객체가 아닌 validator에서 가져온 로직을 사용합니다.
      const errorMessage = validateCardNumber(newValue);

      cardContextApis?.setOneCardState({ type: 'cardNumbers', index, newState: { value: newValue, errorMessage } });
    }
  };

  return (
     {
        if (el) setElement(el, 'cardNumbers', index);
      }}
      onChange={onInputChange}
      error={{ isError }}
    />
  );
});

여러겹의 추상화 -> 굳이 이렇게까지? 가독성이 크게 떨어지고 코드 수정에 불리

YAGNI, You aren't gonna need it - 익스트림 프로그래밍, 론 제프리스

기능에 비해 추상화 레이어가 너무 많아 이해하기 복잡했습니다.

기능이 많이 않다보니 재사용되지 않는 추상화 레이어가 많아졌고 코드의 의도가 희석되어 코드의 이해가 어려워졌던 것입니다.

-> 알고보니 Dan Abramov도 같은 실수를 했었군요,,, ㅎㅎ Goodbye, Clean Code

의존성 다이어그램

의존성 다이어그램을 그려보면 복잡한 구조가 한 눈에 보인다는 리뷰어님의 조언에 따라 다이어그램을 그려보았습니다.

다이어그램을 그려보니 복잡함이 한 눈에 들어왔고 조금씩 구조를 개선하기 위해 노력했습니다.

이렇게 수정!

다이어그램의 내용은 1차 수정이고, 최종적으론 service 객체를 받는 것이 아닌 사용자 스스로 state를 관리하고 그 state만 넘겨받는 것으로 변경했습니다.

대신, 특정 event에 관여할 수 있는 callback을 interface로 제공해 자신의 state를 원활히 관리할 수 있도록 했습니다.

과거 service 객체를 받아오는 형태

service 객체를 받아 매소드를 통해 직접 CardList를 받아오는 형태입니다.

사용자는 service 객체의 interface와 로직을 지켜 전달해주어야합니다. 매우 번거롭습니다. 😰

// service 객체를 받아 매소드를 통해 직접 CardList를 받아오는 형태입니다.
export interface Service {
  get(): Promise;
  post(newStore?: CardList | null): Promise;
}

export function useFetch(service?: Service) {}

state와 callback을 받는 형태

custom hook이 아닌 Context Api를 감싼 component에서 그대로 받습니다.

사용자는 cardList를 state로 직접 다루면서 내부 이벤트에 관여할 수 있는 콜백을 넣어줄 수 있습니다.

훨씬 직관적이고 사용자에게 cardList를 다룰 권한이 넘어가 훨씬 자유롭게 사용할 수 있게 됐습니다. 🙌

// custom hook이 아닌 Context Api를 감싼 component에서 그대로 받습니다.
function ApplicationProvider({
  cardList = {},
  onCardConfirm = (card, cardId) => {
    console.log(`cardId : ${cardId}, card: ${card}`);
  },
  onCardDelete = (card, cardId) => {
    console.log(`cardId : ${cardId}, card: ${card}`);
  },
  onCardUpdate = (card, cardId) => {
    console.log(`cardId : ${cardId}, card: ${card}`);
  },
  onCardSubmit = (card, cardId) => {
    console.log(`cardId : ${cardId}, card: ${card}`);
  },
  children,
}) {
  const AppContextValue = { cardList, onCardConfirm, onCardUpdate, onCardDelete, onCardSubmit };

  return {children};
}