✅ PM2 자동 시작 설정 방법

PM2에서 제공하는 startup 명령어로 부팅 시 자동 실행 설정이 가능하다.

pm2 startup

이 명령을 실행하면 아래와 같은 출력이 나올 것이다:

[PM2] Init system found: systemd
[PM2] To setup the Startup Script, copy/paste the following command:
sudo env PATH=$PATH:/home/ubuntu/.nvm/versions/node/v18.15.0/bin pm2 startup systemd -u ubuntu --hp /home/ubuntu

출력된 이 명령어를 복사해서 그대로 실행하면 된다.

✅ 설정 마무리 (현재 상태 저장)

현재 실행 중인 앱들을 부팅 시에도 실행되도록 저장하려면:

pm2 save

🔁 요약

1. PM2 부팅 자동 실행 스크립트 등록:

   pm2 startup
   sudo env ... # 위 출력된 명령어 실행

2. 현재 상태 저장:

   pm2 save

이제 EC2가 재시작되어도 PM2가 자동으로 실행되고, 앱도 같이 실행된다 🙌

Google의 JSON Style Guide는 JSON 데이터의 일관성과 가독성을 높이기 위한 규칙과 권장사항을 제시한다. 주요 요점을 아래와 같이 정리할 수 있다.

{
  "apiVersion": "...",
  "context": "...",
  "id": "...",
  "method": "...",
  "params": { ... },
  "data": { ... },
  "error": { ... }
}

• 최상위 필드들
  • apiVersion: 이 API의 버전 ("v1" 등)
  • context: 이 요청이 어떤 컨텍스트에서 발생했는지 설명 (예: 트래킹 ID)
  • id: 요청 또는 응답의 고유 식별자
  • method: 호출할 메서드 이름 (RPC 스타일일 때 사용)
  • params: 호출할 메서드에 전달할 인자들 (파라미터 객체)
  • data: 성공 시 응답
  • error: 실패 시 응답

data와 error는 동시에 포함되면 안 되고, 둘 중 하나만 있어야 한다.

data 객체 (성공 시 응답)

실제로 유저가 받고자 하는 데이터를 포함한다. 대부분의 유용한 정보는 이 안에 들어간다.

• kind: 리소스 종류 (예: "calendar#event")
• fields: 필드 필터링용 (필요한 필드만 지정할 때 사용)
• etag: 데이터의 버전(캐싱 용도)
• id: 데이터 자체의 ID
• lang: 언어 코드 ("en", "ko")
• updated: 마지막 수정 날짜 (RFC 3339 형식)
• deleted: 삭제 여부 (boolean)
• currentItemCount, totalItems, itemsPerPage, startIndex, pageIndex, totalPages: 페이지네이션 관련 정보
• pageLinkTemplate: 페이지 링크 형식 템플릿
• next, nextLink, previous, previousLink, self, selfLink, edit, editLink: 링크 객체들 (REST 스타일 탐색을 위한 링크)
• items: 실제 데이터 배열 (예: 게시글 리스트, 유저 리스트 등)

error 객체 (오류 발생 시 응답)

요청이 실패했을 때 포함된다. data는 이 경우 생략된다.

• code: 에러 코드 (HTTP 상태 코드와 유사)
• message: 에러 메시지 (사용자 또는 개발자용)
• errors: 에러 상세 항목들 (복수 가능)
• errors[].domain: 에러가 발생한 도메인 (예: "global" 등)
• errors[].reason: 발생 이유 (예: "notFound" 등)
• errors[].message: 구체적 설명
• errors[].location: 어떤 파라미터에서 에러가 났는지
• errors[].locationType: 예: "parameter"
• errors[].extendedHelp: 추가 설명 URL
• errors[].sendReport: 버그 리포트 제출 링크

결론

이 가이드는 API 설계자와 개발자들이 상호운용성, 유지보수성, 일관성을 확보하는 데 큰 도움이 된다.

• 클라이언트-서버 구조: 클라이언트와 서버는 서로 독립적이며, 클라이언트는 서버로부터 데이터를 요청하고 서버는 해당 요청에 응답하는 역할을 한다.
• 무상태성(Stateless): 서버는 각 요청을 독립적으로 처리하며, 이전 요청의 상태를 저장하지 않는다. 모든 요청은 필요한 모든 정보를 포함해야 한다.
• 캐시 처리 가능(Cachability): 클라이언트는 서버 응답을 캐시할 수 있으며, 이를 통해 성능을 최적화하고 서버에 대한 부하를 줄일 수 있다.
• 계층화 시스템(Layered System): 클라이언트는 중간 서버(게이트웨이, 프록시 등)를 통해 서버와 상호 작용할 수 있으며, 각 계층은 독립적으로 설계된다.
• 인터페이스 일관성(Uniform Interface): 리소스는 통일된 방식으로 접근되며, 특정 URL이 해당 리소스를 나타낸다.
• 리소스 기반 아키텍처: URL은 리소스를 나타내며, 리소스는 HTTP 메서드(주로 GET, POST, PUT, DELETE 등)에 따라 CRUD 작업을 수행한다.

REST API: 이는 REST(Representational State Transfer) 원칙을 따르는 API를 가리킨다. API가 완전히 REST 원칙을 준수하지 않아도 이 용어를 사용할 수 있다.

RESTful API: 이 용어는 REST 원칙을 더 충실하게 따르는 API를 의미한다. 즉, API가 엔드포인트와 자원을 의도된 데이터와 작업에 맞게 설계하고, HTTP 메소드(GET, POST, PUT, DELETE)를 적절히 활용하여 표준적인 방식으로 자원을 표현하는 API를 가리킨다.

API 엔드포인트 설계

이미지 출처

API 엔드포인트는 직관적이고 RESTful한 방식으로 구성하는 게 중요하다. RESTful API는 자원(Resource)을 중심으로 설계된다. 자원은 URL로 표현되며, 각 자원에 대해 HTTP 메서드를 사용해 CRUD(Create, Read, Update, Delete) 작업을 수행한다.

• 엔드포인트 설계 시 고려해야 할 요소

엔드포인트를 설계할 때는 다음과 같은 요소를 고려해야 한다.

• 명확한 URL 구조 : URL은 간결하고 직관적이어야 한다. 어떤 자원과 관계된 것인지 URL만으로 유추할 수 있으면 좋다. 직관적인가 의심이 들 경우 AI의 의견을 참고해보는 것도 도움이 될 것이다.
• HTTP 메서드의 적절한 사용 : 각 메서드는 특정 작업을 수행하기 위해 설계되었다. GET은 데이터를 가져오고, POST는 데이터를 생성하며, PUT은 데이터를 업데이트하고, DELETE는 데이터를 삭제한다.
• 상태 코드의 활용 : 클라이언트에게 요청의 결과를 알려주기 위해 적절한 HTTP 상태 코드를 반환해야 한다. 예를 들어, 요청이 성공하면 200 OK, 자원이 생성되면 201 Created, 요청이 잘못되면 400 Bad Request를 반환할 수 있다.

RESTful API 설계 규칙

1. 리소스는 복수형 명사 리소스는 복수형 명사로 작성한다. 예를 들어, users, orders, products 등과 같이 작성한다. 예시: GET /users → 모든 사용자 조회 POST /orders → 주문 생성

2. 자원의 고유 ID는 URL에 포함 특정 자원에 접근할 때는 해당 자원의 고유 ID를 URL에 포함한다. 예시: GET /users/123 → ID가 123인 사용자 조회 PUT /products/45 → ID가 45인 상품 수정

3. 계층적 관계 표현 자원 간의 계층적 관계가 있을 경우 URL에 중첩해 표현한다. 자원 내의 하위 자원을 나타낼 때 유용하다. 예시: GET /users/123/orders → ID가 123인 사용자의 주문 목록 조회 POST /users/123/orders → ID가 123인 사용자에게 주문 생성

4. HTTP 메서드를 활용한 동작 정의 HTTP 메서드(GET, POST, PUT, DELETE)를 통해 동작을 정의하므로, URL에는 동작을 나타내는 동사를 포함하지 않는다. GET → 조회 (Read) POST → 생성 (Create) PUT 또는 PATCH → 수정 (Update) DELETE → 삭제 (Delete) 예시: DELETE /users/123 → ID가 123인 사용자 삭제 PUT /products/45 → ID가 45인 상품 정보 수정

5. URL에는 소문자만 사용 URL은 소문자만 사용하고, 단어는 하이픈(-)으로 구분한다. 대소문자 혼합은 일관성을 해칠 수 있다. 예시: /user-profiles/123 (O) /UserProfiles/123 (X)

6. 필터링, 정렬, 페이징은 쿼리 파라미터로 필터링, 정렬, 페이징과 같은 추가 조건은 URL 경로 대신 쿼리 파라미터를 사용하여 표현한다. 예시: GET /products?category=books&sort=price_asc&page=2 → 책 카테고리의 제품을 가격 오름차순으로 정렬하고, 2페이지 결과 조회

7. 액션은 경로가 아닌 쿼리 파라미터로 표현 일반적인 CRUD 작업이 아닌 특별한 동작이 필요한 경우, URL 경로 대신 쿼리 파라미터나 추가 경로로 표시한다. 예시: POST /users/123/activate → ID가 123인 사용자를 활성화 POST /orders/45/cancel → 주문을 취소

8. 경로 마지막에 '/'를 넣지 않는다.

자동화 툴

향후에는 API문서화와 테스트를 자동화하여 관리하고 싶어서 Apidog와 같은 툴을 이용해볼까 한다. Apidog의 REST API URL 모범 사례

1. JWT (JSON Web Token)

• 클라이언트가 로그인하면 서버는 JWT를 발급
• 클라이언트는 이 JWT를 Authorization 헤더나 쿠키에 담아 보냄
• 서버는 이 토큰을 검증해서 인증 처리
• Stateless 방식 (서버에 세션 저장 X)

2. 세션 쿠키 (Session Cookie)

• 서버가 세션을 만들고, 식별용 세션 ID를 클라이언트에 쿠키로 저장
• 클라이언트는 요청마다 세션 쿠키를 보냄
• 서버는 세션 ID로 사용자 상태를 찾아서 인증
• Stateful 방식 (세션 상태를 서버에 저장)

3. CSRF 토큰

• 주로 쿠키 기반 인증에서 사용
• 이유: 쿠키는 자동으로 브라우저가 요청에 포함하므로, 악의적 요청도 세션이 살아있으면 처리될 수 있음 → 그래서 요청이 의도된 것인지 확인하려고 CSRF 토큰 사용

🤔 그렇다면 JWT + 세션 + CSRF 토큰을 모두 써야 할까?

🔹 상황 1: JWT를 Authorization 헤더로 보낸다면

• ✅ CSRF 토큰은 필요 없음
• ❌ 세션도 필요 없음 (완전히 stateless)
• JWT를 로컬스토리지에라도 보관? XSS 공격에 취약함

🔹 상황 2: JWT를 HttpOnly 쿠키에 저장한다면

• ✅ CSRF 토큰 필요
  • 이유: 악의적 사이트가 사용자의 쿠키로 요청을 보낼 수 있음
• ⚠️ 동시에 세션을 굳이 쓸 필요는 없음 (JWT 자체가 인증 상태를 저장함)
• SameSite=Strict와 HttpOnly 쿠키를 쓰는 경우, CSRF 토큰은 optional이지만, admin 등 민감 영역엔 추가하기도 함

🔹 상황 3: 기존 세션 기반 인증을 쓰는 경우 (express-session 등)

• ✅ CSRF 토큰 필요
• ❌ JWT는 필요 없음 (중복 인증 시스템)

👉 추천 조합

• ✅ 간편하고 RESTful하게 하고 싶다면:
  JWT + Authorization 헤더 방식 → CSRF 걱정 없음

• ✅ 보안 우선 + 브라우저 자동처리 + 쿠키 기반 원한다면:
  JWT in HttpOnly Cookie + CSRF Token → CSRF 보호 필수

점진적 토큰 갱신의 핵심 원칙

1. 액세스 토큰을 자주 갱신하되, 리프레시 토큰 갱신은 최소화

   • 액세스 토큰이 만료될 때마다 새로운 액세스 토큰을 발급.
   • 리프레시 토큰은 일정 조건에서만 갱신하여 탈취 가능성을 줄임.

2. 리프레시 토큰의 롤링(순환) 방식 적용

   • 리프레시 토큰을 사용할 때마다 새로운 리프레시 토큰을 발급하고, 기존 토큰을 폐기.
   • 이를 통해 탈취된 리프레시 토큰의 재사용 공격을 방지.

3. 사용자가 장기간 로그인 상태를 유지하면 리프레시 토큰도 주기적으로 갱신

   • 일정 기간 동안 리프레시 토큰이 사용되지 않으면 폐기.

점진적 토큰 갱신 구현 방식

1. 기본 토큰 발급

사용자가 로그인하면 액세스 토큰과 리프레시 토큰을 발급한다.

const accessToken = jwt.sign({ userId }, process.env.ACCESS_SECRET, {
  expiresIn: "15m", // 짧은 유효기간
});

const refreshToken = jwt.sign({ userId }, process.env.REFRESH_SECRET, {
  expiresIn: "7d", // 긴 유효기간
});

// 액세스 토큰은 클라이언트가 저장 (ex: 메모리, 상태관리)
// 리프레시 토큰은 쿠키에 저장 (HttpOnly, Secure 설정)
res.cookie("refreshToken", refreshToken, {
  httpOnly: true,
  secure: process.env.NODE_ENV === "production",
  sameSite: "Strict",
});

2. 액세스 토큰 자동 갱신 (프론트엔드)

• 액세스 토큰이 만료되기 약 1~2분 전에 새로운 액세스 토큰을 요청.
• refreshToken을 이용하여 POST /auth/refresh API를 호출.

async function refreshAccessToken() {
  const response = await fetch("/auth/refresh", { method: "POST", credentials: "include" });
  if (response.ok) {
    const data = await response.json();
    return data.accessToken;
  }
  return null;
}

✅ 효과: 사용자는 로그아웃 없이 지속적으로 로그인 유지 가능.

3. 리프레시 토큰 갱신 조건

리프레시 토큰을 매번 갱신하지 않고, 특정 조건에서만 교체한다.

리프레시 토큰을 갱신하는 조건

• ① 액세스 토큰을 갱신할 때, 리프레시 토큰이 30% 이상의 유효 기간을 사용한 경우
  예) 7일짜리 토큰이라면 2일 이상 사용되었을 때만 새 리프레시 토큰 발급
• ② 로그인 유지 시간이 X일 이상 경과한 경우

function shouldRefreshToken(iat, exp) {
  const now = Math.floor(Date.now() / 1000);
  const usedTime = now - iat;
  const totalLifetime = exp - iat;

  return usedTime / totalLifetime > 0.3; // 30% 이상 사용되었으면 갱신
}

✅ 효과: 리프레시 토큰을 자주 갱신하지 않아 보안성에 도움(리프레시 토큰을 자주 갱신하면 새로운 토큰이 클라이언트와 서버 간에 빈번하게 전송됨 → 네트워크에서 탈취될 가능성이 증가.)

4. 리프레시 토큰을 사용한 액세스 토큰 갱신 API

app.post("/auth/refresh", async (req, res) => {
  const refreshToken = req.cookies.refreshToken;
  if (!refreshToken) return res.status(401).json({ message: "Unauthorized" });

  try {
    const payload = jwt.verify(refreshToken, process.env.REFRESH_SECRET);
    const newAccessToken = jwt.sign({ userId: payload.userId }, process.env.ACCESS_SECRET, { expiresIn: "15m" });

    // 리프레시 토큰이 30% 이상 사용되었으면 새로 발급
    if (shouldRefreshToken(payload.iat, payload.exp)) {
      const newRefreshToken = jwt.sign({ userId: payload.userId }, process.env.REFRESH_SECRET, { expiresIn: "7d" });

      res.cookie("refreshToken", newRefreshToken, {
        httpOnly: true,
        secure: process.env.NODE_ENV === "production",
        sameSite: "Strict",
      });
    }

    res.json({ accessToken: newAccessToken });
  } catch (err) {
    return res.status(403).json({ message: "Invalid refresh token" });
  }
});

