🚀 快速安装

复制以下命令并运行，立即安装此 Skill：

npx @anthropic-ai/skills install supercent-io/skills-template/file-organization

💡 提示：需要 Node.js 和 NPM

项目文件组织

何时使用此技能

  • 新项目：初始文件夹结构设计
  • 项目增长：当复杂性增加时进行重构
  • 团队标准化：建立一致的结构

指示

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

src/
├── app/                      # Next.js 13+ 应用路由器
│   ├── (auth)/               # 路由组
│   │   ├── login/
│   │   └── signup/
│   ├── (dashboard)/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── settings/
│   ├── api/                  # API 路由
│   │   ├── auth/
│   │   └── users/
│   └── layout.tsx
│
├── components/               # UI 组件
│   ├── ui/                   # 可复用 UI（按钮、输入框）
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.test.tsx
│   │   │   └── index.ts
│   │   └── Input/
│   ├── layout/               # 布局组件（页眉、页脚）
│   ├── 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

步骤 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：命名约定

文件命名：

组件：         帕斯卡命名.tsx
钩子：         驼峰命名.ts        (useAuth.ts)
工具函数：     驼峰命名.ts        (formatDate.ts)
常量：         大写蛇形命名.ts (API_ENDPOINTS.ts)
类型：         驼峰命名.types.ts  (user.types.ts)
测试：         *.test.ts， *.spec.ts

文件夹命名：

短横线命名：   user-profile/
驼峰命名：     userProfile/       （可选：hooks/， utils/）
帕斯卡命名：   UserProfile/       （可选：components/）

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

变量/函数命名：

// 组件：帕斯卡命名
const UserProfile = () => {};

// 函数：驼峰命名
function getUserById() {}

// 常量：大写蛇形命名
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;

步骤 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';

❌ 反面示例：

// 重新导出所有内容（影响摇树优化）
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

约束条件

必需规则（必须遵守）

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

禁止事项（不得违反）

  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';

参考资料

元数据

版本

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

标签

#文件组织 #项目结构 #文件夹结构 #命名约定 #实用工具

示例

示例 1：基本用法

示例 2：高级用法

📄 原始文档

完整文档（英文）：

https://skills.sh/supercent-io/skills-template/file-organization

💡 提示：点击上方链接查看 skills.sh 原始英文文档，方便对照翻译。

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。