读取首页最新人物¶
请求参数¶
首页“最新”人物列表使用本接口,不读取设计JSON,不要求Flutter逐人请求用户主页。当前认证用户不能出现在列表中;本人屏蔽、对方屏蔽、失活、未完成注册、没有服务端最近活跃时间或头像/昵称没有审核通过的账号不进入结果。默认头像和默认昵称只用于其他明确允许回退的公开读取,不用于首页人物卡。
| 查询参数 | 必填 | 默认值 | 规则 |
|---|---|---|---|
| page | 否 | 1 | JSON整数,范围1–100000 |
| pageSize | 否 | 20 | JSON整数,范围1–100 |
八项App公共头、Bearer、安装/渠道/平台绑定和JWE规则沿用公共请求头、统一响应及AES/JWE。客户端时间、时区、排序字段和用户ID不作为请求参数。
请求示例¶
GET /api/v1/home/latest?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: <installationUuid>
X-Request-Id: <requestUuid>
X-Request-Timestamp: <server-bound-request-time>
Accept: application/jose
X-Budyoo-Encryption: jwe-v1
X-Budyoo-JWE: <encrypted-empty-request>
成功响应¶
HTTP200,Cache-Control: no-store。下例为认证解密后的业务数据,时间均为ISO 8601 UTC;lastActiveMinutes由同一服务端读取时刻计算,供头像左上相对时间直接渲染。
{
"items": [
{
"userId": "00000000-0000-4000-8000-000000000003",
"publicId": "10000003",
"nickname": "示例用户",
"avatarUrl": "/api/v1/media/user-avatars/00000000-0000-4000-8000-000000000003",
"country": "cn",
"gender": "female",
"age": 26,
"spokenLanguage": "zh",
"learningLanguage": "en",
"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"}
},
"vipActive": true,
"presence": {"status": "OFFLINE", "visibility": "VISIBLE", "observedAt": "2026-11-15T04:00:00Z", "lastActiveAt": null},
"lastActiveAt": "2026-11-15T03:58:42Z",
"lastActiveMinutes": 1
}
],
"total": 1,
"page": 1,
"pageSize": 20,
"hasMore": false
}
| 字段 | 语义 |
|---|---|
| items | 当前页有效人物;每条均有已审非空头像与昵称、非空lastActiveAt和非负lastActiveMinutes,未知活跃时间或头像/昵称未通过审核的账号被排除,不伪造当前时间 |
| total | 当前查看者可见且有已知活跃时间的人物总数,与items使用同一读取快照 |
| page、pageSize、hasMore | 服务端真实分页;排序变化或新活动在下一次读取体现 |
| userId、publicId、nickname、gender、country、spokenLanguage、learningLanguage | 已审公开资料字段 |
| avatarUrl | string或null,统一交付后的地址;对应头像必须已有已审公开引用,媒体依赖故障可为null。公共加载组件按mediaDelivery加载,不补发主页请求 |
| age | 使用服务端UTC日期计算的整岁;生日未知或非法时为null,不影响活跃时间渲染 |
| display | 当前Accept-Language下的所选国家和语言四语展示,名称缺失时整页503,不伪造目录值 |
| vipActive | 本条人物当前有效会员,不借用查看者权益或渠道门槛 |
| presence.status | 独立长连接租约观测:ONLINE、OFFLINE或UNKNOWN;OFFLINE不表示最近活跃,UNKNOWN表示长连接未启用 |
| presence.observedAt | 本次在线租约观测时刻;不是最近活跃时间 |
| presence.lastActiveAt | 固定为null,避免把在线租约误称为最近活跃 |
| lastActiveAt | 最近一次成功认证App请求的数据库服务器时间,ISO 8601 UTC;不是登录声明、关系时间或客户端时间 |
| lastActiveMinutes | max(0, floor(serverNow - lastActiveAt))的分钟数;未来时钟偏差按0返回。0显示“刚刚”,1/2显示分钟,达到60显示小时,达到1440显示天,达到525600显示年 |
最近活跃时间由服务端认证过滤器在成功Bearer请求时用数据库CURRENT_TIMESTAMP更新,迁移前可由已认证访问记录回填。未知时间不进入首页最新列表,因此返回记录都可渲染明确的活跃标签。该字段只表示最近成功使用服务的时间,不保证真实人在屏幕前、在线或收到消息;服务端不暴露IP、设备、会话或访问来源。
结果按lastActiveAt DESC, userId DESC排序,分页和total均在同一数据库读取边界内计算。跨时区请求只改变display名称语言,不改变UTC时间或排序;客户端不得用本机当前时间重算接口排序或从presence.observedAt推导活跃。
失败响应¶
| HTTP | code | 处理 |
|---|---|---|
| 400 | BAD_REQUEST/INVALID_CLIENT_HEADERS | 页码、类型或公共头不合法 |
| 401 | UNAUTHORIZED | Bearer、安装、渠道或会话无效 |
| 403 | FORBIDDEN/VIP_REQUIRED/ACCOUNT_DISABLED/ACCOUNT_BANNED | 注册、VIP或账号限制不满足 |
| 426 | HTTPS_REQUIRED | 正式模式要求可信HTTPS |
| 503 | SERVICE_UNAVAILABLE | 活跃时间、公开资料、目录、会员或在线状态必要依赖失败;整页失败,不返回离线、空数组或零值伪装 |
message及字段错误支持中英日韩,未知语言回退英文,code固定。网关或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验收见统一媒体交付。
首页最新人物由本接口直接提供分页;头像、国旗和详情媒体按已有鉴权路径读取。Flutter只消费items中的投影,不调用/api/v1/users/{userId}/profile补齐昵称、会员、在线或活跃时间。刷新、上拉分页和切换VIP筛选使用同一路径的独立请求与请求ID。
当前列表不承诺推送、在线状态或跨设备实时刷新;新的认证活动会在下一次页面读取中体现。未配置长连接时presence为UNKNOWN,但lastActiveAt仍来自持久认证活动时间。