codeprobe-framework

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Standalone Mode

独立模式

If invoked directly (not via the orchestrator), you must first:

Read
```
../codeprobe/shared-preamble.md
```
for the output contract, execution modes, and constraints.
Load applicable reference files from
```
../codeprobe/references/
```
based on the project's tech stack.
Default to
```
full
```
mode unless the user specifies otherwise.

如果直接调用（不通过编排器），您必须先执行以下步骤：

阅读
```
../codeprobe/shared-preamble.md
```
，了解输出约定、执行模式和约束条件。
根据项目技术栈，从
```
../codeprobe/references/
```
加载适用的参考文件。
除非用户另行指定，默认使用
```
full
```
模式。

Framework-Specific Best Practices

框架特定最佳实践

Domain Scope

领域范围

This sub-skill detects framework-specific anti-patterns and convention violations. Unlike other sub-skills that apply universal principles, this one loads framework-specific reference guides and checks against framework idioms.

Supported frameworks:

PHP / Laravel — Eloquent ORM, routing, validation, queues, events, configuration
React / Next.js — Component design, hooks, data fetching, type safety
Python / Django / FastAPI — PEP conventions, ORM patterns, async handling

Important: If no supported framework is detected at the target path, emit zero findings and return an empty summary with a note: "No supported framework detected — skipping framework-specific checks."

Version Awareness: When checking framework conventions, attempt to determine the framework version:

Laravel: check
```
composer.json
```
for
```
laravel/framework
```
version. Laravel 9+ uses attribute-based accessors instead of
```
getXAttribute()
```
.
Next.js: check
```
next.config.*
```
and
```
package.json
```
for Next.js version. 13+ uses App Router with
```
app/
```
directory.
Django: check
```
requirements.txt
```
or
```
setup.py
```
for Django version.

此子技能用于检测框架特定的反模式和规范违反。与其他应用通用原则的子技能不同，本技能会加载框架专属参考指南，并对照框架惯用用法进行检查。

支持的框架：

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版本。

What It Does NOT Flag

不标记的问题

Issues already covered by other sub-skills even if they appear in framework code. Specifically:
- Security issues in framework code → covered by
```
codeprobe-security
```
  (SEC)
- SOLID violations in framework classes → covered by
```
codeprobe-solid
```
  (SRP/OCP/etc.)
- Performance issues like N+1 queries → covered by
```
codeprobe-performance
```
  (PERF)
- Error handling in framework middleware → covered by
```
codeprobe-error-handling
```
  (ERR)
This sub-skill focuses exclusively on framework idiom violations — using the framework incorrectly or ignoring its conventions.
When this sub-skill and another sub-skill flag the same file:line range, the orchestrator's deduplication step (Section 7A) will keep the finding in whichever category is most relevant and mark the framework finding as a duplicate.
Framework-generated boilerplate files (migration stubs, config defaults, scaffolded controllers).
Intentional deviations from framework conventions with clear comments explaining the reason.
Test files — test-specific framework usage has different conventions.

其他子技能已覆盖的问题，即使出现在框架代码中。具体包括：
- 框架代码中的安全问题 → 由
```
codeprobe-security
```
  （SEC）覆盖
- 框架类中的SOLID原则违反 → 由
```
codeprobe-solid
```
  （SRP/OCP等）覆盖
- 如N+1查询之类的性能问题 → 由
```
codeprobe-performance
```
  （PERF）覆盖
- 框架中间件中的错误处理 → 由
```
codeprobe-error-handling
```
  （ERR）覆盖
本子技能仅专注于框架惯用用法违反 —— 错误使用框架或忽略其规范。
当本子技能与其他子技能标记同一文件的同一行范围时，编排器的去重步骤（第7A节）将保留最相关分类的检测结果，并将框架检测结果标记为重复项。
框架生成的样板文件（迁移模板、配置默认值、脚手架控制器）。
故意偏离框架规范且有明确注释说明原因的情况。
测试文件 —— 测试场景下的框架使用有不同规范。

