用途
codeprobe-framework 是 codeprobe 的子技能,专门检测框架特定的反模式与约定违规,即“框架使用不当或忽略其约定”的问题。与其他应用通用原则的子技能不同,它按项目技术栈加载框架专用参考指南,并对照框架惯用法进行检查。
支持的框架
- PHP / Laravel:Eloquent ORM、路由、验证、队列、事件、配置
- React / Next.js:组件设计、hooks、数据获取、类型安全
- Python / Django / FastAPI:PEP 约定、ORM 模式、异步处理
若目标路径未检测到受支持的框架,则输出零发现并返回空摘要,注明“未检测到受支持框架——跳过框架特定检查”。
版本感知
检查框架约定时会尝试确定框架版本:
- 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)
当本技能与其他子技能标记同一 file:line 范围时,编排器的去重步骤会保留最相关类别的发现,并将框架发现标记为重复。此外不标记:框架生成的样板文件(迁移存根、默认配置、脚手架控制器);带明确注释说明原因的有意偏离框架约定;测试文件(测试场景的框架用法有不同约定)。
检测项概览
所有发现使用 FWK- 前缀,按序编号:FWK-001、FWK-002 等。
PHP / Laravel 检测项:
- Eloquent:在可用 Eloquent 查询构造器(where()、join()、whereHas())更清晰安全时使用 DB::select()、DB::statement() 或原始 SQL(排除确实需要原始 SQL 的复杂报表查询);模型缺少 $casts 定义;同一 where() 条件链在 3+ 处重复,应提取为命名 scope。
- 路由:routes/web.php 或 routes/api.php 中超过 3 行的闭包处理器,应移到控制器方法;接受 ID 参数却手动调用 Model::find($id)/findOrFail($id) 而不使用路由模型绑定。
- 验证:控制器方法中超过 5 条规则的内联验证,应使用专用 Form Request 类。
- 队列:请求周期中同步执行可能超过 5 秒的操作(发邮件、生成 PDF、调用外部 API、处理上传),应派发到队列;Job 类缺少 $tries、$timeout 或 $backoff 属性。
- 事件:状态变更后直接调用 3+ 其他服务,应派发事件由监听器处理副作用。
- 配置:在服务类、控制器或 blade 模板中直接调用 env();配置缓存后 env() 返回 null,必须包在 config/ 文件中。
React / Next.js 检测项:
- 组件:单文件超过 200 行;props 穿透 3 层以上(应使用 Context、状态管理或组合)。
- Hooks:useEffect 依赖数组缺失或不正确(包括空 [] 却引用会变化的 props/state);在渲染期间直接调用 setState 导致无限重渲染;自定义 hooks 超过 50 行。
- 数据获取:构建时或请求时可得的数据却用 useEffect + fetch()(Next.js 应使用 getServerSideProps、getStaticProps 或服务端组件);缺少加载与错误状态。
- 类型安全:.tsx/.ts 文件中显式 any;导出函数缺少显式返回类型。
Python / Django / FastAPI 检测项:
- Django:views.py 超过 500 行;模型缺少用于排序、verbose 名称或约束的 Meta 类;模板中访问关联对象却未在视图使用 select_related()/prefetch_related();FastAPI 的 async def 视图函数中使用同步 ORM 调用(阻塞事件循环);函数/变量使用 camelCase 或类使用 snake_case 等非 PEP 8 命名。
使用方式
可通过编排器调用,也可独立运行。独立直接调用时,必须先:读取 ../codeprobe/shared-preamble.md(相对于本 SKILL.md 所在位置解析,即同级 codeprobe 技能目录,而非用户项目)以获取输出契约、执行模式和约束;根据项目技术栈从 ../codeprobe/references/ 加载适用的参考文件(同样解析方式)。除非用户另有说明,默认使用完整模式。
修复提示示例
技能给出的修复示例包括:将 OrderController@store 第 15-30 行的验证规则移入新的 StoreOrderRequest 表单请求类;将 MailService 第 12 行的 env('MAIL_HOST') 替换为 config('mail.mailers.smtp.host') 并将 env 查找移到 config/mail.php;将 220 行的 ProductList 组件拆分为 ProductCard、ProductFilters、ProductPagination;为 useProfile.ts:15 的 useEffect 依赖数组补上缺失的 userId。
适用场景
适用于需要按框架惯用法审查 PHP/Laravel、React/Next.js、Python/Django/FastAPI 代码库的团队,尤其是希望与安全、SOLID、性能、错误处理等专项检查分工协作、避免重复报告的代码审查流程。
限制
仅覆盖上述三个技术栈的框架惯用法问题;不重复报告安全、SOLID、性能、错误处理;不检查框架生成的样板文件、带明确注释的有意偏离和测试文件;版本检测依赖项目配置文件;独立运行时需依赖 codeprobe 同级目录中的共享前置文档和参考文件。