✅ 효과: 리프레시 토큰의 사용량을 체크하고 필요할 때만 갱신하여 보안 유지.

5. 로그아웃 및 리프레시 토큰 무효화

사용자가 로그아웃하면 리프레시 토큰을 즉시 삭제해야 한다.

app.post("/auth/logout", (req, res) => {
  res.clearCookie("refreshToken");
  res.json({ message: "Logged out" });
});

✅ 효과: 탈취된 리프레시 토큰을 이용한 불법 접근 차단.

정리: 점진적 토큰 갱신의 흐름

1. 로그인 시 액세스 토큰(15분)과 리프레시 토큰(7일) 발급
2. 액세스 토큰 만료 전에 POST /auth/refresh 호출하여 갱신
3. 리프레시 토큰이 30% 이상 사용되었을 때만 갱신
4. 새로운 리프레시 토큰 발급 시 기존 토큰은 폐기
5. 로그아웃 시 리프레시 토큰 삭제

✅ 장점

• 사용자 경험 개선: 로그아웃 없이 인증 유지 가능
• 보안 강화: 리프레시 토큰의 수명을 연장하면서도 과도한 재사용 방지
• 서버 부하 최소화: 리프레시 토큰을 자주 갱신하지 않아 데이터베이스 부하 감소

이 방식으로 구현하면 보안과 사용자 경험을 모두 최적화할 수 있다.

1. 주요 저장 방법 비교

각 저장 방식의 자세한 설명과 고려할 사항을 살펴보자.

2. 저장 방식별 상세 분석

1) 메모리 저장 (JavaScript 변수, React 상태 관리 등)

✅ 장점:

• XSS 공격에 안전함 (스크립트가 실행되는 동안만 유지됨).
• CSRF 공격에도 안전함 (브라우저가 자동으로 전송하지 않음).

❌ 단점:

• 새로고침하면 사라짐 → UX가 나빠짐.
• 페이지가 닫히면 다시 로그인해야 함.

🔹 추천 상황:

• 보안이 최우선인 애플리케이션 (ex: 금융 서비스, 관리자 페이지).
• 사용자 경험보다 보안이 더 중요한 경우.

2) HTTP-Only 쿠키 저장 (✅ 추천)

쿠키에 httpOnly, secure, sameSite=strict 속성을 추가하면 XSS 공격에 안전하면서도 자동으로 액세스 토큰을 포함하여 요청할 수 있다.

res.cookie("accessToken", token, {
  httpOnly: true, 
  secure: process.env.NODE_ENV === "production", 
  sameSite: "strict"
});

✅ 장점:

• XSS 공격에 안전 (JavaScript에서 접근 불가).
• 브라우저가 자동으로 요청에 포함 → 개발이 편리함.

❌ 단점:

• CSRF 공격에 취약 → CSRF 보호가 필요함.
  • 대책: SameSite=Strict 설정 또는 CSRF 토큰 추가.
• 도메인 간 요청 제한 (sameSite=strict로 설정 시 외부 사이트에서 요청 불가).

🔹 추천 상황:

• JWT 기반 인증 시스템에서 보안과 편의성을 함께 고려할 때.
• REST API를 사용하는 SPA/SSR 애플리케이션.

✅ 보안 대책 (CSRF 보호):

• API 요청 시 CSRF 토큰 사용 (ex: X-CSRF-Token 헤더).
• SameSite=Strict 설정으로 외부 사이트 요청 차단.

3) localStorage 저장 (❌ 비추천)

localStorage는 XSS 공격에 취약하므로, 보안이 중요한 애플리케이션에서는 사용하지 않는 것이 좋다.

✅ 장점:

• 새로고침해도 유지됨.
• CSRF 공격에 안전함.

❌ 단점:

• XSS 공격에 취약 → 악성 스크립트가 localStorage에서 토큰을 가져갈 수 있음.
• 토큰을 직접 포함해서 요청해야 함 → 번거로움.

🔹 추천 상황:

• 보안이 크게 중요하지 않은 애플리케이션.
• 서버가 정적 리소스만 제공하고, API 요청 시만 인증이 필요한 경우.

4) sessionStorage 저장 (❌ 비추천)

sessionStorage는 XSS 공격에 취약하고, 브라우저를 닫으면 사라지므로 보안성이 높다고 보기 어렵다.

✅ 장점:

• 새로고침해도 유지됨.
• CSRF 공격에 안전함.

❌ 단점:

• XSS 공격에 취약.
• 브라우저를 닫으면 로그아웃됨 → 사용자 경험이 나쁨.

🔹 추천 상황:

• 보안이 중요하지 않고, 짧은 세션만 유지하면 되는 경우.

3. 결론: 언제 어떤 저장 방식을 선택해야 할까?

✅ 최적의 선택:

• 백엔드 API와 함께 JWT를 사용할 경우, httpOnly 쿠키 저장을 추천.
• CSRF 보호를 추가하면 보안성이 높아짐.
• XSS 위험을 최소화하려면 localStorage 사용을 피하는 것이 좋음.

4. 추가 보안 대책

1. CSRF 방어

   • SameSite=Strict 또는 X-CSRF-Token 사용.
   • CSRF 보호가 필요한 경우 쿠키를 사용하지 않고, 헤더 기반 인증 (Authorization: Bearer)을 고려.

2. XSS 방어

   • Content Security Policy (CSP)를 적용하여 악성 스크립트 실행 차단.
   • React 등에서 dangerouslySetInnerHTML 같은 XSS 위험 요소 피하기.

3. 리프레시 토큰은 어디에 저장할까?

   • httpOnly 쿠키에 저장하는 것이 가장 안전.
   • 리프레시 토큰은 주로 보안성이 중요한 정보이므로 JavaScript에서 접근할 수 없게 설정하는 것이 좋음.

5. 최종 추천 구조

• 액세스 토큰: httpOnly 쿠키에 저장.
• 리프레시 토큰: httpOnly 쿠키에 저장.
• CSRF 보호: X-CSRF-Token을 요청 헤더에 포함.

이렇게 하면 XSS, CSRF 공격을 모두 방어하면서도 개발 편의성을 유지할 수 있다.

JWT 갱신은 주로 액세스 토큰(Access Token)과 리프레시 토큰(Refresh Token)을 사용하여 이루어진다. 이 방식의 주요 특징과 과정은 다음과 같다:

토큰 구조

• 액세스 토큰: 짧은 유효 기간(예: 1시간)을 가지며, 사용자 인증에 사용
• 리프레시 토큰: 긴 유효 기간(예: 일주일에서 한 달)을 가지며, 새로운 액세스 토큰을 발급받는 데 사용

갱신 과정

1. 사용자 로그인 시, 서버는 액세스 토큰과 리프레시 토큰을 모두 발급한다.
2. 액세스 토큰이 만료되면, 클라이언트는 리프레시 토큰을 사용하여 새로운 액세스 토큰을 요청한다.
3. 서버는 리프레시 토큰의 유효성을 검증한 후, 새로운 액세스 토큰을 발급한다.

리프레시 토큰이 굳이 필요한가?

액세스 토큰만 사용하면

1. 만료된 후 자동 갱신 불가

   • 액세스 토큰이 만료되면 사용자는 다시 로그인해야 함.
   • UX가 나빠지고, 세션이 자주 끊어질 수 있음.

2. 긴 만료 시간은 보안 취약점

   • 만약 액세스 토큰을 길게 설정하면, 토큰이 탈취되었을 때 위험성이 증가함.
   • 짧게 설정하면 사용자가 자주 로그인해야 하는 불편함이 있음.

3. 토큰을 탈취당하면 재사용 가능

   • 액세스 토큰만 사용하면 탈취된 토큰을 즉시 차단할 방법이 부족함. 서버는 그 토큰을 무효화할 방법이 없으므로 만료 시간이 지날 때까지 유효한 상태로 남아있음.
   • 액세스 토큰을 차단하려면 블랙리스트를 사용해야 하는데, JWT는 기본적으로 서버에서 상태를 저장하지 않는 방식이므로, 블랙리스트를 유지하면 Stateless한 장점이 사라짐.

리프레시 토큰이 필요한 이유

1. 짧은 만료 시간의 액세스 토큰 사용 가능

   • 액세스 토큰을 5~15분 정도의 짧은 시간으로 설정하고, 만료 시 리프레시 토큰을 이용해 자동으로 갱신.
   • 보안이 강화되고, 사용자 경험도 개선됨.

2. 리프레시 토큰이 도난당해도 차단 가능

   • 리프레시 토큰을 서버에서 블랙리스트 관리할 수 있음.
   • 탈취된 토큰을 무효화할 수 있기 때문에 보안성이 증가함.

토큰 탈취를 인지하는 방법

리프레시 토큰이 탈취당했을 때 이를 인지하고 차단하는 방법을 고민해야 한다.
일반적으로 리프레시 토큰은 액세스 토큰보다 훨씬 긴 만료 시간을 가지므로, 보안이 중요하다.

1. 리프레시 토큰 탈취를 인지하는 방법

1) 기존과 다른 IP, 기기에서 요청 감지

• 사용자의 최근 로그인 정보(IP, User-Agent, 기기 정보 등)를 기록하고, 리프레시 요청이 기존 정보와 다르면 의심해야 함.
• 예를 들어:
  • 사용자가 한국에서 로그인했는데, 갑자기 다른 나라에서 리프레시 요청이 발생한다면 이상 징후로 간주 가능.

✅ 대응 방법

• 리프레시 요청이 기존과 다른 환경에서 발생하면 추가 인증(예: 이메일 인증, OTP 요청).
• 비정상적인 경우 리프레시 토큰을 폐기하고 사용자에게 알림 전송.

2) 동일한 리프레시 토큰이 여러 곳에서 사용됨

• 하나의 리프레시 토큰은 한 번만 사용되도록 설계하고, 한 번 사용된 토큰이 또 요청되면 탈취 가능성이 높음.
• 즉, 리프레시 토큰이 재사용되면 탈취된 것으로 판단 가능.

✅ 대응 방법

• 리프레시 토큰을 한 번 사용하면 즉시 폐기하고, 새 리프레시 토큰 발급(Rotating Refresh Token 방식).
• 이전 리프레시 토큰이 다시 사용되면 로그아웃 처리 및 사용자에게 알림 전송.

3) 너무 짧은 시간에 다수의 리프레시 요청 발생

• 정상적인 사용자는 보통 액세스 토큰이 만료될 때만 리프레시 요청을 보냄(예: 15~30분에 한 번).
• 하지만, 탈취된 리프레시 토큰을 사용해 공격자가 여러 번 요청을 보내는 경우 이상 징후로 감지 가능.

✅ 대응 방법

• 일정 시간 내 리프레시 요청 횟수를 제한(rate limiting).
• 예를 들어, 30분 내에 2번 이상 리프레시 요청이 들어오면 계정 보호 모드 발동.

2. 리프레시 토큰 탈취 대응 방법

1) 리프레시 토큰을 DB에서 관리

• 리프레시 토큰을 데이터베이스에 저장하고, 탈취 시 폐기할 수 있도록 관리해야 함.
• Redis 같은 인메모리 저장소를 활용해 빠르게 블랙리스트 처리 가능.

✅ 대응 방법

• 리프레시 토큰을 발급할 때마다 DB에 저장하고, 로그아웃하거나 탈취 의심 시 즉시 삭제.
• 블랙리스트 시스템 운영 → 탈취된 토큰을 무효화하고 다시 사용되지 않도록 방지.

2) 리프레시 토큰 Rotation 적용 (강력 추천)

• 기존 리프레시 토큰을 사용하면 즉시 폐기하고 새 토큰을 발급.
• 즉, 한 번 사용한 리프레시 토큰은 다시 사용할 수 없도록 제한.
• 만약 이전 토큰이 다시 요청되면 탈취 가능성이 크므로, 해당 계정을 보호 모드로 전환.

✅ 대응 방법

• JWT 내부에 jti(unique ID) 포함하고, 서버에서 관리.
• 새 토큰이 발급되면 기존 토큰은 폐기하여 재사용 불가능하도록 함.

3. 리프레시 토큰을 DB에 저장하는 이유

1. 리프레시 토큰은 만료기간이 길다. JWT 액세스 토큰과 달리, 길면 30일 정도인데

2. 사용자가 로그아웃할 때 무효화할 수 있음 DB에 저장하면 특정 사용자의 리프레시 토큰을 삭제해서 강제로 로그아웃시키는 게 가능하다

3. 리프레시 토큰의 재사용 감지 가능 보통 "1회용"으로 사용하고, 새로운 리프레시 토큰을 발급할 때 기존 토큰을 폐기하는 식으로 관리하면, 토큰 탈취를 감지할 수 있다.

4. 결론: 리프레시 토큰 보안 강화를 위해 해야 할 것

✔ IP, 기기 정보 비교 → 다른 환경에서 요청하면 추가 인증 요구
✔ 리프레시 토큰 재사용 방지 → 한 번 사용된 토큰이 다시 사용되면 계정 보호
✔ 요청 횟수 제한 → 짧은 시간 동안 너무 많은 요청이 들어오면 차단
✔ 리프레시 토큰을 서버에서 관리 → 탈취된 토큰을 무효화 가능
✔ Rotation 적용 → 매번 새로운 리프레시 토큰을 발급하여 보안 강화

위 방식을 조합하면 리프레시 토큰이 탈취되더라도 빠르게 감지하고 대응할 수 있다.

JWT의 장점

• 자체 포함(Self-contained): 모든 정보가 토큰에 포함되어 별도의 데이터베이스 조회가 필요 없는 경우도 있음.
• 가볍고 빠름: 단순한 문자열 기반 토큰으로, 빠르게 생성/검증 가능.
• 확장성: JSON 형식이므로 다른 시스템과 통합이 용이.
• Cross-domain 지원: 상태를 서버에 유지하지 않으므로 분산 시스템에서 유용.

JWT의 단점

• 토큰 크기: 토큰 크기가 비교적 크기 때문에 빈번한 요청에 부담이 될 수 있음.
• 토큰 만료: 한 번 발급된 토큰은 만료 전까지는 서버에서 무효화하기 어려움(리프레시 토큰 사용으로 해결 가능).
• 보안 문제: 민감한 데이터를 페이로드에 포함하면 안 됨(평문으로 해독 가능). XSS 공격에 취약할 수 있음(브라우저에 저장된 경우).

JWT는 세 부분으로 나누어지며, 각 부분은 .으로 구분된다.

<Header>.<Payload>.<Signature>

Header (헤더)

• JWT의 타입과 암호화 알고리즘 정보를 담고 있다.
• 보통 아래와 같은 JSON형식이며, Base64Url로 인코딩된다.

  {
  "alg": "HS256", // 해싱 알고리즘 (예: HMAC SHA-256)
  "typ": "JWT"    // 토큰 타입
  }

Payload (페이로드)

• 토큰에 포함된 데이터(Claims)가 들어 있는 부분이다.
• 일반적으로 사용자 정보와 같은 데이터가 포함된다.
• 페이로드도 Base64Url로 인코딩된다. 즉, Base64Url로 디코딩하면, JSON 형태로 사용자 정보나 기타 클레임을 확인할 수 있다.
• Claims 종류
  • 등록된(Registered) Claims: 표준화된 클레임(필수 아님). 예: iss(발급자), exp(만료 시간), sub(주제), aud(대상).
  • 공개(Public) Claims: 사용자 정의 가능. 예: userId, role.
  • 비공개(Private) Claims: 클라이언트와 서버 간 약속된 데이터.

    {
    "sub": "1234567890",
    "name": "John Doe",
    "admin": true,
    "exp": 1712179200 // 만료 시간 (Unix Timestamp)
    }

