@xstools/sdk
v2.0.0-beta.2
Published
Readme
@xstools/sdk
第三方 HTTP API 的薄封装。ESM only。按 vendor 分子路径发布;根入口只导出异常和 logger。
pnpm add @xstools/sdk子路径
| 导入 | Client |
| --- | --- |
| @xstools/sdk/alicloud | AlicloudClientDysmsapi20170525、AlicloudClientOss20190517 |
| @xstools/sdk/dingtalk | DingTalkClient |
| @xstools/sdk/wechat-miniprogram | WechatMiniprogramClient |
| @xstools/sdk/wechat-oplatform | WechatOplatformClient |
| @xstools/sdk/wechat-pay | WechatPayClient |
| @xstools/sdk/wechat-pay-partner | WechatPayPartnerClient |
| @xstools/sdk/xcloud | XcloudClient |
| @xstools/sdk/yzh | YzhClient |
| @xstools/sdk | SdkException*、SdkLogger、SdkClientOptions、sdkLoggerConsole、sdkLoggerNoop |
业务走 vendor 子路径。子路径导出 Client、业务类型和 *RequestOption,不导出 Request 类。
HTTP 用 method;厂商 opcode 用 action(ACS x-acs-action、微信 body action);SDK 调用身份用 operation。封装方法带与方法同名的 operation;公开 doRequest 默认 'doRequest'。action 不会回落到 operation。
用法
import { sdkLoggerConsole } from '@xstools/sdk';
import { WechatMiniprogramClient } from '@xstools/sdk/wechat-miniprogram';
const mini = new WechatMiniprogramClient(
{ appid: process.env.WX_APPID!, appsecret: process.env.WX_APPSECRET! },
{ fetch: mockFetch, timeout: 10_000, logger: sdkLoggerConsole },
);
const session = await mini.code2Session({ js_code: code });第二参 SdkClientOptions:fetch / timeout 交给 HTTP,logger 留在 Client。logger 只记成功 / 进度(info / debug),默认静默。失败只抛异常。
未封装接口走泛型 doRequest,鉴权和错误码仍走该 vendor 的 Request:
const data = await mini.doRequest<{ url_link: string }>({
method: 'POST',
path: '/wxa/generate_urllink',
body: { path: 'pages/index/index' },
});小程序 stable token 缓存在单个 Client 实例内:并发共享一次刷新,失败后下次重取,成功后按上游有效期提前 60 秒刷新。
setSupportVersion 直接设置版本,不预先查询当前版本;checkMode: true 时直接返回,不发起请求。setPrivacySetting 的 keys 是增量:保留远端已有 key,并确保传入的 key 存在。
transactionNotice 只解密已由接入层验签的 resource。不处理签名、重放、订单归属和金额。
错误
import { SdkException, SdkExceptionInternalError, SdkExceptionLogicRejected, SdkExceptionResponse } from '@xstools/sdk';
try {
await mini.code2Session({ js_code: code });
} catch (error) {
if (SdkExceptionResponse.is(error)) {
// HTTP 非 2xx 或厂商业务码。source / operation / message
} else if (SdkExceptionLogicRejected.is(error)) {
// 本包业务判断,message 可给用户
} else if (SdkExceptionInternalError.is(error)) {
// 超时、网络、坏 JSON、本地解码
} else if (SdkException.is(error)) {
// 其它 SDK 错误
}
}用静态 is()。字段是 source、operation、message。
响应
Client → Request.doRequest → getResponse → SdkHttp。
read读 body。非 2xx 解析失败保留原文。!response.ok→SdkExceptionResponse。- 2xx 且
isError(body)非空 →SdkExceptionResponse。isError*只认 body。 - 可选
map(Yzh 剥data/ 解密)。
| vendor | 2xx 成功 |
| --------- | -------------------------------------------------------------- |
| alicloud | Code / Error.Code 为 OK 或缺省 |
| dingtalk | errcode 缺省或 0;body 须 JSON |
| 微信 JSON | errcode 缺省或 0 |
| 微信支付 | 只看 HTTP;body 的 code / message / 自有 detail 摘进异常 |
| xcloud | 只看 HTTP;原样返回 JSON(含 data) |
| yzh | code === '0000';剥 data |
超时、网络、2xx 解不开 JSON 走 SdkExceptionInternalError。
目录
_ 前缀不发布。vendor 根上是 index.ts、client、request(对外只留 doRequest)、types。微信共用实现在 _wechat。
OSS
objectPut 接受 Buffer、ArrayBuffer、SharedArrayBuffer 或 Node 二进制 Readable。limitSize 单位 MB,默认 1;超限在上传前拒绝。objectCopy / objectDelete / objectMove 接受 object key 或 HTTP(S) URL,只规范化一次 key。
测试
pnpm --filter @xstools/sdk test离线测试进 PR CI。直接用 Bun 时在包目录加 --preload ./test/_setup.ts(默认禁止真实 fetch)。真实 API:pnpm --filter @xstools/sdk sdk:test,读 .env.local,不进 CI。
