网页内 API 参考页面逐项完整参考

本页解释网页内 API 参考页面本身的可见控件和阅读方法。它不是隐藏接口清单，也不把网页源码中出现的内部路径当成公开调用说明。真正可以调用的字段、权限和兼容边界以当前公开参考页为准。

页面结构

API 参考页通常分为：

1. 页面标题与基础地址说明；
2. 认证方式和通用响应；
3. API 分类卡片；
4. 单接口详情卡；
5. 请求参数表；
6. 响应字段树；
7. 示例/复制按钮；
8. 弃用或兼容提示。

页面按公开接口分类显示。普通使用者可能只看到读取接口，具有相应账号范围的开发者才适合验证写入、删除或审核流程。

API 分类卡

分类卡可能包含：

• 会话/认证；
• 访问码和二维码；
• 配方；
• 相片；
• 普通缓存；
• 上传缓存；
• 统计；
• 查卡；
• 游玩记录；
• 成绩互动；
• 文件和分页。

分类卡标题旁可能有描述和弃用标记。弃用接口不应作为新客户端的默认路径；先看兼容性说明和替代公开接口。

单接口详情卡

展开接口后通常看到：

• 接口名称；
• 方法和公开路径；
• 功能说明；
• 请求参数；
• 响应字段；
• 复制请求/响应示例；
• 权限或风险提示。

卡片展开/收起只改变显示，不会发起业务请求。复制按钮只复制页面示例，不代表示例中的值可以直接用于真实账号。

请求参数表

请求参数表包含：

列	含义
参数名	页面公开的字段名
类型	string/number/boolean/object/array/file 等
必填	是否缺少即不能完成公开请求
说明	页面给出的用户可理解语义

阅读参数时要同时看类型和是否必填：空字符串、0、false、空数组和缺失字段不是同一个状态。不要从参数名称猜出未写在说明中的内部字段。

响应字段树

响应字段可能使用树状缩进显示四层或更多嵌套：

• 顶层 Envelope；
• data/result 对象；
• 列表数组元素；
• 嵌套统计/评论/会话对象。

数组字段应按“可能为空、可能分页、可能含未知字段”处理。可选字段缺失不应让客户端崩溃；未知字段不应被客户端擅自删除后再回传。

通用响应格式

页面可能展示类似以下占位结构：

{
  "success": true,
  "msg": "<message>",
  "data": {}
}

失败响应通常包含 success: false 和 msg。有些读取接口还会使用状态码、valid、total、分页字段或文件响应；不能只用一个字段判断全部接口。

阅读二进制和文件接口

如果接口说明成功时返回 Blob/文件，页面会提示 Content-Type 或文件类型。客户端应先检查 HTTP 状态和 Content-Type，再决定按 JSON 还是文件读取：

• 成功文件不要强制当 JSON 解析；
• 失败 JSON 不要保存成图片/压缩包；
• 下载文件使用安全文件名和受保护目录；
• 上传/恢复前显示对象名称和账号范围。

认证方式卡

参考页可能说明 Token、二维码文本、用户名/密码或访问码的使用边界。认证值属于敏感输入：

• 不要把真实值写入示例；
• 不要复制到公开工单；
• 不要在日志中完整打印；
• 失效后重新验证，不要无限重试；
• 账号切换后清理旧会话和本地缓存。

参数和响应复制按钮

复制按钮只复制页面可见示例。复制后开发者应立刻替换：

• Token/访问码；
• 时间范围；
• 账号或机台标识；
• 文件索引；
• 内容 ID；
• 目标环境。

不要把复制出来的示例直接提交到生产账号。提交前检查请求是否会产生写入、删除、上传或审核影响。

弃用和兼容提示

页面可能用红色或其它标记显示弃用接口。看到弃用标记时：

1. 阅读页面给出的替代说明；
2. 对照响应字段变化；
3. 客户端对未知字段保持容忍；
4. 先在测试账号验证新接口；
5. 保留旧客户端的只读回退，但不要默认继续写入旧接口。

公开 API 验收工作流

读取工作流

确认账号和权限
→ 取得/验证 Token
→ 读取单页
→ 检查 success/msg/数据类型
→ 处理空数组和可选字段
→ 记录分页游标
→ 继续读取或结束

写入工作流

读取当前状态
→ 保存本地快照
→ 校验请求字段
→ 只提交一次
→ 等待响应
→ 重新读取状态
→ 对照变更前后

请求超时不等于服务端没有执行。写入/删除/上传类请求超时后先回读状态，不要立即重复提交。

文件工作流

读取账号范围
→ 下载/校验文件
→ 保存原始副本
→ 解析或预览
→ 在测试范围恢复/上传
→ 回读记录和索引

公开参考页的错误状态

页面状态	含义	开发者动作
参数表为空	当前接口不需要参数或页面加载异常	看接口说明和请求示例
响应字段树为空	可能是文件响应或示例缺失	不猜字段，按 Content-Type 处理
接口标记弃用	不建议用于新客户端	找替代公开接口
复制按钮无反应	浏览器剪贴板权限/页面状态	手动选择可见文本，不发送敏感值
页面空白	前端资源/浏览器缓存问题	清理页面缓存后只读重开
请求示例失败	示例值过期或权限不足	换测试账号和当前值，不贴真实凭据

隐私、日志和调试

API 参考页不是日志收集器。调试时只保留：

• 请求分类；
• 时间和耗时；
• HTTP 状态；
• success/valid 等布尔结果；
• 脱敏的业务错误；
• 数据条数和分页位置。

不要记录 Token、访问码、密码、二维码、完整文件、完整 URL 查询参数、机台私有地址或原始响应。

页面回归清单

• [ ] 分类卡可以展开/收起；
• [ ] 请求参数表列名、类型和必填状态可读；
• [ ] 响应字段树嵌套层级不丢失；
• [ ] 成功/失败示例可以区分；
• [ ] 文件接口显示二进制处理提示；
• [ ] 弃用接口显示兼容提醒；
• [ ] 复制按钮不改变页面状态；
• [ ] 页面移动端仍能滚动查看长字段；
• [ ] 文档没有把隐藏路径或内部实现当成公开接口。