project-structure-enforcer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Enforce 2026 folder structure best practices with BLOCKING validation.

通过强制拦截式验证，强制执行2026年文件夹结构最佳实践。

Validation Rules

验证规则

BLOCKING Rules (exit 1)

拦截式规则（触发时退出码为1）

Rule	Check	Example Violation
Max Nesting	Max 4 levels from src/ or app/	`src/a/b/c/d/e/file.ts`
No Barrel Files	No index.ts re-exports	`src/components/index.ts`
Component Location	React components in components/ or features/	`src/utils/Button.tsx`
Hook Location	Custom hooks in hooks/ directory	`src/components/useAuth.ts`
Import Direction	Unidirectional: shared → features → app	`features/` importing from `app/`

规则	检查内容	违规示例
最大嵌套深度	从src/或app/开始最多4级嵌套	`src/a/b/c/d/e/file.ts`
禁止桶文件	不允许使用仅用于重新导出的index.ts	`src/components/index.ts`
组件位置	React组件必须放在components/或features/目录下	`src/utils/Button.tsx`
Hook位置	自定义Hook必须放在hooks/目录下	`src/components/useAuth.ts`
导入方向	单向导入：shared → features → app	`features/` 从 `app/` 导入内容

Expected Folder Structures

预期的文件夹结构

React/Next.js (Frontend)

React/Next.js（前端）

src/
├── app/              # Next.js App Router (pages)
│   ├── (auth)/       # Route groups
│   ├── api/          # API routes
│   └── layout.tsx
├── components/       # Reusable UI components
│   ├── ui/           # Primitive components
│   └── forms/        # Form components
├── features/         # Feature modules (self-contained)
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types.ts
│   └── dashboard/
├── hooks/            # Global custom hooks
├── lib/              # Third-party integrations
├── services/         # API clients
├── types/            # Global TypeScript types
└── utils/            # Pure utility functions

src/
├── app/              # Next.js App Router（页面）
│   ├── (auth)/       # 路由组
│   ├── api/          # API路由
│   └── layout.tsx
├── components/       # 可复用UI组件
│   ├── ui/           # 基础组件
│   └── forms/        # 表单组件
├── features/         # 功能模块（独立封装）
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types.ts
│   └── dashboard/
├── hooks/            # 全局自定义Hook
├── lib/              # 第三方集成
├── services/         # API客户端
├── types/            # 全局TypeScript类型
└── utils/            # 纯工具函数

FastAPI (Backend)

FastAPI（后端）

app/
├── routers/          # API route handlers
│   ├── router_users.py
│   ├── router_auth.py
│   └── deps.py       # Shared dependencies
├── services/         # Business logic layer
│   ├── user_service.py
│   └── auth_service.py
├── repositories/     # Data access layer
│   ├── user_repository.py
│   └── base_repository.py
├── schemas/          # Pydantic models
│   ├── user_schema.py
│   └── auth_schema.py
├── models/           # SQLAlchemy models
│   ├── user_model.py
│   └── base.py
├── core/             # Config, security, deps
│   ├── config.py
│   ├── security.py
│   └── database.py
└── utils/            # Utility functions

app/
├── routers/          # API路由处理器
│   ├── router_users.py
│   ├── router_auth.py
│   └── deps.py       # 共享依赖
├── services/         # 业务逻辑层
│   ├── user_service.py
│   └── auth_service.py
├── repositories/     # 数据访问层
│   ├── user_repository.py
│   └── base_repository.py
├── schemas/          # Pydantic模型
│   ├── user_schema.py
│   └── auth_schema.py
├── models/           # SQLAlchemy模型
│   ├── user_model.py
│   └── base.py
├── core/             # 配置、安全、依赖
│   ├── config.py
│   ├── security.py
│   └── database.py
└── utils/            # 工具函数

Nesting Depth Rules

嵌套深度规则

Maximum 4 levels from

src/

app/

ALLOWED (4 levels):
  src/features/auth/components/LoginForm.tsx
  app/routers/v1/users/router_users.py

BLOCKED (5+ levels):
  src/features/dashboard/widgets/charts/line/LineChart.tsx
  ↳ Flatten to: src/features/dashboard/charts/LineChart.tsx

从

src/

或

app/

开始最多允许4级嵌套：

允许（4级）：
  src/features/auth/components/LoginForm.tsx
  app/routers/v1/users/router_users.py

禁止（5级及以上）：
  src/features/dashboard/widgets/charts/line/LineChart.tsx
  ↳ 扁平化处理为：src/features/dashboard/charts/LineChart.tsx