Signature (서명)

• 토큰의 무결성을 보장하기 위해 사용(서명을 통해 토큰이 위조되지 않았음을 확인할 수 있다).
• 헤더와 페이로드를 조합하여 생성:
• 서명 변조가 불가능한 이유
  • 비밀 키(Secret Key) 관리: 서버에서만 비밀 키를 알고 있으며, 이를 노출하지 않는 한 서명을 위조할 수 없다.
  • 강력한 암호화 알고리즘: HMAC-SHA256, RS256 등 강력한 해싱 및 암호화 알고리즘을 사용. 키를 알지 못하면 서명 결과를 맞추는 것은 거의 불가능하다.

    HMACSHA256(
    base64UrlEncode(header) + "." + base64UrlEncode(payload), 
    secretKey
    )

서명이 위조되지 않는다고 해서 JWT 자체가 항상 안전한 것은 아니다. 몇 가지 주의사항을 지켜야 한다

• HttpOnly 쿠키 사용: JavaScript에서 접근 불가
• HTTPS 사용: 네트워크에서 탈취 방지
• 서버는 알고리즘을 명시적으로 지정하고, none을 허용하지 않아야 함: 공격자가 Header의 알고리즘을 none으로 바꿔서 검증을 우회하려는 시도가 있을 수 있음
• 서명 키 관리: 비밀 키(secret)를 안전하게 저장하고 정기적으로 교체.
• 짧은 만료 시간 설정: exp를 짧게 설정하고, 리프레시 토큰을 사용. 서버 측에서 "블랙리스트"를 사용하여 강제 로그아웃 처리.
• Scope 및 Audience 제한: JWT를 특정 리소스나 용도로만 제한. Payload는 인코딩(Base64Url)만 되어 있고 암호화되지 않으므로 민감한 정보는 JWT에 포함하지 말 것.

Client Side Rendering

초기 로드 후, 모든 라우팅과 데이터 로딩을 클라이언트에서 처리한다.

SPA(Single Page Application)를 만들 때 사용한다.

특징

• 초기 로딩 시, 빈 HTML + JavaScript 번들만 받아온다.
• 이후 라우팅은 클라이언트에서만 처리 (페이지 새로고침 없음).
• SEO에 불리하지만, 빠른 페이지 전환이 가능.

사용법

import type { Config } from "@react-router/dev/config";

export default {
  ssr: false, // 서버 사이드 렌더링 비활성화
} satisfies Config;

Server Side Rendering

페이지를 요청할 때마다 서버에서 HTML을 생성해 클라이언트에 전달한다.

특징

• 첫 페이지 로딩 속도가 빠름 (SEO에 유리).
• 클라이언트에 도달하기 전, 완성된 HTML을 받음.
• 서버 인프라가 필요.

사용법

import type { Config } from "@react-router/dev/config";

export default {
  ssr: true, // 서버 사이드 렌더링 활성화
} satisfies Config;

💡 추가 팁

• SSR을 사용해도 clientLoader를 통해 클라이언트 측 데이터 로딩 가능.
• 일부 라우트는 정적 프리렌더링(Static Pre-rendering)으로 처리 가능.

Static Pre-rendering

빌드 시점에 미리 HTML을 생성해 정적으로 호스팅한다.

SEO 최적화와 빠른 로딩 속도를 위해 사용된다.

특징

• 서버 필요 없음 (정적 사이트 호스팅 가능, 예: GitHub Pages, Netlify).
• 특정 경로만 선택적으로 프리렌더링 가능.
• 정적 사이트 생성기(SSG)*처럼 동작.

사용법

import type { Config } from "@react-router/dev/config";

export default {
  async prerender() {
    return ["/", "/about", "/contact"]; // 빌드 시 미리 렌더링할 경로 목록
  },
} satisfies Config;

• 빌드 시점에 "/", "/about", "/contact" 페이지를 정적 HTML로 생성.
• SEO 최적화와 정적 페이지 제공에 유리.

렌더링 방식 비교

🎯 언제 어떤 방식을 사용할까?

• 🛍️ 쇼핑몰/블로그 등 SEO 중요한 서비스 → SSR 또는 Static Pre-rendering
• ⚡ SPA, 대시보드 등 인터랙티브 앱 → CSR
• 📖 정적 정보성 페이지 → Static Pre-rendering

💡 Tip:

• 필요에 따라 CSR + Static Pre-rendering을 조합하거나,
• 일부 페이지만 SSR로 처리할 수 있다.

routes.ts에서 지정하는 파일(예: "./team.tsx")을 Route Module이라고 한다.

route("teams/:teamId", "./team.tsx"),
//                        ^^^^^^^^ Route Module

Route Module이란?

React Router의 핵심 구조로, 각 라우트의 동작을 정의하는 모듈 파일 React 컴포넌트 외에도 데이터 로딩, 액션 처리, 오류 처리 등을 수행

Route Module은 단순한 페이지 컴포넌트가 아니라, 다음과 같은 기능을 포함할 수 있다.

Component (default)

React Router의 Route Module에서 export default로 정의한 컴포넌트는 해당 경로가 매칭될 때 렌더링되는 컴포넌트이다.

// app/routes/my-route.tsx
export default function MyRouteComponent() {
  return (
    <div>
      <h1>Look ma!</h1>
      <p>I'm still using React Router after like 10 years.</p>
    </div>
  );
}

• export default로 내보내면 React Router가 해당 경로에서 이 컴포넌트를 자동으로 렌더링한다.

📌 컴포넌트에 전달되는 Props

라우트가 렌더링될 때, React Router는 몇 가지 props를 자동으로 전달한다.

이 props는 Route.ComponentProps 타입을 따른다.

이 props를 활용하면 별도의 훅 (useLoaderData, useParams 등) 없이도 데이터를 사용할 수 있다.

Props를 활용한 예제

1️⃣ 라우트 설정

import { type RouteConfig, route } from "@react-router/dev/routes";

export default [
  route("users/:userId", "./user.tsx"), // userId를 포함한 동적 라우트
] satisfies RouteConfig;

2️⃣ Route Module (user.tsx)

import type { Route } from "./+types/user";

export default function MyRouteComponent({
  loaderData,
  actionData,
  params,
  matches,
}: Route.ComponentProps) {
  return (
    <div>
      <h1>Welcome to My Route with Props!</h1>
      <p>Loader Data: {JSON.stringify(loaderData)}</p>
      <p>Action Data: {JSON.stringify(actionData)}</p>
      <p>Route Parameters: {JSON.stringify(params)}</p>
      <p>Matched Routes: {JSON.stringify(matches)}</p>
    </div>
  );
}

• params.userId를 통해 users/:userId 경로에서 userId 값을 가져올 수 있다.
• loaderData, actionData는 해당 라우트에서 데이터를 미리 불러올 때 활용된다.

loader

loader()는 라우트 컴포넌트가 렌더링되기 전에 데이터를 제공하는 함수이다. 서버에서 실행되거나 빌드 시점(pre-rendering) 에만 호출된다.

📌 loader의 주요 특징

export async function loader() {
  return { message: "Hello, world!" };
}

export default function MyRoute({ loaderData }) {
  return <h1>{loaderData.message}</h1>;
}

• loader()가 { message: "Hello, world!" } 데이터를 반환
• MyRoute 컴포넌트에서 loaderData.message를 받아 화면에 출력

참고 https://api.reactrouter.com/v7/interfaces/react_router.LoaderFunctionArgs

clientLoader

clientLoader()는 브라우저에서만 실행되는 데이터 로딩 함수이다. serverLoader()의 데이터를 활용할 수도 있고, 독립적으로 동작할 수도 있다.

📌 기본 개념

export async function clientLoader({ serverLoader }) {
  // 서버에서 데이터를 가져옴
  const serverData = await serverLoader();

  // 클라이언트에서 추가 데이터 가져오기
  const clientData = getDataFromClient();

  // 최종 데이터를 반환
  return { ...serverData, clientData };
}

• serverLoader()를 실행하여 서버 데이터를 가져옴
• getDataFromClient()를 호출하여 클라이언트에서 추가 데이터를 로드
• 두 데이터를 합쳐서 반환

Hydration을 활성화하는 경우

export async function clientLoader() {
  // 클라이언트에서 실행할 데이터 로딩 로직
  const data = await fetch("/api/client-data").then((res) => res.json());
  return data;
}

// Hydration 활성화
clientLoader.hydrate = true as const;

• clientLoader.hydrate = true as const;를 설정하면 서버에서 제공된 데이터를 클라이언트에서 보강 가능
• TypeScript에서 true as const를 사용하면 타입이 boolean이 아닌 true로 고정됨
• React Router는 이를 활용해 loaderData의 타입을 자동으로 유추

언제 clientLoader를 사용할까?

1. 클라이언트에서만 필요한 데이터를 불러올 때
   • 예: 사용자 인터랙션 후 특정 데이터를 요청하는 경우
2. 서버 데이터와 클라이언트 데이터를 조합할 때
   • 예: serverLoader()에서 받은 데이터에 추가적인 브라우저 정보를 결합
3. Hydration을 활용할 때
   • 서버에서 렌더링된 데이터를 클라이언트에서 보강하고 싶을 때

📌 clientLoader vs loader 차이점

참고 https://api.reactrouter.com/v7/types/react_router.ClientLoaderFunctionArgs

action

action()은 서버에서 데이터를 변경하는 함수이다. loader()와 함께 사용하면 데이터를 자동으로 갱신한다. <Form>, useFetcher(), useSubmit()과 함께 사용 가능하다

1️⃣ 기본적인 loader()

export async function loader() {
  const items = await fakeDb.getItems();
  return { items };
}

• fakeDb.getItems()를 통해 서버에서 데이터를 가져옴
• 이 데이터는 loaderData.items로 컴포넌트에서 접근 가능

2️⃣ 컴포넌트에서 loaderData 사용

export default function Items({ loaderData }) {
  return (
    <div>
      <List items={loaderData.items} />
      <Form method="post" navigate={false} action="/list">
        <input type="text" name="title" />
        <button type="submit">Create Todo</button>
      </Form>
    </div>
  );
}

• List items={loaderData.items} → loaderData에서 받은 데이터를 리스트로 표시
• <Form> 사용
  • method="post" → POST 요청을 보냄
  • action="/list" → /list 경로의 action()이 호출됨
  • navigate={false} → 페이지 새로고침 없이 데이터만 갱신

3️⃣ 서버에서 데이터 변경 (action())

export async function action({ request }) {
  const data = await request.formData();
  const todo = await fakeDb.addItem({
    title: data.get("title"),
  });
  return { ok: true };
}

• request.formData()를 사용해 폼 데이터 가져오기
• fakeDb.addItem()을 호출해 새로운 할 일 추가
• { ok: true } 반환 (필수는 아니지만, 성공 여부를 전달 가능)
• 자동으로 loader()가 다시 실행되며 데이터가 갱신됨

언제 action()을 사용할까?

1. 서버에서 데이터를 추가, 수정, 삭제할 때
   • 예: 할 일 목록에 새로운 항목 추가 (POST), 항목 수정 (PUT), 삭제 (DELETE)
2. 폼 제출 후 자동으로 리스트를 갱신하고 싶을 때
   • action() 실행 후 React Router가 자동으로 loader()를 다시 실행
3. 페이지 새로고침 없이 서버 데이터를 갱신할 때
   • <Form navigate={false}> → SPA 경험 유지

📌 action()과 loader()의 관계

clientAction

clientAction()은 클라이언트에서 실행되는 action()이다.

✔ 캐시를 무효화하거나 UI 상태를 변경할 때 유용 ✔ 필요하면 serverAction()을 호출해 서버에서도 데이터를 변경 가능 ✔ 서버 요청 없이 데이터를 변경할 때 효과적

export async function clientAction({ serverAction }) {
  fakeInvalidateClientSideCache(); // 캐시 초기화
  const data = await serverAction(); // 서버 데이터 다시 요청
  return data;
}

• 클라이언트 캐시를 무효화 (fakeInvalidateClientSideCache())
• 필요하면 serverAction()을 호출해 서버에서도 데이터 변경 가능
• 데이터를 반환하면 클라이언트에서 활용할 수 있음

참고 https://api.reactrouter.com/v7/types/react_router.ClientActionFunctionArgs

ErrorBoundary

ErrorBoundary()를 정의하면 해당 라우트에서 발생한 오류를 잡아 사용자에게 표시한다.

✔ HTTP 응답 에러(404, 500)와 일반적인 JavaScript 에러를 구분하여 처리 가능 ✔ 예상하지 못한 에러도 대비하여 안전한 UI 제공

import {
  isRouteErrorResponse,
  useRouteError,
} from "react-router";

