用途:让业务逻辑入口点(handler、用例、应用服务方法)保持自包含。当入口点签名中的参数类型或返回类型由项目自行声明时,只要技术栈允许,就应把这些类型放在与入口点相同的文件里,打开一个文件即可看到完整签名及其输入输出结构,无需跳转其他文件。
主要能力与适用范围:适用于声明带项目声明参数/返回类型的入口点;把 command、query、success、error 类型放到与使用它们的入口点分离的文件;为属于单个入口点的类型创建共享类型模块或 barrel 导出;从其他文件导入签名类型到入口点模块。项目声明类型包括 command/query/success/error 类型、为特定入口点声明的 DTO、值对象、载荷类型,以及项目声明的类型别名、接口、结构体、类、枚举等。不包括标准库类型、第三方库或框架类型、跨多个入口点共享的领域实体类型、原始类型或内置泛型。
规则:入口点签名中使用的项目声明类型必须与该入口点声明在同一文件;command 或 query 类型、success 类型与 handler 同文件;error 类型也同文件,除非被多个入口点共享;不要为单个入口点的类型单独建文件,也不要把 CreateReservationCommand 放在 create-reservation-command.ts 而 handler 放在 create-reservation-command-handler.ts。跨多个入口点共享的类型(领域实体、共享错误类型、共享值对象等)可保留在各自模块,豁免此规则。仅当技术栈允许时应用:某些语言或框架强制一文件一类型(如 Java 一个公开类一文件),此时应遵循语言或框架约定;语言允许多个类型定义在同一文件时才应用此规则。
检测流程:找到业务逻辑入口点,识别 handler 函数、用例或应用服务方法;检查签名类型,列出参数与返回类型,判断哪些是项目声明类型;检查每个项目声明类型声明位置,若与入口点不在同一文件则违反规则;若被多个入口点共享则豁免;检查项目技术栈是否强制一文件一类型,若强制则规则不适用。
编写或修改入口点:把签名类型声明在入口点同文件,将 command/query 类型、success 类型、入口点专属 error 类型与 handler 写在同一文件;不要预先创建类型文件;新建入口点时只建一个文件并放入全部内容;仅当类型变为共享时才抽到独立模块,若第二个入口点需要同一类型,此时再移动。
自检问题:入口点签名中是否有项目声明类型位于其他文件?这些类型是否只被该入口点使用?项目技术栈是否允许一文件多类型定义?把这些类型移入入口点文件是否会使模块自包含?若答案为是则应用。
报告结果:说明识别或修改了哪些入口点、哪些类型被归并到入口点文件、哪些类型因共享保留在独立模块、项目技术栈是否对归并施加了限制。