GET/api/v1/home/latest
本人Bearer、完整注册及当前渠道VIP准入、八项App公共头、HTTPS与JWEJSON 响应接入指南 ↗

读取首页最新人物

请求参数

首页“最新”人物列表使用本接口,不读取设计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仍来自持久认证活动时间。