codeprobe-framework

独立模式

如果直接调用（而不是通过编排器调用），你必须先：

1. 阅读 ../codeprobe/shared-preamble.md（相对于此 SKILL.md 的位置解析——即同级的 codeprobe 技能目录，而不是用户的项目），了解输出约定、执行模式和限制。
2. 根据项目的技术栈，从 ../codeprobe/references/（按相同方式解析）加载适用的参考文件。
3. 除非用户另有指定，否则默认使用 full 模式。

框架专属最佳实践

领域范围

此子技能用于检测框架专属的反模式和约定违规。与遵循通用原则的其他子技能不同，它会加载框架专属参考指南，并依据框架惯用做法进行检查。

支持的框架：

1. PHP / Laravel — Eloquent ORM、路由、验证、队列、事件、配置
2. React / Next.js — 组件设计、hooks、数据获取、类型安全
3. Python / Django / FastAPI — PEP 约定、ORM 模式、异步处理

重要： 如果在目标路径下未检测到受支持的框架，则不输出任何发现，并返回一份附带以下说明的空摘要："No supported framework detected — skipping framework-specific checks."

版本感知： 检查框架约定时，尝试确定框架版本：

• Laravel： 检查 composer.json 中的 laravel/framework 版本。Laravel 9+ 使用基于属性的访问器，而不是 getXAttribute()。
• Next.js： 检查 next.config.* 和 package.json，确定 Next.js 版本。13+ 使用带有 app/ 目录的 App Router。
• Django： 检查 requirements.txt 或 setup.py，确定 Django 版本。

---

不会标记的内容

• 其他子技能已涵盖的问题，即使这些问题出现在框架代码中。具体包括：
  • 框架代码中的安全问题 → 由 codeprobe-security（SEC）涵盖
  • 框架类中的 SOLID 违规 → 由 codeprobe-solid（SRP/OCP 等）涵盖
  • N+1 查询等性能问题 → 由 codeprobe-performance（PERF）涵盖
  • 框架中间件中的错误处理问题 → 由 codeprobe-error-handling（ERR）涵盖
• 此子技能只关注框架惯用做法违规——错误地使用框架或忽略其约定。
• 当此子技能和另一子技能标记了同一文件的同一行范围时，编排器的去重步骤（第 7A 节）会保留最相关类别下的发现，并将框架发现标记为重复项。
• 框架生成的样板文件（迁移模板、默认配置、脚手架生成的控制器）。
• 有注释清楚说明原因的有意偏离框架约定。
• 测试文件——测试中特有的框架用法遵循不同的约定。

---

检测说明

PHP / Laravel

ID 前缀	领域	检测内容	检测方法	严重程度
FWK	Eloquent	在 Eloquent 查询构造器可用时使用原始查询	搜索模型或服务代码中的 DB::select()、DB::statement()、原始 SQL 字符串，检查是否可以更清晰、更安全地使用 Eloquent 查询构造器（where()、join()、whereHas()）。排除确实需要原始 SQL 的复杂报表查询。	Minor
FWK	Eloquent	模型缺少 $casts	检查未定义 $casts、却应进行类型转换（日期、布尔值、数组、JSON）的模型属性。查找访问器中的手动类型转换，或对模型属性反复使用 (bool)、(int)、json_decode() 的情况。	Minor
FWK	Eloquent	重复的 WHERE 条件未使用作用域	同一模型中有 3 处或更多位置使用相同的 where() 条件链。应将其提取为命名作用域（scopeActive()、scopePublished()）。	Minor
FWK	路由	在路由闭包中编写逻辑，而非控制器	routes/web.php 或 routes/api.php 中的路由定义使用了超过 3 行的闭包处理函数。应将其移至控制器方法中。	Minor
FWK	路由	缺少路由模型绑定	路由接受 ID 参数，并手动调用 Model::find($id) 或 Model::findOrFail($id)，而非在方法签名中使用路由模型绑定。	Minor
FWK	验证	在控制器中验证，而非使用 Form Request	控制器方法内联验证规则（$request->validate([...])）超过 5 条。应使用专用的 Form Request 类。	Minor
FWK	队列	在请求周期中执行长时间运行的任务	在控制器或请求处理函数中同步执行可能耗时超过 5 秒的操作（发送邮件、生成 PDF、调用外部 API、处理上传内容）。应将其分派到队列中。	Major
FWK	队列	队列任务缺少重试配置	任务类缺少 $tries、$timeout 或 $backoff 属性。发生故障时，这类任务会无限重试。	Minor
FWK	事件	存在紧耦合，适合通过事件解耦	状态变更（创建、更新、删除）后，某个方法直接调用 3 个或更多其他服务。应分派事件，并由监听器处理副作用。	Minor
FWK	配置	在配置文件之外调用 env()	在服务类、控制器或 Blade 模板中直接使用 env() 辅助函数。配置缓存后，env() 会返回 null。必须将其封装在 config/ 文件中。	Major

