Skip to main content

​
获取文章列表

公开接口，不需要认证。返回全部已发布文章的摘要：不含正文 content、不含密文 enc，草稿一律不出现在列表里。 响应示例：
列表没有分页参数——一次返回全部已发布摘要，由前端自行分页（config.js 的 pageSize，默认 8，仅影响前台展示）。排序规则：置顶优先，其次按 date 倒序。search 字段：非加密文章附带正文前 800 个字符，供前台搜索直接匹配正文内容；加密文章不带该字段。这也是列表可以省掉 content 的原因。
响应头： Cache-Control: public, s-maxage=60, stale-while-revalidate=300 + Cache-Tag: posts。管理后台用 api/posts?_=<时间戳> 穿透边缘缓存取最新列表。

​
获取单篇文章

公开接口。草稿只对作者可见：未携带有效会话 token 时读草稿返回 404（未找到该内容），避免草稿全文泄漏。 响应示例：
加密文章（protected: true）的 content 恒为空字符串，正文只以 enc 字段返回，形如 {salt, iv, data}；前端用用户输入的密码本地解密。列表接口不会返回 enc，enc 只在详情接口出现。

​
阅读行为（前后篇导航）

非接口内容，但与文章页强相关：上一篇 / 下一篇点击后一律从新文章的开头开始阅读（不会被上一页的滚动位置带过去）；阅读位置记忆只在手动刷新时恢复。两篇文章之间为交叉淡入淡出过渡，不做整页翻书式切换。相关文章统一排在上下篇导航之下。

​
创建文章

请求体（id 与 title 必填）：
响应（201）：
  • 缺少 id 或 title → 400「缺少 id 或 title」
  • 已存在同 id → 409「已存在相同 id（article-slug），请用 PUT 更新」
  • 写入成功后按 posts / feed / sitemap / post:<id> 标签清边缘缓存

​
更新文章

请求体字段与创建一致（服务端按完整对象覆盖写入 INSERT OR REPLACE，路径里的 :id 优先于请求体 id）。title 为空返回 400「缺少 title」。成功返回 200：
PUT 是整篇覆盖而不是局部合并：未在请求体中出现的字段会按默认值写回。后台编辑器在保存前会先取回完整文章对象，因此正常使用不会丢字段。

​
删除文章

删除是原子级联清理（同一批次执行，同 ID 重建不会复活旧数据）： 文章不存在返回 404「未找到该内容」，成功返回 { "ok": true }。

​
文章增强接口

文章级 SEO、作者页与草稿预览的完整行为见 SEO、多作者 与 预览链接。