Detection Instructions

检测说明

PHP / Laravel

ID Prefix	Area	What to Detect	How to Detect	Severity
`FWK`	Eloquent	Raw queries where Eloquent query builder works	Search for `DB::select()` , `DB::statement()` , raw SQL strings in model/service code where Eloquent's query builder ( `where()` , `join()` , `whereHas()` ) would be cleaner and safer. Exclude complex reporting queries that genuinely need raw SQL.	Minor
`FWK`	Eloquent	Missing `$casts` on model	Model attributes that should be cast (dates, booleans, arrays, JSON) accessed without `$casts` definition. Look for manual casting in accessors or repeated `(bool)` , `(int)` , `json_decode()` on model attributes.	Minor
`FWK`	Eloquent	Repeated WHERE conditions without scopes	Same `where()` condition chain used in 3+ locations on the same model. Should be extracted into a named scope ( `scopeActive()` , `scopePublished()` ).	Minor
`FWK`	Routing	Logic in route closures instead of controllers	Route definitions in `routes/web.php` or `routes/api.php` with closure handlers exceeding 3 lines. Should be moved to controller methods.	Minor
`FWK`	Routing	Missing route model binding	Routes that accept an ID parameter and manually call `Model::find($id)` or `Model::findOrFail($id)` instead of using route model binding in the method signature.	Minor
`FWK`	Validation	Validation in controller instead of Form Request	Controller methods with inline validation rules ( `$request->validate([...])` exceeding 5 rules). Should use a dedicated Form Request class.	Minor
`FWK`	Queues	Long-running tasks in request cycle	Operations likely to take > 5 seconds (sending emails, generating PDFs, calling external APIs, processing uploads) executed synchronously in a controller/request handler. Should be dispatched to a queue.	Major
`FWK`	Queues	Queue jobs without retry configuration	Job classes missing `$tries` , `$timeout` , or `$backoff` properties. Jobs will retry indefinitely on failure without these.	Minor
`FWK`	Events	Tight coupling where events would decouple	After a state change (create, update, delete), a method directly calls 3+ other services. Should dispatch an event and let listeners handle side effects.	Minor
`FWK`	Config	`env()` called outside config files	Using `env()` helper directly in service classes, controllers, or blade templates. `env()` returns `null` when config is cached. Must be wrapped in a `config/` file.	Major

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

React / Next.js

ID Prefix	Area	What to Detect	How to Detect	Severity
`FWK`	Components	Components exceeding 200 LOC	Single component files with more than 200 lines of code. Should be decomposed into smaller, focused components.	Minor
`FWK`	Components	Prop drilling more than 3 levels deep	Props passed through 3+ intermediate components that don't use them. Should use Context, state management, or composition. Trace prop names through component hierarchy.	Minor
`FWK`	Hooks	`useEffect` with missing or incorrect dependency array	`useEffect` hooks where variables used inside the effect are not listed in the dependency array. Also flag `useEffect` with empty `[]` that references props/state that can change.	Major
`FWK`	Hooks	State updates inside render	Calling `setState` /state setter outside of event handlers or effects — directly in the component body during render, causing infinite re-render loops.	Major
`FWK`	Hooks	Custom hooks exceeding 50 LOC	Custom hooks that do too much. Should be composed from smaller hooks.	Minor
`FWK`	Data Fetching	Client-side fetch where SSR/SSG is appropriate	`useEffect` + `fetch()` for data that is available at build time or request time. In Next.js, should use `getServerSideProps` , `getStaticProps` , or server components.	Minor
`FWK`	Data Fetching	Missing error and loading states	Data fetching without corresponding loading indicator and error handling in the UI.	Minor
`FWK`	Type Safety	`any` type usage in TypeScript	Explicit `any` type annotations in `.tsx` / `.ts` files. Should use proper types, `unknown` , or generics.	Minor
`FWK`	Type Safety	Missing return types on exported functions	Exported functions without explicit return type annotations. Rely on inference for internal, but exported API surfaces should be explicitly typed.	Minor

