获取登录方式与协议版本¶
请求参数¶
面向App,服务端使用PostgreSQL;dev/prod表示运行配置,不代表不同服务器。本只读入口可用于当前HTTPS入口的连通性探测。
八项公共请求头全部必填;X-Client-Type只能为app,平台ios/android。成功及业务错误响应设置Cache-Control:no-store,合法请求ID回传X-Request-Id。不需要Authorization。
无路径参数、查询参数和业务请求体。
请求示例¶
示例账号、凭证及UUID为合成数据。当前唯一正式部署环境处于上线前阶段,dev运行配置下手机号和邮箱统一使用123456,仍须先申请challengeId,不发送短信或邮件。公网HTTPS已验收;真实发送供应商及正式开放前的配置检查仍待完成。
base_url='https://api.budyoo.cn' # 当前正式域名;上线前阶段使用隔离开发身份
device_id='4d4ae3ea-6a4a-4f34-a292-8e94551851d7' # 同一安装持久保存
request_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
timestamp="$(date +%s)000"
curl -i --fail-with-body \
-X GET "$base_url/api/v1/auth/options" \
-H 'Accept: application/json' \
-H 'Accept-Language: zh-CN' \
-H 'X-Client-Type: app' \
-H 'X-Platform: android' \
-H 'X-App-Version: 1.0.0' \
-H 'X-App-Build: 1' \
-H 'X-Channel: dev' \
-H "X-Device-Id: $device_id" \
-H "X-Request-Id: $request_id" \
-H "X-Request-Timestamp: $timestamp"
成功响应¶
HTTP 200。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"methods": {
"email": true,
"phone": true,
"google": false,
"apple": false,
"wechat": false
},
"termsVersion": "2026-11-02-draft",
"privacyVersion": "2026-11-02-draft",
"codeLength": 6,
"codeExpiresInSeconds": 300,
"resendAfterSeconds": 60,
"verificationMode": "development-fixed",
"vipGateEnabled": false
},
"errors": []
}
| data字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| methods | object | 否 | email/phone/google/apple/wechat五项boolean,反映实际配置 |
| termsVersion | string | 否 | 当前用户协议同意版本,来自已保存正文集合的持久快照 |
| privacyVersion | string | 否 | 当前隐私政策同意版本,来自已保存正文集合的持久快照 |
| codeLength | integer | 否 | 6 |
| codeExpiresInSeconds | integer | 否 | 300 |
| resendAfterSeconds | integer | 否 | 60 |
| verificationMode | string | 否 | development-fixed:开发固定123456;delivery:真实投递 |
| vipGateEnabled | boolean | 否 | 当前请求发行渠道的VIP准入开关,默认false;资料完成后是否需要付费再进入主页 |
失败响应¶
| HTTP | 业务码 | 条件/处理 |
|---|---|---|
| 400 | INVALID_APP_CHANNEL | 渠道未知、平台不匹配或prod误用dev,不能当关闭VIP门槛 |
| 400 | INVALID_CLIENT_HEADERS | 元数据缺失、重复或不合法 |
| 400 | VALIDATION_FAILED / BAD_REQUEST | 请求字段、类型或JSON不符合契约 |
| 403 | FORBIDDEN | 本批仅接受app类型客户端 |
| 503 | SERVICE_UNAVAILABLE | 当前渠道VIP策略缺失或数据库暂不可用;不按关闭门槛放行 |
错误结构与公共协议一致;字段校验使用errors[].field/message,Accept明确不接受可用响应格式时406可无正文。示意:
{
"code": "INVALID_CLIENT_HEADERS",
"message": "对应当前请求语言的错误提示",
"data": null,
"errors": []
}
接入说明¶
VIP开关按发行渠道独立读取,沿用既有X-Channel/X-Platform及三个VIP布尔字段。登录绑定会话渠道,访问和刷新须一致;历史NULL会话首次合法使用绑定,之后改头返回401。首次注册来源字段只做归因,不决定当前会话门槛。详见渠道与VIP准入。
后台协议保存成功即生效,对应termsVersion或privacyVersion会同事务更新,无需重启或另点发布。这两个值与协议目录的requiredVersion一致,单份正文的contentVersion可不同。不要写死旧配置版本;尚无对应正文的新环境仍使用初始化兼容值,目录保持不可用。版本变化后刷新登录配置并要求用户重新明确同意,不能沿用旧勾选或挑战。
两层跳转与支付边界见注册资料与VIP准入:先完成资料,再判断vipRequired;COMPLETE或nextStep=HOME单独都不足以跳过开启的VIP门槛。渠道开关独立配置(首次初始化默认关闭,升级保留原值),客户端不能自行提交付款成功来获得权益。
登录页按此结果展示实际可用性;国内/国际布局先由闪屏IP配置决定,国内默认手机号、国际默认邮箱。另一种已开放登录方式仍须可选择,避免用户出国或更换网络后无法登录原绑定账号;选择输入类型不改布局、渠道、协议范围或账号关联。开发固定模式下email和phone为true,三方为false;真实投递模式按供应商配置返回可用性。local H2全部不可用。认证要求版本仍独立配置,IP不授予登录或付款权限。
验证:在服务器隔离PostgreSQL上验证认证、字段校验与失败分支;验证码投递使用仅测试源码中的捕获替身,Google/Apple使用临时RSA密钥完成真实验签测试。未向真实用户发送短信/邮件,未使用真实三方应用完成端到端登录,也未代表Flutter已接入。接口实现位于Java的identity/profile/catalog/media模块;完整接入顺序见登录注册接入。