2. 이름과 모듈 경계

2.1 프로젝트 전반의 상수는 루트 constant 폴더에 주제별 파일로 둡니다

프로젝트 전반의 상수를 주제별로 모아 위치와 이름을 일관되게 유지합니다.

상수 자리 고르기

상수 위치는 사용처 수가 아니라 소유자로 정합니다. 소유자 전용 배치는 규칙 2.2를 따릅니다.

flowchart LR
	q1{"소유자를 지워도<br>값이 남는가?"} -- 예 --> q2{"배포 환경마다<br>달라지는가?"} -- 예 --> r3("config 폴더")
	q1 -- 아니요 --> r1("소유자 _constant 폴더")
	q2 -- 아니요 --> r2("루트 constant 폴더")

선언과 내보내기

파일, 심볼 표기는 규칙 2.3을 따릅니다. constant에는 코드와 함께 바뀌는 값만 둡니다.

프로젝트 전반의 값을 쓰는 자리에서 선언합니다.

const default_page_size = 20;
const request_timeout_ms = 20_000;

const productClient = createClient({timeoutMs: request_timeout_ms});
const productQuery = useProductQuery({client: productClient, pageSize: default_page_size});

// 다른 화면이 같은 값을 다시 선언
const default_page_size = 20;

const orderQuery = useOrderQuery({pageSize: default_page_size});

루트 constant 폴더에 둔 이름을 쓰는 자리에서 가져옵니다.

import {api_request_timeout_ms} from "@/constant/api";
import {pagination_default_page_size} from "@/constant/pagination";

const productClient = createClient({timeoutMs: api_request_timeout_ms});
const productQuery = useProductQuery({client: productClient, pageSize: pagination_default_page_size});

import {pagination_default_page_size} from "@/constant/pagination";

const orderQuery = useOrderQuery({pageSize: pagination_default_page_size});

객체 하나에 모아 색인을 손으로 유지합니다.

export const config = {
	api: {request_timeout_ms: 20_000},
	pagination: {default_page_size: 20},
} as const;

주제 파일에 상수를 하나씩 이름 붙여 내보냅니다.

/**
 * 요청 하나의 최대 대기 시간. 게이트웨이가 30초에 끊으므로 그 전에 실패 표시
 */
export const api_request_timeout_ms = 20_000;

// constant/pagination.ts
/**
 * 목록 화면이 처음 불러오는 개수
 */
export const pagination_default_page_size = 20;

함께 보기

• 2.2 소유자 전용 상수는 소유자 _constant 폴더에 둡니다
• 2.4 index.ts 배럴을 만들지 않고 필요한 파일에서 바로 가져옵니다

2.2 소유자 전용 상수는 소유자 _constant 폴더에 둡니다

소유자 전용 상수를 함께 관리하고 파일 이름과 상수 이름에서 소유자 표현을 반복하지 않습니다.

한 소유자의 상수는 그 소유자 아래 _constant에 둡니다. 루트와 소유자를 구분하는 기준은 규칙 2.1를 따릅니다.

계약 파일의 이름은 규칙 2.3을 따릅니다. 소유자 아래에 config, constants, common 폴더는 만들지 않습니다.

한 소유자의 상수를 루트로 올립니다.

// 상품 상세 화면만 쓰는 값이 루트에 있음
export const chart_axis_tick_count = 6;

소유자 아래 주제 파일에 둡니다.

/**
 * 상품 상세 차트의 축 눈금 수. 표시 폭이 좁아 여섯을 넘으면 라벨 겹침
 */
export const chart_axis_tick_count = 6;

파일 이름에 소유자 이름을 되풀이하고 주제를 객체 하나에 모읍니다.

export const product_detail_config = {
	chart_axis_tick_count: 6,
	table_page_size: 20,
} as const;

주제마다 파일을 나누고 상수를 개별 이름으로 내보냅니다.

export const chart_axis_tick_count = 6;

// page/product-detail/_constant/table.ts
export const table_page_size = 20;

함께 보기

• 2.3 파일과 심볼은 역할에 맞는 표기를 씁니다
• 2.1 프로젝트 전반의 상수는 루트 constant 폴더에 주제별 파일로 둡니다

2.3 파일과 심볼은 역할에 맞는 표기를 씁니다

파일과 심볼의 표기가 역할을 드러내 읽는 사람이 종류를 바로 압니다.

역할별 표기

파일과 심볼은 선언 문법이 아니라 역할에 맞게 이름 짓습니다. const로 선언해도 함수, 훅, 스키마, API 결과, 요청 객체, 지역 파생값을 불변 데이터 상수로 보지 않습니다.

