保存注册资料草稿¶
请求参数¶
面向App,服务端使用PostgreSQL;dev/prod表示运行配置,不代表不同服务器。当前公网入口使用HTTPS;仅显式启用的dev固定码HTTP例外可访问隔离开发身份。任何prod组合均关闭固定码与HTTP例外,不能靠X-Forwarded-Proto绕过。
八项公共请求头全部必填;X-Client-Type只能为app,平台ios/android。成功及业务错误响应设置Cache-Control:no-store,合法请求ID回传X-Request-Id。另须 Authorization: Bearer <accessToken>,安装ID必须与会话一致。
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
| country | string | 否 | 正式国家代码,小写2位 |
| nickname | string | 否 | trim后非空,原输入1–8个UTF-16代码单元 |
| gender | string | 否 | male 或 female |
| birthday | string(date) | 否 | 1900-01-01至今天,YYYY-MM-DD;不代表年龄准入策略 |
| spokenLanguage | string | 否 | 资料语言目录中的单个我会的语言id;保存后须与learningLanguage不同 |
| learningLanguage | string | 否 | 资料语言目录中的单个学习语言id;保存后须与spokenLanguage不同 |
| introduction | string | 否 | trim后非空,原输入1–30个UTF-16代码单元 |
| avatarId | string | 否 | 本人上传的UUID;空字符串清除;不传/null保留 |
| interests | string[] | 否 | 0–6个不重复的正式标签代码;[]清空 |
无路径参数和查询参数。
请求示例¶
示例账号、凭证及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"
access_token='替换为实际accessToken'
curl -i --fail-with-body \
-X PATCH "$base_url/api/v1/me/registration" \
-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" \
-H "Authorization: Bearer $access_token" \
-H 'Content-Type: application/json' \
--data '{"country":"cn","nickname":"测试用户","gender":"female","birthday":"2000-01-02","spokenLanguage":"zh","learningLanguage":"en","introduction":"喜欢旅行,正在学英语","interests":["meet","chat"]}'
成功响应¶
HTTP 200。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"userId": "11111111-1111-4111-8111-111111111111",
"registrationStatus": "INCOMPLETE",
"nextStep": "COMPLETE_REGISTRATION",
"registrationStep": 4,
"vipGateEnabled": false,
"vipActive": false,
"vipRequired": false,
"country": "cn",
"nickname": "测试用户",
"gender": "female",
"birthday": "2000-01-02",
"spokenLanguage": "zh",
"learningLanguage": "en",
"introduction": "喜欢旅行,正在学英语",
"avatarId": null,
"interests": [
"chat",
"meet"
],
"completionPercent": 70,
"moderation": {
"avatar": {
"status": "EMPTY",
"reviewId": null,
"reason": null,
"submittedAt": null,
"reviewedAt": null
},
"nickname": {
"status": "NOT_SUBMITTED",
"reviewId": null,
"reason": null,
"submittedAt": null,
"reviewedAt": null
},
"introduction": {
"status": "NOT_SUBMITTED",
"reviewId": null,
"reason": null,
"submittedAt": null,
"reviewedAt": null
},
"published": {
"avatarId": null,
"nickname": null,
"introduction": null
}
}
},
"errors": []
}
| data字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| userId | string(UUID) | 否 | 当前账号编号 |
| completionPercent | integer | 否 | 后端按已保存本人资料计算的0–100整数百分比,只读,不带百分号;规则见资料完善度 |
| registrationStatus | string | 否 | INCOMPLETE 或 COMPLETE |
| nextStep | string | 否 | COUNTRY、PROFILE、INTRO、INTERESTS、COMPLETE_REGISTRATION 或 HOME,保留原导航语义 |
| registrationStep | integer | 否 | 仅1–4:1国家、2资料、3语言生日介绍、4兴趣;完成后仍为4,由registrationStatus区分 |
| vipGateEnabled | boolean | 否 | 当前会话发行渠道的第二层VIP准入开关,动态读取,默认false |
| vipActive | boolean | 否 | 服务端确认的有效VIP权益;未付款、过期或撤销为false |
| vipRequired | boolean | 否 | 资料完成且开关开启、无有效VIP时为true,需进入VIP页 |
| country | string | 是 | 国家目录代码 |
| nickname | string | 是 | 昵称,新写入1–8个UTF-16代码单元;历史昵称按原值返回 |
| gender | string | 是 | male 或 female |
| birthday | string(date) | 是 | YYYY-MM-DD |
| spokenLanguage | string | 是 | 我会的语言代码 |
| learningLanguage | string | 是 | 学习语言代码 |
| introduction | string | 是 | 个人介绍,最多30个UTF-16代码单元 |
| avatarId | string(UUID) | 是 | 本人已上传头像编号 |
| interests | string[] | 否 | 兴趣代码,返回按代码升序,无选择为[] |
失败响应¶
| HTTP | 业务码 | 条件/处理 |
|---|---|---|
| 400 | INVALID_APP_CHANNEL | 渠道未知、平台不匹配或prod误用dev,不能当关闭VIP门槛 |
| 400 | INTEREST_UNAVAILABLE | 新加入停用标签,请刷新目录重新选择 |
| 400 | PROFILE_LANGUAGES_SAME | 我会的语言与想学习的语言相同,请重新选择不同的语言 |
| 400 | INVALID_CLIENT_HEADERS | 元数据缺失、重复或不合法 |
| 400 | VALIDATION_FAILED / BAD_REQUEST | 请求字段、类型或JSON不符合契约 |
| 403 | FORBIDDEN | 本批仅接受app类型客户端 |
| 503 | SERVICE_UNAVAILABLE | 当前渠道VIP策略缺失或数据库暂不可用;不按关闭门槛放行 |
| 426 | HTTPS_REQUIRED | 敏感接口要求HTTPS |
| 401 | UNAUTHORIZED | 未登录、凭证失效或设备不匹配 |
| 400 | INVALID_PROFILE | 未知字典、空白内容、重复标签或不合法日期 |
| 400 | INVALID_AVATAR | 图片不存在或不属于本人 |
| 403 | ACCOUNT_DISABLED | 账号不可用 |
| 409 | REGISTRATION_COMPLETED | 注册已完成 |
错误结构与公共协议一致;字段校验使用errors[].field/message,Accept明确不接受可用响应格式时406可无正文。示意:
{
"code": "INVALID_PROFILE",
"message": "对应当前请求语言的错误提示",
"data": null,
"errors": []
}
接入说明¶
2026-11-20统一媒体交付已部署到唯一正式环境(运行配置仍为dev):已认证App成功响应自动替换受支持用户媒体URL并按需附加顶层mediaDelivery,不再要求能力头;无头、cdn-v1和oss-v1均使用同一结构。服务端选择CDN/OSS/API,客户端按transport加载;原ID、版本、权限、JWE与JSON的no-store保持。非空avatarId及albumPhotoIds按统一规则补充avatarUrl/albumPhotos,单项媒体依赖失败不推翻已提交业务。完整字段、缓存与Flutter验收见统一媒体交付。
本响应直接带回data.completionPercent,前端使用服务端分数,不再按字段数量自行均分,不需要新增请求。completionPercent不是可写字段,本接口沿用忽略未知字段的兼容行为,提交它不会设置分数,响应仍由后端按保存资料计算。本页成功示例按无已绑定相册计算,相册存在性由服务端读取,无需客户端补拉相册。
新增moderation对象,三项avatar/nickname/introduction分别返回status、reviewId、reason、submittedAt及reviewedAt,另有published保存当前实际公开值。类型、可空范围、状态和示例见逐项资料审核。本人响应的原头像、昵称、签名继续表示本人提交内容;保存或注册完成只表示自动进入审核,公开页面只取最后通过值,首次无通过值使用默认头像/四语默认昵称/空签名。审核不新增注册步骤、不改变渠道VIP,其他字段或无变化保存不重复提审;清空头像或签名立即撤下。
VIP开关按发行渠道独立读取,沿用既有X-Channel/X-Platform及三个VIP布尔字段。登录绑定会话渠道,访问和刷新须一致;历史NULL会话首次合法使用绑定,之后改头返回401。首次注册来源字段只做归因,不决定当前会话门槛。详见渠道与VIP准入。
兴趣选项由完整兴趣目录提供。新加入的标签须selectable=true;原已选停用项可保留或取消,取消后不能再加入,完成注册要求所选1–6项全部当前可选。分类停用同样影响其标签;不可选的新提交返回400 INTEREST_UNAVAILABLE,失败不改资料、版本或步骤。
我会的语言(spokenLanguage)与想学习的语言(learningLanguage)按服务端目录id比较,保存后的两项必须不同。PATCH仅传一项时,服务端在用户行锁内与已保存的另一项合并后校验;未提供或null保留,不能通过分次提交绕过。可在同次请求中交换两种不同语言。历史重复资料读取时保持原值,未修改语言的其他资料保存不强制清空;修改任一语言时必须修正重复。校验失败不保存资料、兴趣、版本或注册步骤。
重复语言返回HTTP400,code固定为PROFILE_LANGUAGES_SAME;message按Accept-Language支持中英日韩,未知语言回退英文,data=null、errors=[]。例如中文:
{"code":"PROFILE_LANGUAGES_SAME","message":"我会的语言和想学习的语言不能相同,请重新选择。","data":null,"errors":[]}
两层跳转与支付边界见注册资料与VIP准入:先完成资料,再判断vipRequired;COMPLETE或nextStep=HOME单独都不足以跳过开启的VIP门槛。渠道开关独立配置(首次初始化默认关闭,升级保留原值),客户端不能自行提交付款成功来获得权益。
步骤对应与重登恢复流程见登录注册步骤说明。每次保存资料成功后由服务端同步落库,登录直接返回registrationStep供前端跳转,无需增加或调用单独进度接口;现有刷新和本人资料也返回同一字段,客户端不提交步骤。第4步及已完成用户均返回4,registrationStatus=COMPLETE后还须判断vipRequired:true进入VIP页,false才进入首页。
部分更新:未提供或null字段不覆盖已有草稿。每步离开前保存,重新登录通过获取当前用户恢复。昵称、性别、生日、两种语言、介绍、国家及至少1个兴趣在最终完成时必填,头像选填。注册完成后该接口停止接受修改,使用新增独立资料编辑接口;介绍仍为30字符,性别不可修改,不回退注册步骤。
验证:在服务器隔离PostgreSQL上验证认证、字段校验与失败分支;验证码投递使用仅测试源码中的捕获替身,Google/Apple使用临时RSA密钥完成真实验签测试。未向真实用户发送短信/邮件,未使用真实三方应用完成端到端登录,也未代表Flutter已接入。接口实现位于Java的identity/profile/catalog/media模块;完整接入顺序见登录注册接入。
2026-11-05资料规则验证:服务器隔离PostgreSQL/Redis的529项完整回归通过;8项昵称用例及新增16项语言用例覆盖三条资料写入口、两种语言同次/单项重复、显式null合并、合法交换、失败不改资料/兴趣/版本/步骤、旧重复草稿完成前修正、历史资料非语言修改、领域调用与并发注册提交,以及四语/未知语言回退的真实JWE错误响应。未在运行库创建测试账号或修改真实用户资料。
验证范围¶
2026-11-06服务器隔离PostgreSQL/Redis的clean verify共763项全部通过,新增25项覆盖十项权重、空白与空列表、注册保存/完成、本人资料/主页/编辑读取与保存一致性、媒体暂存与绑定/清空、待审资料、并发读取快照、客户端只读字段、失败不改变分数、四语与英文回退,以及原鉴权/安装/公共头/VIP准入;接口用例通过真实HTTP控制器与JWE认证解密。仅操作隔离合成账号;运行环境的已登录资料和客户端/设备显示未在本次操作,Flutter需接入服务端completionPercent。