接入指南

分页与错误

正确处理列表游标、普通 API 与 OAuth 的错误格式。

先查看具体操作的参数与响应。不同列表可能使用 page/limit 或 cursor/limit;不要假设所有接口采用同一种分页方式。

对使用游标的操作,把响应的 nextCursor 原样放到下一次请求的 cursor 参数,并保持排序和其他筛选条件不变。nextCursor 为 null 时停止;游标是不透明值,不应自己解析或长期缓存。例如资源列表在支持的排序模式下才提供游标,搜索游标还绑定查询与索引状态并有有效期。

资源详情每个展示分组首屏最多返回 20 个完整发布单元;allReleases=true 也不会解除上限。继续加载时请求 /v1/site/resources/{slug}/releases,传入该分组的 displayGroup 与 nextCursor,并保留 loader、mc、type 等上下文。displayGroup 只选择详情页展示分组,不能代替资源筛选器的加载器条件。

帖子详情返回有界的直接回复及子回复预览。继续加载 /v1/site/posts/{id}/replies 时,parent 使用需要展开节点的稳定 ID;首层用帖子的 repliesNextCursor,子层用该回复的 childrenNextCursor。保留返回的祖先上下文与墓碑,不要用数组下标重新编号。内容更新后旧游标可能返回 CURSOR_STALE,此时刷新对应首屏,不继续拼接不同 revision 的数据。

普通查询成功时直接返回操作定义的结果,例如资源列表含 items、total 等字段,没有统一的 ok/data 包装。失败也要按操作和状态码处理:映射 API 统一返回 {"error":{"code":"INVALID_INPUT","message":"请求参数不合法"}}。网站 Cookie 管理沿用各操作的原错误结构。401/403 时检查令牌与 scope,400 时检查参数,不要把重试当作权限修复。

OAuth 授权、令牌与撤销协议有自己的错误格式,如 {"error":"invalid_grant"},并设置不缓存响应。invalid_client 会返回 401;invalid_grant 常需要重新开始授权。两类错误的具体响应以接口参考中的操作为准。