游戏引擎 / 系统课时
支付与分享为什么要独立封装
支付与分享为什么要独立封装
同一个 Cocos Creator 3.8 项目发布到 Web、小游戏和原生 App 后,购买和分享按钮看起来相同,底层却可能是完全不同的渠道 SDK。本课把这两项能力拆成独立端口,明确支付确认与分享回退的边界,让业务层不必跟着渠道变化反复修改。
学习目标
- 解释支付与分享不能合并为通用平台调用的原因。
- 定义业务、渠道适配器和服务端各自承担的职责。
- 使用模拟适配器验证未确认支付不发货、分享不可用可回退。
两种能力的成功标准不同
支付涉及商品、订单、渠道资质和服务端对账。渠道 SDK 返回“唤起成功”或界面关闭,并不等于钱款到账;订单状态必须由可信服务端结合渠道通知或查询确认,发货还要做幂等处理。支付失败、取消和结果未知也不能归为同一种状态。
分享通常只需要标题、图片或可用的邀请信息,但渠道对内容格式、入口、取消回调的支持各不相同。部分渠道只能确认已唤起分享界面,不能可靠证明用户实际转发。因此“分享入口已打开”不应直接触发分享成功奖励。
如果把这两种行为都塞入 PlatformManager.invoke(action, data),调用方就得识别各渠道回调和错误码,既容易误发奖励,也难以分别模拟失败。应当让购买业务只依赖 PaymentPort,邀请业务只依赖 SharePort,由启动阶段选择对应渠道实现。
将订单确认与分享回退分成两条链路
购买流程是“服务端创建订单 → 支付适配器唤起渠道 SDK → 服务端核验结果 → 服务端幂等发货”。客户端即使超时、断线或切后台,也只能展示待确认状态并在恢复后查询,不能根据 SDK 弹窗结果自行发货。
分享流程是“构造邀请内容 → 分享适配器尝试唤起 → 不可用时展示复制文案等替代入口”。用户取消时保持原页面,不把取消记为系统故障。若渠道不提供可靠完成信号,统计事件应记录“发起分享”,而非“分享成功”。

在 Cocos 中用端口契约替代渠道判断
下面是可在 Cocos Creator 3.8 场景运行的最小演示。把代码保存为 assets/scripts/FeatureBoundaryDemo.ts,挂载到场景节点。三个模拟实现只说明接口边界,不会调用真实支付或分享 SDK,也不会创建真实订单。
import { _decorator, Component } from 'cc';
const { ccclass } = _decorator;
type LaunchState = 'opened' | 'cancelled' | 'unsupported';
type OrderState = 'PAID' | 'PENDING';
interface PaymentPort {
open(orderId: string): Promise<LaunchState>;
}
interface SharePort {
open(title: string): Promise<LaunchState>;
}
interface OrderApi {
create(sku: string): Promise<string>;
getState(orderId: string): Promise<OrderState>;
}
@ccclass('FeatureBoundaryDemo')
export class FeatureBoundaryDemo extends Component {
// 模拟服务端仍在确认订单,客户端不能据此发货。
private orders: OrderApi = {
async create(): Promise<string> { return 'DEMO-ORDER'; },
async getState(): Promise<OrderState> { return 'PENDING'; },
};
private payment: PaymentPort = {
async open(): Promise<LaunchState> { return 'opened'; },
};
private sharing: SharePort = {
async open(): Promise<LaunchState> { return 'unsupported'; },
};
async start() {
const orderId = await this.orders.create('starter-pack');
await this.payment.open(orderId);
const state = await this.orders.getState(orderId);
console.log(state === 'PAID'
? '服务端已确认订单,等待服务端发货'
: '订单待确认,客户端不发货');
// 分享不可用时保留邀请信息,展示替代入口。
const shareState = await this.sharing.open('邀请好友挑战');
console.log(shareState === 'unsupported'
? '显示复制邀请文案入口'
: '分享调用已结束,不能据此认定转发成功');
}
}预期输出(运行场景后查看 Console):
订单待确认,客户端不发货
显示复制邀请文案入口示例的 open 返回值只代表适配层可辨认的唤起状态;真实接入时还需处理 Promise 拒绝、超时、取消与渠道返回值不可区分的情况。若支付核验接口暂不可用,订单应保持待确认,并允许重试查询,不应把网络异常解释成支付失败。
替换渠道实现时守住边界
在 Web、微信小游戏和原生包中分别实现两个端口。工厂负责选择实现,业务层不直接读取 wx、浏览器对象或原生插件;没有能力时明确返回 unsupported。实际支付接入中,服务端负责创建渠道订单,适配器获取并使用渠道所需的预支付参数,业务层只持有订单标识。
平台是否开放支付、适用何种支付方式以及分享参数格式,应以当前渠道政策和官方 SDK 文档为准,不能假定所有目标端都支持相同接口。Cocos Creator 3.8 的微信小游戏发布文档也说明,用户、社交和支付等平台 SDK 能力需要开发者自行适配。
验收时至少模拟支付取消、支付唤起成功但服务端仍待确认、重复支付通知、分享不可用和分享取消;再用合法测试环境验证真实回调。支付回调验签、金额和订单归属校验、幂等发货必须留在服务端。这样渠道变化只影响适配层,而不会改变业务的安全判定。