불변 데이터 상수는 한 번 선언해 같은 의미로 쓰는 리터럴, 기본값, 값 집합, 조회표입니다. 함수는 동사, 상수는 주제 접두사와 snake_case, 컴포넌트는 레이어 접두사로 종류를 드러냅니다. 한 단어 상수는 만들지 않습니다. 함수 파일 이름은 내보낸 이름(format-usd.ts → formatUsd), 상수 파일 이름은 공유하는 주제(api.ts → api_*)입니다.

외부 계약이 정한 이름

외부 계약이 정한 이름과 키는 원래 표기를 유지합니다. API 응답, 요청, 생성 DTO, 라이브러리 인자, DOM 속성, 환경 변수와 모듈 상수에 담긴 외부 설정도 같습니다.

역할과 맞지 않는 표기를 씁니다.

// 우리가 선언한 타입은 PascalCase, 그 필드는 camelCase
interface User_Profile {
	avatar_url: string;
}

파일 이름은 kebab-case, 타입 필드는 camelCase로 씁니다.

/**
 * 사용자 프로필
 */
interface UserProfile {
	/**
	 * 프로필 이미지 주소
	 */
	avatarUrl: string;
}

불변 데이터 상수와 값 집합의 이름과 키를 camelCase로 적습니다.

const retryPolicy = {
	maxAttempts: 3,
} as const;

const productStatus = {
	draft: "draft",
	waitingReview: "waiting_review",
	active: "active",
} as const;

불변 데이터 상수와 값 집합은 이름과 상수 키를 모두 snake_case로 적습니다.

/**
 * 요청 재시도 정책. 하위 키도 상수 키
 */
const retry_policy = {
	max_attempts: 3,
} as const;

/**
 * 상품 게시 상태 값 집합
 */
const product_status = {
	draft: "draft",
	waiting_review: "waiting_review",
	active: "active",
} as const;

밖으로 나가는 키를 우리 표기로 바꿉니다.

// 서버 계약은 {category_id, product_name}인데 우리 표기로 바꿔 전송
/**
 * 상품 저장 요청 조립
 */
const toProductSaveBody = (values: ProductFormValues) => {
	return {
		categoryId: values.categoryId,
		productName: values.name.trim(),
	};
};

밖으로 나가는 키만 받는 쪽 표기를 그대로 씁니다.

/**
 * 상품 저장 요청 조립. 서버 계약이 snake_case라 그 표기 그대로 전달
 */
const toProductSaveBody = (values: ProductFormValues) => {
	return {
		category_id: values.categoryId,
		product_name: values.name.trim(),
	};
};

2.4 index.ts 배럴을 만들지 않고 필요한 파일에서 바로 가져옵니다

배럴이나 재노출 계층 없이 선언의 출처를 직접 확인할 수 있습니다.

필요한 파일에서 직접 가져오고 선언 앞에 export를 붙여 이름으로 내보냅니다. index.ts 배럴이나 파일 끝의 export {…} 목록은 만들지 않습니다.

경로 형식은 규칙 2.5를 따릅니다. 같은 경로라도 값, 타입 가져오기를 바꾸면 이 규칙을 적용합니다.

배럴과 섞인 가져오기로 경계를 흐립니다.

import {pagination_default_page_size, toDisplayDate, UserProfile} from "./index";

필요한 파일에서 이름으로 바로 가져옵니다.

import type {UserProfile} from "@/type/user-profile";
import {pagination_default_page_size} from "@/constant/pagination";
import {toDisplayDate} from "@/util/date/to-display-date";

default로 내보내 사용처마다 다른 이름이 생깁니다.

const UiTabs = (props: UiTabsProps) => {
	return <div role="tablist">{props.children}</div>;
};

export default UiTabs;

// 사용처마다 이름을 지어 같은 컴포넌트가 파일마다 다른 이름
import Tabs from "@/component/ui/tabs/ui-tabs";

선언 앞에 export를 붙여 사용처가 그 이름으로 가져옵니다.

export const UiTabs = (props: UiTabsProps) => {
	return <div role="tablist">{props.children}</div>;
};

import {UiTabs} from "@/component/ui/tabs/ui-tabs";

함께 보기

• 2.5 가져오기 경로는 @/로 씁니다

2.5 가져오기 경로는 @/로 씁니다

가져오기 경로를 통일하고 가져오는 파일의 위치로 접근 범위를 판단합니다.

경로 표기

심볼은 @/ 절대경로로 가져옵니다. 편집기 자동 가져오기가 만드는 형식입니다. 심볼 없이 같은 폴더의 파일만 불러올 때는 ./를 허용하며, ../는 쓰지 않습니다.

flowchart LR
	q1{"심볼을<br>가져오는가?"} -- 아니요 --> q2{"같은 폴더의<br>파일인가?"} -- 예 --> r2("./ 로 파일만 불러옴")
	q1 -- 예 --> r1("@/ 절대경로")
	q2 -- 아니요 --> r1

