Back to Details

file-organization

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project File Organization

项目文件组织

When to use this skill

何时使用该Skill

  • 신규 프로젝트: 초기 폴더 구조 설계
  • 프로젝트 성장: 복잡도 증가 시 리팩토링
  • 팀 표준화: 일관된 구조 확립
  • 新项目：初始文件夹结构设计
  • 项目增长：复杂度增加时进行重构
  • 团队标准化：确立统一结构

Instructions

操作步骤

Step 1: React/Next.js 프로젝트 구조

步骤1：React/Next.js 项目结构

src/
├── app/                      # Next.js 13+ App Router
│   ├── (auth)/               # Route groups
│   │   ├── login/
│   │   └── signup/
│   ├── (dashboard)/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── settings/
│   ├── api/                  # API routes
│   │   ├── auth/
│   │   └── users/
│   └── layout.tsx
│
├── components/               # UI Components
│   ├── ui/                   # Reusable UI (Button, Input)
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.test.tsx
│   │   │   └── index.ts
│   │   └── Input/
│   ├── layout/               # Layout components (Header, Footer)
│   ├── features/             # Feature-specific components
│   │   ├── auth/
│   │   └── dashboard/
│   └── shared/               # Shared across features
│
├── lib/                      # Utilities & helpers
│   ├── utils.ts
│   ├── hooks/
│   │   ├── useAuth.ts
│   │   └── useLocalStorage.ts
│   └── api/
│       └── client.ts
│
├── store/                    # State management
│   ├── slices/
│   │   ├── authSlice.ts
│   │   └── userSlice.ts
│   └── index.ts
│
├── types/                    # TypeScript types
│   ├── api.ts
│   ├── models.ts
│   └── index.ts
│
├── config/                   # Configuration
│   ├── env.ts
│   └── constants.ts
│
└── styles/                   # Global styles
    ├── globals.css
    └── theme.ts
src/
├── app/                      # Next.js 13+ App Router
│   ├── (auth)/               # 路由组
│   │   ├── login/
│   │   └── signup/
│   ├── (dashboard)/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── settings/
│   ├── api/                  # API 路由
│   │   ├── auth/
│   │   └── users/
│   └── layout.tsx
│
├── components/               # UI 组件
│   ├── ui/                   # 可复用UI（Button、Input）
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.test.tsx
│   │   │   └── index.ts
│   │   └── Input/
│   ├── layout/               # 布局组件（Header、Footer）
│   ├── features/             # 功能特定组件
│   │   ├── auth/
│   │   └── dashboard/
│   └── shared/               # 跨功能共享组件
│
├── lib/                      # 工具与辅助函数
│   ├── utils.ts
│   ├── hooks/
│   │   ├── useAuth.ts
│   │   └── useLocalStorage.ts
│   └── api/
│       └── client.ts
│
├── store/                    # 状态管理
│   ├── slices/
│   │   ├── authSlice.ts
│   │   └── userSlice.ts
│   └── index.ts
│
├── types/                    # TypeScript 类型定义
│   ├── api.ts
│   ├── models.ts
│   └── index.ts
│
├── config/                   # 配置文件
│   ├── env.ts
│   └── constants.ts
│
└── styles/                   # 全局样式
    ├── globals.css
    └── theme.ts

Step 2: Node.js/Express 백엔드 구조

步骤2：Node.js/Express 后端结构

