文章与博客 API

本节介绍了用于管理和获取博客文章、系统公告以及自定义页面的 API 接口。

公共接口

获取文章列表

获取已发布的文章列表,支持按类型过滤。

接口地址: GET /api/posts

查询参数:

  • type (可选): 按文章类型过滤 (例如 blog, announcement, page)。默认值为 blog。
  • locale (可选): 当前语言代码 (例如 en, zh)。开启多语言且 type=blog 时,仅返回绑定了该语言(或历史未绑定语言 locale = null)的博客文章。
  • category (可选): 按分类 slug 过滤。不存在或已停用的 slug 返回空列表,不会退化成全量;all 会被忽略。

响应示例:

{
  "data": [
    {
      "id": 1,
      "slug": "getting-started",
      "title": "APayShop 新手指南",
      "description": "学习如何在几分钟内建立您的店铺。",
      "imageUrl": "https://example.com/image.jpg",
      "type": "blog",
      "locale": "zh",
      "categoryId": 3,
      "category": { "id": 3, "slug": "tutorials", "name": "教程", "description": null },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-02T00:00:00.000Z"
    }
  ],
  "total": 1
}

category 在未分类时为 null,名称按请求语言本地化。

获取文章分类列表

获取启用的文章分类,按 sort、id 排序,名称按请求语言本地化。

接口地址: GET /api/post-categories

响应示例:

{
  "data": [
    { "id": 3, "slug": "tutorials", "name": "教程", "description": null, "sort": 0 }
  ]
}

通过 Slug 获取文章

通过唯一标识符 (Slug) 获取单篇文章的详情。当站点开启多语言且目标博客文章绑定了特定 locale(例如 zh)时,访问非所属语言的前台路径(如 /blog/:slug)会自动 301 重定向到该文章所属语言的规范路径(如 /zh/blog/:slug)。

接口地址: GET /api/posts/:slug

查询参数:

  • locale (可选): 当前语言代码 (例如 en, zh)。

响应示例:

{
  "id": 1,
  "slug": "getting-started",
  "title": "APayShop 新手指南",
  "content": "<p>这是文章的完整 HTML 内容...</p>",
  "description": "学习如何在几分钟内建立您的店铺。",
  "imageUrl": "https://example.com/image.jpg",
  "type": "blog",
  "locale": "zh",
  "isActive": true,
  "metaData": null,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-02T00:00:00.000Z"
}

管理员接口 (需要登录鉴权)

获取所有文章

获取系统中所有文章的列表(包含草稿)。

接口地址: GET /api/admin/posts

查询参数:

  • type (可选): 按文章类型过滤 (blog, changelog, announcement, page)。
  • locale (可选): 按绑定的文章语言过滤 (例如 en, zh)。
  • status (可选): 按发布状态过滤 (published 或 draft)。
  • category (可选): 按分类 id 过滤,或使用 uncategorized / none 筛选未分类文章。
  • search (可选): 按标题、Slug、Key 或摘要搜索。

创建文章

创建一篇新文章。当 type 为 blog 时,可通过 locale 将该博客绑定到指定语言(如 en、zh);其他类型(changelog、announcement、page)保持 locale = null 并通过 metaData.translations 维护多语言译文。

接口地址: POST /api/admin/posts

请求体示例:

{
  "slug": "new-blog-post",
  "title": "新功能发布",
  "description": "我们刚刚发布了一个很棒的新功能。",
  "content": "<p>详情内容在此...</p>",
  "type": "blog",
  "locale": "zh",
  "categoryId": 3,
  "imageUrl": "https://example.com/image2.jpg",
  "isActive": true
}

categoryId 可选,传 null(或 0/"")表示未分类。

更新文章

更新现有文章内容。

接口地址: PUT /api/admin/posts/:id

删除文章

永久删除指定文章。

接口地址: DELETE /api/admin/posts/:id

获取文章分类列表

获取全部分类(含已停用),并附带每个分类下的文章数 postCount。

接口地址: GET /api/admin/posts/categories

创建文章分类

接口地址: POST /api/admin/posts/categories

请求体示例:

{
  "slug": "tutorials",
  "name": "教程",
  "description": "分步指南。",
  "sort": 0,
  "isActive": true,
  "locales": { "en": { "name": "Tutorials", "description": "Step-by-step guides" } }
}

slug 仅允许小写字母、数字和连字符,且需唯一。locales 为可选的 Record<lang, { name?, description? }>,某语言缺省时回退到顶层的 name/description。

获取 / 更新 / 删除文章分类

  • GET /api/admin/posts/categories/:id
  • PUT /api/admin/posts/categories/:id — 请求体同创建;省略 slug 保持原值。
  • DELETE /api/admin/posts/categories/:id — 使用该分类的文章将变为未分类。