# API(第一阶段 + 博客管理 + 导航书签 + 公开博客) 所有路径以 `/api/v1` 开头,业务 API 需登录 Cookie;不使用浏览器持久化 token。除 GET 外需 `X-CSRF-TOKEN` 请求头,值从 `/auth/csrf` 的 `token` 字段取得(响应也给出 `headerName`)。登录和退出后重新请求 token。 | 方法 | 路径 | 请求/结果 | |---|---|---| | GET | /auth/csrf | `{token,headerName}`,匿名可访问 | | POST | /auth/login | form-urlencoded `username,password`;成功 200,失败 401 | | GET | /auth/me | `{username}` | | POST | /auth/logout | 成功 204,失效会话 | | GET | /dashboard | `{notes,starred,assets,bookmarks,storageBytes,recentNotes}` | | GET | /notes | `q, category, starred, offset`;数组,每页最多 100 | | POST | /notes | `{title,body,category,tag,star,version:0}`;201 + 完整记录 | | GET | /notes/categories | 返回已保存的笔记分类名称数组 | | POST | /notes/categories | `{name}`;创建分类并返回 `{name}`,重名返回 409 | | GET | /notes/categories/usage | 返回分类名称和笔记数 `{name,noteCount}` | | DELETE | /notes/categories | `name` 指定分类,`replacement` 指定迁移目标。空分类可直接删除。有笔记时需提供另一个分类。至少保留一个分类,成功返回 204 | | GET | /notes/{uuid} | 完整记录 | | PUT | /notes/{uuid} | 同创建字段,version 必须是读取时版本;更新返回 version+1;冲突 409 | | DELETE | /notes/{uuid} | 204,移入回收站;不存在返回 404 | | GET | /assets | `q,type=all/image/file,offset`;数组,每页最多 100 | | POST | /assets | multipart 字段 `file`,单文件 1 字节至 15 MB;201 | | GET | /assets/{uuid}/content | PNG/JPEG/GIF 内联,其他附件;`download=true` 强制下载 | | DELETE | /assets/{uuid} | 删除磁盘文件与元数据,204 | | GET | /bookmarks | `q,category,offset`;数组,每页最多 100,按更新时间倒序 | | POST | /bookmarks | `{title,url,description,category,icon_asset_id,is_public}`;默认私有,图标可选,必须是图床图片;仅接受有效的 http(s) URL;201 + 完整记录 | | GET | /bookmarks/{uuid} | 完整记录 | | PUT | /bookmarks/{uuid} | 请求字段与新增一致;更新原记录及公开状态;不存在返回 404 | | DELETE | /bookmarks/{uuid} | 204,移入回收站;不存在返回 404 | | GET | /public/bookmarks | 匿名只读;`offset,limit(1–100,默认 50)`;仅展示已同步至公开快照的记录,返回 `{title,url,description,category,icon_asset_id,updated_at}` | | GET | /public/bookmarks/images/{uuid} | 匿名读取被公开书签选为图标的 PNG/JPEG/GIF;其他图片或未引用图片返回 404 | | GET | /blogs | `q, status=all/draft/published, offset`;数组,每页最多 100,按更新时间倒序 | | POST | /blogs | `{title,summary,body,status,version:0,cover_asset_id,category}`;status 为 draft/published;201 + 完整记录 | | GET | /blogs/{uuid} | 完整记录 | | PUT | /blogs/{uuid} | 同创建字段,version 必须是读取时版本;更新返回 version+1;冲突 409 | | DELETE | /blogs/{uuid} | 204,移入回收站;不存在返回 404 | | GET | /public/blogs | 匿名只读;`offset, limit(1–50,默认 20), q, category`;仅已同步的已发布文章,`{title,summary,slug,updated_at,cover_asset_id,category}`,按更新时间倒序 | | GET | /public/blogs/rss.xml | 匿名订阅最近 30 篇已同步的文章,返回 RSS 2.0 | | GET | /public/blogs/categories | 匿名只读;返回已发布文章的分类列表 | | GET | /public/blogs/{slug} | 匿名只读;仅已同步的已发布文章,额外返回 `body`;草稿或不存在的 slug 均为 404 | | GET | /public/blogs/{slug}/images/{uuid} | 匿名读取该已发布文章引用的封面或 Markdown 图片;其余情况返回 404 | 笔记字段:id(UUID)、title(1–120 非空)、body(最多 1,000,000 字符)、category(1–60 非空)、tag(0–60)、star、version、created_at、updated_at。 资产字段:id、name、media_type、size(字节)、created_at。时间由数据库产生,使用 timestamptz。 书签字段:id(UUID)、title(1–60 非空)、url(有效 http/https 地址,最多 4096 字符)、description(0–160)、category(1–60 非空)、created_at、updated_at。书签为私有数据;管理页面使用 `target="_blank"` 与 `rel="noopener noreferrer"` 打开网址。 博客字段:id(UUID)、title(1–120 非空)、summary(0–200)、body(最多 1,000,000 字符)、status(draft/published,数据库 CHECK 约束)、slug(唯一)、version、created_at、updated_at。列表不返回数量汇总;前端在本地按状态和关键词筛选(页内搜索与全局搜索都按正文匹配)。 `cover_asset_id` 是可选的图床图片 UUID。提交 `null` 可移除封面。Flyway V4 为已有文章新增该字段,删除对应图床原图时自动清空。 `slug` 由服务端在创建时按标题生成:小写 ASCII 字母数字保留,其余转连字符,最多 80 字符;不含字母(如纯中文或纯数字标题)时用 `article`,再追加 id 前 6 位保证唯一。编辑标题不会改变 slug,已分享的链接保持有效。 公开与私有边界: - `/public/**` 可匿名访问,是前端 `/blog`、`/blog/` 页面的唯一数据来源;响应不含 id、version 等内部字段,公开页面请求时使用 `credentials: "omit"`,页面被嵌入或分享时不会带上登录 Cookie。 - 公开接口响应携带 ETag(根据文章版本、封面及当前页文章集合生成),带 `If-None-Match` 的条件请求内容未变时返回 304;公开页面每 30 秒、以及窗口重新获得焦点时做条件请求,文章更新后自动刷新。 - 所有 `/blogs` 管理接口仍需登录和 CSRF。单账户平台,不提供按作者或空间的隔离;公开页面目前可被同一台电脑上的浏览器访问,是否可被互联网访问取决于部署与网络环境。 响应头:所有响应带 `X-Content-Type-Options: nosniff`、`Referrer-Policy: strict-origin-when-cross-origin`、`X-Frame-Options: SAMEORIGIN`。 错误:401 未登录/凭据错误;403 CSRF 不合法;400 输入校验失败(含非法 status 筛选值);404 不存在;409 版本冲突;413 超过上传限制;500 服务失败。控制器业务错误为 `{message}`;安全过滤器错误可能采用 Spring 标准错误格式。前端保留未保存内容并提示错误,不将失败当成功。 ## V4 工作区 | 方法 | 路径 | 用途 | |---|---|---| | GET、POST | /library/{kind}/folders | 知识库及图床的文件夹列表与新增 | | GET | /library/{kind}/facets | 知识库及图床的文件夹计数、标签和图床存储统计 | | GET、POST、PUT | /library/{kind}/categories | 分类列表、新增、改名或迁移后删除 | | POST | /library/{kind}/batch | 对指定 ID 批量移动、加标签、移入回收站或调整书签顺序 | | GET | /library/{kind}/trash | 按模块查看已删除记录 | | POST、DELETE | /library/{kind}/trash/{id} | 恢复或永久删除 | | GET | /notes/{id}/history | 按笔记分页读取版本列表 | | GET、POST | /notes/{id}/history/{version} | 预览历史版本或使用当前版本号恢复 | | GET | /notes/{id}/backlinks | 查找引用当前笔记的双链 | | GET、PUT | /assets/{id} | 读取和编辑文件名、分类、文件夹、标签、描述 | | PUT | /bookmarks/{id}/favorite | 修改常用收藏状态 | | POST | /bookmarks/import | 批量导入并按网址去重,导入项默认私有 | | GET、POST | /publication | 查看待同步清单或按当前发布版本提交同步 | | GET | /publication/export | 导出已发布的博客与书签快照 |