用途:规范应用中相关实现文件的目录分组方式,涉及 index.ts 公共 API、导入路径与文件夹命名。不覆盖 Next.js 包导入优化、Fastify 路由结构或 Drizzle schema 设计。
主要原则:一个文件夹用于聚合 2 个以上同一关注点的实现文件;当所有导出共享同一运行时,index.ts 作为该组的公共 API;文件夹内部去掉文件夹名前缀(oauth-google.ts 改为 oauth/google.ts);文件夹外部通过组路径导入,内部直接导入同级文件;单文件模块保持为文件,测试与实现放在一起;混合运行时则使用带命名入口文件的文件夹,不设统一 index。
必须:文件夹名用 kebab-case;应用本地的组 index 使用具名再导出,避免 export * 巨型 barrel;创建文件夹前先解决同名冲突(auth.ts 与 auth/)。禁止:添加父级巨型 barrel(如 lib/index.ts、components/ui/index.ts);创建 foo/foo.ts 加一个薄再导出 index;在 Fastify 自动加载树(routes/、plugins/)中加 index.ts;将不同运行时的服务端与客户端模块统一到一个 index。建议:组 index 保持小而内聚(单一功能域);再导出可能引发导入循环时使用命名入口文件;优先使用已有包子路径而非新的根 barrel。仓库规则在指定例外时优先于该技能。
限制:假设使用带 .js 扩展名导入说明符的 TypeScript ESM,且采用 kebab-case 目录名。官方文档未提供具体安装命令与价格信息。