文章与博客 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/:idPUT /api/admin/posts/categories/:id— 请求体同创建;省略slug保持原值。DELETE /api/admin/posts/categories/:id— 使用该分类的文章将变为未分类。