No Barrel Files

禁止桶文件

Barrel files (

index.ts

that only re-export) cause tree-shaking issues with Vite/webpack:

typescript

// BLOCKED: src/components/index.ts
export { Button } from './Button';
export { Input } from './Input';
export { Modal } from './Modal';

// GOOD: Import directly
import { Button } from '@/components/Button';
import { Input } from '@/components/Input';

Why? Barrel files:

Break tree-shaking (entire barrel is imported)
Cause circular dependency issues
Slow down build times
Make debugging harder

桶文件（仅用于重新导出的

index.ts

）会导致Vite/webpack的Tree Shaking失效：

typescript

// 禁止：src/components/index.ts
export { Button } from './Button';
export { Input } from './Input';
export { Modal } from './Modal';

// 推荐：直接导入
import { Button } from '@/components/Button';
import { Input } from '@/components/Input';

原因？ 桶文件：

破坏Tree Shaking机制（整个桶文件会被导入）
引发循环依赖问题
增加构建时间
增加调试难度

Import Direction (Unidirectional Architecture)

导入方向（单向架构）

Code must flow in ONE direction:

┌─────────────────────────────────────────────────────────┐
│                                                         │
│   shared/lib  →  components  →  features  →  app       │
│                                                         │
│   (lowest)                                 (highest)    │
│                                                         │
└─────────────────────────────────────────────────────────┘

代码必须遵循单一方向的依赖流：

┌─────────────────────────────────────────────────────────┐
│                                                         │
│   shared/lib  →  components  →  features  →  app       │
│                                                         │
│   (最低层级)                          (最高层级)          │
│                                                         │
└─────────────────────────────────────────────────────────┘

Allowed Imports

允许的导入

Layer	Can Import From
`shared/` , `lib/`	Nothing (base layer)
`components/`	`shared/` , `lib/` , `utils/`
`features/`	`shared/` , `lib/` , `components/` , `utils/`
`app/`	Everything above

层级	可导入的来源
`shared/` , `lib/`	无（基础层级）
`components/`	`shared/` , `lib/` , `utils/`
`features/`	`shared/` , `lib/` , `components/` , `utils/`
`app/`	以上所有层级

Blocked Imports

禁止的导入

typescript

// BLOCKED: shared/ importing from features/
// File: src/shared/utils.ts
import { authConfig } from '@/features/auth/config';  // ❌

// BLOCKED: features/ importing from app/
// File: src/features/auth/useAuth.ts
import { RootLayout } from '@/app/layout';  // ❌

// BLOCKED: Cross-feature imports
// File: src/features/auth/useAuth.ts
import { DashboardContext } from '@/features/dashboard/context';  // ❌
// Fix: Extract to shared/ if needed by multiple features

typescript

// 禁止：shared/从features/导入
// 文件：src/shared/utils.ts
import { authConfig } from '@/features/auth/config';  // ❌

// 禁止：features/从app/导入
// 文件：src/features/auth/useAuth.ts
import { RootLayout } from '@/app/layout';  // ❌

// 禁止：跨功能模块导入
// 文件：src/features/auth/useAuth.ts
import { DashboardContext } from '@/features/dashboard/context';  // ❌
// 修复方案：如果多个功能模块需要，提取到shared/目录

Type-Only Imports (Exception)

仅类型导入（例外情况）

Type-only imports across features are allowed:

typescript

// ALLOWED: Type-only import from another feature
import type { User } from '@/features/users/types';

跨功能模块的仅类型导入是允许的：

typescript

// 允许：从其他功能模块仅导入类型
import type { User } from '@/features/users/types';

Component Location Rules

组件位置规则

React Components (PascalCase .tsx)

React组件（大驼峰命名.tsx）

ALLOWED:
  src/components/Button.tsx
  src/components/ui/Card.tsx
  src/features/auth/components/LoginForm.tsx
  src/app/dashboard/page.tsx

BLOCKED:
  src/utils/Button.tsx       # Components not in utils/
  src/services/Modal.tsx     # Components not in services/
  src/hooks/Dropdown.tsx     # Components not in hooks/

允许：
  src/components/Button.tsx
  src/components/ui/Card.tsx
  src/features/auth/components/LoginForm.tsx
  src/app/dashboard/page.tsx

禁止：
  src/utils/Button.tsx       # 组件不能放在utils/目录
  src/services/Modal.tsx     # 组件不能放在services/目录
  src/hooks/Dropdown.tsx     # 组件不能放在hooks/目录

