App 接口¶
左侧按功能模块展开,默认定位当前页面所在模块;搜索支持模块名、接口名称和路径。下方索引与左侧模块一致。
闪屏布局¶
| 接口 | 方法 | 路径 |
|---|---|---|
| 获取闪屏布局配置 | GET | /api/v1/app/bootstrap |
新客户端先匿名读取IP布局:CN国内、其他已识别地区国际、无法识别默认国内,再展示地区相关协议和登录布局。语言、发行渠道、账号与支付各自独立;网络请求失败仍需重试,不能当作IP回退。新协议目录使用layoutPolicy=ip-v1,具体见独立契约。
登录与会话¶
接口已实现;当前dev手机号与邮箱统一使用固定验证码123456,先申请挑战再验证,不实际发送短信邮件。开发身份与真实身份隔离,后续再切换真实供应商和HTTPS。调用顺序见登录注册接入。
验证码申请的限流提示优化区分60秒冷却与小时额度,并提供Retry-After剩余秒数;错误码保持兼容。准确字段及发布状态见发送登录验证码。
手机与邮箱统一在获取验证码时提示账号封禁;返回403 ACCOUNT_BANNED时不生成挑战、不投递、不进入验证码输入页。验证码登录、刷新、受保护业务和长连接仍由服务端拦截,发码前提示不会取代后续检查;匿名阶段不公开原因或期限,见封禁接入。
| 接口 | 方法 | 路径 |
|---|---|---|
| 获取登录方式与协议版本 | GET |
/api/v1/auth/options |
| 发送登录验证码 | POST |
/api/v1/auth/challenges |
| 验证码登录 | POST |
/api/v1/auth/verify-code |
| 申请三方登录挑战 | POST |
/api/v1/auth/providers/challenges |
| 验证三方登录 | POST |
/api/v1/auth/providers/login |
| 刷新登录凭证 | POST |
/api/v1/auth/refresh |
| 退出登录 | POST |
/api/v1/auth/logout |
| 退出账号会话(兼容路径) | POST |
/api/v1/auth/logout-all |
协议阅读¶
| 接口 | 方法 | 路径 |
|---|---|---|
| 获取四类协议网页地址(中英日韩) | GET |
/api/v1/agreements |
| 读取精确协议版本 | GET |
/api/v1/agreements/{type}/{contentVersion} |
| 打开已生效协议网页 | GET |
/legal/agreements/{id} |
新客户端使用layoutPolicy=ip-v1,按与闪屏相同的后端IP规则选择国内/国际,未知默认国内;无参数旧客户端继续渠道兼容。国内四类中文、国际四类各中英日韩,不接收App自选法域/地区;缺译文不跨范围替代,未发布返回不可用。实现与验证状态见独立契约。
协议后台保存成功即生效,App下一次目录读取即可获得链接。requiredVersion与登录termsVersion/privacyVersion共用当前同意快照,contentVersion为独立正文版本,允许不同;历史正文和用户同意保留。客户端版本变化时刷新配置并重新明确同意,不能自动勾选或重用旧验证码挑战。
注册资料¶
客户端继续在统一请求层发送X-Channel等公共请求头。旧账号渠道为空时,服务端在后续合法登录、刷新或Bearer认证请求中补录一次,无需新接口;已有渠道保持。
登录响应直接返回持久化registrationStep,仅取1–4,不新增进度接口;VIP不计入资料步骤。registrationStatus=COMPLETE后再根据vipRequired决定VIP页或首页;当前渠道vipGateEnabled和服务端vipActive分别返回,默认关闭门槛。刷新及本人资料等既有接口返回同一组字段,见两层准入。
| 接口 | 方法 | 路径 |
|---|---|---|
| 获取当前用户与注册进度 | GET |
/api/v1/me |
| 保存注册资料草稿 | PATCH |
/api/v1/me/registration |
| 完成注册 | POST |
/api/v1/me/registration/complete |
国家与字典¶
| 接口 | 方法 | 路径 |
|---|---|---|
| 获取支持的国家与地区(热门排序、四语、图标) | GET |
/api/v1/catalogs/countries |
| 读取国家与地区图标 | GET |
/api/v1/media/country-flags/{countryCode} |
| 获取支持的资料语言(我会的/学习语言) | GET |
/api/v1/catalogs/languages |
| 获取注册字典 | GET |
/api/v1/catalogs/registration |
新增国家列表及国旗读取入口已随整合版本部署到当前开发API,旧注册字典的热门排序随同发布;公网四语目录与国旗读取已核对。Flutter仍需迁移到新接口,具体字段、排序与验证范围见各自契约。
独立资料语言入口已部署,返回当前10种语种的四语名称、原生名称、文字标记和预设热门排名;“我会的/学习语言”共用并直接保持服务器顺序,Flutter尚需从旧注册字典迁移。App界面语言设置仍独立维护。
兴趣标签¶
完整目录提供分类、四语文字、图标及可选状态,注册和资料编辑共用;后台保存即生效,停用保留历史显示,新选择仍限制1–6个。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取完整兴趣标签目录 | GET | /api/v1/catalogs/interests |
| 读取兴趣标签图标 | GET | /api/v1/media/interest-icons/{id} |
首页最新人物¶
首页“最新”人物列表使用服务端最近活跃时间排序;公开资料、VIP、在线租约和活跃时间一次返回,客户端不逐人请求用户主页。未知活跃时间的账号不进入结果,依赖失败整页返回503。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取首页最新人物 | GET | /api/v1/home/latest |
资料编辑¶
国家/地区实际变更仅限当前有效VIP;非VIP返回403 PROFILE_COUNTRY_VIP_REQUIRED。提交原国家、不传或null不限制其他字段,首次注册选国家保持原流程;详见保存资料。
本人资料、编辑读取/保存、注册保存/完成均返回data.completionPercent,“我的”主页返回data.account.completionPercent;统一为0–100整数,规则见资料完善度,无需额外请求。
编辑首屏只用GET /me/profile读取完整本人资料及display中的所选国家、两种语言、兴趣名称与图标;原PATCH也直接返回最新display。完整可选目录在打开选择器时加载,媒体复用原路径和缓存;version与moderation仍随资料返回。
注册和资料编辑的昵称统一为1–8个UTF-16代码单元,去除首尾空白后不能为空;历史昵称按原值保留。我会的语言与想学习的语言必须不同,部分修改按已存资料合并校验,完成注册再次检查;重复返回400 PROFILE_LANGUAGES_SAME。注册后独立编辑;介绍保持30字符,兴趣1–6个,相册0–9张。上传只暂存,资料页带version统一保存。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取可编辑本人资料 | GET |
/api/v1/me/profile |
| 保存本人资料与相册 | PATCH |
/api/v1/me/profile |
互动视频不要求前端上传首帧:后端在OSS上传确认时截取起始画面并保存,动态列表/详情返回media.posterUrl,本人主页复用已存封面。失败、编码及历史空值范围见上传确认。
头像与相册¶
文件统一OSS直传并由JSON确认后暂存,资料保存后才绑定;五个旧App multipart POST入口已移除并返回410,旧安装包须更新。图片归属、数量限制及权限见各接口。
| 接口 | 方法 | 路径 |
|---|---|---|
| 申请OSS单文件直传(全部已有媒体用途) | POST |
/api/v1/media/uploads |
| 确认OSS上传并取得原媒体回执 | POST |
/api/v1/media/uploads/{uploadId}/complete |
| 取消未确认OSS上传 | DELETE |
/api/v1/media/uploads/{uploadId} |
| 批量获取媒体交付信息 | POST |
/api/v1/media/downloads |
| 申请CDN媒体凭证 | POST |
/api/v1/media/credentials |
| CDN专用远程鉴权回调(App不直调) | GET |
/api/v1/media/cdn/authorize |
| 读取本人上传头像 | GET |
/api/v1/media/avatars/{id} |
| 读取本人相册照片 | GET |
/api/v1/media/album-photos/{id} |
| 读取用户已审公开相册照片 | GET |
/api/v1/media/user-albums/{userId}/{photoId} |
| 丢弃未保存的相册照片 | DELETE |
/api/v1/media/album-photos/{id} |
头像、昵称和个性签名采用逐项资料审核,本人读取新增moderation反馈;上传或保存成功不等于公开。公开资料字段只取已审值,avatarUrl统一由媒体入口按Bearer身份选择本人最新已保存绑定头像或他人已审公开头像,无对应引用才用默认图,前端直接加载返回地址。
我的与设置¶
「我的」首屏使用主页汇总一次读取资料、所选国家/语言名称、关系、钱包和动态/点赞总数及最近三条动态的多图缩略索引与照片张数,以及最多三位最近访客的userId/avatarUrl/vipActive(访客自己的当前有效会员状态);访客总数继续取relationships.visitors,不额外拼接关系列表或逐人资料请求;编辑、列表及安全操作在进入二级页面后按需使用下列接口。关系列表各项新增非空boolean vipActive,表示本条用户的有效VIP,访客及其他kind共用。完整范围见我的与设置接入,最新部署与验证以对应接口文档为准;真实支付及即时客服仍有独立未实现边界。
用户详情昵称页头使用identity.nickname;capabilities提供真实举报/拉黑/取消拉黑能力,本人禁用面向他人操作。我方屏蔽时只返回BLOCKED_BY_ME最小身份与能力,完整资料为null,受保护媒体和动态仍不可见;用户举报为独立真实用户收件,不使用动态ID。
用户主页主体一次返回目标已审资料、VIP、生日及服务端年龄、长连接租约状态、三项关系数、已审相册、所选目录和操作能力;动态继续独立分页。相册照片使用公开相册媒体逐次鉴权;空公开相册隐藏整段,依赖错误不伪装空数据。聊天尚未实现真实会话,canChat=false;三项统计只展示,不开放他人关系列表。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取我的主页汇总 | GET | /api/v1/me/home |
| 读取本人账号与安全 | GET | /api/v1/me/account |
| 申请当前绑定验证码 | POST | /api/v1/me/account/verification-challenges |
| 验证当前绑定并取得操作凭证 | POST | /api/v1/me/account/verification-proofs |
| 申请新绑定验证码 | POST | /api/v1/me/account/binding-challenges |
| 更换本人登录绑定 | PUT | /api/v1/me/account/binding |
| 读取注销条件与计划 | GET | /api/v1/me/account/deletion |
| 提交本人账号注销 | POST | /api/v1/me/account/deletion |
| 读取本人通知偏好 | GET | /api/v1/me/settings/notifications |
| 保存本人通知偏好 | PATCH | /api/v1/me/settings/notifications |
| 读取本人关系统计 | GET | /api/v1/me/relationships/counts |
| 读取本人关系或黑名单(分页及四语展示) | GET | /api/v1/me/relationships |
| 确认粉丝列表已读 | PUT | /api/v1/me/relationships/followers/read |
| 关注用户 | PUT | /api/v1/me/following/{userId} |
| 取消关注用户 | DELETE | /api/v1/me/following/{userId} |
| 屏蔽用户 | PUT | /api/v1/me/blocked-users/{userId} |
| 解除屏蔽用户 | DELETE | /api/v1/me/blocked-users/{userId} |
| 读取用户主页主体 | GET | /api/v1/users/{userId}/profile |
| 举报用户 | POST | /api/v1/users/{userId}/reports |
| 按登录身份读取用户头像及默认图 | GET | /api/v1/media/user-avatars/{userId} |
| 读取本人钱包余额 | GET | /api/v1/me/wallet |
| 读取钱包充值套餐 | GET | /api/v1/me/wallet/recharge |
| 读取本人收支明细 | GET | /api/v1/me/wallet/entries |
我的动态与点赞¶
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取我的动态 | GET | /api/v1/me/posts |
| 读取我的点赞动态(分类分页与全部总数) | GET | /api/v1/me/liked-posts |
| 发布个人动态 | POST | /api/v1/posts |
| 读取动态详情 | GET | /api/v1/posts/{id} |
| 删除本人动态 | DELETE | /api/v1/posts/{id} |
| 点赞动态 | PUT | /api/v1/posts/{id}/like |
| 取消动态点赞 | DELETE | /api/v1/posts/{id}/like |
| 读取动态图片 | GET | /api/v1/media/post-photos/{id} |
| 丢弃动态暂存图片 | DELETE | /api/v1/media/post-photos/{id} |
实时连接¶
| 接口 | 方法 | 路径 | 状态 |
|---|---|---|---|
| 建立长连接 | WebSocket Upgrade | /ws/v1/realtime |
心跳、票据、Redis 路由已验证 |
| 申请连接票据 | POST |
/api/v1/realtime/tickets |
入口已实现,待真实登录联动 |
| 申请开发联调票据 | POST |
/api/v1/realtime/dev-tickets |
仅local/dev且非prod配置,独立密钥保护 |
本阶段只提供连接架构,消息持久化、已读、离线补拉和聊天业务另行接入。
系统与安全¶
设备限制与封禁提示见封禁接入,以下API已部署、Flutter配套进行中;设备采集必须在明确同意后执行,现有安装UUID不替换,设备强制开关保持关闭。提交申诉复用当前App主接口,开发固定码HTTP例外可直接申请,不依赖设备专用地址;设备材料及正式申诉继续HTTPS。
| 接口 | 方法 | 路径 | 状态 |
|---|---|---|---|
| 读取设备风控策略 | GET | /api/v1/security/device-policy | API已部署,客户端配套中 |
| 提交设备安全检查 | POST | /api/v1/security/device-check | API已部署,始终HTTPS,设备启用待验收 |
| 提交封禁申诉 | POST | /api/v1/security/access-appeals | 同次限制只提交一次,重登恢复已提交状态 |
| 接口 | 方法 | 路径 | 状态 |
|---|---|---|---|
| 检查App版本升级 | GET |
/api/v1/app/updates |
已部署,客户端更新接入待完成 |
| 获取系统信息 | GET |
/api/v1/system/info |
已联调 |
| 标准请求测试 | POST |
/api/v1/system/request-test |
仅dev且非prod配置,已联调 |
| 获取接口加密公钥 | GET |
/api/v1/security/encryption-key |
已部署,AES 接入入口 |
JSON 接口可按AES 加密协议使用相同路径收发密文;业务字段仍以各自独立文档为准。
服务地址¶
翻译统一遵循文字翻译规则:DeepSeek非思考模式和十语目标;默认按当前App界面语言、本人会的语言、英文回退。App移除固定中文目标,实际值取响应targetLanguage;未取到界面语言时不提前补英文。供应商和客户端验收范围分别说明。
https://api.budyoo.cn
当前为唯一正式部署环境,处于上线前阶段,没有独立测试服;公网HTTPS已验收,实际运行配置仍为dev。认证数据只经已验证的HTTPS传输,JSON按JWE契约处理。查看加密状态
互动与内容审核¶
一级评论、二级回复、本人评论、提交回执及各动态commentPreview统一新增评论顶层vipActive,表示该评论作者当前有效权益。服务端按页批量判断,Flutter据此显示VIP边框/昵称颜色/图标,不借用动态作者或登录者状态,不逐人补查;实际字段与验证范围见互动共享模型。
2026-11-10评论VIP与当前查看者计数已随908项服务器全量回归更新,接口可接入。先读互动与审核接入,包含字段模型及实际验证范围。发布成功只表示待审核;所有公开互动内容必须APPROVED。
评论与二级回复未通过时仅作者本人可从comments/mine查询;动态发布者也不能查看他人的未通过内容。公开列表、预览及分页total/hasMore只包含已通过且当前可见的记录。Post.commentCount统一按当前Bearer返回公开根/回复加本人可回显未公开记录的完整去重总数,审核通过不重复计数;提交或删除后重读动态详情,前端不本地加减,也不叠加mine.total。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取互动发现流 | GET | /api/v1/posts |
| 读取用户已公开动态 | GET | /api/v1/users/{id}/posts |
| 读取互动目录与发布限制 | GET | /api/v1/community/catalog |
| 读取可选话题 | GET | /api/v1/topics |
| 读取话题详情和参与统计 | GET | /api/v1/topics/{id} |
| 读取评论或二级回复 | GET | /api/v1/posts/{postId}/comments |
| 读取本人评论审核状态 | GET | /api/v1/posts/{postId}/comments/mine |
| 提交评论或回复等待审核 | POST | /api/v1/posts/{postId}/comments |
| 删除本人评论或回复 | DELETE | /api/v1/posts/{postId}/comments/{id} |
| 读取音视频或私有证据 | GET | /api/v1/media/community-files/{id} |
| 读取视频封面 | GET | /api/v1/media/community-files/{id}/poster |
| 丢弃通用暂存文件 | DELETE | /api/v1/media/community-files/{id} |
| 翻译动态正文 | POST | /api/v1/posts/{id}/translation |
| 翻译评论或回复 | POST | /api/v1/posts/{postId}/comments/{id}/translation |
| 提交互动内容举报 | POST | /api/v1/posts/{id}/reports |
| 读取本人举报回执 | GET | /api/v1/me/content-reports |
| 读取本人举报处理结果 | GET | /api/v1/me/content-reports/{id} |
远方明信片¶
先读明信片接入。首信和回信都须人工审核通过后投递,数据与已接入状态分别说明。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取明信片首页 | GET | /api/v1/me/postcards/home |
| 读取明信片收寄偏好 | GET | /api/v1/me/postcard-preferences |
| 保存明信片收寄偏好 | PATCH | /api/v1/me/postcard-preferences |
| 读取本人明信片信箱 | GET | /api/v1/me/postcards |
| 提交待审明信片首信 | POST | /api/v1/postcards |
| 领取一张已通过明信片 | POST | /api/v1/postcards/receive |
| 读取私密明信片详情 | GET | /api/v1/postcards/{id} |
| 拆开明信片或推进已读 | POST | /api/v1/postcards/{id}/open |
| 读取已投递回信或本人审核结果 | GET | /api/v1/postcards/{id}/replies |
| 提交待审明信片回信 | POST | /api/v1/postcards/{id}/replies |
| 保留明信片到旅行册 | PUT | /api/v1/postcards/{id}/keep |
| 取消旅行册明信片保留 | DELETE | /api/v1/postcards/{id}/keep |
| 读取旅行册与真实邮戳 | GET | /api/v1/me/postcard-album |
| 发起明信片聊天邀请 | PUT | /api/v1/postcards/{id}/chat-invitation |
| 接受或婉拒明信片聊天邀请 | PATCH | /api/v1/postcards/{id}/chat-invitation |
| 进入明信片文本会话 | POST | /api/v1/postcards/{id}/chat |
| 读取本人明信片聊天列表 | GET | /api/v1/me/postcard-chats |
| 读取明信片会话与未读 | GET | /api/v1/postcard-chats/{id} |
| 分页读取明信片文本消息 | GET | /api/v1/postcard-chats/{id}/messages |
| 发送明信片文本消息 | POST | /api/v1/postcard-chats/{id}/messages |
| 推进本人聊天已读边界 | PUT | /api/v1/postcard-chats/{id}/read |
| 翻译已通过私密明信片 | POST | /api/v1/postcards/{id}/translation |
| 举报已通过私密明信片 | POST | /api/v1/postcards/{id}/reports |
| 读取本人明信片举报回执 | GET | /api/v1/me/postcard-reports |
| 读取本人明信片举报处理结果 | GET | /api/v1/me/postcard-reports/{id} |
| 读取本人或已通过明信片照片 | GET | /api/v1/media/postcard-photos/{id} |
| 丢弃本人未绑定明信片照片 | DELETE | /api/v1/media/postcard-photos/{id} |
原业务接口中的用户媒体与下载授权已统一为媒体交付协议,并于2026-11-20部署:无能力头/cdn-v1/oss-v1均使用同结构,由后台决定CDN、OSS或API,业务页面直接使用返回URL,私密鉴权集中在公共加载组件。ID、保存字段和原权限保持。唯一正式部署环境仍使用dev配置;服务器及公网探针结果不代替Flutter设备验收。实际结果与待验事项见CDN协议。