说说广场 API 0.31.0 版的调用代码说明
内容提要
Memos 0.31.0 升级后 API 重大变更：列表接口弃用 parent 参数，改用 CEL filter；作者需写 users/{username} 而非数字 ID；resources 更名为 attachments；头像路径移至 /file/users/{username}/avatar；分页仅用 nextPageToken 游标。实测两个问题：防火墙会拦截 exists( 表达式，标签过滤应改用 "标签" in tags；has_link 筛 false 返回空。pageSize 无上限。文末附迁移清单与错误处理。
延伸解读
升级后资源定位方式的变化
0.31.0 将资源定位统一为资源名加 CEL filter。列表接口不再接受 parent 参数，改用 filter 表达式，且 creator 值必须是 users/{username} 而非数字 ID。附件字段从 resources 更名为 attachments，文件地址也变为 /file/attachments/{uid}/{filename}。头像地址移至 /file/users/{username}/avatar。这些改动意味着旧代码中的路径和字段名都需要相应调整。
filter 表达式的限制与陷阱
filter 支持按作者、可见性、标签、正文内容等筛选，但字段名与返回体不一致，例如无法使用 createTime 或 state 进行筛选。标签过滤应使用 "标签" in tags 而非 tags.exists()，因为 exists( 可能被防火墙拦截返回 403。此外，has_link 筛 false 会返回空结果，与直觉不符，使用前建议小样本验证。
分页与错误处理要点
分页仅依赖 nextPageToken 游标，需原样回传，空字符串表示结束。pageSize 无上限，pageSize=1000 可返回 1000 条，调用方需自行限制以防内存问题。错误响应体包含 gRPC 风格 code，与 HTTP 状态码不同，处理时应先判 HTTP 状态再判 body.code。若响应非 JSON，可能是防火墙拦截页，需检查 filter 中是否含敏感关键字。
页面嵌入代码的已知问题
文章提供的嵌入代码中，main.js 在 CDN 上被截断，导致 renderMemos() 未定义完，页面容器为空。同时标签过滤使用 tags.exists() 会触发 403，memoDom 始终为 null 导致点击标签报错。配置项中仅 host、limit、creatorId 被实际使用，其余字段未生效。复用前建议核对 main.js 完整性并替换标签过滤写法。
Q&A
Memos 0.31.0 的列表接口怎么按作者筛选说说？
使用 filter 参数，格式为 creator == "users/{username}"，例如 filter=creator == "users/penn"。注意 creator 的值是资源名 users/{username}，不是数字 ID，数字 ID 会返回 user not found。
0.31.0 里附件字段和文件地址有什么变化？
Memo.resources 改名为 Memo.attachments，附件资源名从 resources/{uid} 变为 attachments/{uid}，文件地址从 /api/v1/resources/{uid} 类改为 /file/attachments/{uid}/{filename}。
为什么用 tags.exists 过滤标签会返回 403？
因为防火墙会拦截请求参数中包含 exists( 的表达式，返回 403 和 1Panel 拦截页。应改用 "标签" in tags 写法，例如 filter=creator == "users/penn" && "memos" in tags，两种写法实测返回条数一致。
0.31.0 的分页机制是怎样的？
使用游标分页，没有 offset 页码。请求时传入 pageSize 和可选的 pageToken，响应返回 nextPageToken。将 nextPageToken 原样作为下一页的 pageToken 回传，直到 nextPageToken 为空字符串表示结束。注意 pageSize 没有上限，pageSize=1000 会返回 1000 条。
0.31.0 的错误码和 HTTP 状态码如何对应？
错误响应体带 code 字段，采用 gRPC 风格错误码：资源不存在 HTTP 404 对应 code 5；filter 语法错 HTTP 400 对应 code 3；未认证 HTTP 401 对应 code 16。处理时应先判 HTTP 状态，再判 body 里的 code。
从旧版升级到 0.31.0 需要做哪些迁移改动？
主要迁移点：parent 参数换成 filter，作者写成 users/{username}；resources 换成 attachments，文件地址换成 /file/attachments/{uid}/{filename}；头像地址换成 /file/users/{username}/avatar；筛选表达式中的 exists( 换成 "标签" in tags；用户名改为精确匹配；shortcuts 换成 views；评论请求显式指定可见性；错误处理同时判 HTTP 状态和 body.code。
