SuperAPI AI 工具集

business-logic-entry-point-command-query-separation

智能体与模型

查看项目

更新于 10-15 20:13

技能介绍

用途:在业务逻辑入口点实施命令-查询分离(CQS)。每个业务逻辑入口点必须恰好属于其一:命令(改变状态)或查询(返回数据而不改变状态),不得在同一入口点混合两者。该技能只约束 CQS,不要求 CQRS 式的读写模型、存储、服务拆分或分布式架构改造。

适用范围:定义启动业务流程的公共函数或方法、用例、应用服务方法、交互器、处理器、外观等业务逻辑入口点;修改业务操作返回形态;在同一业务入口点组合读写行为;向业务逻辑调用方暴露命令或查询行为。

规则:命令改变业务状态,不得返回业务数据,可用 void、unit、undefined、None 或等价形式;若项目使用结果包装或错误信封,可保留但不添加读模型载荷。创建命令是唯一例外,只能返回新建领域实体的 ID,若一次创建多个实体则返回 ID 集合,不得返回完整实体、读模型、派生业务数据或其他载荷。查询不得改变业务状态,不得持久化写入、发出改变状态的副作用、转换实体状态或触发改状态工作流,应保持观测性。若入口点同时改状态和返回数据,应拆分为命令与查询,或由调用方在命令后追加查询。

检测流程:先找出业务逻辑入口点(调用方触发业务行为的公共函数、方法、处理器、用例),判断其是否改变状态(创建、更新、删除、审批、分配、排期、取消等或触发相关副作用),再判断是否返回数据(领域实体、读模型、DTO、计数、列表、布尔值、摘要等)。若两者兼有,除创建命令仅返回 ID 外均属违规。应依据实际行为与返回形态做语义判断,不要仅凭 get、create、handle、execute 等命名。

编写或修改:先确定角色再写代码,命令写成状态变更操作且返回值最小化,查询写成只读操作且不含状态变更。重构混合入口点时把写行为移入命令、读数据移入查询,调用方在需要额外数据时于命令后自行查询,并让角色在方法行为、返回类型与 API 中清晰可见。

评审问题:该入口点是命令还是查询?是否改变业务状态?是否返回业务数据?若是命令,除创建操作的 ID 外是否还返回其他内容?若是查询,是否真正无状态变更?

报告结果:说明识别或修改了哪些入口点、哪些是命令哪些是查询、在何处移除或阻止了混合行为、创建命令是否只返回新建实体 ID。资料未提供具体安装命令、代码示例或平台细节。