xsl
ac0b7ca42b
Spring Boot 3.5.6 / Java 17 JAR with cloud gateway envelope and ping/whoami/echo; Taobao gateway signature verification matching the Node implementation; /pages/mvp page, splash dev entry and local transport contract test; SAE + 聚石塔 runbook and portable JDK/Maven setup; Windows 11 wmic shim for Taobao DevTools.
444 lines
16 KiB
Markdown
444 lines
16 KiB
Markdown
# 淘宝小程序 + Java + SAE 最小 MVP 操作步骤
|
||
|
||
> 目标：先用一个最小页面，把 **淘宝小程序 → 淘宝云网关（或本地直连）→ Java 后端 → 统一 envelope 返回** 这条链路跑通。
|
||
>
|
||
> 本文不包含：真实测肤算法、Face++、账号体系、图片分片上传。这些等链路验证通过后，再按现有 Node 实现的接口契约迁到 Java。
|
||
>
|
||
> 当前时间：2026-10。淘宝开放平台在 2026-05 把聚石塔的部署运维迁到了 ACK/SAE，网上 2023 年以前的“容器部署平台”教程不要照抄。
|
||
|
||
---
|
||
|
||
## 0. 本次交付物
|
||
|
||
| 路径 | 作用 |
|
||
|---|---|
|
||
| `backend-java/` | Spring Boot 3.5.6 + Java 17 的最小后端，含 `ping/whoami/echo` |
|
||
| `backend-java/src/main/java/com/juzi/mvp/gateway/TaobaoSignatureVerifier.java` | 云网关签名校验，算法与现有 Node 实现一致 |
|
||
| `taobao/pages/mvp/` | 淘宝小程序连通性页面，直接复用现有 `utils/transport.js` |
|
||
| `taobao/config.js` | 新增 `mvpLocal` / `mvpBaseUrl`，不影响主应用原来的 18180 配置 |
|
||
| `taobao/app.json` | 注册 `pages/mvp/mvp` |
|
||
| `tools/env-java.ps1` | 一键加载 JDK 17 + Maven 3.9.9 |
|
||
| `backend-java/README.md` | 后端速查 |
|
||
| `docs/SAE-Java-MVP-操作步骤.md` | 本文 |
|
||
|
||
现有 H5、Node 后端、淘宝主流程页面均未改动；只新增 MVP 页面和两个配置字段。
|
||
|
||
---
|
||
|
||
## 1. 环境安装
|
||
|
||
本机已有：
|
||
|
||
- Node.js `v22.23.2`：`C:\Program Files\nodejs`
|
||
- JDK 17：`D:\juzi\tools\jdk17`
|
||
- Maven 3.9.9：`D:\juzi\tools\maven\apache-maven-3.9.9`
|
||
|
||
PowerShell 默认执行策略是 `Restricted`，直接运行 `.ps1` 或 `npm.ps1` 会被拦。每次新开窗口先执行：
|
||
|
||
```powershell
|
||
Set-ExecutionPolicy -Scope Process Bypass
|
||
. D:\juzi\tools\env-java.ps1
|
||
```
|
||
|
||
然后确认：
|
||
|
||
```powershell
|
||
java -version
|
||
mvn -version
|
||
node -v
|
||
npm.cmd -v
|
||
```
|
||
|
||
预期：
|
||
|
||
- `java version "17.x"`
|
||
- `Apache Maven 3.9.9`
|
||
- `v22.23.2`
|
||
- `10.9.x`
|
||
|
||
> 如果 `env-java.ps1` 报 “JDK 17 not found”，检查 `D:\juzi\tools\jdk17\<jdk目录>\bin\java.exe` 是否存在；脚本会自动向下找一层目录。
|
||
>
|
||
> 不要用系统里的 JDK 25 来跑这个 MVP；SAE 运行时选 17，编译也用 17，避免 `UnsupportedClassVersionError`。
|
||
|
||
---
|
||
|
||
## 2. 后端本地启动
|
||
|
||
```powershell
|
||
Set-ExecutionPolicy -Scope Process Bypass
|
||
. D:\juzi\tools\env-java.ps1
|
||
cd D:\juzi\backend-java
|
||
mvn -DskipTests package
|
||
java -jar target\taobao-mvp-backend-0.0.1-SNAPSHOT.jar
|
||
```
|
||
|
||
第一次 `mvn package` 会下载 Spring Boot 依赖，耐心等几分钟。看到类似日志即成功：
|
||
|
||
```text
|
||
Tomcat started on port 8080 (http)
|
||
Started MvpApplication in ...
|
||
```
|
||
|
||
想跑自动化测试（签名算法 + envelope + health）：`mvn test`。
|
||
|
||
### 2.1 另开一个窗口验证
|
||
|
||
```powershell
|
||
curl.exe http://127.0.0.1:8080/actuator/health
|
||
curl.exe -X POST -H "Content-Type: application/json" -d "{}" http://127.0.0.1:8080/api/taobao/ping
|
||
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/api/taobao/echo -ContentType 'application/json' -Body '{"hello":"world"}' | ConvertTo-Json -Depth 5
|
||
```
|
||
|
||
> PowerShell 调原生 `curl.exe` 时，`-d` 里的双引号可能被吞掉（会看到 `{hello:world}` 解析失败）；发 JSON 建议用 `Invoke-RestMethod`，或者把 body 写进文件后用 `--data-binary "@body.json"`。
|
||
|
||
预期 `ping`：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"ok": true,
|
||
"pong": true,
|
||
"server": "java",
|
||
"time": "2026-10-30T...+08:00",
|
||
"transport": "direct",
|
||
"appKey": "",
|
||
"openId": "",
|
||
"env": "",
|
||
"signVerified": false,
|
||
"signMessage": "verify-sign=false, skipped (local/direct mode)"
|
||
}
|
||
}
|
||
```
|
||
|
||
`echo` 预期能看到 `body.hello = "world"`。
|
||
|
||
> 所有 `/api/taobao/**` 返回的都是云网关要求的 envelope；`/actuator/health` 是给 SAE 健康检查用的普通 JSON，不是 envelope。
|
||
|
||
### 2.2 不装 IDE 也能跑的前端契约测试
|
||
|
||
```powershell
|
||
cd D:\juzi
|
||
node taobao\scripts\mvp-local-check.cjs
|
||
```
|
||
|
||
这个脚本用 Node 模拟 `my.request`，加载真实的 `taobao/utils/transport.js`，直连 8080，验证 `ping/echo/whoami` 和 `unwrap` 解包。预期输出 `PASS`，其中 `ping.server = "java"`。如果这里都不过，先别开 IDE。
|
||
|
||
---
|
||
|
||
## 3. 前端本地联调（淘宝 IDE）
|
||
|
||
### 3.1 安装依赖
|
||
|
||
```powershell
|
||
cd D:\juzi\taobao
|
||
npm.cmd ci
|
||
```
|
||
|
||
如果 `npm.cmd` 不在 PATH，用全路径：
|
||
|
||
```powershell
|
||
& "C:\Program Files\nodejs\npm.cmd" ci
|
||
```
|
||
|
||
`@tbmp/mp-cloud-sdk` 已经是 `1.5.10`，与当前 npm 最新版一致。
|
||
|
||
### 3.2 IDE 导入与启动页
|
||
|
||
1. 打开淘宝小程序开发者工具，导入 `D:\juzi\taobao`。
|
||
2. 填入真实小程序 AppID（`mini.project.json` 里的 `appid` 也可以留空，以 IDE 设置为准）。
|
||
3. 工具 → 构建 npm（把 `node_modules` 构建成小程序可用的包）。
|
||
4. 本地 `mvpLocal: true` 时，启动页右上角会出现「SAE MVP 连通性」入口，点它即可进入；也可以把启动页临时设为 `pages/mvp/mvp`。
|
||
5. 用**桌面模拟器**跑；手机上的 `127.0.0.1` 指向手机自己，连不到你电脑。
|
||
|
||
### 3.3 当前配置
|
||
|
||
`taobao/config.js` 新增了：
|
||
|
||
```js
|
||
mvpLocal: true,
|
||
mvpBaseUrl: 'http://127.0.0.1:8080',
|
||
```
|
||
|
||
`pages/mvp/mvp.js` 在 `onLoad` 时如果 `mvpLocal === true`，会临时把 `transport` 改成 `direct`、`baseUrl` 改成 `mvpBaseUrl`，离开页面时恢复。这样不会破坏主应用原来指向 `18180` 的 Node 后端配置。
|
||
|
||
进入页面后会自动调用一次 `/api/taobao/ping`，也可以点三个按钮：
|
||
|
||
- `POST /api/taobao/ping`
|
||
- `POST /api/taobao/whoami`
|
||
- `POST /api/taobao/echo`
|
||
|
||
预期页面显示 `server: "java"`、`pong: true`。
|
||
|
||
> 如果 IDE 拦截 localhost 请求，打开 IDE 的“不校验合法域名”/“开发环境不校验请求域名”开关（不同版本叫法不同）。桌面模拟器一般可以直接访问回环地址。
|
||
|
||
### 3.4 这一步验证了什么
|
||
|
||
- 小程序的 `utils/transport.js` 能走 `direct` 分支；
|
||
- `my.request` 能发 `POST application/json`；
|
||
- `transport.unwrap` 能正确解包 `{success,data}`；
|
||
- Java 后端端口、路径、返回结构都对。
|
||
|
||
---
|
||
|
||
## 4. 云端链路（SAE + 聚石塔云应用）
|
||
|
||
### 4.1 先理解三层关系
|
||
|
||
```text
|
||
淘宝小程序
|
||
└─ @tbmp/mp-cloud-sdk
|
||
└─ 淘宝云网关（校验 appkey/sign，注入 open_id/access_token）
|
||
└─ 聚石塔云应用（应用/环境/流量接入）
|
||
└─ SAE（真正的 Java 容器，跑 JAR）
|
||
```
|
||
|
||
- **SAE 只是算力层**，不是“建一个公网 URL 就能被小程序调用”。
|
||
- 小程序要调通，SAE 应用必须挂在**聚石塔云应用**下，或者走**空应用（不入塔）+ 域名白名单**。
|
||
- 2026-05-11 公告：原聚石塔“应用创建链路”2026-06-20 下线，部署运维迁到 ACK/SAE；聚石塔保留云应用管理、环境管理、流量接入。
|
||
- 参考：[迁移通知](https://api.alidayu.com/support/announcementDetail.htm?source=search&id=25839)、[新链路快速创建云应用](https://open.taobao.com/doc.htm?docId=122332&docType=1)、[云服务产品概述](https://miniapp.open.taobao.com/docV3.htm?docId=118541&docType=1)。
|
||
|
||
### 4.2 构建 JAR
|
||
|
||
```powershell
|
||
Set-ExecutionPolicy -Scope Process Bypass
|
||
. D:\juzi\tools\env-java.ps1
|
||
cd D:\juzi\backend-java
|
||
mvn -DskipTests clean package
|
||
```
|
||
|
||
产物：
|
||
|
||
```text
|
||
D:\juzi\backend-java\target\taobao-mvp-backend-0.0.1-SNAPSHOT.jar
|
||
```
|
||
|
||
### 4.3 SAE 创建应用
|
||
|
||
在 SAE 控制台“创建应用 → 代码包部署 → 设置代码包部署”里按下面选：
|
||
|
||
| 配置项 | 选择 |
|
||
|---|---|
|
||
| 技术栈语言 | **Java** |
|
||
| 代码包类型 | **JAR 包部署** |
|
||
| 应用运行环境 | **标准 Java 应用运行环境** |
|
||
| Java 环境 | **Open JDK 17** |
|
||
| 文件上传方式 | 上传 JAR 包 |
|
||
| 启动命令 | 默认 `java -jar` |
|
||
| 应用端口 | **8080** |
|
||
| 健康检查 | HTTP `GET /actuator/health`，期望 200 |
|
||
| 实例数 | **2**（至少 2，避免单点） |
|
||
| 时区 | **Asia/Shanghai** |
|
||
| 地域/命名空间/VPC | 用聚石塔创建云应用时分配的那套，不要自己新建默认命名空间 |
|
||
|
||
**不要选**：
|
||
|
||
- WAR 包部署
|
||
- `apache-tomcat-*`
|
||
- `EDAS-Container-*`
|
||
- Open JDK 25
|
||
|
||
原因：WAR/Tomcat 是给外置 Tomcat 的老项目；EDAS-Container 是 HSF/Pandora Boot 专用；Open JDK 25 与 Spring Boot 3.5 的兼容性没有 17 稳。
|
||
|
||
环境变量（SAE → 应用设置 → 环境变量）：
|
||
|
||
```text
|
||
TAOBAO_APP_KEY=你的AppKey
|
||
TAOBAO_APP_SECRET=你的AppSecret
|
||
TAOBAO_VERIFY_SIGN=true
|
||
```
|
||
|
||
> `TAOBAO_APP_SECRET` 只能放服务端，绝不能进小程序代码或 `config.js`。
|
||
|
||
建议 JVM 参数（按实例规格调整，堆小于容器内存）：
|
||
|
||
```text
|
||
-Xms512m -Xmx1024m -Duser.timezone=Asia/Shanghai
|
||
```
|
||
|
||
### 4.4 流量接入
|
||
|
||
- 云应用走**内网私网 SLB**：聚石塔“流量接入”里绑定私网 SLB，后端端口 8080。
|
||
- 不要给云应用开公网入口；公网只用于你自己调试。
|
||
- 如果后端要调 TOP/奇门/外部 API，给 SAE 配 **NAT 网关或 EIP**，否则容器只入不出，调用会超时。
|
||
- 数据库在 RDS 时，把 SAE 的网段/安全组加进 RDS 白名单。
|
||
|
||
### 4.5 聚石塔/开放平台关联
|
||
|
||
1. 聚石塔控制台 → 云应用 → 新建云应用（按 2026-05 新链路向导）。
|
||
2. 部署方式选 SAE；创建测试环境、正式环境。
|
||
3. 在 SAE 里把 JAR 部署到对应应用/环境。
|
||
4. 聚石塔 → 流量接入 → 绑定私网 SLB（测试/正式各一套，或共用一个正式 SLB）。
|
||
5. 开放平台控制台 → 云托管 → 关联云应用 → 选择你的云应用和对应 SLB。
|
||
6. 在“服务测试”里调用 `POST /api/taobao/ping`，确认返回 `success: true`。
|
||
7. 在 `taobao/config.js` 里把 `mvpLocal` 改成 `false`，并配置：
|
||
|
||
```js
|
||
transport: 'cloud',
|
||
baseUrl: 'https://你的HTTPS域名',
|
||
cloudAppId: '控制台拿到的 cloudAppId',
|
||
cloudEnv: 'test', // 先 test，验收后改 online
|
||
```
|
||
|
||
8. 进入 `pages/mvp/mvp`，点 `ping`，看到 `transport: "gateway"`、`signVerified: true` 即通。
|
||
|
||
> 账号必须一致：创建云应用的聚石塔账号，要和开放平台小程序账号一致；子账号看不到云应用。小程序上线后默认云应用不能再改，选择时确认好。
|
||
|
||
### 4.6 空应用（不入塔）作为备选
|
||
|
||
如果这个 SAE 应用不在聚石塔，不能直接“关联云应用”。只能走空应用：
|
||
|
||
1. 开放平台 → 云托管 → 云应用管理 → 新建空应用。
|
||
2. 关联一个**没有敏感数据权限**的 AppKey。
|
||
3. 设置域名白名单，提交审批（HTTPS、已备案域名）。
|
||
4. 调用时 `exts.domain` 传你的域名；现有 `transport.js` 已经会传 `domain: config.baseUrl`。
|
||
|
||
注意：现有 `transport.js` 的 cloud 分支还要求 `config.cloudAppId` 非空。如果空应用控制台没有给 cloudAppId，需要先把这行校验放宽（或暂时先用聚石塔云应用）。
|
||
|
||
空应用只适合内容/工具/轻服务；电商交易、用户敏感数据类大概率不适合，还是得入塔。
|
||
|
||
---
|
||
|
||
## 5. 云网关接口契约（Java 后端必须遵守）
|
||
|
||
现有 Node 实现已经按这个契约写了，Java 迁移时照抄：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {},
|
||
"errorCode": "xxxx",
|
||
"errorMessage": "xxxx"
|
||
}
|
||
```
|
||
|
||
- 只支持 **GET/POST**；POST 必须 `application/json`。
|
||
- 请求体 **≤128KB**；超时默认 3s、最大 10s。
|
||
- 平台会往 URL 追加 `app_key`、`open_id`、`access_token`、`sign`、`env`、`mini_app_id` 等系统参数；自定义参数不要重名。
|
||
- 成功时小程序 SDK 只把 `data` 返回给页面；`errorCode/errorMessage` 在失败时返回。
|
||
- 发布前把 `cloudEnv` 从 `test` 改成 `online`；默认云应用上线后不能改。
|
||
- 图片/长任务不要塞进一个请求：现有实现是 64KiB 分片上传 + 异步任务 + 轮询。
|
||
|
||
参考：[云应用调用](https://open.m.taobao.com/docs/doc.htm?treeId=622&articleId=118538&docType=1)。
|
||
|
||
---
|
||
|
||
## 6. 签名校验
|
||
|
||
Java 的 `TaobaoSignatureVerifier` 与现有 `h5/lib/taobao-auth.js` 算法一致：
|
||
|
||
1. 取全部 query 参数，排除 `sign` 和空值，按 key 升序，拼成 `key1value1key2value2...`。
|
||
2. 末尾追加**原始 JSON body**（不要重新序列化）。
|
||
3. `sign_method=md5`：`MD5(secret + content + secret)`；`sign_method` 为空：`MD5(content + secret)`；`hmac*` 用 HMAC。
|
||
4. 结果转大写十六进制，与 `sign` 比较。
|
||
|
||
本地 `TAOBAO_VERIFY_SIGN=false`，没有 `app_key/sign`，直接放行，返回 `signVerified:false`。
|
||
|
||
云端 `TAOBAO_VERIFY_SIGN=true`：
|
||
|
||
- `app_key` 必须等于 `TAOBAO_APP_KEY`；
|
||
- `open_id` 必须符合 `[A-Za-z0-9_-]{4,256}`；
|
||
- `sign` 必须是 32–64 位十六进制；
|
||
- 重复 query 参数直接拒绝；
|
||
- 校验失败返回 `success:false, errorCode:"SIGN_INVALID"`。
|
||
|
||
如果云端一直 `SIGN_INVALID`，按顺序查：
|
||
|
||
1. SAE 环境变量是否真的注入（重启后生效）。
|
||
2. `TAOBAO_APP_KEY` 是否和云应用/小程序一致。
|
||
3. 网关用的 `sign_method` 与后端是否匹配。
|
||
4. body 是否被反向代理/框架重新序列化（必须保留原始字节）。
|
||
5. 是否有重复的 `open_id`/`app_key` 参数。
|
||
|
||
---
|
||
|
||
## 7. 常见问题
|
||
|
||
| 现象 | 排查 |
|
||
|---|---|
|
||
| `UnsupportedClassVersionError` | 编译 JDK 高于 SAE 运行时；统一用 17 |
|
||
| `404` | 路径不对；云应用 path 是否带 `/api/taobao`；WAR 的 context path |
|
||
| `502/504` | SAE 端口不是 8080、健康检查失败、SLB 后端端口不对 |
|
||
| `success:false` + `SIGN_INVALID` | 见第 6 节 |
|
||
| `cloud init failed` | IDE 未登录、AppID/cloudAppId 不匹配、cloudEnv 不对 |
|
||
| `请先配置淘宝云应用和 HTTPS 服务地址` | `transport:'cloud'` 但 `baseUrl` 不是 HTTPS 或 `cloudAppId` 为空 |
|
||
| `直连接口仅用于本机联调` | `transport:'direct'` 但 `baseUrl` 不是 localhost/127.0.0.1 |
|
||
| `Cannot find module '@tbmp/mp-cloud-sdk'` | `npm.cmd ci` 后，在 IDE 里执行“构建 npm” |
|
||
| 手机真机请求失败 | 127.0.0.1 是手机自己；真机必须走云端 HTTPS |
|
||
| 请求超过 10 秒 | 云网关最大 10s；改异步任务 + 轮询 |
|
||
| 返回体超过 128KB | 分页/裁剪字段，不要把大图 base64 放进响应 |
|
||
|
||
### 7.1 淘宝 IDE 报 `install miniapp extension fail: ... wmic ...`
|
||
|
||
Windows 11 24H2 起默认移除了 `wmic.exe`，而淘宝开发者工具在安装小程序扩展时会执行：
|
||
|
||
```text
|
||
wmic path win32_VideoController get caption
|
||
```
|
||
|
||
找不到 `wmic` 就报这个错。本机已经放了一个兼容 shim：
|
||
|
||
```text
|
||
C:\Users\youmi\.local\bin\wmic.cmd
|
||
```
|
||
|
||
修复步骤：
|
||
|
||
1. 完全退出淘宝开发者工具（任务管理器里不要留 `淘宝开发者工具.exe`）。
|
||
2. 重新打开 IDE，再导入 `D:\juzi\taobao`。
|
||
|
||
如果 shim 丢了，重新运行：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File D:\juzi\tools\fix-taobao-ide-wmic.ps1
|
||
```
|
||
|
||
永久方案（需要管理员 PowerShell）：
|
||
|
||
```powershell
|
||
DISM /Online /Add-Capability /CapabilityName:WMIC~~~~
|
||
```
|
||
|
||
装完后 `C:\Windows\System32\wmic.exe` 会优先于 shim，shim 可以删除。如果 DISM 提示找不到这个能力，说明系统镜像没带 WMIC FoD，继续用 shim 即可。
|
||
|
||
---
|
||
|
||
## 8. 下一步（MVP 通过后）
|
||
|
||
1. 把 `h5/lib/taobao-routes.js` 的接口逐个迁到 Java：
|
||
- `POST /api/taobao/challenge`
|
||
- `POST /api/taobao/session`
|
||
- `POST /api/taobao/me`
|
||
- `POST /api/taobao/photo`（64KiB 分片）
|
||
- `POST /api/taobao/skin-analyze`（异步任务）
|
||
- `POST /api/taobao/analysis`（轮询）
|
||
- `POST /api/taobao/reports`
|
||
- `POST /api/taobao/logout`
|
||
2. 所有 `/api/taobao/**` 统一走签名校验 + envelope。
|
||
3. 账号/历史/图片存到 RDS/OSS，不要放容器本地磁盘。
|
||
4. 保留 H5 的 Node 路由不变，淘宝走 Java；两边共用同一套业务规则时，先以现有 Node 实现为契约。
|
||
5. 接 SLS 日志、Actuator 健康检查、告警，再切正式流量。
|
||
|
||
---
|
||
|
||
## 9. 命令速查
|
||
|
||
```powershell
|
||
# 每个新窗口
|
||
Set-ExecutionPolicy -Scope Process Bypass
|
||
. D:\juzi\tools\env-java.ps1
|
||
|
||
# 后端
|
||
cd D:\juzi\backend-java
|
||
mvn -DskipTests clean package
|
||
java -jar target\taobao-mvp-backend-0.0.1-SNAPSHOT.jar
|
||
|
||
# 本地验证
|
||
curl.exe http://127.0.0.1:8080/actuator/health
|
||
curl.exe -X POST -H "Content-Type: application/json" -d "{}" http://127.0.0.1:8080/api/taobao/ping
|
||
|
||
# 前端依赖
|
||
cd D:\juzi\taobao
|
||
npm.cmd ci
|
||
```
|