SuperAPI AI 工具集

codeprobe-architecture

编程与开发

查看项目

更新于 10-29 16:14

技能介绍

codeprobe-architecture 是 codeprobe 技能集中的架构与结构分析子技能,用于在代码审查中识别架构层面的问题,并以 ARCH-xxx 编号输出发现项。

一、使用方式 该技能可独立运行:若直接调用(非通过编排器),需先读取同级的 codeprobe 技能目录下的 shared-preamble.md,以获得输出契约、执行模式与约束;再根据项目技术栈加载 codeprobe/references/ 下的相关参考文件。未特别指定时默认使用 full 模式。若通过 /codeprobe audit 或 /codeprobe architecture 调用,编排器会预先运行 scripts/dependency_mapper.py 生成依赖图,并以 === DEPENDENCY_GRAPH === 标记提供 JSON 数据,供技能直接使用。

二、主要检测能力

  1. 分层违规:检查控制器中是否含数据库查询、复杂业务条件、计算或校验逻辑;模型中是否含 HTML 生成、展示格式化等表现层逻辑;视图模板中是否直接调用数据库或 ORM。
  2. 循环依赖:优先使用预加载依赖图的 circular_dependencies 数组,每个循环报一条发现;无依赖图时回退到追踪 import/require/use 语句,重点关注模块级循环。
  3. 上帝对象:文件超过 500 LOC(不含空行与注释)、类含 20 个以上方法、单文件承担请求到响应的 4 个以上关注点。
  4. 贫血领域模型:实体类只有属性、getter/setter 与构造赋值而无业务方法;或全部逻辑集中在 3 个以上 Service 类中操作纯数据容器。
  5. 边界缺失:20 个以上源文件的项目没有模块/领域划分;同一数据表被多个无关功能直接访问;功能模块间直接导入内部文件而非通过接口或事件。
  6. 目录结构:违反框架约定;20 个以上文件时层与层之间没有目录分离。
  7. 配置/环境:源码中硬编码 URL、端口、主机名、IP、文件路径;缺少环境抽象层或 5 处以上直接读取环境变量而无集中配置模块。

三、不检测的情况 少于 5 个文件的小项目或脚本(扁平结构合理);刻意保持薄层的微服务;框架惯用的单体模式(如 Laravel 默认结构、Rails 约定、Next.js app 目录约定);明确标注的原型与概念验证代码;生成的代码目录(dist/、build/、.next/、pycache 等)。

四、辅助脚本 可运行 codeprobe 技能 scripts/ 目录下的 file_stats.py 获取每个文件的 LOC、类数量与方法数量,用于识别上帝对象和统计概况:python3 scripts/file_stats.py <target_path>。若无 Python 3 或脚本不可用,可改为人工读取统计,不中断分析。

五、输出与修复建议 所有发现项使用 ARCH- 前缀顺序编号。技能会为每个问题给出修复提示示例,例如将控制器中的计价逻辑移入独立 Service、将 850 LOC 的 UserManager 拆分为多个职责单一的服务、通过抽取共享接口解除 billing 与 shipping 之间的循环依赖、用环境变量替换硬编码 URL,以及按领域建立目录结构等。

六、适用场景与限制 适用于中大型项目的架构审查与代码质量检查,尤其适合分层、模块边界与依赖关系的系统性排查。其判定以规则与启发式扫描为主,部分结论依赖预生成依赖图的准确性;小项目和框架惯用结构会被有意排除,以免过度工程化。关于收费、平台支持范围等事实,资料暂未提供。