export function ErrorBoundary() {
  const error = useRouteError();

• useRouteError() → 현재 라우트에서 발생한 에러 정보를 가져오는 React Router 훅
• error 변수에 라우트에서 발생한 에러 정보가 담김

1️⃣ HTTP 응답 에러 처리

  if (isRouteErrorResponse(error)) {
    return (
      <div>
        <h1>
          {error.status} {error.statusText}
        </h1>
        <p>{error.data}</p>
      </div>
    );
  }

• isRouteErrorResponse(error) → 에러가 HTTP 응답 관련 에러인지 확인 (404, 500 등)
• error.status와 error.statusText를 이용해 HTTP 상태 코드와 메시지 표시
• error.data를 표시해 서버에서 전달된 추가 에러 메시지를 출력

예제:

throw new Response("Not Found", { status: 404 });

이런 응답이 발생하면, 에러 화면은 아래와 같이 표시됨:

404 Not Found

2️⃣ 일반적인 JavaScript 에러 처리

  else if (error instanceof Error) {
    return (
      <div>
        <h1>Error</h1>
        <p>{error.message}</p>
        <p>The stack trace is:</p>
        <pre>{error.stack}</pre>
      </div>
    );
  }

• 에러가 일반적인 JavaScript Error 객체인지 확인
• error.message → 에러 메시지 표시
• error.stack → 에러가 발생한 위치(콜스택) 표시

예제:

throw new Error("Something went wrong!");

이런 에러가 발생하면 화면에는 아래와 같이 표시됨:

Error
Something went wrong!
The stack trace is:
...

3️⃣ 예상하지 못한 에러 처리

  else {
    return <h1>Unknown Error</h1>;
  }

• 위 두 가지 조건을 만족하지 않는 경우 (null, undefined, 기타 예외적인 값)
• "Unknown Error" 메시지를 표시

HydrateFallback

HydrateFallback은 초기 페이지 로드 시, clientLoader가 데이터를 불러오는 동안 임시로 보여줄 UI를 정의한다.

✔ 초기 로딩 지연 → clientLoader가 데이터를 가져오는 동안 로딩 화면을 표시 ✔ 클라이언트 전용 → 서버 렌더링 없이 클라이언트에서만 작동 ✔ 로딩 UX 개선 → 사용자에게 빈 화면 대신 로딩 메시지나 스피너를 보여줄 수 있음

1️⃣ clientLoader – 클라이언트 데이터 로딩

export async function clientLoader() {
  const data = await fakeLoadLocalGameData();
  return data;
}

• clientLoader가 데이터를 비동기적으로 가져옴
• 이 과정에서 컴포넌트가 바로 렌더링되지 않음 → 데이터 로딩이 끝난 후에야 렌더링됨

2️⃣ HydrateFallback – 로딩 중 임시 화면

export function HydrateFallback() {
  return <p>Loading Game...</p>;
}

• clientLoader가 데이터 로딩 중일 때 이 컴포넌트가 대신 렌더링됨
• 사용자에게 "Loading Game..." 메시지를 보여줌
• 로딩 스피너, 애니메이션 등으로 대체 가능

3️⃣ Component – 데이터 로딩 후 렌더링

export default function Component({ loaderData }) {
  return <Game data={loaderData} />;
}

• clientLoader가 데이터를 모두 가져오면, Component가 렌더링됨
• loaderData를 받아서 실제 게임 컴포넌트에 데이터를 넘김

headers

headers 함수는 서버 렌더링(SSR) 시 클라이언트에 전달할 HTTP 헤더를 설정한다.

✔ SEO 최적화, 보안 설정, 캐싱 등 다양한 목적에 사용 ✔ 클라이언트가 아닌 서버에서만 호출됨 ✔ 특정 라우트에 커스텀 헤더를 추가 가능

export function headers() {
  return {
    "X-Stretchy-Pants": "its for fun",
    "Cache-Control": "max-age=300, s-maxage=3600",
  };
}

1️⃣ X-Stretchy-Pants: 커스텀 헤더

• "X-"로 시작하는 커스텀 헤더
• 브라우저에 직접적인 영향은 없지만, 디버깅이나 로그 추적에 사용 가능

2️⃣ Cache-Control: 캐싱 전략

• max-age=300 → 클라이언트 브라우저가 5분(300초) 동안 캐시
• s-maxage=3600 → CDN 또는 프록시 서버가 1시간(3600초) 동안 캐시
• 캐싱을 통해 서버 부하 감소 및 페이지 로딩 속도 향상

handle

handle객체는 라우트에 커스텀 데이터를 추가할 때 사용한다. 이를 통해 라우트에 부가 정보를 넣어 다양한 기능을 구현할 수 있다.

✔ 메타데이터, 브레드크럼, 권한 정보 등 저장 가능 ✔ useMatches 훅을 통해 모든 라우트의 handle 정보 접근 가능 ✔ 단순히 데이터 전달용으로 사용됨 (렌더링에는 직접 관여하지 않음)

export const handle = {
  its: "all yours",
};

• 이 라우트를 사용할 때 useMatches 훅으로 접근 가능
• 결과: { its: "all yours" }

links

links 함수는 HTML <head>에 <link> 태그를 추가하기 위한 용도로 사용된다. 이 함수가 반환한 링크들은 전역적으로 적용되며, 주로 아이콘, 스타일시트, 폰트, 프리로드 등을 설정할 때 사용한다.

✔ 파비콘(favicon), 외부 CSS, 자원 프리로드 설정 가능 ✔ 모든 라우트의 링크들이 자동으로 통합되어 <head>에 적용 ✔ <Links /> 컴포넌트를 통해 <head>에 삽입

export function links() {
  return [
    {
      rel: "icon", // 브라우저 탭의 아이콘 설정
      href: "/favicon.png",
      type: "image/png",
    },
    {
      rel: "stylesheet", // 외부 CSS 파일 불러오기
      href: "https://example.com/some/styles.css",
    },
    {
      rel: "preload", // 이미지 미리 불러오기
      href: "/images/banner.jpg",
      as: "image",
    },
  ];
}

결과적으로 생성되는 <head> 태그

<head>
  <link rel="icon" href="/favicon.png" type="image/png" />
  <link rel="stylesheet" href="https://example.com/some/styles.css" />
  <link rel="preload" href="/images/banner.jpg" as="image" />
</head>

<Links /> 컴포넌트로 적용

import { Links } from "react-router";

export default function Root() {
  return (
    <html>
      <head>
        <Links /> {/* 모든 라우트의 links를 적용 */}
      </head>
      <body>
        <h1>My App</h1>
      </body>
    </html>
  );
}

활용 예시

meta

meta 함수는 HTML <head>에 메타 태그를 추가하기 위한 용도로 사용된다. 주로 SEO 최적화, SNS 공유 설정(Open Graph), 문서 정보 제공 등에 활용된다.

✔ <title> 태그 설정 ✔ meta 태그로 SEO 및 SNS 미리보기 설정 ✔ 모든 라우트의 메타 태그가 통합되어 <head>에 삽입됨

export function meta() {
  return [
    { title: "Very cool app" }, // <title> 태그 설정
    {
      property: "og:title",     // Open Graph: SNS 공유 시 제목
      content: "Very cool app",
    },
    {
      name: "description",      // 검색 엔진 및 미리보기에 표시될 설명
      content: "This app is the best",
    },
  ];
}

결과적으로 생성되는 <head> 태그

<head>
  <title>Very cool app</title>
  <meta property="og:title" content="Very cool app" />
  <meta name="description" content="This app is the best" />
</head>

<Meta /> 컴포넌트로 적용

import { Meta } from "react-router";

export default function Root() {
  return (
    <html>
      <head>
        <Meta /> {/* 모든 라우트의 meta를 적용 */}
      </head>
      <body>
        <h1>My App</h1>
      </body>
    </html>
  );
}

활용 예시

참고 https://api.reactrouter.com/v7/interfaces/react_router.MetaArgs

shouldRevalidate

shouldRevalidate 함수는 라우트의 데이터가 다시 로드되어야 하는지를 결정한다. 기본적으로, 모든 라우트는 액션 후에 자동으로 데이터가 재검증(revalidate) 된다. 하지만, 데이터에 영향이 없는 경우 재검증을 건너뛸 수 있다.

✔ 성능 최적화: 필요할 때만 데이터 다시 가져오기 ✔ 불필요한 API 호출 방지로 서버 비용 절감 ✔ 복잡한 폼이나 대용량 데이터 페이지에 유용

import type { ShouldRevalidateFunctionArgs } from "react-router";

export function shouldRevalidate(arg: ShouldRevalidateFunctionArgs) {
  return true; // true면 데이터를 다시 가져오고, false면 재검증 X
}

특정 액션에 대해 재검증 방지

export function shouldRevalidate({ formAction }) {
  // "/profile/update"에서 발생한 액션이면 재검증 방지
  return formAction !== "/profile/update";
}

ShouldRevalidateFunctionArgs 주요 값

💡 언제 사용하면 좋을까?

React Router는 다양한 라우팅 패턴을 지원하며, 주요 메서드는 다음과 같다:

• route() 특정 경로에 대한 컴포넌트 연결
• index() 부모 경로의 기본 자식 라우트
• layout() 공통 레이아웃을 적용하는 라우트
• prefix() 여러 경로에 공통 접두사(prefix) 추가

Configuring Routes

React Router v7에서는 app/routes.ts 파일에서 경로(route)를 설정한다. route()에는 두 파라미터가 있다. URL과 일치하는 URL 패턴과 동작을 정의하는 컴포넌트에 대한 파일 경로다.

// app/routes.ts
import {
  type RouteConfig,
  route,
} from "@react-router/dev/routes";

export default [
  route("some/path", "./some/file.tsx"),
  //    패턴 ^              ^ 파일경로
] satisfies RouteConfig;

// app/routes.ts
import {
  type RouteConfig,
  route,
  index,
  layout,
  prefix,
} from "@react-router/dev/routes";

export default [
  // 기본 경로 ('/')
  index("./home.tsx"),

  // '/about' 경로
  route("about", "./about.tsx"),

  // '/auth' 관련 경로 (레이아웃 적용)
  layout("./auth/layout.tsx", [
    route("login", "./auth/login.tsx"),       // '/auth/login'
    route("register", "./auth/register.tsx"), // '/auth/register'
  ]),

  // '/concerts'로 시작하는 경로 (접두사 사용)
  ...prefix("concerts", [
    index("./concerts/home.tsx"),          // '/concerts'
    route(":city", "./concerts/city.tsx"), // '/concerts/:city'
    route("trending", "./concerts/trending.tsx"), // '/concerts/trending'
  ]),
] satisfies RouteConfig;

📌 파일 기반 라우팅 (fs-routes) @react-router/fs-routes 패키지를 사용하면 폴더 구조에 따라 자동으로 라우트를 구성할 수 있다.

// app/routes.ts
import { type RouteConfig, route } from "@react-router/dev/routes";
import { flatRoutes } from "@react-router/fs-routes";

export default [
  route("/", "./home.tsx"), // 수동으로 정의한 기본 경로
  ...(await flatRoutes()), // 파일 시스템 기반 라우트 자동 생성
] satisfies RouteConfig;

• flatRoutes() → 파일 시스템을 스캔해 폴더 구조대로 라우트를 생성
• 파일 시스템 라우팅과 수동 라우트 설정을 혼합할 수 있다.

Route Modules

routes.ts에서 참조되는 파일은 각 경로의 동작을 정의한다.

// app/routes.ts
route("teams/:teamId", "./team.tsx"),
//           route module ^^^^^^^^

// app/team.tsx
// provides type safety/inference
import type { Route } from "./+types/team";

// provides `loaderData` to the component
export async function loader({ params }: Route.LoaderArgs) {
  let team = await fetchTeam(params.teamId);
  return { name: team.name };
}

// renders after the loader is done
export default function Component({
  loaderData,
}: Route.ComponentProps) {
  return <h1>{loaderData.name}</h1>;
}

액션(actions), 헤더(headers), 에러 바운더리(error boundaries) 등 자세한 부분은 다음 포스트에서 다룬다.

Nested Routes

중첩 라우트(Nested Routes)는 부모 라우트 내부에 자식 라우트를 포함하는 방식이다. 이를 통해 관련된 여러 페이지를 논리적으로 그룹화하고, 공통 UI를 유지하면서 개별 페이지를 동적으로 교체할 수 있다.

// app/routes.ts
import {
  type RouteConfig,
  route,
  index,
} from "@react-router/dev/routes";

export default [
  // 부모 라우트
  route("dashboard", "./dashboard.tsx", [
    // 자식 라우트
    index("./home.tsx"), // "/dashboard"
    route("settings", "./settings.tsx"), // "/dashboard/settings"
  ]),
] satisfies RouteConfig;

• dashboard.tsx가 부모 라우트이며, 그 내부에 home.tsx와 settings.tsx가 중첩됨
• /dashboard를 방문하면 home.tsx가 렌더링됨
• /dashboard/settings를 방문하면 settings.tsx가 렌더링됨

// app/dashboard.tsx
import { Outlet } from "react-router";

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      {/* 자식 라우트(home.tsx 또는 settings.tsx)가 렌더링될 위치 */}
      <Outlet />
    </div>
  );
}

• <Outlet />은 dashboard.tsx 내부에서 자식 라우트가 렌더링될 자리를 지정함
• /dashboard일 때는 home.tsx가 <Outlet />에 렌더링됨
• /dashboard/settings일 때는 settings.tsx가 <Outlet />에 렌더링됨

Root Route

routes.ts의 모든 경로는 app/root.tsx 모듈 내부에 중첩되어 있다.

Layout Routes

layout()은 새로운 URL 세그먼트를 추가하지 않고, 자식 라우트를 감싸는 부모 역할을 한다.

// app/routes.ts
import {
  type RouteConfig,
  route,
  layout,
  index,
  prefix,
} from "@react-router/dev/routes";

export default [
  // 마케팅 페이지의 공통 레이아웃을 정의
  layout("./marketing/layout.tsx", [
    index("./marketing/home.tsx"), // `/`
    route("contact", "./marketing/contact.tsx"), // `/contact`
  ]),

  // "projects"라는 경로를 가지는 하위 그룹을 생성
  ...prefix("projects", [
    index("./projects/home.tsx"), // `/projects`
    layout("./projects/project-layout.tsx", [
      route(":pid", "./projects/project.tsx"), // `/projects/:pid`
      route(":pid/edit", "./projects/edit-project.tsx"), // `/projects/:pid/edit`
    ]),
  ]),
] satisfies RouteConfig;

위의 설정을 기준으로 경로와 렌더링 결과를 정리하면:

✔ layout()은 새로운 URL 세그먼트를 추가하지 않지만, 내부적으로 자식 라우트를 감싸는 부모 역할을 한다. ✔ /projects/:pid 경로로 접근하면, project-layout.tsx가 먼저 렌더링되고, 그 안의 <Outlet />을 통해 project.tsx가 출력된다.

📌 layout()을 사용할 때 이 필요한 이유 layout()은 단독으로 화면을 렌더링하는 것이 아니라, 자식 라우트를 감싸는 부모 역할을 한다. 이를 위해 을 사용해야 한다.

// ./projects/project-layout.tsx
import { Outlet } from "react-router";

export default function ProjectLayout() {
  return (
    <div>
      <aside>Example sidebar</aside> {/* 모든 하위 페이지에서 공통으로 표시 */}
      <main>
        <Outlet /> {/* 여기에 자식 라우트가 렌더링됨 */}
      </main>
    </div>
  );
}

• ProjectLayout은 모든 projects 관련 페이지의 공통 레이아웃을 제공
• <Outlet />을 사용하여, projects/:pid, projects/:pid/edit 등의 자식 라우트가 동적으로 렌더링됨
• projects/:pid로 접근하면, <Outlet />에 project.tsx가 렌더링됨
• projects/:pid/edit로 접근하면, <Outlet />에 edit-project.tsx가 렌더링됨

📌 layout() vs route() 차이점**

✔ layout()을 사용하면 여러 페이지에서 공통 레이아웃을 쉽게 유지할 수 있음 ✔ route()는 특정 경로에 해당하는 개별 페이지를 정의하는 용도

Index Routes

index()는 부모 URL이 호출되었을 때 기본으로 렌더링될 컴포넌트를 지정한다. 자식 경로를 가질 수 없다. (즉, index() 내부에는 또 다른 route()를 추가할 수 없음)

// app/routes.ts
import {
  type RouteConfig,
  route,
  index,
} from "@react-router/dev/routes";

export default [
  // renders into the root.tsx Outlet at /
  index("./home.tsx"),
  route("dashboard", "./dashboard.tsx", [
    // renders into the dashboard.tsx Outlet at /dashboard
    index("./dashboard-home.tsx"),
    route("settings", "./dashboard-settings.tsx"),
  ]),
] satisfies RouteConfig;

Route Prefixes

prefix를 사용하면 공통 경로(prefix)를 여러 개의 하위 경로에 적용할 수 있다. 즉, 부모 레이아웃 없이 특정 그룹의 경로에 동일한 접두사를 추가하는 기능이다.

다음 경로에 대하여 ✅ /projects ✅ /projects/:pid ✅ /projects/:pid/edit

부모 레이아웃 사용

layout("./projects/layout.tsx", [
  index("./projects/home.tsx"),
  route(":pid", "./projects/project.tsx"),
  route(":pid/edit", "./projects/edit-project.tsx"),
]);

• 모든 하위 경로가 layout.tsx를 거쳐야 한다. layout.tsx가 필요하지 않다면 불필요한 중첩을 만들게 된다.

prefix를 사용한 개선된 방식

export default [
  ...prefix("projects", [
    index("./projects/home.tsx"),
    layout("./projects/project-layout.tsx", [
      route(":pid", "./projects/project.tsx"),
      route(":pid/edit", "./projects/edit-project.tsx"),
    ]),
  ]),
];

• projects/라는 공통 접두사가 자동 적용된다.
• /projects/는 레이아웃 없이 직접 렌더링된다.
• /projects/:pid, /projects/:pid/edit는 레이아웃을 적용한다.

Dynamic Segments

동적 세그먼트(Dynamic Segments)는 경로의 특정 부분을 변수처럼 사용하는 기능이다. 경로에서 :paramName 형태로 작성하면 URL에서 해당 값을 추출하여 params 객체로 전달할 수 있다.