접근 가능한 소유 경계는 경로 표기가 아니라 가져오는 파일의 위치로 판단합니다. 가져오기 방향은 프레임워크 규칙을 따릅니다.

src 아래 루트 폴더

루트의 소유자는 프로젝트이며 constant, util, type, hook에도 소유자 아래 역할 폴더의 규칙을 적용합니다. 배치는 규칙 2.1와 규칙 3.4이 정합니다.

상대경로로 심볼을 가져옵니다.

import {PgReviewSection} from "./_pg-review-section";
import {toSummary} from "../_function/to-summary";

심볼은 @/, 같은 폴더의 CSS 파일만 ./로 씁니다.

import {toSummary} from "@/page/product-detail/_function/to-summary";
import {PgReviewSection} from "@/page/product-detail/product-table-section/_pg-review-section";

import "./pg-product-table-section.css";

함께 보기

• 2.4 index.ts 배럴을 만들지 않고 필요한 파일에서 바로 가져옵니다

2.6 환경 값은 config/env.ts를 거쳐서 읽습니다

환경마다 달라지는 값이 쓰는 파일로 흩어지지 않고 한 파일에서 읽힙니다.

값의 자리

환경 값은 루트 config/env.ts에서만 읽고 env_ 상수로 내보냅니다. 다른 파일은 그 이름을 쓰며 import.meta.env와 process.env를 직접 읽지 않습니다.

flowchart LR
	q1{"배포 환경마다<br>달라지는가?"} -- 예 --> q2{"기능을 켜고 끄는<br>플래그인가?"} -- 예 --> r2("config/feature.ts 의<br>feature_ 상수")
	q1 -- 아니요 --> r1("constant 폴더")
	q2 -- 아니요 --> r3("config/env.ts 의<br>env_ 상수")

feature_ 상수는 env_ 값에서 파생합니다. 배포 환경은 프로젝트 단위이므로 config는 루트에만 둡니다.

읽을 때 확인할 것

쓰는 파일마다 직접 읽고 없을 때 리터럴로 덮습니다.

const baseUrl = import.meta.env.VITE_API_BASE_URL ?? "http://localhost:3000";

// 다른 파일이 같은 키를 다시 읽고 같은 리터럴로 덮음
const orderExportBaseUrl = import.meta.env.VITE_API_BASE_URL ?? "http://localhost:3000";

config/env.ts가 한 번 읽고 없으면 드러냅니다.

if (!import.meta.env.VITE_API_BASE_URL) {
	throw new MissingEnvironmentValueError("VITE_API_BASE_URL");
}

/**
 * API 서버 주소. 배포 환경마다 다름
 */
export const env_api_base_url = import.meta.env.VITE_API_BASE_URL;

import {env_api_base_url} from "@/config/env";

const productClient = createClient({baseUrl: env_api_base_url});

함께 보기

• 2.1 프로젝트 전반의 상수는 루트 constant 폴더에 주제별 파일로 둡니다
• 5.1 ??, ||, 기본 매개변수 자리에 리터럴을 적지 않습니다

2.7 타입 이름은 값의 역할과 수명으로 짓습니다

이름만 읽고 값이 무엇이며 어느 시점에 존재하는지 구분할 수 있습니다.

역할어 고르기

값의 역할과 수명을 판단한 뒤, 의미를 더하는 역할어만 붙입니다. 도메인 명사로 충분하면 ChartPoint, TableRow처럼 씁니다.

이름을 정하는 기준

단순 가공, 표시 결과에는 VM, ViewModel, 막연한 Model과 그 대응 파일 이름을 쓰지 않습니다.

소유자와 막연한 화면 계약 접미사를 반복합니다.

/**
 * 주문 화면 데이터
 */
interface OrderViewModel {
	/**
	 * 조회 시점의 행 목록
	 */
	rows: OrderRow[];
	/**
	 * 조회에 사용한 필터
	 */
	filters: OrderFilters;
}

const orderVM: OrderViewModel = response.data;

한 조회 시점에 고정된 값이라는 역할을 이름에 표시합니다.

// page/orders/_type/summary-snapshot.ts: 폴더 이름이 이미 orders
/**
 * 한 조회 시점의 주문 요약 목록과 조건
 */
interface SummarySnapshot {
	/**
	 * 조회 시점의 행 목록
	 */
	rows: OrderRow[];
	/**
	 * 조회에 사용한 필터
	 */
	filters: OrderFilters;
}

const summarySnapshot: SummarySnapshot = responseOrderSummarySuspense.data;

함께 보기

• 2.3 파일과 심볼은 역할에 맞는 표기를 씁니다