file-organization

技能：文件组织

适用范围

• 适用于：在应用和软件包中分组相关实现文件、index.ts 公共 API、导入路径、文件夹命名
• 不适用于：Next.js 的 lucide 风格软件包导入优化、Fastify 路由结构或 Drizzle 架构设计

假设

• 使用 TypeScript ESM，导入说明符中带 .js 扩展名
• 目录名称采用 kebab-case
• 应用本地分组索引使用命名再导出；如果文件夹是已发布的模块边界，软件包子路径可以使用 export *

原则

• 一个文件夹用于分组同一关注点的 2+ 个实现文件
• 当所有导出共享同一运行时，index.ts 就是该分组的公共 API
• 在文件夹内省略文件夹名称前缀（oauth-google.ts → oauth/google.ts）
• 在文件夹外导入分组（.../feature/index.js）；在文件夹内直接导入同级文件
• 单文件模块保持为文件；测试与实现文件放在一起
• 运行时不同 → 使用包含命名入口文件的文件夹，不设统一索引

约束

必须

• 文件夹名称使用 kebab-case
• 应用本地分组索引使用命名再导出（避免使用 export * 的大型汇总文件）
• 创建文件夹前解决基础名称冲突（auth.ts 与 auth/）

禁止

• 添加父级大型汇总文件（lib/index.ts、components/ui/index.ts）
• 创建 foo/foo.ts 并搭配一个简单的再导出索引
• 在 Fastify 自动加载目录树（routes/、plugins/）中添加 index.ts
• 当服务端和客户端模块使用不同运行时时，将它们统一到同一个索引中

应当

• 保持分组索引精简且内聚（专注于一个功能领域）
• 再导出会产生导入循环时，使用命名入口文件
• 优先使用现有软件包子路径，而非新增根级汇总文件

交互

• 与 next-v16 互补（汇总导入优化 ≠ 功能分组索引）
• 与 typescript-v6 互补（ESM 路径、命名导出）
• 仓库规则如有例外规定（catalogs mapper、Drizzle 架构索引），则以仓库规则为准

模式

分组索引（相同运行时）

oauth/
  shared.ts
  google.ts
  index.ts    # named re-exports only

使用方：import { getOAuthAllowedCallbackUrls } from '../lib/oauth/index.js'

拆分运行时（无统一索引）

logger/
  server.ts
  client.ts
  # no index.ts

使用方直接导入命名入口文件（logger/server、logger/client）。

命名入口（避免循环）

catalogs/
  index.ts      # dictionaries only
  mapper.ts     # imports from ./index.js — not re-exported

反模式

模式	原因
同一级别堆满带前缀的文件	难以浏览；应使用文件夹
lib/index.ts 再导出所有内容	大型汇总文件；会拖慢构建并模糊边界
auth.ts 与 auth/ 并存	容易引发模块解析问题
将 cookies 与 document 放在统一索引中	会破坏服务端/客户端边界