KwaiShopSDK 为 PHP 开发者提供完整的快手电商 API 集成解决方案

大家好，我是小皮。

概述

在技术蓬勃发展的当下，快手电商开放平台的 KwaiShopSDK，本应是普惠所有开发者的得力工具，涵盖快手电商相关开放能力，从 Token 获取到请求封装、响应解释，每个环节都暗藏助力高效开发的玄机。

其本地化设计，理应为开发者开辟便捷通道，无论经验如何，都能借它在 API 调用之路上畅行无阻。可现实却令人咋舌，面对 PHP 这片高手云集、活力满满的领域，官方竟然缺失 PHP 版本的 SDK！

这简直荒谬至极。PHP 开发者们为互联网立下汗马功劳，如今却像被抛弃的孩子。看着其他语言开发者仗着官方 SDK 大步快跑，自己只能徒手在荆棘中挣扎，太不公平！好比马拉松赛场，别人装备精良、补给充足，自己却赤脚前行、无水可饮。

幸有补救性 SDK，让 PHP 开发者不至于掉队，能凭本事搭起投放管理系统，但背后是他们付出的诸多额外心血。官方这种"偏心"做法，实在该反省，给 PHP 开发者们一个交代！

项目地址：https://github.com/whalesky-labs/kwaishop-php-sdk

功能特性

• 支持 PHP 8.1+
• 支持 FPM
• 支持 Swoole Coroutine
• 内置 Guzzle 传输实现
• 支持 MD5 与 HMAC_SHA256 签名
• 提供统一的 Config 配置对象
• 提供 OAuth 能力：授权地址生成、code 换取 token、刷新 token、client_credentials
• 提供统一请求工厂与响应解析器
• 提供按文档分类组织的接口实现目录：src/Api/*
• 提供标准请求基座：get()、post()、postJson()、upload()
• 提供 rawRequest() 作为网关兜底调用能力
• 提供 PHPUnit 测试底座与本地手动调试脚本

使用条件

开发者条件

• 使用 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) 创建。

• 第 4 个参数是关联数组形式的 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、请求工厂、响应解析器都可以在多请求场景下安全复用
• 默认传输层基于 Guzzle
• SDK 会自动识别当前运行时；当检测到 Swoole Coroutine 且 hook 未开启时，默认传输层会自动尝试开启 coroutine hook
• SDK 会自动识别 FPM / CLI / Swoole 运行环境并调整连接复用策略：
• FPM / CLI 默认保持连接复用
• 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,    ]);

认证与授权

快手电商开放平台接入时常用的核心凭据包括：

• app_key

• app_secret

• sign_secret

• 需商家授权的接口通常还需要 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驿站」作者小皮。