SuperAPI AI 工具集

solid-php

编程与开发

查看项目

更新于 10-28 08:31

技能介绍

用途

solid-php 是一个面向 Laravel 13 / PHP 8.3+ 项目的代码规范技能,用于在应用 SOLID 原则时提供约束与工作流指导,主要覆盖文件行数限制、接口放置位置和 PHPDoc 文档强制要求。

主要能力

  • 强制代理工作流:任何实现开始前,需并行启动三个代理:explore-codebase(分析现有架构)、research-expert(通过 Context7 验证 Laravel/PHP 文档)、mcp__context7__query-docs(检查 SOLID 模式)。实现完成后运行 sniper 进行验证。
  • DRY 复用约束:编写新代码前必须 Grep 代码库查找相似类名、方法或逻辑;检查共享位置 FuseCore/Core/App/Services/、FuseCore/Core/App/Traits/、FuseCore/[Module]/App/Contracts/;若存在相似代码则扩展复用而非重复;被 2 个以上功能使用的代码应放入共享 Services 或 Traits;出现 3 次以上的重复逻辑提取为共享 helper 或 Trait;写入后验证未引入重复。
  • FuseCore 模块化架构自动检测:检测到 FuseCore/ 目录或 modules 中存在 module.json 时,判定为 FuseCore Modular 架构,接口位置为 FuseCore/[Module]/App/Contracts/;共享代码位于 FuseCore/Core/App/。
  • 代码放置决策树:HTTP 验证放入 Http/Requests/,单一操作放入 Actions/,业务逻辑放入 Services/,数据访问放入 Repositories/,数据传输放入 DTOs/,接口放入 Contracts/,事件放入 Events/,授权放入 Policies/。
  • 模式选择决策树:HTTP 处理用 Controller,验证用 FormRequest,单一操作用 Action,复杂逻辑用 Service,数据访问用 Repository,数据结构用 DTO,抽象用 Interface。

关键规则

  1. 文件行数须在 FUSE_SOLID_MAX_LINES(默认 200)以内,应远早于钩子上限进行拆分,不得绕过;Controller 仅处理 HTTP 关注点,Model 仅含关系与类型转换,Service 仅含业务逻辑。
  2. 接口分离:模块接口仅放在 FuseCore/[Module]/App/Contracts/,共享接口放在 FuseCore/Core/App/Contracts/。
  3. PHPDoc 必填,需包含参数、返回值与抛出异常说明。

参考与模板

提供 SOLID 各原则参考文档(solid-principles.md、single-responsibility.md、open-closed.md、liskov-substitution.md、interface-segregation.md、dependency-inversion.md)、反模式文档、决策指南、PHP 8.5 特性、Laravel 标准结构与 FuseCore 结构说明;模板包括 code-templates.md(Service、DTO、Repository、Interface)、controller-templates.md(Controller、Action、FormRequest、Policy)、refactoring-guide.md(遗留代码迁移步骤)。

禁止反模式

包括:文件超过行数上限、Controller 含业务逻辑、接口定义在实现文件中、Model 含业务逻辑、直接 new 具体依赖、缺少 PHPDoc、缺少 strict_types、胖类(超过 5 个公共方法)、重复逻辑、编码前未 Grep 搜索。

最佳实践

应使用构造器属性提升、依赖接口、final readonly class、declare(strict_types=1)、提前拆分、DTO 传输数据;不应使用属性赋值、依赖具体类、可变类、省略类型声明、等到钩子阻止才拆分、使用数组传输数据。

Laravel 13 要点

PHP 最低 8.3;支持 readonly 类、类型化类常量、#[\Override] 属性、原生 json_validate()、动态类常量获取。L13 更严格的 SOLID 规则:DTO/值对象优先使用 final readonly class;每个继承方法使用 #[\Override](在 CI 中捕获);类型化常量。

适用场景与限制

适用于采用 Laravel 13 与 PHP 8.3+ 的 FuseCore 模块化项目,用于规范代码结构、文件规模、接口位置和文档。限制:资料未提供具体安装命令、收费方式、平台信息或效果数据;规则依赖 FuseCore 特定目录约定,非该架构项目需自行调整。