// app/routes.ts
route("teams/:teamId", "./team.tsx"),

• ✅ /teams/123
• ✅ /teams/abc

// app/team.tsx
import type { Route } from "./+types/team";

export async function loader({ params }: Route.LoaderArgs) {
  //                           ^? { teamId: string }
}

export default function Component({
  params,
}: Route.ComponentProps) {
  params.teamId;
  //        ^ string
}

하나의 경로에서 여러 개의 동적 세그먼트를 사용할 수도 있다.

// app/routes.ts
route("c/:categoryId/p/:productId", "./product.tsx"),

• ✅ /c/electronics/p/5678
• ✅ /c/books/p/1234

  // app/product.tsx
  import type { Route } from "./+types/product";
  

async function loader({ params }: LoaderArgs) { // ^? { categoryId: string; productId: string } }

❗ 주의할 점
각 동적 세그먼트는 고유해야 한다.
동일한 이름의 세그먼트를 사용하면 나중에 정의된 값이 기존 값을 덮어쓴다.
```tsx
route(":id/:id", "./error.tsx"); // 잘못된 예제

Optional Segments

세그먼트 끝에 ?를 추가하여 경로 세그먼트를 선택 사항으로 만들 수 있다.

경로 매개변수(:param 형태)를 선택적으로 허용할 수 있다.

// app/routes.ts
route(":lang?/categories", "./categories.tsx"),

• ✅ /categories
• ✅ /en/categories
• ✅ /ko/categories

동적인 매개변수뿐만 아니라 일반적인 경로 세그먼트도 선택적으로 만들 수 있다.

// app/routes.ts
route("users/:userId/edit?", "./user.tsx");

• ✅ /users/123
• ✅ /users/123/edit

Splats

스플랫(Splats)은 catchall 또는 star segments라고도 하며, /* 패턴을 사용하여 경로의 나머지 부분을 모두 포함하는 라우팅 방식이다. 즉, 특정 경로 이후의 모든 하위 경로를 하나의 변수로 받아올 수 있다.

// app/routes.ts
route("files/*", "./files.tsx"),

• /files/로 시작하는 모든 URL을 files.tsx에서 처리한다.

// app/files.tsx
export async function loader({ params }: Route.LoaderArgs) {
  console.log(params["*"]); // "docs/readme.md" (예시)
}

• params["*"]을 사용하면 files/ 이후의 모든 문자열을 가져올 수 있다.

Splats를 변수명으로 할당하기

const { "*": splat } = params;
console.log(splat); // "docs/readme.md"

• 구조 분해 할당을 이용해 params["*"]를 splat이라는 이름으로 바꿀 수 있다.

Component Routes

Component Routes는 URL에 따라 특정 컴포넌트를 렌더링하는 기능을 제공한다.

import { Routes, Route } from "react-router";

function Wizard() {
  return (
    <div>
      <h1>Some Wizard with Steps</h1>
      <Routes>
        <Route index element={<StepOne />} />
        <Route path="step-2" element={<StepTwo />} />
        <Route path="step-3" element={<StepThree />} />
      </Routes>
    </div>
  );
}

🔹 Wizard 컴포넌트 내부에서 <Routes>를 사용 → 이 컴포넌트는 자체적으로 라우팅을 관리한다. 🔹 index → 기본적으로 렌더링될 StepOne 컴포넌트 🔹 step-2, step-3 → URL이 /step-2, /step-3일 때 각각 StepTwo, StepThree를 렌더링

다만, Component Routes 방식은 기존의 route module 방식과 달리 몇 가지 제약이 있다.

❌지원되지 않는 기능:

• 데이터 로딩 (Loaders) → URL 이동 시 서버에서 데이터를 미리 가져오는 기능이 없음
• 액션 (Actions) → form을 통한 데이터 변경 및 자동 UI 갱신 기능이 없음
• 코드 스플리팅 (Code Splitting) → 필요한 페이지의 코드만 로드하는 기능이 없음
• SEO 설정 → 페이지별 메타태그 관리 기능이 없음

✅ 주로 사용하는 경우:

• 다단계 마법사(Wizard) UI처럼 특정 컴포넌트 내에서 단계별 이동이 필요한 경우
• 앱 내부에서 별도의 작은 라우팅을 만들고 싶을 때
• 데이터 로딩과 관련 없는 단순한 UI 라우팅이 필요할 때

지금까지의 React Router는 단순한 라우팅 라이브러리였지만, 이제는 Next.js처럼 자체적인 데이터 관리와 렌더링 방식까지 제공하는 프레임워크로 발전하고 있다. Remix 팀은 Remix와 React Router의 기능이 매우 유사해졌다는 점을 인식하고, 두 프로젝트를 통합하기로 결정했다. React Router v7은 Remix의 모든 주요 기능을 포함하게 되었다.

React Router를 라이브러리로 사용하는 경우

기존 React Router v6처럼 클라이언트 측 라우팅(SPA)을 위한 라이브러리로 사용한다.

특징

• URL을 컴포넌트와 매칭하는 역할만 수행
• URL 데이터 제공 및 페이지 간 이동 지원
• 싱글 페이지 앱(SPA)에 적합: 자체적인 프론트엔드 인프라를 가진 앱에서 쉽게 적용 가능
• 오프라인 및 동기(sync) 아키텍처에 유리: 서버 상태 변화 없이 즉각적인 로컬 반응 가능
• 서버 렌더링(SSR), SEO, 코드 스플리팅 같은 기능이 없음
• v6에서 업그레이드할 때 큰 변경 없이 사용 가능

React Router를 프레임워크로 사용하는 경우

React Router를 완전한 프레임워크처럼 사용할 수도 있다.

특징

• Vite 번들러 및 개발 서버와 통합
• 핫 모듈 교체(HMR) 지원
• 파일 기반 또는 설정 기반 라우팅
• 타입 안전한 데이터 로딩(loaders) 및 액션(actions) 지원
• 자동 페이지 데이터 리로드
• 서버 사이드 렌더링(SSR), SPA, 정적 렌더링 지원
• SEO, 에러 경계, 자산(asset) 로딩 관리 가능

결론

React Router를 단순히 라우팅을 위한 라이브러리로 사용할 수도 있고, 프레임워크처럼 완전한 데이터 관리 및 SSR 기능까지 포함한 풀스택 환경으로 사용할 수도 있다. 만약 기존 React Router v6처럼 간단한 클라이언트 측 라우팅을 원한다면 라이브러리 모드가 적합하다. 더 강력한 기능(SSR, 데이터 로딩, 타입 안전성 등)을 원한다면 프레임워크 모드를 활용할 수 있다.

향후 React Router: The Framework의 공식문서를 정리하고자 한다.

참고 https://velog.io/@hazae23/Merging-Remix-and-React-Router

vscode를 사용할 때, vite + React + typescript의 초기 tsconfig.app.json에는 두 가지가 에러가 표시된다.

1. Option 'tsBuildInfoFile' cannot be specified without specifying option 'incremental' or option 'composite'.

2. Unknown compiler option 'noUncheckedSideEffectImports'.

해결

1. 첫 번째의 경우 "incremental": true, 옵션을 추가하면 해결된다.

   "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",

incremental 옵션: https://www.typescriptlang.org/tsconfig/#incremental

2. 두 번째의 경우 vscode내장된 TypeScript의 버전이 5.6.3 미만이기 때문.

• 아무 타입스크립트 파일을 열어놓고Ctrl+Shift+P를 눌러서 TypeScript: Select TypeScript Version에 들어가서 버전을 5.6.3 이상을 선택하면 해결됨

• 만약 선택지에 최신 버전의 타입스크립트가 없는 경우, 선택지에 전역 설치된 TypeScript가 나오게 하는 방법:

  1. .vscode 폴더를 프로젝트 최상단에 만들고
  2. 하위에 settings.json 파일 생성 (아래 예시는 윈도우의 경우)

{
  "typescript.tsdk": "C:\\Users\\<유저명>\\AppData\\Roaming\\npm\\node_modules\\typescript\\lib"
}

Immer?

immer는 JavaScript에서 불변성(immutability)을 관리하기 쉽게 해주는 라이브러리다. 특히, 상태 관리 라이브러리에서 불변성을 유지하는 것이 중요한데, immer는 이를 간단하고 효율적으로 처리할 수 있게 도와준다.

불변성(immutability)?

불변성은 데이터를 직접 변경하지 않고, 변경하려는 데이터를 복사하여 새로 만든 뒤 수정하는 방식을 의미한다.

Redux에서는 상태(state)가 불변(immutable)해야 한다. 왜냐하면 Redux는 상태 변경을 감지하기 위해 참조(reference) 비교를 사용하기 때문이다.

만약에 상태를 직접 수정할 경우

1. state 객체가 직접 수정되면 기존 상태와 새로운 상태가 같은 참조를 가짐.
2. Redux는 상태가 변경되었다고 인지하지 못함.
3. React 컴포넌트가 리렌더링되지 않음.

즉, 상태를 직접 수정하는 대신 기존 상태를 복사하고 변경된 새 상태를 반환해야 한다는 것이다.

JavaScript에서는 객체와 배열이 참조 타입(reference type)이기 때문에, 불변성을 유지하려면 보통 객체나 배열을 복사한 뒤 수정해야 한다. 변경된 경로만 새로운 객체가 되고, 변경되지 않은 부분은 기존 객체의 참조를 유지해서 불필요한 메모리 사용을 줄이려고 하기 때문이다.

const state = { count: 0 };

// 불변성을 유지하기 위해 새로운 객체를 생성
const newState = { ...state, count: state.count + 1 };
console.log(newState); // { count: 1 }
console.log(state);    // { count: 0 } (원본은 변경되지 않음)

하지만 문제는, 복잡한 중첩 구조의 객체를 다룰 때 불변성을 유지하는 코드가 번잡하고 실수가 많아질 수 있다.😫

const state = {
    user: {
        profile: {
            name: "John",
            age: 30
        }
    }
};

const newState = {
    ...state,
    user: {
        ...state.user,
        profile: {
            ...state.user.profile,
            age: 31
        }
    }
};

immer의 장점

깊은 중첩 구조도 쉽게 업데이트 가능해진다.

const state = {
    user: {
        profile: {
            name: "John",
            age: 30
        }
    }
};

const newState = produce(state, draft => {
    draft.user.profile.age = 31; // 간단하게 작성
});

console.log(newState.user.profile.age); // 31
console.log(state.user.profile.age);    // 30

상태를 "수정하는 것처럼" 작성하면 되므로 가독성이 높아진다.👍

결론

• Redux 상태 관리에서 리듀서를 작성할 때.
• React 컴포넌트에서 복잡한 상태를 업데이트할 때.
• 중첩된 데이터 구조를 간단히 수정하고 싶을 때.

immer는 복잡한 불변성 코드를 간단하고 안전하게 작성할 수 있게 해주는 도구로, 상태 관리 작업을 훨씬 쉽게 만들어준다

파이썬에서 상수 선언 관례

파이썬에서는 상수를 선언할 수 있는 특별한 문법이 없지만, 변수 이름을 모두 대문자로 작성하여 상수처럼 사용하는 것이 일반적인 관례이다. 이는 개발자 간의 암묵적 규칙으로, 상수로 선언된 변수는 변경하지 말라는 의미를 전달한다.

예시:

PI = 3.14159
MAX_CONNECTIONS = 100
API_KEY = "your-api-key-here"

• PI, MAX_CONNECTIONS, API_KEY는 상수로 사용된다고 간주된다.
• 하지만 문법적으로 값을 변경하는 것을 막을 수는 없다.

  PI = 3.14  # 변경 가능 (경고나 오류 없음)

상수를 엄격히 보호하는 방법

상수를 변경하지 못하도록 강제하려면, 다음과 같은 방법을 사용할 수 있다:

1. 클래스를 활용한 상수 선언

class Constants:
    PI = 3.14159
    MAX_CONNECTIONS = 100

# 상수처럼 사용
print(Constants.PI)

이 경우, Constants.PI는 변경할 수는 있지만, 관례적으로 상수처럼 사용된다.

2. frozen 데이터 구조 사용 (e.g., frozen dataclass)

Python 3.8+에서는 @dataclass(frozen=True)를 사용하여 상수 같은 동작을 구현할 수 있다:

from dataclasses import dataclass

@dataclass(frozen=True)
class Constants:
    PI: float = 3.14159
    MAX_CONNECTIONS: int = 100

# 상수처럼 사용
constants = Constants()
print(constants.PI)

# constants.PI = 3.14  # 오류 발생 (상수 값을 변경하려고 시도)

3. typing.Final 사용

Python 3.8+에서는 Final을 통해 상수임을 표현할 수 있다:

from typing import Final

PI: Final = 3.14159
MAX_CONNECTIONS: Final = 100

# PI = 3.14  # MyPy를 사용하면 경고 발생 (런타임에서는 오류 없음)

결론

파이썬에서 상수를 선언하는 공식 키워드는 없지만, 대문자 변수명을 사용하거나 Final 또는 @dataclass(frozen=True) 같은 기능을 활용해 상수처럼 사용할 수 있다.

문제 상황: 인덱스 누적

alter: true 옵션을 사용한 상태에서 여러 번 sequelize.sync()를 실행했더니, 데이터베이스 테이블에 설정된 인덱스가 점점 누적되었다. 결국 특정 테이블의 인덱스 개수가 64개를 초과하며 아래와 같은 오류가 발생했다:

Error: Too many indexes on table 'your_table_name'; the limit is 64

해당 문제는 테이블에 이미 존재하는 인덱스와 새로운 인덱스가 계속 추가되는 방식으로 동작하기 때문이다. sequelize.sync()가 테이블 스키마를 업데이트하면서 인덱스를 중복 생성하는 구조적 한계를 드러낸 것이다.

원인 분석

sequelize.sync({ alter: true })는 다음과 같이 작동한다.

1. 데이터베이스의 기존 테이블 구조와 모델 정의를 비교
2. 차이가 발견되면, 테이블 구조를 업데이트
3. 인덱스와 같은 제약 조건도 업데이트 대상에 포함
4. 기존 인덱스를 삭제하지 않고 새롭게 추가하기 때문에 동일한 필드에 대해 중복된 인덱스가 생성될 수 있다.

이 과정을 반복 실행하면 인덱스가 계속 누적되면서 데이터베이스의 인덱스 제한에 도달하게 된다.

해결 방법

1. alter 대신 force 옵션 사용

   • force: true 옵션은 테이블을 완전히 삭제하고 다시 생성한다.

   • 기존 데이터도 모두 삭제되므로 초기 개발 환경이나 데이터가 없어도 되는 상황에서만 사용 가능하다.

     await sequelize.sync({ force: true });

     이 방법은 반복 실행 시에도 인덱스가 누적되지 않으며, 테이블 정의와 인덱스가 항상 모델과 일치하도록 보장한다.

2. 인덱스 관리 로직 추가

   • sequelize.sync()를 사용하지 않고, 데이터베이스 마이그레이션 도구(예: Sequelize CLI)를 활용해 명시적으로 인덱스를 관리한다.

   • 기존 인덱스를 삭제하거나 필요한 경우에만 추가하도록 설계한다.

     // 예: 마이그레이션 파일에서 인덱스 추가
     await queryInterface.addIndex('your_table', ['your_column'], {
     name: 'your_index_name',
     unique: true,
     });

결론

sequelize.sync({ alter: true })는 빠르고 간편한 옵션이지만, 반복 실행 시 예상치 못한 부작용을 초래할 수 있다. 특히 인덱스 누적 문제는 예기치 못한 영향을 미칠 수 있으므로 주의가 필요하다.

개발 환경에서는 force: true 옵션을 사용하거나, 프로덕션 환경에서는 명시적으로 마이그레이션 도구를 활용해 데이터베이스를 관리하는 것이 좋겠다.

1. 후위 연산자 (result++)

• 값을 먼저 반환한 후, 증가한다.
• 즉, result++는 현재 값을 반환하고 나서 result를 1 증가시킨다.

2. 전위 연산자 (++result)

• 값을 먼저 증가한 후, 반환한다.
• 즉, ++result는 result를 먼저 1 증가시키고 나서 증가된 값을 반환한다.

코드 분석

(1) result = result++;

1. result++는 후위 연산자이므로, 현재 값이 반환된 후 result가 1 증가한다.
2. 하지만, result =로 인해 반환된 현재 값이 다시 result에 할당된다.
3. 따라서 증가한 값은 덮어쓰여져 무시된다.
   • 결과: result의 값이 변하지 않는다.

예시:

let result = 5;
result = result++;
console.log(result); // 출력: 5

(2) result = ++result;

1. ++result는 전위 연산자이므로, result를 먼저 1 증가시킨다.
2. 증가된 값이 result =에 의해 다시 result에 할당된다.
3. 결과적으로, result는 정상적으로 1 증가한다.

예시:

let result = 5;
result = ++result;
console.log(result); // 출력: 6

정리

왜 이런 차이가 발생하는가?

result = result++;는 값을 증가시키는 작업과 다시 할당하는 작업이 충돌하면서 발생한다.

• result++의 반환값(증가 전 값)이 result에 덮어써지므로 실제 증가한 값이 적용되지 않는다.
  ++result는 증가 후 값을 반환하므로 이런 충돌이 발생하지 않는다.

Tip: 코드의 명확성을 위해 result++와 ++result를 대입문과 함께 사용하는 것은 지양하는 것이 좋다.

AI

요즘 AI 페어 프로그래밍

AI 시대에 개발자로 살아남는 29가지 LLM 프롬프트 엔지니어링 with 깃허브 코파일럿, 클로드, 챗GPT

코딩테스트

코딩 테스트 합격자 되기 - 파이썬 편

자료구조, 알고리즘, 빈출 100 문제로 대비하는 코테 풀 패키지

코딩 테스트 합격자 되기 - 자바스크립트 편

프로그래머스 제공 100 문제로 완벽 대비

데이터베이스

기초부터 차근차근 데이터베이스 배우기

비전공자도 쉽게 이해하는 데이터베이스 입문

보안

입문자를 위한 컴퓨터 보안

개념부터 실습까지 한 권으로 따라잡기

포텐의 정보보안 카페

모든 사람을 위한 쉽고 톡톡 튀는 정보보안 콘서트

운영체제

Linux가 보이는 그림책

클라우드 시대의 새로운 OS에 대응

Node.js

Node.js 백엔드 개발자 되기

TypeScript + Node.js + Express + NestJS로 배우는 자바스크립트 백엔드 입문자를 위한 풀 패키지

추천하는 책이 더 있다면 알려주세요. 감사합니다.

5.1 Identifiers

식별자는 변수, 함수, 클래스, 인터페이스, 타입, 속성 등의 이름을 나타낸다.

식별자에서 허용되는 문자: 영문 대소문자 (A-Z, a-z): 일반적인 알파벳 문자. 숫자 (0-9): 알파벳과 함께 사용 가능. 단, 숫자로 시작할 수는 없다.

특정 상황에서만 밑줄 사용: 상수: ALL_CAPS 스타일의 상수 이름에 밑줄을 사용. 예: MAX_LENGTH, DEFAULT_VALUE. 구조화된 테스트 메서드 이름: 테스트 메서드에서 논리적 구조를 나타내기 위해 밑줄 사용 가능. 예: test_addition_of_two_numbers

달러 기호($): JavaScript 및 TypeScript에서 $는 변수 이름에 허용되지만, 일반적으로 특별한 목적으로만 사용한다. 예: AngularJS에서 $scope, jQuery에서 $ 같은 경우.

허용되지 않는 문자: 비ASCII 문자(예: 한글, 특수 기호 등)는 식별자로 사용하지 않는다. 예: 이름, #value, @count 등은 허용되지 않음.

5.1.1 Naming style

• 프로퍼티나 메서드의 맨 앞이나 맨 뒤에 밑줄('_')사용하지 않기
• 선택적 매개변수 앞에 opt_ 접두사를 사용하지 않기
• 인터페이스를 특별히 표시하지 않기
  • 'I'또는 'Interface' 같은 접두사/접미사는 불필요하며, 코드의 명확성과 가독성을 해친다. 인터페이스를 도입할 때는 이름을 통해 그 인터페이스가 왜 존재하는지, 어떤 역할을 수행하는지 설명해야 한다.
• Observable 변수 구분을 위한 $ 접미사의 사용 여부는 팀의 판단에 따름

Before

interface ITodoItem {
  title: string;
  completed: boolean;
}

interface TodoItemInterface {
  title: string;
  completed: boolean;
}

• I나 Interface와 같은 특별한 표시는 코드에 의미를 더하지 않는다.
• 이름만으로는 이 인터페이스가 어떤 용도인지 알기 어렵다.

After

interface TodoItemStorage {
  title: string;
  completed: boolean;
}

• 의미 있는 이름: TodoItemStorage는 저장소 형식을 표현하기 위한 인터페이스임을 명확히 나타낸다.
• 클래스(TodoItem)와 역할을 구분하면서도 관계가 명확하다.

5.1.2 Descriptive names

이름은 설명적이고 명확해야 한다. 모호하거나 익숙하지 않은 약어를 사용하지 말고, 단어 내에서 문자를 삭제하여 약어의 사용을 지양하자.

예외: 10줄 이하 범위에 속하는 변수, 즉 내보내는 API에 속하지 않는 인수는 짧은(예: 문자 하나) 변수 이름을 사용할 수 있다.

명확하고 서술적인 이름 사용: 변수나 식별자는 코드만 봐도 무슨 역할을 하는지 쉽게 이해할 수 있는 이름을 사용해야 한다. 외부인이나 새로운 독자가 봐도 직관적으로 의미를 알 수 있도록 이름을 정해야 한다.

모호하거나 생소한 약어 지양: 특정 프로젝트 내부에서만 통용되는 약어나 생소한 약어는 사용하지 말 것. 약어를 쓸 때는 일반적으로 알려진 약어만 사용한다. 예: URL, DNS, Id 등.

단어 내 글자를 생략하지 말 것: 단어의 중간 글자를 삭제하거나 축약하여 의미를 모호하게 만들지 말 것. 예: cstmrId → customerId로 작성.

짧은 범위에서는 간결한 이름 허용: 범위가 10줄 이하인 코드(로컬 변수, 함수 인자 등)에서는 단일 문자 또는 간결한 이름이 허용된다. 예: i, n, x 등.

헝가리안 표기법 지양: 변수 이름에 타입 정보를 접두사로 붙이는 헝가리안 표기법은 사용하지 않는다. 예: kSecondsPerDay (잘못된 헝가리안 표기법).

올바른 CamelCase: CamelCase 표기법을 사용할 때, 약어는 일관되게 소문자로 처리. 예: customerId (올바름), customerID (잘못된 CamelCase).

Before

const n = 5; // 의미 불명확
const nErr = 0; // 애매한 약어
const cstmrId = "12345"; // 축약으로 가독성 저하
const wgcConnections = []; // 팀 내부에만 알려진 약어
const customerID = "12345"; // 잘못된 CamelCase

After

const itemCount = 5; // 명확한 이름
const errorCount = 0; // 가독성이 좋은 이름
const customerId = "12345"; // 축약하지 않은 명확한 이름
const connections = []; // 약어를 제거하여 직관적으로 수정

5.1.3 Camel case

약어는 단어처럼 취급: 약어(Acronym)가 포함된 식별자 이름은 단어처럼 혼합 대소문자로 작성해야 한다. BAD: loadHTTPURL (약자를 전체 대문자로 작성하면 읽기 어렵다.) GOOD: loadHttpUrl (Http는 단어처럼 취급되어 첫 글자만 대문자로 표기)

플랫폼 이름이 특별한 경우는 예외: 특정 플랫폼이나 API 이름이 약자를 대문자로 사용하는 경우, 해당 관례를 따라야 한다. (XMLHttpRequest는 JavaScript의 API 이름에서 사용되는 표준.)

5.1.4 Dollar sign

$는 일반적인 경우 식별자 이름에 사용하지 않는 것이 좋다. 다만, 서드파티 프레임워크의 명명 규칙에 따라 사용하거나, Observable 값을 구분하기 위해 명확한 목적으로 사용할 수 있다. $를 사용할 경우, 프로젝트 내에서 일관성을 유지하는 것이 중요하다.

5.2 Rules by identifier type

식별자의 종류에 따라 일관된 네이밍 스타일을 사용해야 한다:

5.2.1 Type parameters

타입 매개변수는 제네릭(generic)을 사용할 때 선언되며, 함수, 클래스, 인터페이스, 타입 별칭 등에 유연한 타입 지정을 제공한다. 단일 대문자 또는 PascalCase를 사용할 수 있다.

function getKey<K, V>(key: K, value: V): K {
  return key;
}

class ApiResponse<DataType> {
  constructor(public data: DataType, public success: boolean) {}
}
const userResponse = new ApiResponse<{ id: number; name: string }>({
  id: 1,
  name: "Alice",
}, true);

5.2.2 Test names

테스트의 목적과 동작을 명확하게 나타내고, 테스트가 어떤 상황에서 어떤 결과를 예상하는지를 쉽게 이해할 수 있도록 _ (밑줄) 구분자를 사용하여 테스트 메서드를 설명적이고 읽기 쉽게 작성한다.

• 구조는 일반적으로 testX_whenY_doesZ() 형태를 따른다.
  • X: 테스트하려는 기능 또는 행동.
  • Y: 조건이나 상황.
  • Z: 예상되는 결과 또는 행동

function testLogin_whenCredentialsAreValid_doesRedirectToDashboard() {
  // 로그인 기능 테스트
}

• testLogin: 로그인 기능을 테스트.
• whenCredentialsAreValid: 사용자 자격 증명이 유효한 경우에 대해 테스트.
• doesRedirectToDashboard: 유효한 자격 증명으로 로그인할 때 대시보드로 리디렉션되는지 확인.

function testCalculateTotalPrice_whenItemIsAdded_doesIncreaseTotalPrice() {
  // 상품 추가 시 총 가격이 증가하는지 테스트
}

• testCalculateTotalPrice: 총 가격 계산 기능을 테스트.
• whenItemIsAdded: 아이템이 장바구니에 추가될 때.
• doesIncreaseTotalPrice: 아이템을 추가하면 총 가격이 증가하는지 확인.

구체적이고 설명적이어야 한다. 지나치게 짧거나 모호한 이름을 피하고, 테스트가 무엇을, 언제, 어떻게 확인하는지 명확하게 나타내야 한다. 너무 긴 이름은 가독성을 떨어뜨릴 수 있으므로 적당히 사용한다.

5.2.3 _ prefix/suffix

밑줄을 접두사나 접미사로 사용하지 않기: 식별자는 가능하면 의미가 명확해야 하며, 밑줄을 접두사나 접미사로 사용할 경우 어떤 의미가 있는지 또는 그 식별자가 특별한 목적을 가지고 있는지 명확히 전달되지 않는다.

단독으로 밑줄 사용 금지: 식별자가 의미를 가지지 않게 된다. 변수나 매개변수는 그 목적이 분명해야 한다. (파이썬에서는 매개변수가 사용되지 않음을 나타내는 경우 단독으로 밑줄을 사용함)

구조 분해 할당을 사용할 때, 배열이나 튜플에서 불필요한 요소를 무시하려면 단순히 중간에 ,를 삽입하여 해당 요소를 무시할 수 있다.

const [a, , b] = [1, 5, 10];  // a <- 1, b <- 10, 중간 요소 5는 무시

5.2.4 Imports

모듈 네임스페이스 (camelCase): 모듈을 네임스페이스로 가져올 때는 camelCase를 사용한다.

import * as fooBar from './foo_bar';  // 올바른 네임스페이스 네이밍

파일 이름 (snake_case): 파일 이름은 snake_case를 사용해야 하며, 이는 소문자와 밑줄(_)로 단어를 구분하는 스타일이다. 예를 들어 foo_bar.ts와 같이 작성된다.

(작성자 첨언) 그러나 모듈과 파일 이름은 camelCase나 kebab-case를 사용하기도 한다.

5.2.5 Constants

CONSTANT_CASE의 사용: 상수(Constant) 값에 CONSTANT_CASE를 사용하여 변하지 않아야 하는 값들을 명확하게 표시하고, 이를 통해 코드에서 해당 값을 수정하지 않도록 유도한다.

static readonly와 CONSTANT_CASE: 클래스에서 static readonly 속성도 상수로 다루어질 수 있다. readonly 키워드를 사용하면 해당 속성의 값을 변경할 수 없다는 점에서 불변성을 보장할 수 있다.

class Foo {
  private static readonly MY_SPECIAL_NUMBER = 5;

  bar() {
    return 2 * Foo.MY_SPECIAL_NUMBER;
  }
}

Global Scope와 CONSTANT_CASE: CONSTANT_CASE는 모듈 수준에서만 사용된다. 모듈의 최상위에서 정의된 상수값에 대해서만 CONSTANT_CASE를 사용하는 것이 권장된다. 지역 변수나 함수 내부에서 선언된 값은 camelCase를 사용해야 한다.

5.2.6 Aliases

로컬 별칭은 기존 심볼의 네이밍 규칙과 형식을 따르며, 그 목적에 맞는 적절한 선언 방법을 사용해야 한다.

기존 심볼의 네이밍 규칙을 따르기: 로컬에서 기존의 변수를 별칭으로 사용할 때, 별칭의 이름은 기존 심볼의 형식과 규칙을 따라야 한다. 예를 들어, 상수는 대문자 및 밑줄을 사용한 CONSTANT_CASE 형식을 따르고, 변수나 객체는 camelCase 형식을 사용해야 한다. 이렇게 하면 일관된 네이밍 규칙을 유지할 수 있다.

const { BrewStateEnum } = SomeType;  // 기존 심볼
const CAPACITY = 5;  // 기존 상수

• BrewStateEnum은 SomeType에서 추출된 객체의 속성이다. 이 값을 사용할 때 로컬에서 새로운 이름을 지정할 수 있다.
• CAPACITY는 값 5를 나타내는 상수이다. 이 값을 사용하려면 로컬에서 CAPACITY라는 이름을 그대로 사용해야 한다.

로컬 별칭 생성 방법: 로컬에서 별칭을 생성할 때, 변수와 클래스 필드에 대해 서로 다른 방식으로 선언해야 한다.

• 변수의 로컬 별칭은 const를 사용하여 선언해야 한다.
• 클래스 필드의 로컬 별칭은 readonly 속성을 사용하여 선언해야 한다.

  class Teapot {
  readonly BrewStateEnum = BrewStateEnum;  // 클래스 필드에서 BrewStateEnum을 읽기 전용으로 설정
  readonly CAPACITY = CAPACITY;  // 클래스 필드에서 CAPACITY를 읽기 전용으로 설정
  }

• BrewStateEnum과 CAPACITY는 각각 기존 값의 별칭이다. 클래스 필드에 대해 readonly를 사용하면 불변 값임을 명확하게 나타낼 수 있다.
• 이 별칭들은 클래스의 속성으로 사용되며, 외부에서 해당 값을 변경할 수 없도록 보장한다.

템플릿에서의 별칭: 프레임워크나 템플릿을 사용할 때, 별칭을 생성하여 템플릿에 노출하려는 경우에도 이 규칙이 적용된다. 별칭을 만들 때 접근 제어자(예: public, private)를 올바르게 지정하는 것이 중요하다. 프레임워크에서는 특정 데이터나 속성을 템플릿에서 직접 사용할 수 있도록 노출해야 할 때가 많은데, 이때도 접근 제어자를 적절히 설정하여 외부에서 접근할 수 있는지, 또는 내부에서만 접근할 수 있는지를 정의해야 한다.

class Teapot {
  public readonly BrewStateEnum = BrewStateEnum;  // 템플릿에서 사용될 수 있도록 공개
  private readonly CAPACITY = CAPACITY;  // 내부에서만 사용될 수 있도록 제한
}

• public 접근 제어자는 템플릿에서 이 값을 사용할 수 있도록 함.
• private 접근 제어자는 템플릿에서 사용되지 않도록 하여, 외부 접근을 제한.

참고자료

Google TypeScript Style Guide

GitHub - google/gts: ☂️ TypeScript style guide, formatter, and linter.

Typescript Google Code Style Part 1
Typescript Google Code Style Part 2 Typescript Google Code Style Part 3

ts.dev - TypeScript style guide

4.8 Primitive literals

4.8.1 String literals

Single Quotes 사용: (작성자 생각: JSON과 구별하기 위함인가?🤷) 일반적인 문자열 리터럴에서는 싱글 쿼트(')를 사용하는 것이 권장된다. 더블 쿼트(")도 사용할 수 있지만, 싱글 쿼트를 사용하면 일반적인 코드 스타일과 일관성을 유지할 수 있다. Before

const greeting = "Hello, world!";

After

const greeting = 'Hello, world!';

문자열에 싱글 쿼트가 포함되어 있는 경우, 이스케이프(\') 대신 템플릿 리터럴을 사용하는 것이 가독성을 높인다. Before

const message = 'It\'s a beautiful day!';

After

const message = `It's a beautiful day!`;

템플릿 문자열 사용: 템플릿 문자열은 백틱(`)으로 감싸고, 문자열 내에서 동적 데이터 삽입과 여러 줄 문자열 작성을 간단히 처리할 수 있다. 복잡한 문자열 연결 작업은 템플릿 문자열로 대체하는 것이 더 명확하고 가독성이 좋다.

Before

const message = 'Hello, ' + name + '! You have ' + count + ' messages.';

After

const message = `Hello, ${name}! You have ${count} messages.`;

줄 바꿈(Line Continuation) 금지: 문자열을 백슬래시(\)를 사용해 줄 바꿈하면 코드의 가독성이 떨어지고, 공백과 관련된 에러가 발생할 가능성이 있다. 예를 들어, 백슬래시 뒤에 공백이 있으면 에러를 초래한다. 줄 바꿈이 필요한 경우, 문자열 연결(+)을 사용하거나 템플릿 문자열을 활용한다.

Before

const longString = 'This is a very long string that spans multiple lines. \
It can cause tricky errors if there is any trailing whitespace.';

After

// 문자열 연결
const longString = 'This is a very long string ' +
    'that spans multiple lines without issues.';

// 템플릿 리터럴 사용
const longString = `This is a very long string 
that spans multiple lines cleanly.`;

// 템플릿 문자열로 여러 줄 처리
function arithmetic(a, b) {
  return `Here is a table of arithmetic operations:
${a} + ${b} = ${a + b}
${a} - ${b} = ${a - b}
${a} * ${b} = ${a * b}
${a} / ${b} = ${a / b}`;
}

4.8.2 Number literals

숫자 리터럴 표기법: JavaScript에서는 숫자를 다양한 진법(Decimal, Hexadecimal, Octal, Binary)으로 표현할 수 있다. 숫자 리터럴의 접두사는 소문자로 통일해야 한다.

const decimal = 42;     // 10진수
const hex = 0x2a;       // 16진수
const octal = 0o52;     // 8진수
const binary = 0b101010; // 2진수

선행 0 금지: 숫자 리터럴에 선행 0(leading zero)를 사용하는 경우 혼란을 초래할 수 있다. 예전에는 선행 0이 있는 숫자가 8진수로 해석되었기 때문이다(ECMAScript 5 이전). ECMAScript 6 이상에서는 선행 0을 사용하는 숫자 리터럴은 문법 오류로 간주된다. 따라서 선행 0은 반드시 0x, 0o, 0b와 같이 올바른 접두사가 뒤따라야 한다.

Before

// 예전 JavaScript에서 선행 0은 8진수로 해석되었다.
const octal = 052; // 42 (8진수)

After

// 올바른 8진수 표현
const octal = 0o52;

4.8.3 Type coercion

암시적 강제 변환(Implicit coercion) 지양하기: 암시적 강제 변환은 코드의 의도를 불분명하게 만들고, 예상치 못한 오류를 초래할 수 있다. Before

if (!!foo) {...}  // BAD:불필요한 암시적 강제 변환
while (!!foo) {...}

After

if (foo) {...}  // GOOD: 간결하게 작성
while (foo) {...}

문자열 명시적 변환에 String() 또는 Boolean() 함수를 사용하기:

const bool = Boolean(false); // false
const str = String(123);     // "123"
const bool2 = !!str;         // true
const str2 = `result: ${bool2}`; // "result: true"

• 변환이 명확하고 코드 리뷰 시 쉽게 파악할 수 있음
• 암시적 강제 변환보다 의도를 명확히 표현
• !! 연산자를 사용하여 값을 명시적으로 boolean으로 변환

열거형 값을 불리언으로 변환하지 않기: 열거형(Enum)은 기본적으로 숫자 값과 매핑되며, 첫 번째 값은 0으로 할당된다.
Boolean(enumValue)나 !!enumValue를 사용하면:

• 첫 번째 값(0)은 falsy로 평가
• 나머지 값은 truthy로 평가 이런 동작은 예상치 못한 오류를 유발할 수 있다.

Before

enum SupportLevel {
  NONE,
  BASIC,
  ADVANCED,
}

const level: SupportLevel = SupportLevel.NONE;
let enabled = Boolean(level); // 잘못된 방식: `NONE`이 `false`로 평가됨

After

enum SupportLevel {
  NONE,
  BASIC,
  ADVANCED,
}

const level: SupportLevel = SupportLevel.NONE;
let enabled = level !== SupportLevel.NONE; // 명시적 비교

숫자형 변환에 Number() 사용하기: 숫자 값을 파싱할 때는 Number()를 사용하고, 결과가 유효한지 명시적으로 확인해야 한다:

• isNaN: 숫자가 NaN인지 확인
• isFinite: 숫자가 유한한 값인지 확인

Before

const x = +y; // 가독성이 낮고, 실수하기 쉬움
const n = parseInt(someString, 10); // 에러 발생 가능
const f = parseFloat(someString); // 에러 발생 가능

• 문자열에 추가적인 문자가 포함될 경우 오류가 발생하지 않고 잘못된 값을 반환함.

After

let f = Number(someString); // 숫자로 변환
if (!isFinite(f)) throw new Error('Invalid number'); // 유효성 확인
if (isNaN(f)) handleError(); // NaN인지 확인
f = Math.floor(f);           // 정수로 변환

Number(''), Number(' '), Number('\t')는 NaN 대신 0을 반환한다. Number('Infinity'), Number('-Infinity')는 Infinity와 -Infinity를 반환한다. 지수 표기법, 예를들어 Number('1e+309'), Number('-1e+309')은 무한대로 오버플로될 수 있다. 이러한 경우 특별한 처리가 필요할 수 있다.

4.9 Control structures

4.9.1 Control flow statements and blocks

모든 제어 흐름문(if, else, for, while, 등)은 항상 중괄호로 코드 블록을 감싸야 한다. 단, if 문이 한 줄로 끝나는 경우에는 중괄호 생략이 허용된다.

Before

if (x)
  doSomething(); // 중괄호 없이 여러 줄 코드 작성 시 가독성 문제 발생

After

if (x) {
  doSomething();
}

for (let i = 0; i < 10; i++) {
  console.log(i);
}

if (x) x.doSomething(); // 한 줄 코드인 경우에만 중괄호 생략 가능

제어문 내부에서 변수 할당은 지양해야 한다. 이는 할당(=)과 비교(==)를 혼동할 가능성을 줄이기 위함이다. 단, 의도적으로 할당하는 경우 이중 괄호를 사용해 의도를 명확히 표시한다.

Before

if (x = someFunction()) {
  // 할당이 조건문 내부에 있어 혼동 가능
}

After

x = someFunction();
if (x) {
  // x를 사용
}

while ((x = someFunction())) {
  // 할당이 의도적임을 알 수 있음
}

배열을 반복 처리할 때는 다음과 같은 방식을 우선적으로 사용한다:

• for ... of: 배열의 값을 직접 반복
• Array.prototype.forEach: 반복 동작을 콜백 함수로 처리
• 전통적인 for 루프: 인덱스가 필요한 경우에만 사용

  for (const value of someArr) {
  console.log(value);
  }
  

for (let i = 0; i < someArr.length; i++) { const value = someArr[i]; // 인덱스가 필요한 경우 console.log(i, value); }

for (const [i, value] of someArr.entries()) { console.log(i, value); }

> `for ... in`은 배열이 아닌 객체 순회용이며, 배열의 인덱스를 문자열로 반환하기 때문에 비직관적이므로 배열에 사용하지 말자.

객체를 반복 처리할 때는 `for ... in`보다 Object.keys, Object.values, Object.entries를 권장한다.
```typescript
for (const key of Object.keys(obj)) {
  console.log(key);
}

for (const value of Object.values(obj)) {
  console.log(value);
}

for (const [key, value] of Object.entries(obj)) {
  console.log(key, value);
}

for (const key in obj) {
  if (!obj.hasOwnProperty(key)) continue;
  doWork(key, obj[key]);
}

4.9.2 Grouping parentheses

코드를 작성할 때 불필요한 괄호 사용을 피하되, 읽기 쉽고 오해의 소지가 없도록 작성하라.

선택적인 그룹화 괄호는 작성자와 검토자가 그룹화 괄호 없이는 코드가 오해받을 가능성이 전혀 없고, 코드의 읽기가 더 쉬워지지 않을 것에 동의하는 경우에만 생략한다. (모든 독자가 연산자 우선순위 표 전체를 암기하고 있다고 가정하는 것은 합리적이지 않다.)

delete, typeof, void, return, throw, case, in, of, yield 다음에 나오는 전체 표현식 주위에 불필요한 괄호를 사용하지 말자. Before

return (a + b); 
throw (new Error('Error message'));

After

return a + b; 
throw new Error('Error message');

4.9.3 Exception handling

예외는 언어의 중요한 부분이므로 예외적인 경우가 발생할 때마다 사용해야 한다. 사용자 정의 예외는 함수에서 추가적인 오류 정보를 전달하는 좋은 방법을 제공한다.

new를 사용한 인스턴스화 하기: throw Error()보다는 throw new Error()를 사용. 이는 다른 객체 인스턴스화 방식과 일관성을 유지한다. Before

throw Error('Foo is not a valid bar.');

After

throw new Error('Foo is not a valid bar.');

Error만 throw 하기: 일반적으로 JavaScript에서는 throw 키워드를 사용해 예외를 발생시킬 때 Error 객체를 던진다. 임시 오류 처리 방식(오류 컨테이너 참조 유형 전달이나 오류 속성이 있는 객체 반환 등)보다 예외를 throw하는 것을 권장한다. Before

throw 'oh noes!';

new Promise((resolve, reject) => void reject('oh noes!'));
Promise.reject();
Promise.reject('oh noes!');

After

throw new Error('oh noes!');

class MyError extends Error {}
throw new MyError('my oh noes!');

new Promise((resolve) => resolve());
new Promise((resolve, reject) => void reject(new Error('oh noes!')));
Promise.reject(new Error('oh noes!'));

• Error 객체만이 의미 있는 스택 추적 정보를 제공한다.
• 임의의 값을 던지면 디버깅이 어려워진다.

오류를 잡을 때 코드는 발생한 모든 오류가 Error 인스턴스라고 가정해야 한다.

function assertIsError(e: unknown): asserts e is Error {
  if (!(e instanceof Error)) throw new Error("e is not an Error");
}

try {
  doSomething();
} catch (e: unknown) {
  // All thrown errors must be Error subtypes. Do not handle
  // other possible values unless you know they are thrown.
  assertIsError(e);
  displayError(e.message);
  // or rethrow:
  throw e;
}

과도하게 방어적인 코드를 작성하지 말자: 대부분의 코드에서 throw는 Error 객체를 던지기 때문에, 항상 모든 경우의 타입(string, number 등)을 방어적으로 처리하는 코드는 불필요한 반복적 방어가 된다. 문제를 일으킬 가능성이 적은 상황에서 "모든 경우"를 처리하려는 과도한 방어는 코드 복잡성을 높이고 유지보수를 어렵게 만든다.

만약 사용하는 API가 Error가 아닌 다른 타입(예: 문자열)을 던지는 비정상적인 동작을 하는 경우에 한하여 방어적 코드를 작성하고 주석을 추가하여 문제의 출처를 명확히 설명하자.

빈 catch 블록 피하기: Before

try {
  shouldFail();
} catch (e) {
  // 아무것도 하지 않음
}

After

try {
  // 작업 수행
} catch (e: unknown) {
  // 왜 아무것도 하지 않는지 주석으로 설명
  // 예: 특정 예외는 무시해도 되는 상황
}

4.9.4 Switch statements

모든 switch 문에 default 그룹을 포함하기: switch 문에는 항상 default 그룹을 포함해야 하며, 이 그룹은 항상 마지막에 위치한다. 빈 그룹도 괜찮다. 코드가 없는 경우라도 주석으로 의도를 명시하라.

모든 비어 있지 않은 case 그룹은 명시적으로 종료하기: case 블록이 비어 있지 않다면, 반드시 명시적으로 종료해야 한다. 종료 방법은 break, return, 또는 throw를 사용하는 것이다. 명시적으로 종료하지 않으면 다음 case 블록으로 실행이 넘어가는 fall-through로 의도치 않은 동작을 유발할 수 있다. 물론 여러 조건을 같은 방식으로 처리하고 싶을 때 의도적인 묶음 처리는 사용해도 된다.

switch (x) {
  case 1:
    doSomething();
    break; // 명시적으로 종료
  case 2: // fall-through! => 다음 case로 실행이 넘어감
  case 3:
    doSomethingElse();
    break;
  default:
    // nothing to do.
}

4.9.5 Equality checks

삼중 등호(===, !==) 사용하기: JavaScript의 동등 비교 연산자(==, !=)에서 발생하는 타입 강제 변환(type coercion)에 따른 예측 불가능한 동작을 방지하기 위해 항상 삼중 등호(===, !==)를 사용할 것을 권장한다. ==는 두 값이 다른 타입일 경우, 비교를 시도하기 위해 한쪽 값을 다른 타입으로 변환한다. 이러한 변환은 예상치 못한 결과를 초래할 수 있다. 또한, 타입 강제 변환을 수행하는 ==는 JavaScript 엔진이 더 많은 작업을 처리해야 하므로 느리다. 삼중 등호는 타입을 체크한 뒤 바로 값을 비교하므로 성능이 더 효율적이다.

예외: null 비교에서만 ==와 != 허용 단, null과 undefined를 동시에 비교해야 할 때는 예외적으로 ==와 !=를 사용할 수 있다.

if (foo === null || foo === undefined) {
  console.log('foo is null or undefined');
}

if (foo == null) {
  console.log('foo is null or undefined'); // true
}

4.9.6 Type and non-nullability assertions

TypeScript의 타입 단언(type assertions)과 null 불가능성 단언(non-nullability assertions)을 신중하게 사용할 것을 권장한다.

타입 단언 시, as 문법을 사용하라: <Foo>와 같은 앵글 브래킷 문법은 혼란을 줄 수 있으므로 지양한다. as를 사용하면 멤버 접근 시 명확성을 높이기 위해 괄호가 추가되기 때문이다.

Before

const x = (<Foo>z).length;
const y = <Foo>z.length; // 오해의 소지가 있음

After

const x = (z as Foo).length; // 괄호가 명확성을 보장

타입 단언과 null 불가능성 단언은 반드시 필요한 경우에만 사용하라: 타입 단언 (x as SomeType)과 null 불가능성 단언 (y!)은 컴파일러에게 특정 값이 어떤 타입임을 강제로 알리는 기능이다. 하지만 런타임에서는 실제로 타입이나 null 체크를 수행하지 않는다. 따라서:

• 잘못된 단언은 런타임 에러로 이어질 수 있다.
• 단언은 개발자의 책임을 가중시키며 코드 안정성을 떨어뜨릴 수 있다.

Before

const x: unknown = "hello";
console.log((x as number).toFixed(2)); // 런타임 에러 발생!

After 타입 체크나 null 체크를 명시적으로 작성하라.

if (typeof x === "number") {
  console.log(x.toFixed(2)); // 안전한 실행
}

타입 단언이나 null 불가능성 단언을 반드시 사용해야 할 경우, 주석을 통해 해당 단언이 안전하다고 판단한 이유를 기록한다. (명백한 경우에는 주석이 생략 가능하다.)

// x는 Foo 타입임이 보장된다 (어떤 이유 때문인지 명시).
(x as Foo).foo();

// y는 null이 될 수 없음을 알고 있다 (해당 상황 설명).
y!.bar();

이중 단언문 (Double Assertions) TypeScript는 일반적으로 "더 구체적이거나 더 일반적인 타입"으로의 단언만 허용한다. 안전하다고 확신하는 경우, 이중 단언문을 사용할 수 있다. 중간 타입으로 any나 {} 대신 unknown을 권장한다. Before

(x as any as Foo).fooMethod();

After

(x as unknown as Foo).fooMethod();

객체 리터럴에는 타입 어노테이션을 사용하여 에러를 사전에 방지하라: 객체 리터럴에서는 타입 단언 (as Foo) 대신 타입 어노테이션 (: Foo) 사용을 권장한다. 타입 어노테이션을 사용하면 인터페이스 변경 시 잘못된 필드가 자동으로 감지된다. Before

interface Foo {
  bar: number;
  baz?: string;
}

const foo = {
  bar: 123,
  bam: 'abc', // 오류가 발생하지 않음!
} as Foo;

After

interface Foo {
  bar: number;
  baz?: string;
}

const foo: Foo = {
  bar: 123,
  bam: 'abc', // bam이 Foo에 정의되지 않았다고 에러 발생
};

4.9.7 Keep try blocks focused

try 블록에 포함된 코드는 최소화하는 것이 좋다: 어떤 코드가 예외를 던질 가능성이 있는지 명확하게 드러나도록 하기 위함이다.

Before

try {
  const result = methodThatMayThrow(); // 예외를 던질 가능성 있음
  use(result);                         // 예외를 던지지 않음
} catch (error: unknown) {
  // ...
}

• use(result)는 예외를 던지지 않지만 try 블록 안에 포함되어 있어 독자에게 혼란을 줄 수 있다.
• After*

  let result;
  try {
   result = methodThatMayThrow(); // 예외를 던질 가능성이 있는 코드만 포함
  } catch (error: unknown) {
   // ...
  }
  use(result); // 예외를 던지지 않는 코드는 `try` 블록 밖으로 이동

• 이제 독자가 methodThatMayThrow()만 예외를 던질 가능성이 있음을 명확히 알 수 있다.

  try {
  use(methodThatMayThrow()); // 코드가 간단하므로 별도로 나눌 필요 없음
  } catch (error: unknown) {
  // ...
  }

루프 안에 try 블록을 반복적으로 선언하면 성능 문제가 발생할 수 있다: 이 경우, try 블록의 범위를 루프 전체로 확장하는 것이 낫다. Before

for (const item of items) {
  try {
    processItem(item); // 매번 `try` 블록이 재생성됨
  } catch (error: unknown) {
    // ...
  }
}

After

try {
  for (const item of items) {
    processItem(item); // `try` 블록이 한 번만 생성됨
  }
} catch (error: unknown) {
  // ...
}

4.10 Decorators

데코레이터는 클래스, 메서드, 필드, 또는 파라미터에 메타데이터를 추가하거나, 동작을 수정할 수 있도록 도와주는 특수한 문법이다. 데코레이터는 @ 기호로 시작하며, 함수 형태로 정의된다.

@Component({
  selector: 'my-component',
  template: '<p>My Component</p>',
})
class MyComponent {}

새로운 데코레이터를 정의하지 말고, 프레임워크 제공 데코레이터만 사용하라: 데코레이터는 TypeScript에서 실험적(Experimental)으로 도입되었다. 하지만 JavaScript 표준화 기구인 TC39의 최종 표준안과는 다르게 동작하는 부분이 있다. 실험적 기능이기 때문에 이미 발견된 몇 가지 버그들이 수정되지 않을 가능성이 있다. 이런 이유로 새로운 데코레이터를 정의하거나 사용하는 것이 위험할 수 있다. 프레임워크에서 제공하는 공식 데코레이터만 사용해야 한다.

데코레이터는 빈 줄 없이 바로 적용 대상 앞에 위치시켜 가독성과 유지보수성을 높여라: Before

/** JSDoc comments */
@Component({...}) 

class MyComponent {}  // 빈 줄이 있어서 잘못된 예

After

/** JSDoc comments */
@Component({...})
class MyComponent {}  // 빈 줄 없이 바로 연결

class MyComp {
  @Input() myField: string;  // 같은 줄
  @Input()
  myOtherField: string;  // 다음 줄로 감싸기
}

• 필드에 데코레이터를 붙일 때는 같은 줄에 작성하거나 다음 줄로 감싸는 방식 모두 허용된다.

4.11 Disallowed features

4.11.1 Wrapper objects for primitive types

래퍼 클래스(wrapper class)는 JavaScript의 원시 타입(String, Boolean, Number)을 객체로 감싸는 기능을 제공한다. 예를 들어, String, Boolean, Number는 각각 원시 타입을 객체처럼 다룰 수 있게 해 준다.

const s = new String('hello');  // 문자열 'hello'를 String 객체로 감쌈
const b = new Boolean(false);  // 불리언 false를 Boolean 객체로 감쌈
const n = new Number(5);       // 숫자 5를 Number 객체로 감쌈

원시 타입을 감싸는 래퍼 클래스를 직접 인스턴스화하지 말자: 래퍼 클래스를 인스턴스화하면 원시 값이 아니라 객체가 생성된다. 이로 인해 의도와 다른 동작을 초래할 수 있다. 원시 타입을 객체로 감싸는 것은 메모리와 성능 측면에서 불필요한 오버헤드를 발생시킨다. 원시 타입 자체는 가볍고 빠르게 동작하도록 설계되었다.

Before

const b = new Boolean(false);
console.log(b);  // Boolean {false}
console.log(b == true);  // true
console.log(b ? 'true' : 'false');  // 'true'

new Boolean(false)는 불리언 객체를 반환하며, 객체는 항상 true로 평가된다. 즉, 실제 값이 false임에도 true로 평가되는 문제가 발생한다.

const s1 = 'hello';
const s2 = new String('hello');

console.log(s1 === s2);  // false (문자열 vs 객체)
console.log(s1 == s2);   // true (느슨한 비교로 동등하다고 평가)

After

const s = 'hello';  // 원시 문자열
const b = false;    // 원시 불리언
const n = 5;        // 원시 숫자

const s = String('hello');  // 문자열로 변환
const b = Boolean(0);       // 불리언으로 변환
const n = Number('42');     // 숫자로 변환

• 타입 강제 변환은 래퍼 클래스 함수 호출로 처리해야 한다.
• 이는 +, ''와 같은 비권장 방식보다 명시적이고 안전하다.

4.11.2 Automatic Semicolon Insertion

모든 문장을 세미콜론으로 명시적으로 끝내야 한다. 이렇게 하면 잘못된 세미콜론 삽입으로 인한 버그를 방지하고 ASI 지원이 제한된 도구(예: clang-format)와의 호환성을 보장한다.

4.11.3 Const enums

const enum을 사용해서는 안 된다: const enum은 컴파일 결과에서 사라지므로, JavaScript로 작성된 코드나 다른 모듈에서 이 열거형을 참조할 수 없다. 만약 const enum을 사용한 TypeScript 코드가 JavaScript 모듈과 함께 사용될 경우, 예상치 못한 오류가 발생할 수 있다. const enum은 값이 인라인되기 때문에 디버깅 과정에서 열거형 이름을 볼 수 없다. 이는 디버깅 정보를 잃게 만들고, 유지보수를 어렵게 한다. 또한 열거형의 값이 여러 곳에 인라인으로 삽입되면, 열거형 값이 변경될 때 컴파일된 JavaScript의 모든 참조를 다시 컴파일해야 한다. const 열거형은 모듈의 JavaScript 사용자에게 열거형을 보이지 않게 하는 최적화와 관련된 별도의 언어 기능이며, JavaScript 표준이 아니다. 따라서 다른 환경에서 호환되지 않을 가능성이 있다.

enum:

enum Color {
  Red,
  Green,
  Blue,
}

console.log(Color.Red);  // 출력: 0

컴파일 후 JavaScript:

var Color;
(function (Color) {
  Color[Color["Red"] = 0] = "Red";
  Color[Color["Green"] = 1] = "Green";
  Color[Color["Blue"] = 2] = "Blue";
})(Color || (Color = {}));

console.log(Color.Red);  // 출력: 0

const enum:

const enum Color {
  Red,
  Green,
  Blue,
}

console.log(Color.Red);  // 출력: 0

컴파일 후 JavaScript:

console.log(0);  // `Color.Red`가 상수로 대체됨

4.11.4 Debugger statements

debugger문은 프로덕션 코드에 포함되어서는 안 된다. debugger는 JavaScript에서 디버깅을 위해 사용되는 명령어로, 코드 실행을 중단하고 디버깅 세션을 시작할 수 있도록 돕는다. 이 명령어는 주로 브라우저의 개발자 도구나 Node.js의 디버깅 모드에서 실행될 때 유용하게 사용된다.

function debugMe() {
  debugger;  // 디버거가 활성화된 상태에서 실행 시, 코드가 중단된다.
  console.log("This will not run unless debugger is removed.");
}

debugger는 코드 실행을 중단시키므로, 사용자가 웹 애플리케이션을 사용할 때 예기치 않게 페이지가 멈추거나 동작이 중단될 수 있다. 프로덕션 환경에서는 디버깅을 위한 코드 실행 중단이 사용자 경험을 방해하거나 서비스의 가용성에 악영향을 미칠 수 있다.

debugger 문이 코드에 남아 있으면, 프로덕션 환경에서도 디버깅을 할 수 있는 상태로 남게 된다. 이는 보안 위험을 초래할 수 있다. 공격자는 브라우저의 개발자 도구를 통해 디버거를 활성화하고 애플리케이션의 상태를 추적하거나 악용할 수 있다. 특히, 민감한 데이터를 처리하는 애플리케이션에서는 이러한 디버깅 코드가 보안 취약점을 유발할 수 있다.

배포 후 디버깅은 실제 코드에 debugger를 삽입하는 대신, 로그 파일이나 에러 추적 시스템을 활용하여 디버깅을 수행하는 것이 좋다.

4.11.5 with

with 키워드 사용 금지: 코드를 이해하기 어렵게 만들고 ES5 이후로 strict 모드에서 금지되었다.

4.11.6 Dynamic code evaluation

eval이나 Function(...string) 생성자를 사용 금지(코드 로더 제외). 이러한 기능은 잠재적으로 위험하며 엄격한 콘텐츠 보안 정책을 사용하는 환경에서는 제대로 작동하지 않는다.

const userInput = "alert('Hacked!')";
eval(userInput);  // 위험: 사용자가 악의적인 코드를 삽입할 수 있음

const userInput = "alert('Malicious code')";
const fn = new Function(userInput);
fn();  // 위험: 악의적인 코드 실행

4.11.7 Non-standard features

표준화된 ECMAScript 및 Web Platform 기능만 사용하자: 비표준 ECMAScript나 웹 플랫폼 기능으로 간주되는 것들은 다음과 같다.

• 구식 기능 또는 더 이상 지원되지 않는 기능
• 표준화되지 않은 새로운 ECMAScript 기능
• 현재 TC39 작업 초안이나 제안 중인 기능
• 제안되었지만 아직 완성되지 않은 웹 표준
• 외부 트랜스파일러 확장 기능
• 특정 JavaScript 런타임을 타겟팅하는 API 사용

4.11.8 Modifying builtin objects

내장 타입을 수정하지 마라: JavaScript에는 내장된 타입들, 예를 들어 Array, Object, String, Number, Boolean, Function 등이 있다.

내장 타입을 수정하면, 기존 코드나 외부 라이브러리가 의도한 대로 동작하지 않을 수 있다. 예를 들어, Array에 새로운 메서드를 추가하면, 다른 코드에서 기존 메서드들과 충돌하거나 예기치 않은 결과를 초래할 수 있다. Array.prototype에 newMethod를 추가한다고 가정했을 때, 다른 라이브러리가 같은 이름의 메서드를 추가하거나, 예상치 못한 방식으로 동작할 수 있다.

표준 JavaScript 동작을 변경하는 것은 코드의 호환성 문제를 유발할 수 있다. 예를 들어, 새로운 자바스크립트 버전이나 다른 환경에서는 다르게 동작할 가능성이 있으며, 이는 예상치 못한 버그를 초래할 수 있다.

내장 타입을 수정하면 디버깅을 어렵게 만들 수 있다. 수정된 메서드는 JavaScript 엔진의 표준 동작을 변경하므로, 문제가 발생할 경우 이를 추적하기가 힘들어진다.

글로벌 객체에 심볼을 추가하지 마라: 글로벌 객체는 JavaScript 실행 환경에서 전역적으로 접근 가능한 객체를 의미한다. 브라우저에서는 window, Node.js에서는 global 객체가 해당된다. 이 규칙은 글로벌 객체에 심볼이나 속성을 추가하지 말고, 추가가 필요하다면 꼭 필요한 경우에만 하라는 것이다.

글로벌 객체는 애플리케이션 내 모든 코드에서 접근 가능하다. 여기에 심볼이나 속성을 추가하면, 전역 변수의 이름이 충돌할 가능성이 높아지며, 이는 코드의 예기치 못한 동작을 초래할 수 있다. 특히, 외부 라이브러리나 다른 개발자와 협업할 때 문제가 될 수 있다.

글로벌 객체에 불필요한 심볼이나 속성이 많이 추가되면, 코드의 복잡성이 증가하고, 성능에도 영향을 미칠 수 있다. 이는 특히 대규모 애플리케이션에서 문제가 될 수 있다.

글로벌 객체에 의도치 않은 속성이 추가되면, 디버깅할 때 혼란을 초래할 수 있다. 어떤 코드에서 해당 심볼을 수정하거나 참조할 수 있기 때문에, 문제가 발생했을 때 추적이 어렵다.

글로벌 객체에 심볼을 추가할 때는 반드시 그 이유를 명확히 하고, 외부에서 이 심볼에 접근하거나 수정할 가능성을 최소화해야 한다.

참고자료

Google TypeScript Style Guide

GitHub - google/gts: ☂️ TypeScript style guide, formatter, and linter.

Typescript Google Code Style Part 1
Typescript Google Code Style Part 2 Typescript Google Code Style Part 3

ts.dev - TypeScript style guide