支付宝小程序开发：JSAPI 与生活服务

认识支付宝小程序与 JSAPI

支付宝小程序是运行在支付宝客户端内的轻应用，它提供了丰富的原生能力调用接口，称为 JSAPI（JavaScript API）。通过 JSAPI，你可以让小程序轻松使用手机硬件、读取用户信息、调用支付、获取地理位置等能力，无需额外开发原生模块。生活服务类小程序（如点餐、缴费、出行）尤其依赖这些接口连接线上功能与线下场景。

为什么选择 JSAPI

• 统一调用方式：所有原生能力均通过 my.xxx() 异步调用，支持 Promise 与回调。
• 安全鉴权：敏感接口（如支付、用户信息）依赖支付宝的授权体系，确保数据安全。
• 跨端一致：一套代码同时兼容 iOS 和 Android 的支付宝客户端。

开发环境准备

1. 注册成为开发者：登录 支付宝开放平台 完成实名认证，进入“小程序”板块创建应用。
2. 安装开发者工具：下载并安装支付宝小程序 IDE（支持 macOS / Windows），使用支付宝账号登录。
3. 创建项目：选择“新建小程序”，填写 AppID（可在开放平台管理中心查看）或使用测试号，选定模板后即可进入开发界面。

基础架构与 JSAPI 调用方式

一个支付宝小程序由 JSON 配置、AXML 模板、ACSS 样式和 JS 逻辑文件组成。JSAPI 在 Page 或 Component 的生命周期函数/事件处理函数中调用。

通用调用格式

// Promise 写法（推荐）
my.chooseImage({
  count: 1,
  success: (res) => { console.log(res.apFilePaths) },
  fail: (err) => { console.error(err) }
}).then(res => {
  // 也可处理
}).catch(err => { /*...*/ });

需注意的权限配置

部分接口需要在 app.json 或对应页面的 .json 中声明权限，例如获取位置需要 scope.userLocation。线上版本还需在开放平台的应用详情页勾选“接口权限”。

核心 JSAPI 与生活服务能力

界面交互

用于提升用户体验，如提示框、加载动画、导航栏控制。

网络请求与数据缓存

安全提示：网络请求必须使用 HTTPS，且需将后端域名在开放平台添加为安全域名。

用户授权与个人信息

生活服务类小程序常需获取用户手机号或身份信息。核心 API：

// 获取登录授权码（用于后端换取 user_id）
my.getAuthCode({
  scopes: 'auth_user',
  success: (res) => {
    // 将 res.authCode 传给服务端
  }
});

// 获取用户信息（头像、昵称等）
my.getOpenUserInfo({
  success: (res) => {
    const userInfo = JSON.parse(res.response).response;
    // userInfo.avatar, userInfo.nickName
  }
});

授权流程：getAuthCode → 后端用 authCode 换取 access_token → 通过 access_token 调用支付宝会员信息接口。

支付能力

JSAPI 支付是线下生活服务的核心。调用 my.tradePay 并传入后端生成的订单字符串（tradeNO）。

my.tradePay({
  tradeNO: '2023090822001...', // 从服务端获取
  success: (res) => {
    if (res.resultCode == 9000) {
      // 支付成功
    }
  }
});

完整流程：用户触发支付 → 前端请求后端生成订单 → 后端调用 alipay.trade.create → 返回 tradeNO → 前端调起支付。

设备与地图

生活服务（如查找门店、签到）依靠位置能力。

// 获取当前位置
my.getLocation({
  type: 0,    // 0：默认 wgs84，1：gcj02
  success: (res) => {
    console.log(res.longitude, res.latitude);
  }
});

// 打开内置地图
my.openLocation({
  longitude: '120.12',
  latitude: '30.28',
  name: '杭州西湖',
  address: '杭州市西湖区'
});

注意：需要在 app.json 中配置 "permission": { "scope.userLocation": { "desc": "用于提供附近服务" } }。