src/
├── api/                      # API layer
│   ├── routes/
│   │   ├── auth.routes.ts
│   │   ├── user.routes.ts
│   │   └── index.ts
│   ├── controllers/
│   │   ├── auth.controller.ts
│   │   └── user.controller.ts
│   └── middlewares/
│       ├── auth.middleware.ts
│       ├── errorHandler.ts
│       └── validation.ts
│
├── services/                 # Business logic
│   ├── auth.service.ts
│   ├── user.service.ts
│   └── email.service.ts
│
├── repositories/             # Data access layer
│   ├── user.repository.ts
│   └── session.repository.ts
│
├── models/                   # Database models
│   ├── User.ts
│   └── Session.ts
│
├── database/                 # Database setup
│   ├── connection.ts
│   ├── migrations/
│   └── seeds/
│
├── utils/                    # Utilities
│   ├── logger.ts
│   ├── crypto.ts
│   └── validators.ts
│
├── config/                   # Configuration
│   ├── index.ts
│   ├── database.ts
│   └── env.ts
│
├── types/                    # TypeScript types
│   ├── express.d.ts
│   └── models.ts
│
├── __tests__/                # Tests
│   ├── unit/
│   ├── integration/
│   └── e2e/
│
└── index.ts                  # Entry point
src/
├── api/                      # API 层
│   ├── routes/
│   │   ├── auth.routes.ts
│   │   ├── user.routes.ts
│   │   └── index.ts
│   ├── controllers/
│   │   ├── auth.controller.ts
│   │   └── user.controller.ts
│   └── middlewares/
│       ├── auth.middleware.ts
│       ├── errorHandler.ts
│       └── validation.ts
│
├── services/                 # 业务逻辑层
│   ├── auth.service.ts
│   ├── user.service.ts
│   └── email.service.ts
│
├── repositories/             # 数据访问层
│   ├── user.repository.ts
│   └── session.repository.ts
│
├── models/                   # 数据库模型
│   ├── User.ts
│   └── Session.ts
│
├── database/                 # 数据库配置
│   ├── connection.ts
│   ├── migrations/
│   └── seeds/
│
├── utils/                    # 工具函数
│   ├── logger.ts
│   ├── crypto.ts
│   └── validators.ts
│
├── config/                   # 配置文件
│   ├── index.ts
│   ├── database.ts
│   └── env.ts
│
├── types/                    # TypeScript 类型定义
│   ├── express.d.ts
│   └── models.ts
│
├── __tests__/                # 测试文件
│   ├── unit/
│   ├── integration/
│   └── e2e/
│
└── index.ts                  # 入口文件

Step 3: Feature-Based 구조 (대규모 앱)

步骤3：基于功能的结构（大型应用）

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   │   ├── LoginForm.tsx
│   │   │   └── SignupForm.tsx
│   │   ├── hooks/
│   │   │   └── useAuth.ts
│   │   ├── api/
│   │   │   └── authApi.ts
│   │   ├── store/
│   │   │   └── authSlice.ts
│   │   ├── types/
│   │   │   └── auth.types.ts
│   │   └── index.ts
│   │
│   ├── products/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── api/
│   │   └── types/
│   │
│   └── orders/
│
├── shared/                   # Shared across features
│   ├── components/
│   ├── hooks/
│   ├── utils/
│   └── types/
│
└── core/                     # App-wide
    ├── store/
    ├── router/
    └── config/
src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── LoginForm.tsx
│   │   └── SignupForm.tsx
│   │   ├── hooks/
│   │   │   └── useAuth.ts
│   │   ├── api/
│   │   │   └── authApi.ts
│   │   ├── store/
│   │   │   └── authSlice.ts
│   │   ├── types/
│   │   │   └── auth.types.ts
│   │   └── index.ts
│   │
│   ├── products/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── api/
│   │   └── types/
│   │
│   └── orders/
│
├── shared/                   # 跨功能共享资源
│   ├── components/
│   ├── hooks/
│   ├── utils/
│   └── types/
│
└── core/                     # 应用全局资源
    ├── store/
    ├── router/
    └── config/

Step 4: 명명 규칙 (Naming Conventions)

步骤4：命名规范

파일명:
Components:       PascalCase.tsx
Hooks:            camelCase.ts        (useAuth.ts)
Utils:            camelCase.ts        (formatDate.ts)
Constants:        UPPER_SNAKE_CASE.ts (API_ENDPOINTS.ts)
Types:            camelCase.types.ts  (user.types.ts)
Tests:            *.test.ts, *.spec.ts
폴더명:
kebab-case:       user-profile/
camelCase:        userProfile/       (선택: hooks/, utils/)
PascalCase:       UserProfile/       (선택: components/)

✅ 일관성이 중요 (팀 전체가 같은 규칙 사용)
변수/함수명:
typescript
// Components: PascalCase
const UserProfile = () => {};

// Functions: camelCase
function getUserById() {}

// Constants: UPPER_SNAKE_CASE
const API_BASE_URL = 'https://api.example.com';

// Private: _prefix (선택)
class User {
  private _id: string;

  private _hashPassword() {}
}

// Booleans: is/has/can prefix
const isAuthenticated = true;
const hasPermission = false;
const canEdit = true;
文件名:
组件：       PascalCase.tsx
Hooks：      camelCase.ts        (useAuth.ts)
工具函数：    camelCase.ts        (formatDate.ts)
常量：       UPPER_SNAKE_CASE.ts (API_ENDPOINTS.ts)
类型定义：    camelCase.types.ts  (user.types.ts)
测试文件：    *.test.ts, *.spec.ts
文件夹名:
kebab-case:       user-profile/
camelCase:        userProfile/       (可选：hooks/, utils/)
PascalCase:       UserProfile/       (可选：components/)

✅ 一致性至关重要（团队全员遵循同一规则）
变量/函数名:
typescript
// 组件：PascalCase
const UserProfile = () => {};

