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

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                  # 入口文件

步骤 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/                   # 跨功能共享
│   ├── components/
│   ├── hooks/
│   ├── utils/
│   └── types/
│
└── core/                     # 应用核心
    ├── store/
    ├── router/
    └── config/

步骤 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/)

✅ 一致性是关键 (整个团队使用相同的规则)

变量/函数名 :

// 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 前缀
const isAuthenticated = true;
const hasPermission = false;
const canEdit = true;

步骤 5: index.ts 桶文件

components/ui/index.ts :

// ✅ 好的示例: 重新导出命名导出
export { Button } from './Button/Button';
export { Input } from './Input/Input';
export { Modal } from './Modal/Modal';

// 用法:
import { Button, Input } from '@/components/ui';

❌ 不好的示例 :

// 重新导出所有内容 (影响 tree-shaking)
export * from './Button';
export * from './Input';

输出格式

项目模板

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

约束条件

必须遵守的规则 (MUST)

1. 一致性 : 整个团队使用相同的规则
2. 清晰的文件夹名称 : 角色必须明确
3. 最大深度 : 建议 5 层或更少

禁止事项 (MUST NOT)

1. 过度嵌套 : 避免 7 层以上的文件夹深度
2. 模糊的名称 : 避免 utils2/, helpers/, misc/
3. 循环依赖 : 禁止 A → B → A 的引用

最佳实践

1. 就近放置 : 将相关文件放在一起 (组件 + 样式 + 测试)
2. 基于功能 : 按功能模块化
3. 路径别名 : 使用 @/ 简化导入

tsconfig.json :

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  }
}

用法 :

// ❌ 不好的示例
import { Button } from '../../../components/ui/Button';

// ✅ 好的示例
import { Button } from '@/components/ui';

参考资料

• React 文件结构
• Node.js 最佳实践
• 整洁架构

元数据

版本信息

• 当前版本 : 1.0.0
• 最后更新 : 2025-01-01
• 兼容平台 : Claude, ChatGPT, Gemini

标签

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

示例

示例 1: 基本用法

示例 2: 高级用法

每周安装次数

1

代码仓库

akillness/oh-my-gods

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

mcpjam1

claude-code1

replit1

junie1

windsurf1

zencoder1

Step 2: Node.js/Express Backend Structure

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

Step 3: Feature-Based Structure (Large-Scale Apps)

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/

Step 4: Naming Conventions

File Names :

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

Folder Names :

kebab-case:       user-profile/
camelCase:        userProfile/       (optional: hooks/, utils/)
PascalCase:       UserProfile/       (optional: components/)

✅ Consistency is key (entire team uses the same rules)

Variable/Function Names :

// Components: PascalCase
const UserProfile = () => {};

// Functions: camelCase
function getUserById() {}

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

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

  private _hashPassword() {}
}

// Booleans: is/has/can prefix
const isAuthenticated = true;
const hasPermission = false;
const canEdit = true;

Step 5: index.ts Barrel Files

components/ui/index.ts :

// ✅ Good example: Re-export named exports
export { Button } from './Button/Button';
export { Input } from './Input/Input';
export { Modal } from './Modal/Modal';

// Usage:
import { Button, Input } from '@/components/ui';

❌ Bad example :

// Re-export everything (impairs tree-shaking)
export * from './Button';
export * from './Input';

Output format

Project Template

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

Required Rules (MUST)

1. Consistency : Entire team uses the same rules
2. Clear Folder Names : Roles must be explicit
3. Max Depth : Recommend 5 levels or fewer

Prohibited (MUST NOT)

1. Excessive Nesting : Avoid 7+ levels of folder depth
2. Vague Names : Avoid utils2/, helpers/, misc/
3. Circular Dependencies : Prohibit A → B → A references

Best practices

1. Colocation : Keep related files close (component + styles + tests)
2. Feature-Based : Modularize by feature
3. Path Aliases : Simplify imports with @/

tsconfig.json :

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  }
}

Usage :

// ❌ Bad example
import { Button } from '../../../components/ui/Button';

// ✅ Good example
import { Button } from '@/components/ui';

References

• React File Structure
• Node.js Best Practices
• Clean Architecture

Metadata

Version

• Current Version : 1.0.0
• Last Updated : 2025-01-01
• Compatible Platforms : Claude, ChatGPT, Gemini

Tags

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

Examples

Example 1: Basic usage

Example 2: Advanced usage

Weekly Installs

1

Repository

akillness/oh-my-gods

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

mcpjam1

claude-code1

replit1

junie1

windsurf1

zencoder1