yansongda/artful 开发指南
开发命令
对 src/ PHP 代码的任何修改,需运行以下三项检查:
composer cs-fix && composer analyse && composer test
测试
composer test # PHPUnit 9.x + Mockery 1.6
- 测试前需安装
hyperf/pimple(default 框架兜底容器):本地开发执行composer require hyperf/pimple --dev,注意该命令会修改 composer.json,提交时勿包含此改动(CI 各矩阵已显式安装,无需提交) - Mock HTTP 客户端避免真实请求
代码风格
composer cs-fix # 代码格式化检查(dry-run)
静态分析
composer analyse # PHPStan level 5
文档
cd web && pnpm web:dev # 文档开发
cd web && pnpm web:build # 文档构建
cd web && pnpm web:preview # 本地预览
本地开发环境
优先本地 PHP 环境;若无 PHP,使用 Container 作为备选,详见 container-dev Skill。
CI 矩阵
PHP 8.1-8.3 + Laravel/Hyperf/Default
代码规范
declare(strict_types=1);必须use导入,禁止\Yansongda\Artful\...- 日志/异常消息用中文
- 命名:
- 插件:
{Action}Plugin.php(如AddRadarPlugin、ParserPlugin) - 打包器:
{Type}Packer.php(如JsonPacker、XmlPacker) - 方向:
{Type}Direction.php(如CollectionDirection) - 服务提供者:
{Name}ServiceProvider.php
- 插件:
核心架构
插件管道
StartPlugin -> [业务插件] -> AddRadarPlugin -> [HTTP 请求] -> ParserPlugin
每个插件实现 PluginInterface::assembly(Rocket $rocket, Closure $next): Rocket,通过 $next($rocket) 串联。
核心载体 Rocket
贯穿整条管道,承载:
params:原始参数payload:待发送数据(Collection)radar:PSR-7RequestInterface(HTTP 请求)destination:最终结果(Collection|MessageInterface)destinationOrigin:原始响应(RequestInterface|ResponseInterface)
扩展点
| 类型 | 契约 | 职责 |
|---|---|---|
| Plugin | PluginInterface |
管道节点,组装/解析请求响应 |
| Packer | PackerInterface |
payload 序列化/反序列化(pack/unpack) |
| Direction | DirectionInterface |
响应解析方向(guide) |
| Shortcut | ShortcutInterface |
快捷方式,返回插件列表(getPlugins) |
HTTP 客户端
HttpClientFactory 优先从容器获取 HttpClientInterface(PSR-18),否则创建 GuzzleHttp\Client。默认依赖 guzzlehttp/guzzle(7.x 或 8.x),需用户自行安装。
新增插件流程
- 在
src/Plugin/创建{Name}Plugin.php,实现PluginInterface assembly()中操作Rocket(组装 payload、设置 radar 等),并return $next($rocket)- 通过
Artful::artful([插件...], $params)串联执行,或封装为Shortcut - 补充测试:
tests/Plugin/{Name}PluginTest.php,Mock HTTP 客户端 - 运行
composer cs-fix && composer analyse && composer test
常见错误
- 忽略
declare(strict_types=1); - 直接写完整命名空间而非
use导入 - 插件
assembly()忘记return $next($rocket),导致管道中断 - 测试未 Mock HTTP 客户端导致真实网络请求
- 修改
src/后未跑cs-fix/analyse/test三项检查
