file-organizer

文件组织

概述

设计并维护组织良好的项目结构，使其能够随着团队和代码库的增长而扩展。本技能涵盖 monorepo 模式、按功能与按层组织的架构、命名约定、索引/聚合导出文件、配置文件的存放位置，以及文档结构。

每当需要建立、审查或重构项目的文件组织，以提升清晰度和可扩展性时，都应运用本技能。

多阶段流程

阶段 1：评估

1. 审查当前项目结构并找出痛点
2. 衡量项目规模（文件数、团队规模、功能数）
3. 找出现有命名约定和导入模式
4. 列出配置文件的位置
5. 检查循环依赖或过深的嵌套

停止 — 未了解当前状态及其痛点前，不要提出新结构。

阶段 2：策略选择

1. 使用下方决策表选择组织策略
2. 定义命名约定和文件存放规则
3. 规划聚合导出的边界
4. 制定配置文件存放规则
5. 记录导入顺序约定

停止 — 未记录目标结构并取得团队共识前，不要开始迁移。

阶段 3：迁移规划

1. 为现有项目规划迁移路径（渐进式，而非一次性全面迁移）
2. 确定需要移动的文件及其新位置
3. 梳理所需的导入变更
4. 尽可能创建自动化 codemod
5. 定义迁移出现问题时的回滚方案

停止 — 未确认每个渐进步骤后测试均通过前，不要执行迁移。

阶段 4：执行与验证

1. 一次移动一个功能或模块
2. 使用自动化工具更新导入
3. 每次移动后确认测试通过
4. 完成迁移后移除旧结构
5. 记录约定，供团队参考

架构策略决策表

项目规模	团队规模	建议	原因
< 20 个文件	1-2 名开发者	按层组织	简单，开销低
20-100 个文件	2-5 名开发者	混合式	兼顾简单性和可扩展性
100+ 个文件	5+ 名开发者	按功能组织	独立模块可减少冲突
多个应用共享代码	任意	Monorepo	共享包具有清晰边界
快速原型 / MVP	1-3 名开发者	按层组织	优先速度而非结构，之后再重构
企业级、多团队	10+ 名开发者	按功能组织 + Monorepo	每个功能模块由团队负责

架构模式

按功能组织（领域驱动）

按业务领域组织。每个功能都独立成模块。

src/
  features/
    auth/
      components/
        LoginForm.tsx
        SignupForm.tsx
      hooks/
        useAuth.ts
      api/
        auth.api.ts
      types/
        auth.types.ts
      utils/
        auth.utils.ts
      __tests__/
        auth.test.ts
      index.ts          # Public API (barrel export)
    dashboard/
      components/
      hooks/
      api/
      types/
      index.ts
    billing/
      ...
  shared/               # Cross-feature shared code
    components/
      Button.tsx
      Modal.tsx
    hooks/
      useDebounce.ts
    utils/
      format.ts
    types/
      common.types.ts

最适合：开发者超过 5 人的团队、中大型应用、领域边界清晰的项目。

按层组织（技术导向）

按技术关注点组织。

src/
  components/
    Button.tsx
    Modal.tsx
    LoginForm.tsx
    DashboardCard.tsx
  hooks/
    useAuth.ts
    useDebounce.ts
  services/
    auth.service.ts
    billing.service.ts
  utils/
    format.ts
    validation.ts
  types/
    auth.types.ts
    billing.types.ts
  pages/
    Home.tsx
    Dashboard.tsx

最适合：小型团队（1-3 人）、简单应用、快速原型开发。

混合式（默认推荐）

结合两种方式：共享层 + 功能模块。

src/
  app/                  # App-level concerns
    layout.tsx
    providers.tsx
    routes.tsx
  features/             # Feature modules
    auth/
    dashboard/
    billing/
  components/           # Shared UI components
    ui/                 # Design system atoms
    layout/             # Layout components
  hooks/                # Shared hooks
  lib/                  # Shared utilities
  types/                # Shared types
  config/               # App configuration
  styles/               # Global styles

Monorepo 模式

Turborepo / pnpm 工作区

root/
  apps/
    web/                # Next.js web app
      package.json
    api/                # API server
      package.json
    mobile/             # React Native app
      package.json
  packages/
    ui/                 # Shared component library
      package.json
    config/             # Shared configs (ESLint, TypeScript)
      eslint/
      typescript/
      package.json
    utils/              # Shared utilities
      package.json
    types/              # Shared type definitions
      package.json
  package.json          # Root workspace config
  turbo.json            # Turborepo pipeline config
  pnpm-workspace.yaml

包边界

• 应用可以依赖包，但不能依赖其他应用
• 包可以依赖其他包
• 不允许循环依赖
• 每个包都应职责清晰且单一
• 共享包通过 index.ts 聚合导出

配置共享

// packages/config/typescript/base.json
{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "target": "ES2022"
  }
}

// apps/web/tsconfig.json
{
  "extends": "@repo/config/typescript/nextjs",
  "include": ["src"]
}

命名约定

文件和目录

类型	约定	示例
组件	PascalCase	UserProfile.tsx
Hooks	以 use 为前缀的 camelCase	useAuth.ts
工具	camelCase	formatDate.ts
类型	以 .types 为后缀的 camelCase	auth.types.ts
测试	使用相同名称并以 .test 为后缀	UserProfile.test.tsx
样式	使用相同名称并以 .module.css 为后缀	UserProfile.module.css
常量	camelCase 或文件名中使用 UPPER_SNAKE	config.ts
API/服务	以 .api 或 .service 为后缀的 camelCase	auth.api.ts
目录	kebab-case	user-profile/

