大家好，我是小皮。
概述
在技术蓬勃发展的当下，快手电商开放平台的 KwaiShopSDK，本应是普惠所有开发者的得力工具，涵盖快手电商相关开放能力，从 Token 获取到请求封装、响应解释，每个环节都暗藏助力高效开发的玄机。
其本地化设计，理应为开发者开辟便捷通道，无论经验如何，都能借它在 API 调用之路上畅行无阻。可现实却令人咋舌，面对 PHP 这片高手云集、活力满满的领域，官方竟然缺失 PHP 版本的 SDK！
这简直荒谬至极。PHP 开发者们为互联网立下汗马功劳，如今却像被抛弃的孩子。看着其他语言开发者仗着官方 SDK 大步快跑，自己只能徒手在荆棘中挣扎，太不公平！好比马拉松赛场，别人装备精良、补给充足，自己却赤脚前行、无水可饮。
幸有补救性 SDK，让 PHP 开发者不至于掉队，能凭本事搭起投放管理系统，但背后是他们付出的诸多额外心血。官方这种"偏心"做法，实在该反省，给 PHP 开发者们一个交代！
项目地址：https://github.com/whalesky-labs/kwaishop-php-sdk
功能特性
- 提供 OAuth 能力：授权地址生成、
code 换取 token、刷新 token、client_credentials - 提供按文档分类组织的接口实现目录：
src/Api/* - 提供标准请求基座：
get()、post()、postJson()、upload() - 提供
rawRequest() 作为网关兜底调用能力
使用条件
开发者条件
- 使用 SDK 需要首先注册成为快手电商开发者，请参考 开发者快速入门文档
- 使用 SDK 需要先拥有 API 的访问权限，所有 SDK 的使用与应用拥有的权限组相关联
SDK 目录
src/├── Api/ # 按官方文档分类组织的接口封装│ ├── Comment/ # 评价 API│ ├── Cs/ # 客服 / 会话 API│ ├── Distribution/ # 分销 / 招商 / CPS API│ ├── Dropshipping/ # 代打代发 API│ ├── Express/ # 电子面单 / 打印 API│ ├── Funds/ # 资金 / 对账 / 提现 API│ ├── Industry/ # 行业能力 API│ ├── Invoice/ # 发票 API│ ├── Item/ # 商品 API│ ├── Live/ # 直播场景 API│ ├── Logistics/ # 地址 / 运费模板 / 物流 API│ ├── Member/ # 会员 API│ ├── MerchantMember/ # 商家会员 API│ ├── Order/ # 订单 API│ ├── Photo/ # 图文 / 图片素材 API│ ├── Promotion/ # 营销 API│ ├── Refund/ # 售后 / 退款 API│ ├── Scm/ # 供应链 / 库存 / 仓储 API│ ├── Security/ # 安全日志 / 解密 API│ ├── ServiceMarket/ # 服务市场 API│ ├── Shop/ # 店铺 API│ ├── Sms/ # 短信 API│ ├── Tool/ # 工具类开放能力 API│ ├── User/ # 用户 / 商家信息 API│ └── Virtual/ # 虚拟商品 API├── Auth/ # OAuth 鉴权与 Token 对象├── Client/ # SDK 主客户端、请求基座与请求流水线│ └── Pipeline/ # 请求构建与响应解析流水线├── Config/ # 配置对象├── Exception/ # SDK 异常体系├── Generated/ # 自动生成的客户端方法映射├── Runtime/ # FPM / CLI / Swoole 运行时识别├── Signing/ # MD5 / HMAC_SHA256 签名实现├── Support/ # 通用辅助工具└── Transport/ # HTTP 传输抽象与 Guzzle 实现
说明：
Api/* 目录按官方文档分类组织，方便快速定位对应接口Client/* 目录提供 SDK 入口、请求抽象与请求处理流水线Generated/* 目录用于承载自动生成的客户端方法映射KwaiShopClient 当前位于 KwaiShopSDK\Client\KwaiShopClient- 如果你想查看某个接口是否已封装，优先到对应分类目录中检索
安装
composer require whalesky-labs/kwaishop-php-sdk
快速开始
<?phpdeclare(strict_types=1);useKwaiShopSDK\Exception\KwaiShopException;useKwaiShopSDK\Client\KwaiShopClient;$client = new KwaiShopClient('your-app-key','your-app-secret','your-sign-secret', ['accessToken' => 'your-access-token', ]);try { $response = $client ->OpenShopInfoGet() ->setParams([]) ->send(); print_r($response);} catch (KwaiShopException $e) {echo"错误: {$e->getMessage()}";}
KwaiShopClient 统一通过 new KwaiShopClient($appKey, $appSecret, $signSecret, $options) 创建。
- 常用选项包括：
accessToken、baseUrl、connectTimeout、readTimeout、autoDetectRuntime、signMethod、userAgent
当前 1.0.0 已完成可稳定复用的 SDK 底座，并按官方文档分类提供接口封装。
Hyperf 集成（推荐）
如果你的项目运行在 Hyperf / Swoole Coroutine 场景，建议在项目里封装一个初始化类，统一管理凭据和运行时选项，业务代码只拿现成客户端。
namespaceApp\Support;useHyperf\Contract\ConfigInterface;useKwaiShopSDK\Client\KwaiShopClient;finalclassKwaiShopClientFactory{publicfunction__construct( private readonly ConfigInterface $config, ){ }publicfunctionmake(?string $accessToken = null): KwaiShopClient{ $config = $this->config->get('kwaishop', []); $options = is_array($config['options'] ?? null) ? $config['options'] : []; $token = $accessToken ?? ($config['access_token'] ?? null);if (is_string($token) && $token !== '') { $options['accessToken'] = $token; }returnnew KwaiShopClient( (string) ($config['app_key'] ?? ''), ($config['app_secret'] ?? null) !== null ? (string) $config['app_secret'] : null, (string) ($config['sign_secret'] ?? ''), $options ); }}
这样业务层只需要依赖这个工厂；如果你的 Hyperf 项目已经自行管理协程 hook 或运行时策略，可以在 options 中把 autoDetectRuntime 设为 false。
运行环境
本 SDK 以 FPM 与 Swoole Coroutine 双运行时为目标进行约束设计。
- SDK 核心对象保持无状态，不在静态变量、全局单例中存放请求上下文
KwaiShopClient、Config、请求工厂、响应解析器都可以在多请求场景下安全复用- SDK 会自动识别当前运行时；当检测到
Swoole Coroutine 且 hook 未开启时，默认传输层会自动尝试开启 coroutine hook - SDK 会自动识别
FPM / CLI / Swoole 运行环境并调整连接复用策略： Swoole / Swoole Coroutine 默认关闭跨请求连接复用，避免长驻 worker 中复用陈旧连接- 如果你的项目已经有自定义协程 HTTP 客户端，也可以直接注入自定义
TransportInterface 实现
Swoole Coroutine 示例
useKwaiShopSDK\Client\KwaiShopClient;useSwoole\Runtime;Runtime::enableCoroutine(true);$client = new KwaiShopClient('your-app-key','your-app-secret','your-sign-secret',);
如果你明确不希望 SDK 自动处理运行时识别，可以关闭：
useKwaiShopSDK\Client\KwaiShopClient;$client = new KwaiShopClient('your-app-key','your-app-secret','your-sign-secret', ['autoDetectRuntime' => false, ]);
认证与授权
快手电商开放平台接入时常用的核心凭据包括：
需商家授权的接口通常还需要 accessToken
推荐在初始化 Config 时传入默认 accessToken
如果是多商家场景，也可以在单次请求时通过 setAccessToken() 临时覆盖
SDK 当前提供的 OAuth 能力包括：
- 构建授权地址：
buildAuthorizeUrl() - 通过
code 换取 token：getAccessToken() - 刷新 token：
refreshAccessToken() - 获取应用 token：
getClientCredentialsToken()
以上方法通过 $client->oauth() 返回的 OAuth 客户端调用，例如：
$oauth = $client->oauth();$authorizeUrl = $oauth->buildAuthorizeUrl('https://your-callback.test/oauth/callback', ['merchant_order', 'merchant_item'],'your-state');
如果你需要本地联调 OAuth 或功能测试，可以再结合项目中的测试脚本使用。
感谢大家阅读，个人观点仅供参考，欢迎在评论区发表不同观点。
欢迎关注、分享、点赞、收藏、在看，我是微信公众号「PHP驿站」作者小皮。
