PATCH/api/v1/me/profile
Bearer,完成注册且通过VIP准入,ROLE_USERJSON 响应接入指南 ↗

保存本人资料与相册

请求参数

面向App,必须登录、完成注册并通过动态VIP准入。八项公共头全部必填,app/ios或android,安装UUID与会话绑定。正式要求HTTPS;当前dev仅隔离固定码账号允许明文HTTP。JSON遵循统一JWE协议;选择密文时仍要求HTTPS。未完成注册返回403,待VIP返回403/VIP_REQUIRED。

公共头见请求头,四语见公共响应,加密见JWE协议。客户端类型和图片UUID本身不授予权限。

无查询参数。 | 正文字段 | 类型 | 必填 | 约束与部分更新语义 | | --- | --- | --- | --- | | expectedVersion | integer(int64) | 是 | 非负;使用读取响应的version,冲突409后重读,不自动覆盖 | | country | string | 否 | 目录内小写国家代码;不传/null保留;实际变更仅限目标用户为有效VIP | | nickname | string | 否 | 输入1–8个UTF-16代码单元,trim后非空;不传/null保留 | | birthday | string(date) | 否 | 1900-01-01至服务端当天;不传/null保留 | | spokenLanguage | string | 否 | 资料语言目录内单个id;不传/null保留;保存后须与learningLanguage不同 | | learningLanguage | string | 否 | 资料语言目录内单个id;不传/null保留;保存后须与spokenLanguage不同 | | introduction | string | 否 | 输入最多30个UTF-16代码单元,保存时trim;空字符串清空,不传/null保留 | | avatarId | string | 否 | 本人上传头像UUID;空字符串清除引用,不传/null保留 | | interests | string[] | 否 | 1–6个不重复的字典代码,不能清空;不传/null保留 | | albumPhotoIds | string(UUID)[] | 否 | 0–9个不重复的本人有效照片;[]清空,不传/null保留 |

至少提供一个非null可编辑字段;仅版本号不是有效编辑。未知字段(包括gender、userId、registrationStatus、registrationStep、VIP字段)拒绝,不能通过后台修改只读属性。长度按UTF-16代码单元计算,表情可能占两个;以原输入长度校验后trim。

仅当前服务端有效VIP可以更改已注册资料的国家/地区;按目标用户权益判断,App和后台代改共用规则,不由渠道VIP门槛、管理员身份或客户端声明放行。country不传、null或与已保存值相同仍按原规则保存;首次注册选择国家不受此限制。非VIP实际变更返回HTTP403/PROFILE_COUNTRY_VIP_REQUIRED,整次PATCH不写资料、相册、兴趣、审核候选或版本,后台不写成功审计。到期、撤销、尚未生效均不算有效VIP;开发管理员测试覆盖沿用既有dev且非prod规则,权益读取失败返回503。

请求示例

示例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 PATCH "$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" \
  -H 'Content-Type: application/json' --data '{"expectedVersion":0,"nickname":"合成用户","introduction":"喜欢旅行和摄影","interests":["photo","travel"],"albumPhotoIds":[]}'

成功响应

以下成功示例按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

失败响应

HTTP code 条件
400 INTEREST_UNAVAILABLE 新加入停用标签,请刷新目录重新选择
400 PROFILE_LANGUAGES_SAME 我会的语言与想学习的语言相同,请重新选择不同的语言
400 BAD_REQUEST/VALIDATION_FAILED/INVALID_PROFILE 类型、日期、长度、字典、重复兴趣、缺少版本或未知字段
400 INVALID_CLIENT_HEADERS 公共头缺失、重复或格式错误
401 UNAUTHORIZED 未登录、会话失效或安装不匹配
403 PROFILE_COUNTRY_VIP_REQUIRED 目标用户当前不是有效VIP,却提交不同的国家;保持原表单,不作为登录失效或VIP准入跳转
403 FORBIDDEN/VIP_REQUIRED 未完成注册或VIP准入未通过
404 NOT_FOUND 用户或归属范围内的图片不存在/已删除
426 HTTPS_REQUIRED 当前路径不允许明文HTTP
503 SERVICE_UNAVAILABLE 数据库/Redis依赖暂不可用
409 PROFILE_CONFLICT expectedVersion过期;重读并由用户确认,禁止自动覆盖
409 REGISTRATION_INCOMPLETE 目标用户尚未完成注册,后台也不代为完成注册
403 ACCOUNT_DISABLED 目标账号被禁用
400 INVALID_AVATAR/INVALID_PHOTO 文件无效、已删除、跨用户或相册重复/超过9张
400/409 加密协议错误码 JWE缺失、篡改、过期、重放,按公共加密协议处理

非VIP修改国家的中文失败示例:

{"code":"PROFILE_COUNTRY_VIP_REQUIRED","message":"仅VIP用户可以修改国家或地区。","data":null,"errors":[]}

错误结构示例:

{"code":"PROFILE_CONFLICT","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验收见统一媒体交付。

本响应直接带回data.completionPercent,前端使用服务端分数,不再按字段数量自行均分,不需要新增请求。保存成功后以本响应的最新资料和分数一次回填;版本冲突、字段校验或依赖失败保留原已保存分数。completionPercent不是请求字段,提交它返回400。

编辑资料首次进入只请求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,其他字段或无变化保存不重复提审;清空头像或签名立即撤下。

兴趣选项由完整兴趣目录提供。新加入的标签须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":[]}

新编辑接口与注册草稿分开:不会回退registrationStep,不改变性别、身份或VIP。客户端可按字段确认即时调用本接口,不要求统一保存按钮。相册选中照片后立即暂存上传,取得编号再以expectedVersion和完整albumPhotoIds调用本接口;删除确认后提交剩余列表。仅上传不绑定,上传及绑定不是同一事务;失败不能宣称相册已保存,写请求超时不自动重发。兴趣沿用选择确认后局部提交。删除相册项使对应照片软删除;原有照片相对顺序保留,不支持手动排序或封面。头像替换只改变引用,旧头像不物理删除。

验证范围

2026-11-06服务器隔离PostgreSQL/Redis的clean verify共784项全部通过,新增25项覆盖十项权重、空白与空列表、注册保存/完成、本人资料/主页/编辑读取与保存一致性、媒体暂存与绑定/清空、待审资料、并发读取快照、客户端只读字段、失败不改变分数、四语与英文回退,以及原鉴权/安装/公共头/VIP准入;接口用例通过真实HTTP控制器与JWE认证解密。仅操作隔离合成账号;运行环境的已登录资料和客户端/设备显示未在本次操作,Flutter需接入服务端completionPercent。

2026-11-06服务器隔离PostgreSQL/Redis的clean verify共784项全部通过,零失败/错误/跳过;新增16项国家修改权限回归覆盖App、后台及领域入口的非VIP拒绝与原子回滚,省略/null/原值兼容、有效VIP即时放行、未生效/到期/撤销权益、开发测试覆盖设置及取消、首次注册选择国家、字段/版本校验、权益故障503,以及四语/未知及缺省英文的真实JWE响应。仅使用隔离合成账号和测试权益,未在运行库创建账号、发放VIP或修改用户资料;本轮不包含Flutter国家选择器界面改动。