kknongchang_2506/ThirdParty

ThirdParty 第三方包目录

目录说明

此目录用于存放第三方服务对接包，每个包都遵循ThirdParty模块的标准化规范。

目录结构

ThirdParty/
├── README.md           # 本说明文件
├── Urs/               # URS包示例
│   ├── UrsRequest.php      # URS请求类
│   ├── UrsWebhook.php      # URS Webhook处理器
│   └── UrsServiceProvider.php # URS服务提供者
└── [其他包]/           # 其他第三方服务包

包开发规范

1. 命名空间

• 所有包使用 ThirdParty\{包名} 命名空间
• 包名使用大驼峰命名法，如：Urs、Alipay、Wechat

2. 必需文件

每个包至少包含以下文件：

请求类 ({包名}Request.php)

• 继承 App\Module\ThirdParty\Services\BaseRequest
• 实现 handler(array $params): array 方法
• 处理对第三方服务的主动调用

Webhook处理器 ({包名}Webhook.php)

• 继承 App\Module\ThirdParty\Services\BaseWebhook
• 实现 handler(string $action, Request $request): array 方法
• 处理来自第三方服务的回调

服务提供者 ({包名}ServiceProvider.php)

• 继承 Illuminate\Support\ServiceProvider
• 在 boot() 方法中注册Webhook处理器
• 可选：注册其他服务到容器

3. 配置要求

• 在 thirdparty_services 表中注册服务配置
• 服务代码（code字段）与包名保持一致（小写）
• 配置信息存储在 config 字段中（JSON格式）

4. 使用示例

创建请求类

<?php
namespace ThirdParty\YourPackage;
use App\Module\ThirdParty\Services\BaseRequest;

class YourPackageRequest extends BaseRequest
{
    public function __construct()
    {
        parent::__construct('your_package'); // 服务代码
    }
    
    protected function handler(array $params): array
    {
        // 实现具体的请求逻辑
        $config = $this->getConfig();
        // ... 业务逻辑
        return $result;
    }
}

创建Webhook处理器

<?php
namespace ThirdParty\YourPackage;
use App\Module\ThirdParty\Services\BaseWebhook;
use Illuminate\Http\Request;

class YourPackageWebhook extends BaseWebhook
{
    public function __construct(Request $request)
    {
        parent::__construct('your_package', $request);
    }
    
    protected function handler(string $action, Request $request): array
    {
        // 实现具体的Webhook处理逻辑
        switch ($action) {
            case 'notify':
                return $this->handleNotify($request);
            // ... 其他操作
        }
    }
}

注册服务提供者

<?php
namespace ThirdParty\YourPackage;
use Illuminate\Support\ServiceProvider;
use App\Module\ThirdParty\Services\WebhookDispatchService;

class YourPackageServiceProvider extends ServiceProvider
{
    public function boot()
    {
        WebhookDispatchService::registerPackageHandlers('your_package', [
            'notify' => YourPackageWebhook::class,
            // ... 其他处理器
        ]);
    }
}

注册步骤

1. 在composer.json中注册命名空间

{
    "autoload": {
        "psr-4": {
            "ThirdParty\\YourPackage\\": "ThirdParty/YourPackage/"
        }
    }
}

2. 在config/app.php中注册服务提供者

'providers' => [
    // ...
    ThirdParty\YourPackage\YourPackageServiceProvider::class,
],

3. 在数据库中注册服务配置

INSERT INTO `kku_thirdparty_services` (
    `name`, `code`, `type`, `provider`, `description`, 
    `base_url`, `auth_type`, `status`, `config`
) VALUES (
    '您的服务名称', 'your_package', 'CUSTOM', 'YOUR_PROVIDER', '服务描述',
    'https://api.yourservice.com', 'API_KEY', 'ACTIVE',
    JSON_OBJECT(
        'api_url', 'https://api.yourservice.com',
        'app_id', 'your_app_id',
        'app_secret', 'your_app_secret'
    )
);

基类功能

BaseRequest 提供的功能

• ✅ 自动配置读取
• ✅ 配额检查和更新
• ✅ 请求日志记录
• ✅ 错误处理
• ✅ 凭证管理

BaseWebhook 提供的功能

• ✅ 签名验证
• ✅ 请求格式验证
• ✅ Webhook日志记录
• ✅ 错误处理和响应
• ✅ 配置访问

Webhook路由

所有Webhook请求都通过以下路由格式访问：

POST /thirdParty/webhook/{包名}/{处理器路由}

例如：

• /thirdParty/webhook/urs/register - URS注册通知
• /thirdParty/webhook/alipay/notify - 支付宝支付通知
• /thirdParty/webhook/wechat/callback - 微信回调

监控和日志

所有包的请求和Webhook处理都会自动记录到 thirdparty_logs 表中，可以通过后台管理界面查看：

• 请求参数和响应数据
• 执行时间和状态
• 错误信息和堆栈跟踪
• 调用统计和性能分析

注意事项

1. 包名唯一性 - 确保包名在整个系统中唯一
2. 服务代码一致性 - 包名与数据库中的服务代码保持一致
3. 错误处理 - 继承基类的错误处理机制，不要自行捕获异常
4. 配置安全 - 敏感配置信息会自动加密存储
5. 版本兼容 - 确保包与ThirdParty模块版本兼容

技术支持

如有问题，请参考：

• app/Module/ThirdParty/Docs/基础架构使用示例.md - 详细使用示例
• app/Module/ThirdParty/Docs/第三方包.md - 规范说明
• app/Module/ThirdParty/README.md - 模块文档