外观
API 调试台

截图为当前实现,分享链接为占位示例。
窄屏布局

调试台是手动请求工作区,不执行轮询或后台自动更新。API 地址与 Bearer Token 在“设置”页修改,也可点击底部地址打开设置。设置页支持独立地址 /playground/#settings,切换页面不会丢失当前请求草稿和响应。
第一个请求
- 粘贴公开分享链接,在参数表单里选择“读取范围”和“返回字段”,默认“根画板”和“完整”。
- 点击“发送”,或使用 Ctrl / ⌘ + Enter。
- 右侧查看 HTTP 状态、总耗时和正文大小。
- 点击状态栏中的耗时,查看分段耗时和上游请求次数,不用离开当前响应。
- 点击请求区右上角“生成请求代码”图标,在浮窗中复制 cURL(Bash)、JavaScript Fetch 或 Python 示例。
根画板默认不展开子画板。需要嵌套内容时选择“完整递归”。预览中的“子画板未展开”不是空内容。
读取范围与返回字段
两组选项分别位于参数表单的对应标题下,用透明边框按钮展示,不使用下拉菜单。每组按钮下方显示当前选项的说明。
- **读取范围:**根画板、完整递归。切换范围不会改变字段选择或分享链接。
- **返回字段:**完整、标准、精简、自定义。标准和精简会自动填入对应的排除规则;首次选择自定义以标准规则作为编辑起点,从其他排除模式进入时保留当前规则。完整会清空字段规则。
修改排除规则后自动转为“自定义”,请求体采用 view: "full" 加当前 exclude,因此从规则中删掉一个字段路径就能恢复该字段。自定义也可填写“保留字段”,编辑时会清空排除规则和 view。表单与 JSON 共用状态,切换回参数表单时会反映 JSON 中的配置。
JSON 中给标准或精简视图添加额外排除规则时,也会标为“自定义”,并在表单里列出预设规则和额外规则。重复点击已激活的“自定义”不会重置当前配置。
API 请求地址同步显示非默认的 scope、view 和字段参数。字段数组在地址中以逗号连接并编码;实际发送和生成代码使用同一个地址,并带上对应的 POST JSON 请求体。服务端仍以请求体为准,不能只复制地址当作 GET 接口使用。Milanote 分享链接保持原样,分享链接和 Token 不加入 API 地址的查询参数。
字段规则
字段输入框下方有“通配符”“board.*”“**.location”三个悬停提示,键盘聚焦也可查看:* 匹配一级字段,** 匹配任意层级;board.* 匹配画板的一级字段并包含选中对象的内容;**.location 匹配任意层级的位置数据。
排除字段和保留字段均为每行一条路径,例如:
text
**.location
**.timestamps输入过程中保留未完成的草稿;离开输入框或发送请求时静默剔除空行、重复、未知、语法错误和只有通配符的规则(如 **、*、**.*),不弹错误提示。一行用逗号写多个路径也会作为无效规则移除。有效的递归路径如 **.location 正常保留。生成代码及地址预览同样使用清理后的规则。
若规则全部被移除,则发送时省略空数组;没有其他字段配置时返回完整字段。HTTP API 的直接调用仍严格校验字段规则,调试台的静默清理不改变服务端契约。
请求代码浮窗
点击请求区右上角“生成请求代码”图标,打开锚定按钮的浮窗,没有遮罩。可切换语言、复制代码,点击外部、关闭按钮或 Escape 收起。
未填分享链接时也能生成示例,使用 https://app.milanote.com/your-board/shared-view?p=your-permission 占位链接,并显示替换提醒;API 地址为空时使用 https://YOUR_API_HOST。占位符只用于生成代码,不写回表单。直接发送请求仍需有效链接。非法 JSON 或非空但无效的链接仍需要修正后才能生成可执行代码。
编辑与响应
参数表单和 JSON 请求体同步。非法 JSON 会保留草稿并阻止发送;include 不能和 view、exclude 混用。
JSON 编辑器支持高亮、折叠和搜索。响应区保留完整 HTTP 正文,非 JSON 错误也可查看。响应头和画板预览单独显示。full、standard、compact 和 include / exclude 结果均可预览:完整模型使用画板布局,精简结果按实际返回字段显示。缺失字段不会伪造补齐,未返回子内容与空数组区别展示;其他 JSON、错误正文和非 JSON 内容也可在预览中查看。
“KB 正文”是解码后的正文 UTF-8 大小,不是压缩后的网络传输量。
多标签与历史
每个请求标签有独立草稿和响应。鼠标中键或关闭按钮均可关闭标签;只剩一个标签时不显示关闭按钮,中键也不会关闭最后一个请求。标签溢出时可横向滚动,悬停出现浮动滚动条,不挤压标签高度。关闭或取消会停止该标签当前请求;迟到的响应不会覆盖其他标签。可同时调试多个请求,拖动中间分隔线调整宽度;窄屏通过历史 / 收藏、请求、响应切换区域。左侧默认显示历史,没有接口目录或服务能力入口。
收藏按钮显式保存请求配置和 API 地址到浏览器,未发送或未完成的 JSON 草稿也可以保存,最多保留最近 100 条。分享链接含权限参数,保存前应确认设备可信。Bearer Token 仅存在会话内存,不随收藏保存;修改 API 地址、打开收藏或重放历史会清空 Token,需要时在设置页重新填写。
自动历史只保存最近 100 条操作类型、时间、状态和耗时,不保存链接、画板名称或响应。只有当前会话内的历史可恢复完整请求。关闭或刷新页面后,响应会清空。
点击历史标题旁的垃圾桶可清空历史及本次会话的重放记录;收藏需在“收藏”列表逐项删除,清空历史不会删除收藏。未主动保存的草稿以及设置页中的 API 地址修改只存在当前页面内存,刷新后恢复构建时的默认 API 地址;打开收藏时恢复该收藏保存的地址。主题偏好会保留在浏览器。
快捷操作
| 操作 | 快捷键 / 入口 |
|---|---|
| 搜索预设和收藏 | Ctrl / ⌘ + K |
| 发送当前请求 | Ctrl / ⌘ + Enter |
| 关闭弹窗 | Escape |
| 调整请求区宽度 | 聚焦分隔线后使用左右方向键 |
| 切换主题 | 侧栏太阳 / 月亮按钮或设置页 |
| 复制、下载响应 | 响应区右上角 |
复制失败时可手动选择正文或代码。网络错误时检查 API 服务地址、服务是否运行及 CORS 配置。Bearer Token 可在设置页填写,生成代码时以占位符表示。
自动更新与存储属于用户自部署扩展,见部署指南。