Hello OP 对接 SUD OpenPaaS 示例
本文以 helloOP-developer(helloOP 开发者中心)为参考实现,说明平台应用(APP)如何落地 存量数据同步流程 中描述的 OAuth 2.0 授权与存量数据拉取能力。
本示例对应的抽象协议见 开放接口(Webhook)。helloOP 采用 Spring Authorization Server 标准 OAuth 2.0 端点 + 开发者业务 API,语义对齐 Webhook 规范,路径与请求形态按 RFC 6749 / 业务约定实现。
1. 示例定位
| 抽象角色(存量同步 SOP) | helloOP 中的对应 |
|---|---|
| 平台应用(APP)= AS + RS | helloOP-developer-server |
| SUD OpenPaaS = OAuth2 Client | 在 helloOP 中注册的第三方应用(oauth2_registered_client) |
| 游戏厂商(CP) | helloOP 开发者账号(t_developer) |
cp_id | JWT uid claim(开发者主键 ID) |
业务目标不变:厂商在 SUD OpenPaaS 发起「绑定 helloOP 账号」→ 浏览器完成 helloOP 登录授权 → SUD 换取 Token → 拉取该开发者的主体与游戏存量数据。
2. helloOP-developer 模块结构
helloOP-developer/
├── helloOP-developer-api/ # Feign / DTO(跨服务)
└── helloOP-developer-server/ # Spring Boot 应用
└── src/main/java/.../developer/
├── config/
│ └── SecurityConfig.java # 多层安全过滤链 + OAuth2 AS
├── controller/
│ ├── auth/LoginController # POST /developer/login(开发者控制台)
│ ├── developer/DeveloperController
│ │ # GET /developer/info(OpenPaaS 拉取主体)
│ ├── app/DeveloperAppController # POST /developer/app/create(注册 Client)
│ └── game/DeveloperGameController
│ # 游戏列表 / 详情 / 资质 / ICP 拉取
└── service/ # 开发者、应用、游戏业务实现2.1 安全过滤链(理解对接的关键)
| Order | 匹配路径 | 认证方式 | 用途 |
|---|---|---|---|
| 1 | /oauth2/** | OAuth2 协议 | 授权、换码、刷新、吊销等标准端点 |
| 2 | /developer/** | Bearer JWT(须含 uid) | 开发者业务 API;OpenPaaS 拉数走此链 |
| 3 | /external/**、/pink/** | 放行 | 其他外部能力(与本示例无关) |
| 4 | 其余 | 表单登录 | login.html 等;Authorization Code 流程的登录页 |
两条登录路径不要混用:
| 对比项 | AS 表单登录(对接 SUD 时使用) | 自定义 REST 登录 |
|---|---|---|
| 入口 | 浏览器访问 /oauth2/authorize → 未登录跳转 /login.html | POST /developer/login |
| 产出 | Session → 继续授权 → 颁发 authorization_code | 直接返回开发者 JWT |
| 适用 | 第三方(SUD OpenPaaS)绑定账号 | 开发者本人使用控制台管理应用/游戏 |
SUD 对接必须走 Authorization Code,不要用 POST /developer/login 代替授权流程。
3. 完整对接流程
3.1 阶段零:将 SUD 注册为 OAuth2 Client(一次性)
由 helloOP 侧具备开发者权限的管理员完成(可在控制台或通过 API):
POST /developer/login获取管理用 JWT(仅用于创建 Client,与用户绑定流程无关)。POST /developer/app/create注册应用:httpPOST /developer/app/create Authorization: Bearer {开发者管理JWT} Content-Type: application/json { "clientName": "SUD OpenPaaS", "redirectUris": [ "https://{sud-op-host}/callback" ], "scopes": "read write" }响应中的
clientId/clientSecret(明文仅返回一次)配置到 SUD OpenPaaS 后端;后续所有厂商绑定复用这对凭证。
提供 redirectUris 后,Client 将启用 authorization_code(并通常同时支持 refresh_token 等)。
3.2 阶段一:用户授权(浏览器)
用户浏览器 SUD OpenPaaS helloOP-developer
│ │ │
│ 点击「绑定 helloOP」│ │
│───────────────────→│ │
│ 302 重定向 │ │
│←───────────────────│ │
│ Location: │
│ https://{helloOP}/oauth2/authorize │
│ ?response_type=code │
│ &client_id={clientId} │
│ &redirect_uri=https://{sud}/callback │
│ &scope=read write │
│ &state={随机值} │
│───────────────────────────────────────────────────────→│
│ │ 校验 client_id /│
│ │ redirect_uri │
│ │ 未登录 → /login.html
│ 展示 helloOP 登录页 │ │
│←───────────────────────────────────────────────────────│
│ POST /oauth2/do-login(表单:username + password) │
│───────────────────────────────────────────────────────→│
│ │ 认证通过 → 生成 code
│ 302 → redirect_uri?code=...&state=... │
│←───────────────────────────────────────────────────────│
│───────────────────→│ 校验 state │要点:
- 登录页在 helloOP 域名下,SUD 看不到账号密码;
state由 SUD 生成并在回调时校验;redirect_uri必须与注册时完全一致。
3.3 阶段二:用授权码换 Token(服务端)
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code={AUTHORIZATION_CODE}
&redirect_uri=https://{sud}/callback
&client_id={clientId}
&client_secret={clientSecret}成功响应(标准 OAuth2):
{
"access_token": "eyJhbG...",
"token_type": "Bearer",
"expires_in": 7200,
"refresh_token": "...",
"scope": "read write"
}helloOP 通过 OAuth2TokenCustomizer 在 access_token 中写入 uid(开发者 ID)。SUD 可将该 uid 视为抽象协议中的 cp_id,用于账号映射。
3.4 阶段三:拉取存量数据
所有拉取接口均需:
Authorization: Bearer {access_token}且 Token 必须包含 uid claim;client_credentials 颁发的无 uid Token 不能访问 /developer/**。
推荐顺序:
| 顺序 | helloOP 接口 | 说明 |
|---|---|---|
| 1 | GET /developer/info | 主体信息;主体 ID 从 Token uid 解析,无需路径传参 |
| 2 | GET /developer/game/list | 已上线游戏列表(分页) |
| 3 | GET /developer/game/basic-info?bundle_id= | 单游戏基本信息 |
| 4 | GET /developer/game/qualification?bundle_id= | 单游戏资质(软著/版号等) |
| 5 | GET /developer/game/icp-filing?bundle_id= | 单游戏 ICP 备案(对应 game.queryICP) |
列表项中的 bundle_id(包名)作为后续详情/资质/ICP 的查询键。
3.5 阶段四:Token 续签
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token={refresh_token}
&client_id={clientId}
&client_secret={clientSecret}解绑时可调用 POST /oauth2/revoke 吊销 Token。
4. 抽象 Webhook ↔ helloOP 接口映射
| 存量同步 Webhook | helloOP 实现 | 差异说明 |
|---|---|---|
| oauth.authorize | GET /oauth2/authorize | 标准浏览器重定向;成功后 302 回 redirect_uri,而非 JSON 包一层 code |
| oauth.accessToken | POST /oauth2/token(grant_type=authorization_code) | application/x-www-form-urlencoded;厂商标识在 JWT uid,不单独返回 cp_id 字段 |
| oauth.refreshToken | POST /oauth2/token(grant_type=refresh_token) | 同上,标准 Token 端点 |
| cp.queryDetail | GET /developer/info | 字段:id / subject_name / subject_type / uscc / username / status |
| cp.queryKYC | GET /developer/info | 主体级 KYC 与 info 同构;更细主办方/负责人见 game.queryICP |
| game.queryList | GET /developer/game/list | 分页键为 page_no / page_size;列表项为 bundle_id / name / version |
| game.queryDetail | GET /developer/game/basic-info?bundle_id= | 请求键为 bundle_id,非 game_id |
| game.queryKYC | GET /developer/game/qualification?bundle_id= | 结构化 software_copyright / publication_number 等 |
| game.queryICP | GET /developer/game/icp-filing?bundle_id= | 含顶层 license_no;枚举字段返回文案 |
若 APP 选择完全按 Webhook 文档实现自定义 HTTPS 接口(JSON Body + 签名头),语义仍应对齐上表;helloOP 选择标准 OAuth2 + REST GET,便于与 Spring Authorization Server 生态兼容。
5. 拉取接口字段摘要
5.1 主体信息 GET /developer/info
| 字段 | 说明 |
|---|---|
id | 三方平台主体 ID(即 Token uid / 映射用 cp_id) |
subject_name | 主体名称 |
subject_type | 0 个人,1 企业 |
uscc | 统一社会信用代码(企业) |
username | 登录用户名 |
status | 0 禁用,1 启用 |
5.2 游戏列表 GET /developer/game/list
| 字段 | 说明 |
|---|---|
list[].bundle_id | 游戏包名(后续拉取键) |
list[].name | 游戏名称 |
list[].version | 最新版本号 |
total / page_no / page_size | 分页信息 |
仅返回已上线(status=1)游戏。
5.3 游戏基本信息 / 资质 / ICP
- basic-info:名称、图标、引擎、分类、简介、客服与隐私政策等
- qualification:
software_copyright、publication_number、补充材料等 - icp-filing:主办方、负责人、游戏备案、前置审批、授权书等
请求均携带 bundle_id Query 参数与 Bearer Token。统一响应外壳为:
{
"ret_code": 0,
"ret_msg": "success",
"data": { },
"timestamp": 1719820800000
}6. 端到端时序(helloOP)
7. 对接检查清单
APP(helloOP)侧
- [ ] 已注册 SUD Client,
redirect_uri白名单正确 - [ ] Authorization Code 登录页可正常认证开发者账号
- [ ] access_token 含
uid,且/developer/**拒绝无uidToken - [ ] 提供主体、游戏列表、详情、资质(及 ICP)拉取接口
- [ ] 支持
refresh_token;可选支持revoke
SUD OpenPaaS 侧
- [ ] 安全存储
client_id/client_secret - [ ] 授权发起带随机
state,回调严格校验 - [ ] 仅服务端换码,前端不接触
client_secret - [ ] 用
uid完成厂商账号映射并持久化 Token - [ ] 按列表分页拉全量游戏,缺失项可告警重试
- [ ] Token 过期自动刷新;刷新失败引导重新授权