Custom Hooks (useX pattern)

自定义Hook（useX命名模式）

ALLOWED:
  src/hooks/useAuth.ts
  src/hooks/useLocalStorage.ts
  src/features/auth/hooks/useLogin.ts

BLOCKED:
  src/components/useAuth.ts   # Hooks not in components/
  src/utils/useDebounce.ts    # Hooks not in utils/
  src/services/useFetch.ts    # Hooks not in services/

允许：
  src/hooks/useAuth.ts
  src/hooks/useLocalStorage.ts
  src/features/auth/hooks/useLogin.ts

禁止：
  src/components/useAuth.ts   # Hook不能放在components/目录
  src/utils/useDebounce.ts    # Hook不能放在utils/目录
  src/services/useFetch.ts    # Hook不能放在services/目录

Python File Location Rules

Python文件位置规则

Routers

路由文件

ALLOWED:
  app/routers/router_users.py
  app/routers/routes_auth.py
  app/routers/api_v1.py

BLOCKED:
  app/users_router.py          # Not in routers/
  app/services/router_users.py # Router in services/

允许：
  app/routers/router_users.py
  app/routers/routes_auth.py
  app/routers/api_v1.py

禁止：
  app/users_router.py          # 不能放在routers/目录外
  app/services/router_users.py # 路由文件不能放在services/目录

Services

服务文件

ALLOWED:
  app/services/user_service.py
  app/services/auth_service.py

BLOCKED:
  app/user_service.py           # Not in services/
  app/routers/user_service.py   # Service in routers/

允许：
  app/services/user_service.py
  app/services/auth_service.py

禁止：
  app/user_service.py           # 不能放在services/目录外
  app/routers/user_service.py   # 服务文件不能放在routers/目录

Common Violations

常见违规情况

1. Too Deep Nesting

1. 嵌套过深

BLOCKED: Max nesting depth exceeded: 5 levels (max: 4)
  File: src/features/dashboard/widgets/charts/line/LineChart.tsx
  Consider flattening: src/features/dashboard/charts/LineChart.tsx

禁止：超过最大嵌套深度：5级（最大允许4级）
  文件：src/features/dashboard/widgets/charts/line/LineChart.tsx
  建议扁平化处理为：src/features/dashboard/charts/LineChart.tsx

2. Barrel File Created

2. 创建了桶文件

BLOCKED: Barrel files (index.ts) discouraged - causes tree-shaking issues
  File: src/components/index.ts
  Import directly from source files instead

禁止：不推荐使用桶文件（index.ts）——会导致Tree Shaking失效
  文件：src/components/index.ts
  建议直接从源文件导入

3. Component in Wrong Location

3. 组件位置错误

BLOCKED: React components must be in components/, features/, or app/
  File: src/utils/Button.tsx
  Move to: src/components/Button.tsx

禁止：React组件必须放在components/、features/或app/目录下
  文件：src/utils/Button.tsx
  建议移动到：src/components/Button.tsx

4. Invalid Import Direction

4. 导入方向违规

BLOCKED: Import direction violation (unidirectional architecture)
  features/ cannot import from app/
  Import direction: features -> shared, lib, components

Allowed flow: shared/lib -> components -> features -> app

禁止：导入方向违规（单向架构要求）
  features/不能从app/导入
  允许的导入流向：features → shared, lib, components

正确依赖流：shared/lib → components → features → app

5. Cross-Feature Import

5. 跨功能模块导入

BLOCKED: Cannot import from other features (cross-feature dependency)
  File: src/features/auth/useAuth.ts
  Import: from '@/features/dashboard/context'
  Extract shared code to shared/ or lib/

禁止：不能从其他功能模块导入（跨功能模块依赖）
  文件：src/features/auth/useAuth.ts
  导入来源：@/features/dashboard/context
  建议将共享代码提取到shared/或lib/目录

Migration Guide

迁移指南

Flattening Deep Nesting

扁平化过深的嵌套

bash

undefined

bash

undefined

Before (5 levels)

迁移前（5级）

src/features/dashboard/widgets/charts/line/LineChart.tsx src/features/dashboard/widgets/charts/line/LineChartTooltip.tsx

After (4 levels) - Flatten last two levels

迁移后（4级）——合并最后两级目录

src/features/dashboard/charts/LineChart.tsx src/features/dashboard/charts/LineChartTooltip.tsx

undefined