// 函数：camelCase
function getUserById() {}

// 常量：UPPER_SNAKE_CASE
const API_BASE_URL = 'https://api.example.com';

// 私有成员：_前缀（可选）
class User {
  private _id: string;

  private _hashPassword() {}
}

// 布尔值：is/has/can 前缀
const isAuthenticated = true;
const hasPermission = false;
const canEdit = true;

Step 5: index.ts 배럴 파일

步骤5：index.ts 桶文件

components/ui/index.ts:
typescript
// ✅ 좋은 예: Named exports 재export
export { Button } from './Button/Button';
export { Input } from './Input/Input';
export { Modal } from './Modal/Modal';

// 사용:
import { Button, Input } from '@/components/ui';
❌ 나쁜 예:
typescript
// 모든 것을 재export (tree-shaking 저해)
export * from './Button';
export * from './Input';
components/ui/index.ts:
typescript
// ✅ 推荐：具名导出重导出
export { Button } from './Button/Button';
export { Input } from './Input/Input';
export { Modal } from './Modal/Modal';

// 使用方式:
import { Button, Input } from '@/components/ui';
❌ 不推荐:
typescript
// 全部重导出（不利于Tree Shaking）
export * from './Button';
export * from './Input';

Output format

输出格式

프로젝트 템플릿

项目模板

my-app/
├── .github/
│   └── workflows/
├── public/
├── src/
│   ├── app/
│   ├── components/
│   ├── lib/
│   ├── types/
│   └── config/
├── tests/
├── docs/
├── scripts/
├── .env.example
├── .gitignore
├── .eslintrc.json
├── .prettierrc
├── tsconfig.json
├── package.json
└── README.md
my-app/
├── .github/
│   └── workflows/
├── public/
├── src/
│   ├── app/
│   ├── components/
│   ├── lib/
│   ├── types/
│   └── config/
├── tests/
├── docs/
├── scripts/
├── .env.example
├── .gitignore
├── .eslintrc.json
├── .prettierrc
├── tsconfig.json
├── package.json
└── README.md

Constraints

约束条件

필수 규칙 (MUST)

必须遵循的规则（MUST）

  1. 일관성: 팀 전체가 같은 규칙 사용
  2. 명확한 폴더명: 역할이 명확해야 함
  3. 최대 깊이: 5단계 이하 권장
  1. 一致性：团队全员使用同一规则
  2. 清晰的文件夹名：明确体现其作用
  3. 最大深度：推荐不超过5级

금지 사항 (MUST NOT)

禁止事项（MUST NOT）

  1. 과도한 중첩: 폴더 깊이 7단계 이상 지양
  2. 모호한 이름: utils2/, helpers/, misc/ 지양
  3. 순환 의존성: A → B → A 참조 금지
  1. 过度嵌套：避免文件夹深度超过7级
  2. 模糊命名：避免使用utils2/、helpers/、misc/这类名称
  3. 循环依赖：禁止A → B → A的引用关系

Best practices

最佳实践

  1. Colocation: 관련 파일은 가까이 (컴포넌트 + 스타일 + 테스트)
  2. Feature-Based: 기능별로 모듈화
  3. Path Aliases: 
    @/
    사용으로 import 간소화
tsconfig.json:
json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  }
}
사용:
typescript
// ❌ 나쁜 예
import { Button } from '../../../components/ui/Button';

// ✅ 좋은 예
import { Button } from '@/components/ui';
  1. 就近原则：相关文件放置在一起（组件+样式+测试）
  2. 基于功能：按功能进行模块化
  3. 路径别名：使用
    @/
    简化导入路径
tsconfig.json:
json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  }
}
使用方式:
typescript
// ❌ 不推荐
import { Button } from '../../../components/ui/Button';

// ✅ 推荐
import { Button } from '@/components/ui';

References

参考资料

Metadata

元数据

버전

版本

  • 현재 버전: 1.0.0
  • 최종 업데이트: 2025-01-01
  • 호환 플랫폼: Claude, ChatGPT, Gemini
  • 当前版本：1.0.0
  • 最后更新：2025-01-01
  • 兼容平台：Claude, ChatGPT, Gemini

태그

标签

#file-organization
#project-structure
#folder-structure
#naming-conventions
#utilities
#file-organization
#project-structure
#folder-structure
#naming-conventions
#utilities

Examples

示例

Example 1: Basic usage

示例1：基础用法

<!-- Add example content here -->
<!-- 在此添加示例内容 -->

Example 2: Advanced usage

示例2：进阶用法

<!-- Add advanced example content here -->
<!-- 在此添加进阶示例内容 -->