读取可编辑本人资料¶
请求参数¶
面向App,必须登录、完成注册并通过动态VIP准入。八项公共头全部必填,app/ios或android,安装UUID与会话绑定。正式要求HTTPS;当前dev仅隔离固定码账号允许明文HTTP。JSON遵循统一JWE协议;选择密文时仍要求HTTPS。未完成注册返回403,待VIP返回403/VIP_REQUIRED。
公共头见请求头,四语见公共响应,加密见JWE协议。客户端类型和图片UUID本身不授予权限。
无查询参数。 无业务请求体。
请求示例¶
示例UUID为合成数据;deviceId必须复用当前安装,不要每次新建。以下示例覆盖八项公共头;禁止日志输出Cookie或Bearer。
base_url='https://api.budyoo.cn' # 仅隔离开发账号;正式使用HTTPS
device_id='4d4ae3ea-6a4a-4f34-a292-8e94551851d7' # 当前会话对应安装
access_token='替换为当前开发会话'
curl --fail-with-body -X GET "$base_url/api/v1/me/profile" \
-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: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
-H "X-Request-Timestamp: $(date +%s)000" \
-H "Authorization: Bearer $access_token"
成功响应¶
以下成功示例按2026-11-20已部署的统一协议展示;CDN示例为合成对象,默认头像示例使用API通道,真实地址及权限以服务端返回为准。
HTTP200,Cache-Control:no-store;合法请求ID回传。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"userId": "11111111-1111-4111-8111-111111111111",
"registrationStatus": "COMPLETE",
"version": 1,
"updatedAt": "2026-11-03T10:00:00Z",
"country": "cn",
"nickname": "合成用户",
"gender": "female",
"birthday": "2000-01-02",
"spokenLanguage": "zh",
"learningLanguage": "en",
"introduction": "喜欢旅行和摄影",
"avatarId": null,
"interests": [
"photo",
"travel"
],
"albumPhotoIds": [],
"completionPercent": 70,
"moderation": {
"avatar": {
"status": "EMPTY",
"reviewId": null,
"reason": null,
"submittedAt": null,
"reviewedAt": null
},
"nickname": {
"status": "PENDING",
"reviewId": "00000000-0000-4000-8000-000000000002",
"reason": null,
"submittedAt": "2026-11-06T00:00:00Z",
"reviewedAt": null
},
"introduction": {
"status": "PENDING",
"reviewId": "00000000-0000-4000-8000-000000000003",
"reason": null,
"submittedAt": "2026-11-06T00:00:00Z",
"reviewedAt": null
},
"published": {
"avatarId": null,
"nickname": null,
"introduction": null
}
},
"display": {
"language": "zh-CN",
"country": {
"id": "cn",
"name": "中国",
"names": {
"zh-CN": "中国",
"en": "China",
"ja": "中国",
"ko": "중국"
},
"flagUrl": "/api/v1/media/country-flags/cn"
},
"spokenLanguage": {
"id": "zh",
"name": "中文",
"names": {
"zh-CN": "中文",
"en": "Chinese",
"ja": "中国語",
"ko": "중국어"
},
"nativeName": "中文"
},
"learningLanguage": {
"id": "en",
"name": "英语",
"names": {
"zh-CN": "英语",
"en": "English",
"ja": "英語",
"ko": "영어"
},
"nativeName": "English"
},
"interests": [
{
"id": "photo",
"groupId": "lifestyle",
"name": "摄影",
"names": {
"zh-CN": "摄影",
"en": "Photography",
"ja": "写真",
"ko": "사진"
},
"iconId": "00000000-0000-4000-8000-000000000004",
"iconUrl": "/api/v1/media/interest-icons/00000000-0000-4000-8000-000000000004",
"enabled": true,
"selectable": true,
"sortOrder": 4,
"version": 0
},
{
"id": "travel",
"groupId": "lifestyle",
"name": "旅行",
"names": {
"zh-CN": "旅行",
"en": "Travel",
"ja": "旅行",
"ko": "여행"
},
"iconId": "00000000-0000-4000-8000-000000000005",
"iconUrl": "/api/v1/media/interest-icons/00000000-0000-4000-8000-000000000005",
"enabled": true,
"selectable": true,
"sortOrder": 5,
"version": 0
}
]
},
"albumPhotos": []
},
"errors": []
}
| data字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| userId | string(UUID) | 否 | 资料所属用户,不由请求体指定 |
| completionPercent | integer | 否 | 后端按已保存本人资料计算的0–100整数百分比,只读,不带百分号;规则见下文 |
| registrationStatus | string | 否 | INCOMPLETE/COMPLETE;只读,后台可读取未完成资料 |
| version | integer(int64) | 否 | 从0开始;每次编辑保存递增,下一次作为expectedVersion |
| updatedAt | string(date-time) | 否 | 带时区ISO 8601;仅展示,不能代替version |
| country | string | 是 | 249国家/地区目录的小写代码 |
| nickname | string | 是 | 新写入1–8个UTF-16代码单元;历史昵称按原值返回 |
| gender | string | 是 | male/female,注册后只读 |
| birthday | string(date) | 是 | YYYY-MM-DD,1900-01-01至服务端当天 |
| spokenLanguage | string | 是 | 字典中的单个我会的语言代码 |
| learningLanguage | string | 是 | 字典中的单个学习语言代码 |
| introduction | string | 是 | 最多30个UTF-16代码单元;编辑后允许空字符串 |
| avatarId | string(UUID) | 是 | 本人上传头像引用,无头像为null |
| avatarUrl | string或null | 非空avatarId时补充 | 后台生成的媒体URL,单项不可用为null,交由公共媒体组件加载 |
| interests | string[] | 否 | 按代码升序,完成账号保留1–6个 |
| albumPhotoIds | string(UUID)[] | 否 | 0–9张;保留旧照片相对顺序,新照片按提交顺序追加 |
| albumPhotos | object[] | 否 | 与albumPhotoIds同序,每项id与可空url;媒体失败不丢失照片ID |
| display | object | 否 | 仅当前选择的名称及图标,不是完整可选目录 |
| display.language | string | 否 | zh-CN/en/ja/ko;未知或缺省界面语言回退en |
| display.country | object | 是 | id/name/names/flagUrl;未选择或历史未知为null,原country不改写 |
| display.spokenLanguage/learningLanguage | object | 是 | id/name/names/nativeName;未选择或历史未知为null |
| display.interests | object[] | 否 | 仅interests中有目录元数据的已选项,顺序与原interests一致;含停用已选项 |
| 各项names | object | 否 | zh-CN/en/ja/ko四语名称;name按本次Accept-Language生成 |
| 兴趣项id/groupId/name | string | 否 | 稳定标签ID、分类ID和当前语言名,不依赖客户端本地映射 |
| 兴趣项iconId/iconUrl | UUID/string | 否 | 不可变图标引用及既有媒体路径,不携带二进制或外部地址 |
| 兴趣项enabled/selectable | boolean | 否 | 标签自身启用/标签和分类均启用;旧已选停用项保留显示 |
| 兴趣项sortOrder/version | integer | 否 | 目录排序及标签修订,兼容完整兴趣目录单项结构;不替代资料version |
资料完善度¶
data.completionPercent为后端计算的整数,范围0–100,客户端显示时再加%,不接受客户端写入。各项完成即取得整项分值,分数直接相加,无取整误差。
| 项目 | 分值 | 完成条件 |
|---|---|---|
| 头像 | 20 | 已保存绑定的avatarId非空 |
| 昵称 | 10 | 本人已保存昵称非空且非纯空白 |
| 性别 | 5 | 已填写 |
| 生日 | 5 | 已填写 |
| 国家 | 10 | 已选择国家代码 |
| 我会的语言 | 10 | 已选择spokenLanguage |
| 学习语言 | 10 | 已选择learningLanguage |
| 兴趣 | 10 | 至少保存1个非空兴趣代码,多选不叠加 |
| 个人介绍 | 10 | 本人已保存介绍非空且非纯空白 |
| 相册 | 10 | 至少保存绑定1张照片,多张不叠加 |
按本人已保存值计分,待审/驳回不改变填写状态,不使用moderation.published或默认头像、默认昵称、翻译展示文案补分。空值、空串、纯空白、未保存的输入和暂存上传均不计分;清空或解绑成功后即时扣回。完整国家/语言目录和媒体下载不参与计算,旧选择代码缺少display元数据时仍按已保存选择计分。
例如其他项目均已完成,仅缺介绍和相册时为80,补介绍后90,保存绑定首张相册照片后100。本页合成示例无头像、无相册,其他项齐全,因此为70。没有任何资料时为0;读取失败返回原错误,不能用0伪装成功。
GET/PATCH本人编辑资料、GET本人资料、注册草稿保存及完成结果在data.completionPercent返回同一规则;“我的”主页在data.account.completionPercent返回。它表示填写完整度,不代替registrationStatus、registrationStep、VIP准入或审核结果;不强制100分才能完成注册或进入主页。
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | BAD_REQUEST/VALIDATION_FAILED | 路径UUID、请求格式或必填参数不合法 |
| 400 | INVALID_CLIENT_HEADERS | 公共头缺失、重复或格式错误 |
| 401 | UNAUTHORIZED | 未登录、会话失效或安装不匹配 |
| 403 | FORBIDDEN/VIP_REQUIRED | 未完成注册或VIP准入未通过 |
| 404 | NOT_FOUND | 用户或归属范围内的图片不存在/已删除 |
| 426 | HTTPS_REQUIRED | 当前路径不允许明文HTTP |
| 503 | SERVICE_UNAVAILABLE | 数据库/Redis依赖暂不可用 |
| 400/409 | 加密协议错误码 | JWE缺失、篡改、过期、重放,按公共加密协议处理 |
错误结构示例:
{"code":"UNAUTHORIZED","message":"按Accept-Language返回中文、英文、日文或韩文提示","data":null,"errors":[]}
未知或缺省语言回退英文;code不翻译。字段校验明细在errors[].field/message。网关可能先返回429/413,不能当成认证过的JWE业务响应。
接入说明¶
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验收见统一媒体交付。
国家/地区只有当前有效VIP可以实际修改;非VIP读取及其他字段编辑仍按原准入规则,具体失败码和原值兼容见保存接口。本响应不新增VIP或可编辑开关,保存时由服务端实时核验权益。
本响应直接带回data.completionPercent,前端使用服务端分数,不再按字段数量自行均分,不需要新增请求。
编辑资料首次进入只请求GET /api/v1/me/profile:一次取得头像、昵称、相册、性别、生日、国家、介绍、两种语言和当前已选兴趣。display补齐当前选择的四语名称及图标,不返回完整国家/语言/兴趣列表、注册字典、VIP、钱包或统计。version、updatedAt和moderation保留资料并发及审核所需信息。
完整国家、语言或兴趣目录仅在用户打开对应选择器时按需加载;display.interests不是完整可选目录,不得拿来限制新增选项。原interests保留所有真实选择代码;历史未知标签缺少display元数据时保留原ID并明确展示,不自动删除或回退设计数据。头像、相册、国旗及兴趣图标继续通过已有媒体路径/缓存按需读取,媒体失败独立重试,不重新拉取资料JSON。
PATCH成功也直接返回同一份资料及新display,按服务端结果一次回填,不需要保存后再GET或补拉目录。兴趣集合没有实际变化时省略interests,服务端按原值保留;历史未知ID不因缺少展示元数据而被自动删除,也不作为新选项提交。读取的资料/审核与动态兴趣元数据共享只读REPEATABLE_READ快照;保存的资料、审核提交及展示组装同事务,依赖失败整体503并回滚写入。后台原资料接口保持原结构,本次不扩展后台展示字段。
新增moderation对象,三项avatar/nickname/introduction分别返回status、reviewId、reason、submittedAt及reviewedAt,另有published保存当前实际公开值。类型、可空范围、状态和示例见逐项资料审核。本人响应的原头像、昵称、签名继续表示本人提交内容;保存或注册完成只表示自动进入审核,公开页面只取最后通过值,首次无通过值使用默认头像/四语默认昵称/空签名。审核不新增注册步骤、不改变渠道VIP,其他字段或无变化保存不重复提审;清空头像或签名立即撤下。
新编辑接口与注册草稿分开:不会回退registrationStep,不改变性别、身份或VIP。先读取version及照片编号,再进入编辑;App旧GET /me继续承担登录恢复,不添加进度请求。
验证范围¶
2026-11-06服务器隔离PostgreSQL/Redis的clean verify共784项全部通过,新增25项覆盖十项权重、空白与空列表、注册保存/完成、本人资料/主页/编辑读取与保存一致性、媒体暂存与绑定/清空、待审资料、并发读取快照、客户端只读字段、失败不改变分数、四语与英文回退,以及原鉴权/安装/公共头/VIP准入;接口用例通过真实HTTP控制器与JWE认证解密。仅操作隔离合成账号;运行环境的已登录资料和客户端/设备显示未在本次操作,Flutter需接入服务端completionPercent。