src/features/dashboard/charts/LineChart.tsx src/features/dashboard/charts/LineChartTooltip.tsx

undefined

Removing Barrel Files

移除桶文件

bash

undefined

bash

undefined

Before

迁移前

src/components/index.ts # Re-exports everything import { Button, Input } from '@/components';

src/components/index.ts # 重新导出所有组件 import { Button, Input } from '@/components';

After - Direct imports

迁移后——直接导入

import { Button } from '@/components/Button'; import { Input } from '@/components/Input';

undefined

import { Button } from '@/components/Button'; import { Input } from '@/components/Input';

undefined

Fixing Cross-Feature Imports

修复跨功能模块导入

bash

undefined

bash

undefined

Before - Cross-feature dependency

迁移前——跨功能模块依赖

src/features/auth/useAuth.ts imports from src/features/users/types

src/features/auth/useAuth.ts 从 src/features/users/types 导入

After - Extract to shared

迁移后——提取到shared目录

src/shared/types/user.ts src/features/auth/useAuth.ts imports from src/shared/types/user src/features/users/... imports from src/shared/types/user

undefined

src/shared/types/user.ts src/features/auth/useAuth.ts 从 src/shared/types/user 导入 src/features/users/... 从 src/shared/types/user 导入

undefined

Related Skills

Capability Details

能力详情

folder-structure

Keywords: folder structure, directory structure, project layout, organization Solves:

Enforce feature-based organization
Validate proper file placement
Maintain consistent project structure

关键词： 文件夹结构、目录结构、项目布局、组织方式 解决的问题：

强制执行基于功能的组织方式
校验文件的正确放置
维护一致的项目结构

nesting-depth

Keywords: nesting, depth, levels, max depth, deep nesting Solves:

Limit directory nesting to 4 levels
Prevent overly complex structures
Improve navigability

关键词： 嵌套、深度、层级、最大深度、过深嵌套 解决的问题：

限制目录嵌套为4级
避免过于复杂的结构
提升可导航性

import-direction

Keywords: import, unidirectional, circular, dependency direction Solves:

Enforce unidirectional imports
Prevent circular dependencies
Maintain clean architecture

关键词： 导入、单向、循环、依赖方向 解决的问题：

强制执行单向导入规则
防止循环依赖
维护清晰的架构

component-location

Keywords: component location, file placement, where to put Solves:

Validate React component placement
Enforce hook location rules
Block barrel files

关键词： 组件位置、文件放置、存放位置 解决的问题：

校验React组件的放置位置
强制执行Hook位置规则
阻止桶文件的使用

project-structure-enforcer

Original

Translation

Validation Rules

验证规则

BLOCKING Rules (exit 1)

拦截式规则（触发时退出码为1）

Expected Folder Structures

预期的文件夹结构

React/Next.js (Frontend)

React/Next.js（前端）

FastAPI (Backend)

FastAPI（后端）

Nesting Depth Rules

嵌套深度规则

No Barrel Files

禁止桶文件

Import Direction (Unidirectional Architecture)

导入方向（单向架构）

Allowed Imports

允许的导入

Blocked Imports

禁止的导入

Type-Only Imports (Exception)

仅类型导入（例外情况）

Component Location Rules

组件位置规则

React Components (PascalCase .tsx)

React组件（大驼峰命名.tsx）

Custom Hooks (useX pattern)

自定义Hook（useX命名模式）

Python File Location Rules

Python文件位置规则

Routers

路由文件

Services

服务文件

Common Violations

常见违规情况

1. Too Deep Nesting

1. 嵌套过深

2. Barrel File Created

2. 创建了桶文件

3. Component in Wrong Location

3. 组件位置错误

4. Invalid Import Direction

4. 导入方向违规

5. Cross-Feature Import

5. 跨功能模块导入

Migration Guide

迁移指南

Flattening Deep Nesting

扁平化过深的嵌套

Before (5 levels)

迁移前（5级）

After (4 levels) - Flatten last two levels

迁移后（4级）——合并最后两级目录

Removing Barrel Files

移除桶文件

Before

迁移前

After - Direct imports

迁移后——直接导入

Fixing Cross-Feature Imports

修复跨功能模块导入

Before - Cross-feature dependency

迁移前——跨功能模块依赖

After - Extract to shared

迁移后——提取到shared目录

Related Skills

相关技能

Capability Details

能力详情

folder-structure

folder-structure

nesting-depth

nesting-depth

import-direction

import-direction

component-location