258 lines
7.5 KiB
Markdown
258 lines
7.5 KiB
Markdown
|
# Google Play IAP 服务端集成
|
|||
|
|
|
|||
|
|
## 系统设计
|
|||
|
|
|
|||
|
|
### 目标
|
|||
|
|
|
|||
|
|
- 客户端购买成功后，服务端使用 `purchaseToken` 二次校验 Google Play Developer API。
|
|||
|
|
- RTDN 进入后，先做 Pub/Sub 来源校验，再二次查询 Google Play Developer API，同步本地订单、token、权益状态。
|
|||
|
|
- 对订阅与一次性商品统一落库，保证幂等、防重放和可审计。
|
|||
|
|
|
|||
|
|
### 核心流程
|
|||
|
|
|
|||
|
|
1. 客户端发起购买，BillingClient 中建议设置 `obfuscatedAccountId = 当前 userId`。
|
|||
|
|
2. 客户端支付成功后调用 `/api/google-play/purchases/verify`。
|
|||
|
|
3. 服务端调用 Google Play Developer API：
|
|||
|
|
- 订阅：`purchases.subscriptionsv2.get`
|
|||
|
|
- 一次性商品：`purchases.productsv2.getproductpurchasev2`
|
|||
|
|
4. 服务端更新 `google_play_purchase_token`、`google_play_order`、`google_play_user_entitlement`。
|
|||
|
|
5. 对需要确认的订单执行 acknowledge / consume。
|
|||
|
|
6. Google Play RTDN 推送到 `/api/google-play/rtdn`。
|
|||
|
|
7. webhook 校验 topic / subscription / OIDC JWT 后，再次查询 Developer API，再更新本地状态。
|
|||
|
|
|
|||
|
|
### 幂等策略
|
|||
|
|
|
|||
|
|
- RTDN 事件以 `message_id` 幂等，重复消息直接忽略。
|
|||
|
|
- 订单以 `order_key` 幂等：
|
|||
|
|
- 有 `google_order_id` 时用订单号。
|
|||
|
|
- 没有订单号时回退为 `TOKEN:{purchaseToken}`。
|
|||
|
|
- 购买 token 表以 `purchase_token` 唯一。
|
|||
|
|
- 一次性商品发货前先看 `delivery_status`，已发货不重复发。
|
|||
|
|
- 订阅不做“累加式延长”，而是直接把用户 VIP 到期时间同步为 Google 返回的最新 `expiryTime`，天然幂等。
|
|||
|
|
|
|||
|
|
### 本地权益映射
|
|||
|
|
|
|||
|
|
- `subscription` -> `VIP_SUBSCRIPTION`
|
|||
|
|
- 一次性商品且 `duration_days > 0` 或 `unit` 包含 `vip/member/会员` -> `VIP_ONE_TIME`
|
|||
|
|
- 一次性商品且 `unit` 像 `coin/quota/credit/金币/次数`，或商品名/`durationValue` 可解析数值 -> `WALLET_TOP_UP`
|
|||
|
|
- 其他一次性商品 -> `NON_CONSUMABLE`
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
src/main/java/com/yolo/keyborad/
|
|||
|
|
├── config/
|
|||
|
|
│ ├── GooglePlayHttpConfig.java
|
|||
|
|
│ └── GooglePlayProperties.java
|
|||
|
|
├── controller/
|
|||
|
|
│ └── GooglePlayController.java
|
|||
|
|
├── googleplay/
|
|||
|
|
│ ├── GooglePlayApiClient.java
|
|||
|
|
│ ├── GooglePlayApiException.java
|
|||
|
|
│ ├── GooglePlayConstants.java
|
|||
|
|
│ ├── GooglePlayEntitlementApplier.java
|
|||
|
|
│ ├── GooglePlayPubSubAuthService.java
|
|||
|
|
│ ├── GooglePlayServiceAccountTokenProvider.java
|
|||
|
|
│ ├── GooglePlayStateService.java
|
|||
|
|
│ └── model/
|
|||
|
|
│ ├── GooglePlayPurchaseSnapshot.java
|
|||
|
|
│ ├── GooglePlaySyncCommand.java
|
|||
|
|
│ └── GooglePlaySyncResult.java
|
|||
|
|
├── mapper/
|
|||
|
|
│ ├── GooglePlayOrderMapper.java
|
|||
|
|
│ ├── GooglePlayPurchaseTokenMapper.java
|
|||
|
|
│ ├── GooglePlayRtdnEventMapper.java
|
|||
|
|
│ └── GooglePlayUserEntitlementMapper.java
|
|||
|
|
├── model/
|
|||
|
|
│ ├── dto/googleplay/
|
|||
|
|
│ │ ├── GooglePlayPubSubPushRequest.java
|
|||
|
|
│ │ └── GooglePlayPurchaseVerifyReq.java
|
|||
|
|
│ ├── entity/googleplay/
|
|||
|
|
│ │ ├── GooglePlayOrder.java
|
|||
|
|
│ │ ├── GooglePlayPurchaseToken.java
|
|||
|
|
│ │ ├── GooglePlayRtdnEvent.java
|
|||
|
|
│ │ └── GooglePlayUserEntitlement.java
|
|||
|
|
│ └── vo/googleplay/
|
|||
|
|
│ └── GooglePlayPurchaseVerifyResp.java
|
|||
|
|
└── service/
|
|||
|
|
├── GooglePlayBillingService.java
|
|||
|
|
└── impl/
|
|||
|
|
└── GooglePlayBillingServiceImpl.java
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 建表 SQL
|
|||
|
|
|
|||
|
|
- 文件：`src/main/resources/sql/google-play-iap.sql`
|
|||
|
|
|
|||
|
|
四张表职责：
|
|||
|
|
|
|||
|
|
- `google_play_order`：每一笔 Google 订单/续费周期的最终状态与发货状态。
|
|||
|
|
- `google_play_purchase_token`：一个 purchase token 的最新状态快照。
|
|||
|
|
- `google_play_user_entitlement`：用户实际拥有的本地权益。
|
|||
|
|
- `google_play_rtdn_event`：RTDN 审计与重试记录。
|
|||
|
|
|
|||
|
|
## 接口定义
|
|||
|
|
|
|||
|
|
### 1. 客户端购买校验
|
|||
|
|
|
|||
|
|
- `POST /api/google-play/purchases/verify`
|
|||
|
|
- 需要登录态与签名
|
|||
|
|
|
|||
|
|
请求体：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"packageName": "com.example.app",
|
|||
|
|
"productId": "vip_monthly",
|
|||
|
|
"productType": "subscription",
|
|||
|
|
"purchaseToken": "xxxx"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
响应体：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 0,
|
|||
|
|
"message": "ok",
|
|||
|
|
"data": {
|
|||
|
|
"userId": 1001,
|
|||
|
|
"productId": "vip_monthly",
|
|||
|
|
"productType": "SUBSCRIPTION",
|
|||
|
|
"purchaseToken": "xxxx",
|
|||
|
|
"orderId": "GPA.1234-5678-9012-34567",
|
|||
|
|
"orderState": "ACTIVE",
|
|||
|
|
"entitlementState": "ACTIVE",
|
|||
|
|
"deliveryStatus": "NOT_REQUIRED",
|
|||
|
|
"accessGranted": true,
|
|||
|
|
"acknowledged": true,
|
|||
|
|
"consumed": false,
|
|||
|
|
"expiryTime": "2026-04-18T10:00:00.000+00:00",
|
|||
|
|
"lastSyncedAt": "2026-03-18T10:01:00.000+00:00"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. RTDN Webhook
|
|||
|
|
|
|||
|
|
- `POST /api/google-play/rtdn`
|
|||
|
|
- 不需要登录态，不走 app 签名，单独做 Pub/Sub 校验
|
|||
|
|
|
|||
|
|
Pub/Sub Push body：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"message": {
|
|||
|
|
"messageId": "136969346945",
|
|||
|
|
"data": "base64-encoded-json"
|
|||
|
|
},
|
|||
|
|
"subscription": "projects/your-project/subscriptions/google-play-rtdn-push"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
关键请求头：
|
|||
|
|
|
|||
|
|
- `Authorization: Bearer <OIDC JWT>`
|
|||
|
|
- `X-Goog-Topic: projects/your-project/topics/google-play-rtdn`
|
|||
|
|
|
|||
|
|
成功响应：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 0,
|
|||
|
|
"message": "ok",
|
|||
|
|
"data": true
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## RTDN 状态处理
|
|||
|
|
|
|||
|
|
### 订阅
|
|||
|
|
|
|||
|
|
- `SUBSCRIPTION_PURCHASED`
|
|||
|
|
- Developer API 状态通常为 `ACTIVE`
|
|||
|
|
- 新建/更新 token、order、VIP 权益
|
|||
|
|
- 如未 acknowledge，则服务端补 acknowledge
|
|||
|
|
|
|||
|
|
- `SUBSCRIPTION_RENEWED`
|
|||
|
|
- 再查 `subscriptionsv2.get`
|
|||
|
|
- 取最新 `expiryTime` 覆盖本地 VIP 到期时间
|
|||
|
|
- 不做“在旧时间上加时长”，避免 RTDN 重放导致多发
|
|||
|
|
|
|||
|
|
- `SUBSCRIPTION_CANCELED`
|
|||
|
|
- 若 `subscriptionState=CANCELED` 但 `expiryTime` 仍未来
|
|||
|
|
- 本地仍保留 VIP，`autoRenewEnabled=false`
|
|||
|
|
- 到期后等待 `EXPIRED`
|
|||
|
|
|
|||
|
|
- `SUBSCRIPTION_IN_GRACE_PERIOD`
|
|||
|
|
- 本地继续保留 VIP
|
|||
|
|
- entitlement state 记为 `IN_GRACE_PERIOD`
|
|||
|
|
|
|||
|
|
- `SUBSCRIPTION_ON_HOLD`
|
|||
|
|
- 立即取消本地 VIP 可用态
|
|||
|
|
- 保留 token/order 记录，等待恢复或过期
|
|||
|
|
|
|||
|
|
- `SUBSCRIPTION_RESTARTED` / `SUBSCRIPTION_RECOVERED`
|
|||
|
|
- 再查最新状态
|
|||
|
|
- 若恢复为 `ACTIVE`，重新开启 VIP
|
|||
|
|
|
|||
|
|
- `SUBSCRIPTION_PAUSED`
|
|||
|
|
- 本地取消 VIP 可用态
|
|||
|
|
- 记录 `autoResumeTime`
|
|||
|
|
|
|||
|
|
- `SUBSCRIPTION_EXPIRED`
|
|||
|
|
- 本地关闭 VIP
|
|||
|
|
- entitlement state -> `EXPIRED`
|
|||
|
|
|
|||
|
|
- `SUBSCRIPTION_REVOKED`
|
|||
|
|
- 本地关闭 VIP
|
|||
|
|
- entitlement state -> `REVOKED`
|
|||
|
|
|
|||
|
|
- `SUBSCRIPTION_PENDING_PURCHASE_CANCELED`
|
|||
|
|
- 用当前 token 查到 `linkedPurchaseToken` 后，再同步旧 token
|
|||
|
|
- 旧订阅权益继续保持
|
|||
|
|
|
|||
|
|
### 一次性商品
|
|||
|
|
|
|||
|
|
- `ONE_TIME_PRODUCT_PURCHASED`
|
|||
|
|
- 若映射为钱包充值：仅当 `delivery_status != DELIVERED` 才入账
|
|||
|
|
- 若映射为一次性 VIP 或非消耗型权益：同样只发一次
|
|||
|
|
- 钱包型商品在发货后执行 consume
|
|||
|
|
- 非消耗型商品执行 acknowledge
|
|||
|
|
|
|||
|
|
- `ONE_TIME_PRODUCT_CANCELED`
|
|||
|
|
- 一般是 pending 订单被取消
|
|||
|
|
- 本地标记为 `CANCELED`，不发货
|
|||
|
|
|
|||
|
|
- `VoidedPurchaseNotification`
|
|||
|
|
- 先二次查询 Developer API；若 404，则结合本地 token/order 记录做最终回滚
|
|||
|
|
- 订阅按 `REVOKED`
|
|||
|
|
- 一次性商品按 `REFUNDED`
|
|||
|
|
- 钱包余额不足以回滚时，订单标记 `MANUAL_REVIEW`，日志显式报错
|
|||
|
|
|
|||
|
|
## 安全校验
|
|||
|
|
|
|||
|
|
- RTDN 入口校验 `X-Goog-Topic`
|
|||
|
|
- 校验 `subscription` 字段
|
|||
|
|
- 调用 `tokeninfo` 校验 Pub/Sub OIDC JWT
|
|||
|
|
- 校验 `aud`
|
|||
|
|
- 校验 `email` 与 `email_verified`
|
|||
|
|
- 校验 `iss` 必须是 Google Accounts
|
|||
|
|
- 客户端校验接口可要求 `obfuscatedExternalAccountId == userId`
|
|||
|
|
|
|||
|
|
## 测试样例
|
|||
|
|
|
|||
|
|
建议执行：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
mvn -q test -Dtest=GooglePlay*
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
覆盖点：
|
|||
|
|
|
|||
|
|
- 订阅首次购买与续费
|
|||
|
|
- 订阅取消但未过期
|
|||
|
|
- 订阅宽限期
|
|||
|
|
- 一次性商品发货幂等
|
|||
|
|
- RTDN 重放幂等
|