React / Next.js

ID Prefix	Area	What to Detect	How to Detect	Severity
FWK	组件	超过 200 行代码的组件	超过 200 行代码的单个组件文件。应将其拆分为更小、更专注的组件。	轻微
FWK	组件	属性逐层传递超过 3 层	属性经过 3 个或更多中间组件传递，而这些组件并未使用这些属性。应使用 Context、状态管理或组合。沿组件层级追踪属性名称。	轻微
FWK	Hooks	useEffect 缺少依赖数组或依赖数组不正确	useEffect 中使用的变量未列入依赖数组的情况。也应标记依赖数组为空 []，但引用了可能发生变化的属性或状态的 useEffect。	主要
FWK	Hooks	在渲染过程中更新状态	在事件处理程序或 effect 之外调用 setState／状态设置器——直接在组件主体的渲染过程中调用，导致无限重新渲染循环。	主要
FWK	Hooks	超过 50 行代码的自定义 Hooks	承担过多职责的自定义 Hooks。应将其组合为更小的 Hooks。	轻微
FWK	数据获取	适合使用 SSR／SSG 时却在客户端获取数据	对构建时或请求时可用的数据使用 useEffect + fetch()。在 Next.js 中，应使用 getServerSideProps、getStaticProps 或服务端组件。	轻微
FWK	数据获取	缺少错误和加载状态	获取数据时，UI 中没有相应的加载指示器和错误处理。	轻微
FWK	类型安全	在 TypeScript 中使用 any 类型	在 .tsx／.ts 文件中显式注解 any 类型。应使用合适的类型、unknown 或泛型。	轻微
FWK	类型安全	导出函数缺少返回类型	导出函数没有显式的返回类型注解。内部函数可以依赖类型推断，但导出的 API 应显式声明类型。	轻微

Python / Django / FastAPI

ID Prefix	Area	What to Detect	How to Detect	Severity
FWK	Django	views.py 超过 500 行代码	单个视图模块包含过多视图。应将其拆分为多个视图模块，或使用 ViewSets。	轻微
FWK	Django	缺少模型 Meta 类	Django 模型未设置用于排序、详细名称或约束的 Meta 类。	轻微
FWK	Django	模板中的 N+1 问题	模板标签访问关联对象，但视图中未使用 select_related()／prefetch_related()。	主要
FWK	FastAPI	异步视图中进行同步数据库调用	在 async def 视图函数中使用同步 ORM 调用（Django ORM、同步 SQLAlchemy）。这会阻塞事件循环。	主要
FWK	Python	命名不符合 PEP 8	函数／变量使用 camelCase（应使用 snake_case），类使用 snake_case（应使用 PascalCase）。	轻微

---

ID 前缀与修复提示词示例

所有发现项都使用 FWK- 前缀，并按顺序编号：FWK-001、FWK-002 等。

修复提示词示例

• “将 OrderController@store（第 15-30 行）中的验证规则移到新的 StoreOrderRequest 表单请求类中：运行 php artisan make:request StoreOrderRequest，移入验证数组，并在控制器方法签名中为参数指定类型 StoreOrderRequest。”
• “将 app/Services/MailService.php 第 12 行的 env('MAIL_HOST') 调用替换为 config('mail.mailers.smtp.host')。配置缓存后，env() 函数会返回 null。将环境变量查找移到它所属的 config/mail.php 中。”
• “src/components/ProductList.tsx 中的 ProductList 组件（220 行代码）应该拆分：将 ProductCard（第 50-90 行）、ProductFilters（第 100-140 行）和 ProductPagination（第 160-200 行）提取为同一目录中的独立组件。”
• “将缺失的依赖项 userId 添加到 src/hooks/useProfile.ts:15 的 useEffect 依赖数组中。当前的空数组 [] 意味着副作用只会使用初始 userId 运行一次，之后即使它发生变化，也不会重新获取数据。”