ID前缀	领域	检测内容	检测方式	严重程度
`FWK`	组件	组件代码超过200行	单个组件文件代码行数超过200行，应拆分为更小、职责单一的组件。	轻微
`FWK`	组件	属性穿透超过3层	属性经过3个及以上不使用该属性的中间组件传递，应使用Context、状态管理或组合模式。追踪属性名称在组件层级中的传递路径。	轻微
`FWK`	Hooks	`useEffect` 缺少或依赖数组错误	`useEffect` 钩子中使用的变量未列入依赖数组，或标记使用空数组 `[]` 但引用了可能变化的props/state的 `useEffect` 。	严重
`FWK`	Hooks	渲染过程中更新状态	在事件处理程序或钩子之外直接调用 `setState` /状态设置函数——即在组件渲染期间的组件主体中调用，导致无限重渲染循环。	严重
`FWK`	Hooks	自定义Hooks超过50行	自定义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` exceeding 500 LOC	Single view module with too many views. Should be split into separate view modules or use ViewSets.	Minor
`FWK`	Django	Missing model `Meta` class	Django models without `Meta` class for ordering, verbose names, or constraints.	Minor
`FWK`	Django	N+1 in templates	Template tags accessing related objects without `select_related()` / `prefetch_related()` in the view.	Major
`FWK`	FastAPI	Sync database calls in async views	Using synchronous ORM calls (Django ORM, SQLAlchemy sync) inside `async def` view functions. Blocks the event loop.	Major
`FWK`	Python	Non-PEP 8 naming	`camelCase` for functions/variables (should be `snake_case` ), `snake_case` for classes (should be `PascalCase` ).	Minor

ID前缀	领域	检测内容	检测方式	严重程度
`FWK`	Django	`views.py` 超过500行	单个视图模块包含过多视图，应拆分为多个视图模块或使用ViewSets。	轻微
`FWK`	Django	模型缺少 `Meta` 类	Django模型未定义 `Meta` 类用于排序、verbose名称或约束。	轻微
`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 Prefix & Fix Prompt Examples

ID前缀及修复提示示例

All findings use the

FWK-

prefix, numbered sequentially:

FWK-001

FWK-002

, etc.

所有检测结果使用

FWK-

前缀，按顺序编号：

FWK-001

、

FWK-002

等。

Fix Prompt Examples

修复提示示例

"Move the validation rules from
```
OrderController@store
```
(lines 15-30) into a new
```
StoreOrderRequest
```
form request class: run
```
php artisan make:request StoreOrderRequest
```
, move the validation array, and type-hint
```
StoreOrderRequest
```
in the controller method signature."
"Replace the
```
env('MAIL_HOST')
```
call at line 12 of
```
app/Services/MailService.php
```
with
```
config('mail.mailers.smtp.host')
```
. The
```
env()
```
function returns
```
null
```
when the config is cached. Move the env lookup to
```
config/mail.php
```
where it belongs."
"The
```
ProductList
```
component at
```
src/components/ProductList.tsx
```
(220 LOC) should be decomposed: extract
```
ProductCard
```
(lines 50-90),
```
ProductFilters
```
(lines 100-140), and
```
ProductPagination
```
(lines 160-200) into separate components in the same directory."
"Add missing dependency
```
userId
```
to the
```
useEffect
```
dependency array at
```
src/hooks/useProfile.ts:15
```
. The current empty array
```
[]
```
means the effect runs once with the initial
```
userId
```
and never refetches when it changes."

"将
```
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行）提取为同一目录下的独立组件。"
"在
```
src/hooks/useProfile.ts:15
```
的
```
useEffect
```
依赖数组中添加缺失的
```
userId
```
依赖。当前的空数组
```
[]
```
意味着该钩子仅在初始
```
userId
```
时执行一次，当
```
userId
```
变化时不会重新获取数据。"