扫码与图片

餐饮点餐、商品识别等场景常会用到扫码。

// 调起扫码
my.scan({
  type: 'qr', // qr / bar / all
  success: (res) => {
    console.log(res.code); // 扫码结果
  }
});

实战：一个简易的“附近优惠”生活服务页

设想一个场景：用户进入小程序后自动获取位置，展示附近的优惠商家列表，并可使用扫码领取优惠。

页面结构 (pages/index/index.axml)

<view class="container">
  <view class="location">当前定位：{{address}}</view>
  <button onTap="getNearbyShops" type="primary">刷新附近商家</button>
  <view a:for="{{shops}}" a:key="id" class="shop-card">
    <text>{{item.name}} - {{item.distance}}m</text>
    <button size="mini" onTap="claimCoupon" data-id="{{item.id}}">领取优惠</button>
  </view>
  <button onTap="scanCode" type="primary">扫一扫领券</button>
</view>

逻辑实现 (pages/index/index.js)

Page({
  data: { shops: [], address: '' },
  onLoad() {
    this.getLocation();
  },
  getLocation() {
    my.showLoading({ content: '定位中...' });
    my.getLocation({ type: 1, success: (res) => {
      this.setData({ address: `${res.longitude.toFixed(2)},${res.latitude.toFixed(2)}` });
      this.fetchShops(res.longitude, res.latitude);
    }, complete: () => my.hideLoading() });
  },
  fetchShops(lng, lat) {
    my.request({
      url: 'https://api.yourdomain.com/shops',
      data: { longitude: lng, latitude: lat },
      success: (res) => { this.setData({ shops: res.data || [] }); }
    });
  },
  claimCoupon(e) {
    const shopId = e.target.dataset.id;
    my.request({
      url: 'https://api.yourdomain.com/coupon/claim',
      method: 'POST',
      data: { shopId },
      success: (res) => { my.alert({ title: '成功', content: '优惠券已发放到卡包' }); }
    });
  },
  scanCode() {
    my.scan({ type: 'qr', success: (res) => {
      // 假设二维码内容为券码字符串
      my.request({
        url: 'https://api.yourdomain.com/coupon/redeem',
        data: { code: res.code }
      });
    }});
  }
});

高级能力与最佳实践

页面跳转与服务间互通

生活服务小程序常需跳转到其他小程序或生活号。使用 my.navigateToMiniProgram 或 my.navigateToAlipayPage 实现联盟生态内的流转。

// 跳转到另一小程序
my.navigateToMiniProgram({
  appId: '2021001...',
  path: 'pages/detail/index',
  success: () => {}
});

安全与性能优化

• 敏感数据加密：涉及用户手机等接口（如 my.getPhoneNumber）返回的是加密数据，需在后端解密。
• 避免频繁调用位置/扫码：做好用户引导和异常处理，防止因权限未开启而白屏。
• 使用 my.setKeepScreenOn 保持亮屏：在扫码或支付界面提升体验。
• 域名配置：所有后端 API 域名务必配置为安全域名，且不得使用 IP 地址或未备案域名。

版本兼容与测试

支付宝客户端版本众多，建议：

• 使用 my.canIUse 检测 API 可用性。
• 提审前用“真机调试”模式覆盖主流机型。
• 敏感 API 申请需提供测试账号和详细使用说明，便于审核。

总结

支付宝小程序的生活服务能力通过 JSAPI 得到全面释放，开发者只需掌握标准的异步调用模式，即可快速集成位置、支付、扫码、用户信息等功能。在规划生活服务类小程序时，建议：

1. 以用户授权和隐私保护为最高优先级，合规获取数据。
2. 将核心交易逻辑放在后端，前端仅作展示和调起。
3. 善用支付宝生态内的跳转能力，实现多场景联动。

开始你的第一个生活服务小程序吧，使用 JSAPI 打通线上线下，为用户提供即用即走的便捷服务。