组件文件命名

# Single-file component
Button.tsx

# Component with co-located files
Button/
  Button.tsx
  Button.test.tsx
  Button.stories.tsx
  Button.module.css
  index.ts            # Re-exports Button

导入顺序约定

// 1. External packages
import React from 'react';
import { useQuery } from '@tanstack/react-query';

// 2. Internal packages (monorepo)
import { Button } from '@repo/ui';

// 3. Feature-level imports
import { useAuth } from '@/features/auth';

// 4. Relative imports (same feature)
import { LoginForm } from './LoginForm';
import { authSchema } from './auth.types';

// 5. Styles
import styles from './Auth.module.css';

索引文件与 Barrel 导出

Barrel 导出模式

// features/auth/index.ts — Public API
export { LoginForm } from './components/LoginForm';
export { useAuth } from './hooks/useAuth';
export type { User, AuthState } from './types/auth.types';

// Do NOT export internal implementation details
// Do NOT export utility functions used only within the feature

Barrel 导出决策表

场景	使用 Barrel？	原因
功能模块的公共 API	是，始终使用	边界清晰，表面范围可控
共享组件库	是，始终使用	为使用者提供统一的导入入口
工具库	是，始终使用	便于发现共享函数
功能内部	否	直接导入，避免间接引用
会导致循环依赖	否	打破循环，直接导入
会影响 Tree-shaking（已验证）	否	为缩小打包体积，使用直接导入

配置文件的位置

根目录配置

root/
  .editorconfig         # Editor settings
  .eslintrc.js          # ESLint config (or eslint.config.js)
  .gitignore            # Git ignore rules
  .prettierrc           # Prettier config
  .env.example          # Environment variable template
  docker-compose.yml    # Docker composition
  Dockerfile            # Container build
  package.json          # Dependencies and scripts
  tsconfig.json         # TypeScript config
  next.config.js        # Framework config
  tailwind.config.ts    # Tailwind config
  vitest.config.ts      # Test config

环境文件

.env                    # Local defaults (gitignored)
.env.example            # Template with dummy values (committed)
.env.local              # Local overrides (gitignored)
.env.development        # Development-specific (committed or not)
.env.production         # Production-specific (committed or not)
.env.test               # Test-specific (committed or not)

文档结构

docs/
  architecture/
    adr/                # Architecture Decision Records
      001-framework.md
      002-database.md
    diagrams/
  api/                  # API documentation
  guides/
    getting-started.md
    deployment.md
  contributing.md

迁移策略

增量迁移（推荐）

1. 在现有代码旁创建目标结构
2. 一次迁移一个功能／模块
3. 使用自动化 codemod 更新导入
4. 每次迁移后通过测试进行验证
5. 完成迁移后移除旧结构

自动化工具

• ts-morph：以编程方式重构 TypeScript
• jscodeshift：JavaScript codemod
• IDE 重构：重命名／移动时自动更新导入
• ESLint import/order：强制执行导入顺序

反模式／常见错误

反模式	失败原因	替代做法
文件夹嵌套过深（> 4 层）	难以浏览，导入路径过长	扁平化结构，使用路径别名
将 utils/ 当作杂物堆	最终变成难以维护的杂物抽屉	按领域或用途组织工具
功能之间存在循环依赖	构建失败，归属不明确	功能只从共享模块或自身模块导入
Barrel 导出重新导出所有内容	破坏 Tree-shaking，导致打包体积膨胀	只导出公共 API
命名不一致（混用多种规范）	增加认知负担，引发合并冲突	选定一种规范，并用 linter 强制执行
配置散落在多个位置	难以查找和维护	将所有配置放在项目根目录
测试放在单独的目录树中	难以找到对应文件的测试	将测试与源代码放在一起
一个扁平文件夹中有 100+ 个文件	无法浏览	按子模块或功能分组
索引文件中包含逻辑	导入时会产生意外的副作用	索引文件只用于重新导出
一次性大规模迁移（一次移动所有内容）	风险高，难以回滚	增量移动，每次移动后运行测试

防止自我合理化的约束

• 不要在不了解当前痛点的情况下重组——先评估。
• 不要跳过团队对齐步骤——结构变更会影响所有人。
• 不要一次迁移所有内容——每次移动一个模块，并通过测试验证。
• 不要为了“未来可扩展性”创建深层嵌套结构——在复杂度要求之前，保持结构扁平。
• 不要忽视 Barrel 导出对打包体积的影响——使用打包分析器进行验证。

集成点

技能	关联方式
senior-frontend	前端项目结构采用基于功能或混合模式
senior-architect	架构决策决定模块边界和包结构
senior-fullstack	全栈项目需要协调前端／后端的组织方式
clean-code	命名规范和模块边界有助于践行整洁代码原则
deployment	Monorepo 结构会影响 CI/CD 流水线配置
laravel-specialist	Laravel 项目遵循框架特定的目录规范

技能类型

FLEXIBLE — 选择适合项目规模、团队结构和复杂度的组织策略。命名规范和 Barrel 导出模式仅为建议，应根据现有项目规范进行调整。