游戏引擎 / 系统课时

小游戏平台 API 怎样做隔离

小游戏平台 API 怎样做隔离

同一款 Cocos Creator 3.8 游戏发布到微信、其他小游戏和网页时,直接在玩法脚本里调用 wx 会让功能迁移与测试都变得困难。本课把登录、分享、生命周期调用集中到平台适配器,并为支付保留独立的服务端确认边界。

学习目标

  • 区分核心玩法、平台能力接口和渠道适配器的职责。
  • 实现可在微信小游戏与浏览器预览间切换的登录、分享和前后台事件适配。
  • 理解支付验证与事件注销为何不能留在普通玩法脚本里。

让业务依赖能力而不是渠道

玩家点击“登录”时,业务真正需要的是一个可交给服务端兑换登录态的凭据,而不是知道 wx.login 的参数。类似地,“邀请好友”是业务动作,微信分享面板才是渠道实现。直接散落 wx 调用会产生三类问题:网页预览报未定义、换渠道要修改多处、销毁场景后留下生命周期监听。

把依赖方向固定为:玩法组件调用 PlatformPort;创建游戏时选择 WechatPort 或 PreviewPort;适配器才可接触平台全局对象。支付单列 PaymentPort,避免把支付回调误当作订单已完成。

核心玩法通过平台适配器访问小游戏能力的架构图

实现一个最小可用适配器

在项目脚本中新建 PlatformGatewayDemo.ts,挂到首场景的常驻测试节点上。示例只实现登录、主动分享和前台恢复,浏览器侧使用无鉴权的预览桩;支付接口仅定义契约,不会假装完成一笔交易。代码中的 WxSDK 是本例所用微信 API 的最小类型声明,并非独立的第三方库。

ts
import { _decorator, Component } from 'cc';

const { ccclass } = _decorator;
type LoginResult = { channel: 'wechat'; code: string } | { channel: 'preview' };

interface PlatformPort {
  login(): Promise<LoginResult>;
  share(title: string): void;
  onForeground(listener: () => void): () => void;
}

interface PaymentPort {
  pay(serverOrderId: string): Promise<'confirmed' | 'cancelled'>;
}

type WxSDK = {
  login(options: {
    success: (res: { code?: string }) => void;
    fail: (err: { errMsg?: string }) => void;
  }): void;
  shareAppMessage(options: { title: string }): void;
  onShow(listener: () => void): void;
  offShow(listener: () => void): void;
};

class WechatPort implements PlatformPort {
  constructor(private readonly sdk: WxSDK) {}

  login(): Promise<LoginResult> {
    return new Promise((resolve, reject) => {
      this.sdk.login({
        success: ({ code }) => code
          ? resolve({ channel: 'wechat', code })
          : reject(new Error('empty login code')),
        fail: ({ errMsg }) => reject(new Error(errMsg || 'login failed')),
      });
    });
  }

  share(title: string): void {
    this.sdk.shareAppMessage({ title });
  }

  onForeground(listener: () => void): () => void {
    this.sdk.onShow(listener);
    return () => this.sdk.offShow(listener); // 用同一函数引用解除监听
  }
}

class PreviewPort implements PlatformPort {
  async login(): Promise<LoginResult> {
    return { channel: 'preview' }; // 不伪造微信登录凭据
  }
  share(title: string): void {
    console.info('[preview] share:', title);
  }
  onForeground(_listener: () => void): () => void {
    return () => {};
  }
}

@ccclass('PlatformGatewayDemo')
export class PlatformGatewayDemo extends Component {
  private readonly port: PlatformPort = (() => {
    const sdk = (globalThis as typeof globalThis & { wx?: WxSDK }).wx;
    return sdk ? new WechatPort(sdk) : new PreviewPort();
  })();
  private disposeShow: () => void = () => {};

  start(): void {
    this.disposeShow = this.port.onForeground(
      () => console.info('[lifecycle] foreground')
    );
    void this.port.login()
      .then(result => console.info('[login] channel:', result.channel))
      .catch(error => console.warn('[login] failed:', error));
  }

  onShareTap(): void {
    this.port.share('一起来玩');
  }

  onDestroy(): void {
    this.disposeShow();
  }
}

预期输出:浏览器预览启动后,控制台打印:

text
[login] channel: preview

构建为微信小游戏并成功取得临时登录凭据时,显示 [login] channel: wechat。把场景中的“分享”按钮点击事件绑定到 onShareTap,微信端应调起分享流程;浏览器端仅打印分享标题。微信登录码属于一次性临时凭据,应交由业务服务端交换会话,不能直接当玩家 ID,也不应打印码值。

把支付和生命周期当作边界

支付能力虽然也由渠道提供,但真正的业务结果是“后端已确认订单”。调用 PaymentPort.pay(serverOrderId) 前应先从服务端创建订单;渠道完成支付流程后,由服务端依据该渠道的交易规则核验订单,再向游戏返回 confirmed。渠道不支持支付或没有资质时,明确提示不可用,不能返回模拟成功;游戏不应仅凭客户端成功回调发放道具。

前后台事件不等于节点显示隐藏。wx.onShow 只负责通知小游戏回到前台;首次进入场景的初始化仍由 Cocos 组件生命周期负责。示例把 offShow 封装为清理函数,在 onDestroy 调用,避免反复进入场景后重复处理恢复事件。若使用持久化平台服务,监听应由服务创建一次,并在服务销毁时清理。

验收隔离是否有效

先在浏览器预览确认没有 wx is not defined,登录返回预览状态、按钮仅输出分享日志;再构建微信小游戏,确认登录成功时只把凭据交给服务端、分享由用户点击触发,切后台再返回仅打印一次恢复事件。最后切回浏览器,不修改任何玩法脚本就能继续运行,才算把渠道差异真正封装起来。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

小游戏平台 API 怎样做隔离

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通