读取本人关系或黑名单¶
请求参数¶
首屏、下拉刷新和上拉加载统一使用本接口,每次只读取这一份业务JSON。头像与国旗按返回的媒体地址加载并使用原有缓存策略,客户端无需额外请求完整国家/语言目录或逐人读取公开资料。
| 查询参数 | 必填 | 默认值 | 规则 |
|---|---|---|---|
| kind | 是 | 无 | friends好友、following关注、followers粉丝、visitors访客、blocked黑名单;好友为互相关注 |
| q | 否 | 空字符串 | 最多80个UTF-16代码单元,按已审核公开昵称大小写无关地字面包含检索;%、_不作为通配符 |
| page | 否 | 1 | 整数1–100000,从1开始 |
| pageSize | 否 | 20 | 整数1–100 |
只查询Bearer所属本人的关系,要求ROLE_USER、已完成注册及满足当前渠道VIP准入。每次请求均校验八项公共头,安装标识与会话一致,渠道与平台沿用当前会话规则。客户端元数据不授予身份或权限。
提示及display.name按当前App的Accept-Language返回,支持zh-CN、en、ja、ko,地区标签归一到对应语言;缺省或不支持的语言回退英文,固定code不翻译。JSON沿用统一响应及AES/JWE,正式使用可信HTTPS及真实JWE,GET信封放X-Budyoo-JWE。显式dev固定码/HTTP兼容范围以公共协议为准。
请求示例¶
以下为JWE封装后的请求结构,Token、请求编号、时间戳与信封由统一客户端生成,示例编号为合成数据。业务查询参数参与原有JWE上下文绑定。
GET /api/v1/me/relationships?kind=friends&page=1&pageSize=20 HTTP/1.1
Authorization: Bearer <本次登录的accessToken>
Accept-Language: zh-CN
X-Client-Type: app
X-Platform: android
X-App-Version: 1.0.0
X-App-Build: 1
X-Channel: xiaomi
X-Device-Id: 00000000-0000-4000-8000-000000000001
X-Request-Id: 00000000-0000-4000-8000-000000000002
X-Request-Timestamp: <当前13位毫秒时间戳>
Accept: application/jose
X-Budyoo-Encryption: jwe-v1
X-Budyoo-JWE: <统一客户端生成的compact-JWE>
同一kind、q与pageSize下,首屏和下拉刷新发送page=1,成功后替换列表;上拉发送上一成功页的page+1,成功后追加。只有成功时推进页码,搜索或关系类型变化后从第一页重新读取。
成功响应¶
以下成功示例按2026-11-20已部署的统一协议展示;CDN示例为合成对象,默认头像示例使用API通道,真实地址及权限以服务端返回为准。
新增data.followerNotifications:kind=followers必为非空{unreadCount,lastSequence,readSequence},其他kind为null,与本页及total共用同一读取快照。未读是完整粉丝提示总数,不受q或分页缩减;GET不清零。成功展示无搜索首屏后才取本响应lastSequence调用确认粉丝列表已读,后来新增保留;搜索/加载更多/失败不确认。旧服务缺失字段表示未知,不当0。
HTTP200,Cache-Control: no-store。下列JSON为认证解密后的完整合成示例,数据不代表线上用户。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"items": [
{
"profile": {
"userId": "00000000-0000-4000-8000-000000000003",
"publicId": "10000003",
"nickname": "示例用户",
"country": "cn",
"gender": "female",
"spokenLanguage": "zh",
"learningLanguage": "en",
"introduction": "喜欢学习语言",
"avatarId": "00000000-0000-4000-8000-000000000004",
"interests": [
"chat"
],
"avatarUrl": "https://media.budyoo.cn/media/avatars/00000000-0000-4000-8000-000000000004.png"
},
"avatarUrl": "/api/v1/media/user-avatars/00000000-0000-4000-8000-000000000003",
"vipActive": true,
"occurredAt": "2026-11-06T00:00:00Z",
"following": true,
"followsYou": true,
"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"
}
}
}
],
"total": 1,
"page": 1,
"pageSize": 20,
"hasMore": false,
"followerNotifications": null
},
"errors": [],
"mediaDelivery": [
{
"path": "/api/v1/media/avatars/00000000-0000-4000-8000-000000000004",
"url": "https://media.budyoo.cn/media/avatars/00000000-0000-4000-8000-000000000004.png",
"access": "PRIVATE",
"expiresAt": null,
"cacheKey": "budyoo-media:v1:4d955213596e5c695cc74585914c44df80e780b4cfa8694efca8363d1c371bb8",
"cacheMaxAgeSeconds": 0,
"code": "SUCCESS",
"transport": "CDN",
"requestHeaders": {
"X-Budyoo-Media-Path": "/api/v1/media/avatars/00000000-0000-4000-8000-000000000004"
},
"authorization": {
"origin": "https://media.budyoo.cn",
"headerName": "X-Budyoo-Media-Token",
"credentialPath": "/api/v1/media/credentials"
}
},
{
"path": "/api/v1/media/user-avatars/00000000-0000-4000-8000-000000000003",
"url": "/api/v1/media/user-avatars/00000000-0000-4000-8000-000000000003",
"access": "API",
"expiresAt": null,
"cacheKey": "/api/v1/media/user-avatars/00000000-0000-4000-8000-000000000003",
"cacheMaxAgeSeconds": 0,
"code": "SUCCESS",
"transport": "API",
"requestHeaders": {},
"authorization": null
}
]
}
| 字段 | 含义 |
|---|---|
| items | 当前页记录数组,只含活跃且注册完成的目标账号 |
| total | 当前kind及q匹配的真实总数,与当前页在同一只读数据库快照中读取 |
| page、pageSize | 本次页码与每页上限 |
| hasMore | page × pageSize < total;为false时本次结果已到尾页 |
| items[].profile | 原公开资料结构;昵称、签名、头像编号只读取已审核公开值,不包含生日、登录地址或私有相册 |
| profile.userId、publicId | 内部用户UUID及公开数字ID字符串,沿用原协议 |
| profile.nickname、gender | 页面昵称及female/male性别代码;客户端按真实字段展示 |
| profile.country、spokenLanguage、learningLanguage | 用户所选国家、我会的语言及学习语言的原始代码,保留原字段 |
| profile.introduction、avatarId、interests | 公开签名、可空头像UUID和兴趣编号列表,沿用原协议 |
| items[].avatarUrl | string或null;后台按查看者选取有权媒体并返回URL,无引用使用API默认图。屏蔽或媒体故障为null,公共加载组件按mediaDelivery处理 |
| items[].vipActive | boolean,非空。当前记录profile.userId的实际有效会员,生效且未到期/撤销才为true;dev且非prod沿用现有管理员测试覆盖。与查看者权益、vipRequired及渠道门槛无关 |
| items[].occurredAt | ISO 8601关系时间;关注/好友为本人关注时间,粉丝为对方关注时间,访客为最近访问时间,黑名单为本人屏蔽时间 |
| items[].following、followsYou | 本人是否关注对方、对方是否关注本人 |
| items[].display.language | 本次名称采用的归一语言标签 |
| display.country | 当前资料国家的id、当前语言name、四语names与flagUrl,来源与原国家目录一致 |
| display.spokenLanguage、learningLanguage | 当前所选语言的id、当前语言name、四语names和nativeName,来源与原语言目录一致 |
每个names对象都包含zh-CN、en、ja、ko四个键。展示项只投影这一人的选择;历史未知或空代码对应的display.country/语言项为null,原profile代码保留。资料国家不按IP推断,未知项不伪造名称或国旗。
每条记录的vipActive只表示本条profile.userId在本次读取时的有效权益,不能借用当前登录者的account.vipActive、vipRequired或渠道开关。生效、到期、撤销、未来生效及开发测试覆盖复用既有统一会员判断;字段始终为JSON boolean,不返回null、字符串或缺省值。Flutter可用true显示既有会员头像边框、昵称渐变及本地V徽章,false显示普通样式,无需颜色、边框图片、徽章URL或新增请求。旧客户端可忽略兼容新增字段;兼容旧服务时客户端应保留未知状态,不把缺失字段认定为非VIP。
单页在原只读REPEATABLE_READ事务中,通过membership/api一次批量读取本页实际返回的去重用户编号,不逐人读取主页或会员,不使用首页最多3位访客预览代替完整分页。空页、搜索无匹配及越过尾页不读取会员;必要会员依赖异常整份503,不伪造false。读取不会新增访客、关注或屏蔽记录,既有公开资料与媒体、分页、排序、过滤、鉴权及JWE规则保持。
列表按关系时间倒序,再按目标用户唯一UUID倒序,所有kind共用此规则。每次请求使用独立快照,关系发生变化后刷新第一页获取当前结果。
无匹配记录时返回以下data;越过尾页时同样返回空items及hasMore=false,total仍是当前匹配总数。
{"items": [], "total": 0, "page": 1, "pageSize": 20, "hasMore": false, "followerNotifications": null}
失败响应¶
| HTTP | code | 处理 |
|---|---|---|
| 400 | BAD_REQUEST/INVALID_CLIENT_HEADERS | kind缺失或无效、q过长、分页越界或类型错误、公共头不合法 |
| 401 | UNAUTHORIZED | 无效凭据、安装不一致或会话已撤销 |
| 403 | FORBIDDEN/ACCOUNT_DISABLED | 角色、账号状态或准入不满足;本接口ROLE_USER方法校验对注册未完成/VIP待准入返回FORBIDDEN |
| 426 | HTTPS_REQUIRED | 当前模式要求安全传输 |
| 503 | SERVICE_UNAVAILABLE | 数据库、会员等必要依赖不可用,整页失败,不降级false、部分记录或成功空页 |
| 500 | INTERNAL_ERROR | 未预期读取失败,保留正常错误响应 |
失败使用正常HTTP状态及标准code/message/data/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验收见统一媒体交付。
访客查询、统计及主页访客预览共用有效账号及双向屏蔽过滤;历史残留访问也不会使已屏蔽、禁用、注销或未完成注册的账号进入访客列表或总数。预览最多3位,独立访客总数不受预览上限影响。
头像统一读取响应中的avatarUrl,业务身份仍以/api/v1/media/user-avatars/{userId}表示;真实加载地址与授权由统一mediaDelivery返回,不能假定avatarUrl始终是API相对路径。后台按当前查看者身份选择本人最新已保存绑定头像或他人最后审核通过头像;本人待审/驳回图不因此公开。各自没有对应引用时才返回API默认PNG,上传未保存不生效。公开资料avatarId仍只表示已审引用,客户端直接加载后台URL,私密鉴权交由公共加载组件;CDN/OSS不附带本站Bearer。原准入与双向屏蔽保持,媒体不可用时URL为null,缓存不得绕过当前权限。
列表原profile、avatarUrl、occurredAt、following、followsYou及display继续返回;新增顶层vipActive,五类kind均完整提供,公开profile结构不扩展。客户端直接使用profile.nickname、profile.gender、avatarUrl及display中的国家、国旗和两种语言名称渲染好友页。头像鉴权和国旗媒体继续使用既有入口及缓存,JSON加密规则保持统一。
公开昵称、个性签名和avatarId字段仅使用最后审核通过且仍公开的值,头像媒体依据Bearer选择规则;昵称搜索不匹配未审草稿,见资料审核。
Flutter负责上下拉手势、加载动画、失败保留原列表与页码、防重复请求,以及切换账号/退出后隔离迟到响应;只有成功空结果显示空态。后台返回一份完整分页数据,不填入设计人物或演示数字。完整功能范围见我的与设置接入。
2026-11-06服务器隔离PostgreSQL/Redis的clean verify共738项全部通过,新增23项覆盖四语及英文回退、五类关系、所选目录投影、同时间分页/刷新/尾页/空页、审核昵称及可读头像、旧未知代码、计数与展示故障503、同一快照、鉴权/安装/公共头/准入和分页边界,使用真实HTTP控制器与JWE认证解密。测试只操作隔离合成账号;新增字段的实际客户端和设备接入另行验收。
2026-11-11列表会员字段通过服务器隔离PostgreSQL/Redis完整clean verify:969项通过,0失败/错误/跳过。新增RelationshipVipIntegrationTest 23项经真实HTTP控制器及JWE覆盖五类kind的混合会员、未开通/生效/到期/撤销/未来生效、仅按当前页批量查询、分页/公开昵称搜索/空页、查看者与渠道独立、开发测试覆盖、后续状态更新、会员故障四语及英文回退、同一快照、过滤、原头像与鉴权;原关系列表23项及首页访客VIP、公开资料和媒体回归保持。开发版本20261111-relationship-vip-002929已发布,备份独立恢复、构建与运行JAR/源码与镜像摘要、健康检查通过,186份后台静态文件逐字节保持。真实dev HTTP标准JSON入口23项通过,使用空闲合成账号核对五类空列表、四语及英文回退、搜索与尾页、鉴权/安装/渠道/公共头/分页边界及退出后失效;非空混合会员与真实JWE由上述隔离测试覆盖。验收会话已退出,线上未新增访客、关注或会员,原有11条访客编号及时间保持。客户端模型、边框/昵称/V图标及真机验收由Flutter任务单独完成。