ZundaLink 文档

Appearance

公开 API 字段校验与输入边界 ​

API 文档中的类型说明只是第一层约束。客户端还要校验空值、范围、编码、权限和字段之间的关系。校验失败应在本地提示，避免把明显无效的写入发送到服务。

通用字符串规则 ​

对所有用户输入执行：

  • 去掉意外的首尾空白，但不要静默修改二维码、访问码或文件名；
  • 区分空字符串、未提供和 null；
  • 限制最大长度并显示剩余长度；
  • 不把换行、智能引号和不可见控制字符混入 JSON；
  • 不把用户输入拼接到 HTML、URL 或日志中；
  • 失败时保留原输入，方便用户修正。

Token、密码、访问码和二维码文本不要用普通文本日志记录，也不要在验证失败提示中回显完整值。

Token 输入 ​

请求前检查：

  1. Token 非空；
  2. 当前账号与 Token 属于同一会话；
  3. 没有已经标记为过期；
  4. 不把 Token 放在 URL 查询参数；
  5. 页面切换账号后丢弃旧请求结果。

本地格式检查不能证明 Token 有效。仍要调用验证接口，并尊重服务返回的 valid、expires_at 和 expired。

用户名和密码 ​

用户名在页面约束范围内检查长度和空白。密码至少满足当前页面显示的长度规则，不要在客户端自行放宽服务端限制。密码输入框使用密码类型，错误消息不能包含密码。

注册、绑定和修改密码都属于写入动作：

  • 禁止自动循环注册；
  • 不缓存明文密码到导出文件；
  • 修改成功后退出并重新登录；
  • 登录失败时不要把密码替换成 Token 重试。

二维码与访问码 ​

二维码图片校验：

  • 文件确实是图片；
  • 图片可解码；
  • 保留完整定位点；
  • 不要自动裁切到缺少边界；
  • 识别失败时允许改用文本；
  • 识别结果不要自动发送多次。

文本输入校验：

  • 不插入手动换行、空格或引号；
  • 不在输入框中拼接多个码；
  • 过期后重新生成；
  • 不把图片文件名当作二维码文本。

一次性码和长期码要在 UI 上标出不同生命周期，不要使用同一个“保存凭据”选项处理两者。

布尔字段 ​

开关值必须是真正的 JSON 布尔值：

json
{ "enable": true }

不要把 "true"、1、"on" 直接当作布尔值发送。页面展示的“开/关”应映射到明确的目标值；保存后重新读取确认服务端实际值。

数字字段 ​

数字校验包括：

  1. 是否为有限数字；
  2. 是否为整数或允许小数；
  3. 是否在页面显示的最小/最大范围；
  4. 单位是否正确；
  5. 空值是拒绝、默认还是代表 0。

例如音量为 0–100、截图自动刷新间隔为页面允许的 0–20 秒、侧载投币数为页面允许的 1–50。范围之外的值不要依赖服务端截断。

时间字段 ​

如果页面或接口要求时间字符串：

  • 使用当前公开格式；
  • 明确时区；
  • 保留原始输入和解析结果；
  • 不把本地时间自动转换后再写回而不告知用户；
  • release_time 尚未到达时不要标记订单失败。

时间戳输入应是正整数时，拒绝小数、负数、指数形式和包含空格的混合文本。不要用当前时间猜测管理员要求的事件时间。

逗号分隔列表 ​

只有页面明确要求列表时才使用逗号分隔。校验规则：

  • 使用英文逗号；
  • 每一项去除意外首尾空格；
  • 拒绝空项或在保存前明确提示；
  • 不自动把昵称转为编号；
  • 不自动加方括号；
  • 删除前保留原列表。

名单、内容过滤和订单筛选是不同用途，不能把一个列表直接复制到另一个列表。

JSON 字段 ​

编辑器应在本地显示：

  • 解析成功/失败；
  • 顶层类型；
  • 必填字段缺失；
  • 字段类型不匹配；
  • 可能的敏感值提示。

合法 JSON 不一定符合业务结构。保存前还要检查顶层数组/对象要求、字段关系、路径占位符和条目唯一性。修改时保留未知字段，避免把服务未来字段删除。

路径和 URL ​

路径校验：

  • Windows 路径中的反斜杠在 JSON 中需要转义；
  • 不允许把密码放在路径或 URL 中；
  • 不根据另一台设备的目录猜测当前路径；
  • 访问已有文件前检查目标机台是否可达；
  • 不把本地路径写入公开日志。

URL 校验：

  • 只接受页面或管理员允许的协议；
  • 默认使用 HTTPS；
  • 不在 URL 中拼接 Token、密码或访问码；
  • 清理查询参数中的敏感值；
  • 下载前确认来源和文件类型。

文件上传 ​

上传前检查：

  1. 用户选择了文件；
  2. 文件类型和大小在页面限制内；
  3. 文件来自用户明确选择，不是隐藏目录自动扫描；
  4. 文件不会被自动转发到无关服务；
  5. 预览或转换失败时不提交半成品。

头像上传可以在浏览器侧调整为方形 JPEG，但不能把转换后的图片误当作原文件备份。内容压缩包提交前清理凭据、个人信息和无关的临时目录。

分页字段 ​

start 和 end 必须是非负整数，并满足 end > start。客户端应限制单页大小，避免请求过大的范围。下一页根据实际返回长度推进，不能把 end 当成包含边界。

服务返回的 total 只在当前快照范围内参考。读取期间数据新增或删除时，客户端要防止重复和遗漏，并在导出报告中记录范围。

互动字段 ​

互动接口的校验：

  • musicId 是数字且来自当前页面或公开索引；
  • action 只使用页面允许的选项；
  • 评论正文非空且不超过页面限制；
  • parentId 属于当前曲目的可见评论；
  • 删除评论前确认是本人或拥有权限；
  • 反馈理由不包含凭据、个人隐私和未公开内部信息。

写入成功后回读 social 或 comments，不要只更新本地计数。

备份和恢复字段 ​

备份对象允许新增字段，但恢复前必须检查：

  • 来源账号；
  • 导出时间；
  • 客户端/服务版本；
  • 顶层类型；
  • 是否包含明显的另一个账号标识；
  • 是否是完整对象而非截断文件。

无法确认来源时不要恢复。恢复返回条数不应被当作数据完整性证明。

文件名和索引名 ​

文件名、上传快照索引和安装项名称应来自服务返回的列表或用户明确确认。拒绝路径穿越、空名称、包含控制字符和跨账号复制的索引。删除请求前二次读取列表，避免使用过期名称。

错误消息 ​

服务返回的 msg 可以展示给用户，但要：

  • 限制显示长度；
  • 不在 HTML 中原样插入未转义内容；
  • 不把完整错误体发送到第三方；
  • 按业务失败和网络失败分别显示；
  • 提供可执行的下一步。

不要把“格式错误”自动翻译成“数据丢失”，也不要把“权限不足”翻译成“服务不存在”。

校验后的发送前清单 ​

  • [ ] 当前账号和 Token 正确；
  • [ ] 请求路径属于公开文档；
  • [ ] Content-Type 正确；
  • [ ] 必填字段已填写；
  • [ ] 字段类型正确；
  • [ ] 范围和单位正确；
  • [ ] 文件/列表来自当前状态；
  • [ ] 未把敏感值写进日志；
  • [ ] 写入前已经保存原值；
  • [ ] 写入后计划重新读取；
  • [ ] 超时不会自动重放高风险动作。

Released under the CC BY-NC-SA 4.0 License.

Copyright © 2025-2026 ZundaLink