新闻资讯插件（news）
新闻资讯插件的接口文档，基于插件版本 v1.1.4（核心版本 0.0.2）。管理端前缀 /admin/plugin/news，用户端前缀 /api/plugin/news。
通用约定与宿主一致：统一响应 {code, msg, data}（HTTP 恒为 200）；管理端接口走 Permission 路由组，需 Authorization: Bearer <token> 且角色拥有对应 METHOD:/path 权限；用户端公开接口无需登录；分页 page 默认 1、page_size 默认 20 最大 100；时间展示到秒；cover 为相对路径、cover_url 为按当前存储配置补全的访问地址。
管理端分类接口
分类列表
接口地址
text
GET /admin/plugin/news/category/list接口说明
分页返回新闻分类，支持按名称或标识搜索。
接口参数说明
| Query 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
keyword | string | 否 | 匹配分类名称或标识，最长 64 字符 |
status | integer | 否 | 1 启用，2 停用 |
page | integer | 否 | 页码，默认 1 |
page_size | integer | 否 | 每页数量，最大 100 |
响应示例
json
{
"code": 0,
"msg": "success",
"data": {
"list": [
{
"id": 1,
"name": "公司新闻",
"slug": "company",
"sort": 100,
"status": 1,
"remark": "公司动态与公告",
"created_at": "2026-09-25 10:00:00"
}
],
"total": 1
}
}响应参数说明
data 为 { "list": CategoryItem[], "total": integer }，CategoryItem 字段：
| 响应字段 | 类型 | 说明 |
|---|---|---|
list[].id | integer | 分类 ID |
list[].name | string | 分类名称，最长 64 字符 |
list[].slug | string | 唯一分类标识，最长 64 字符 |
list[].sort | integer | 排序值，越大越靠前 |
list[].status | integer | 1 启用，2 停用 |
list[].remark | string | 分类备注 |
list[].created_at | string | 创建时间 |
total | integer | 数据总数 |
保存分类
接口地址
text
POST /admin/plugin/news/category/save接口说明
新增时 id 传 0，修改时传现有分类 ID。管理端新增页面会自动生成标识，保存前允许修改；分类创建后 slug 不可变，修改请求中的该字段不会覆盖数据库原值。slug 受数据库唯一索引保护，并发提交相同标识只会有一个请求成功。
接口参数说明
| Body 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 分类 ID，新增传 0 |
name | string | 是 | 分类名称，最长 64 字符 |
slug | string | 是 | 唯一标识，创建后不可变 |
sort | integer | 否 | 排序值，越大越靠前 |
status | integer | 否 | 1 启用，2 停用 |
remark | string | 否 | 分类备注 |
响应示例
json
{
"code": 0,
"msg": "success",
"data": {
"id": 1,
"name": "公司新闻",
"slug": "company",
"sort": 100,
"status": 1,
"remark": "公司动态与公告",
"created_at": "2026-09-25 10:00:00"
}
}响应参数说明
成功时 data 返回完整 CategoryItem：
| 响应字段 | 类型 | 说明 |
|---|---|---|
data.id | integer | 分类 ID |
data.name | string | 分类名称，最长 64 字符 |
data.slug | string | 唯一分类标识，最长 64 字符 |
data.sort | integer | 排序值，越大越靠前 |
data.status | integer | 1 启用，2 停用 |
data.remark | string | 分类备注 |
data.created_at | string | 创建时间 |
常见失败：分类标识已存在、修改对象不存在、字段不符合长度或枚举约束。
删除分类
接口地址
text
POST /admin/plugin/news/category/delete接口说明
删除分类。接口在事务中检查文章引用；分类下存在未删除文章时拒绝删除。重复删除返回「分类不存在」，不作为幂等成功处理。
接口参数说明
| Body 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 分类 ID |
响应示例
json
{ "code": 0, "msg": "success", "data": null }响应参数说明
成功时 data 为 null。
管理端文章接口
文章列表
接口地址
text
GET /admin/plugin/news/article/list接口说明
分页返回文章，分类通过预加载返回，支持分类、状态与启用状态筛选。
接口参数说明
| Query 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
keyword | string | 否 | 匹配标题或文章标识，最长 200 字符 |
category_id | integer | 否 | 分类 ID |
status | integer | 否 | 1 草稿，2 已发布，3 已下线 |
enable_status | integer | 否 | 1 启用，2 禁用 |
page | integer | 否 | 页码，默认 1 |
page_size | integer | 否 | 每页数量，最大 100 |
响应示例
json
{
"code": 0,
"msg": "success",
"data": {
"list": [
{
"id": 100,
"category_id": 12,
"category": { "id": 12, "name": "公司新闻", "slug": "company" },
"title": "新闻插件正式发布",
"slug": "news-plugin-release",
"summary": "新闻资讯插件 1.1.0 发布说明",
"cover": "uploads/2026/09/news-cover.webp",
"cover_url": "https://static.example.com/uploads/2026/09/news-cover.webp",
"status": 2,
"enable_status": 1,
"view_count": 101,
"virtual_view_count": 100,
"total_view_count": 201,
"published_at": "2026-09-24T18:30:00+08:00",
"created_at": "2026-09-24T18:00:00+08:00"
}
],
"total": 1
}
}响应参数说明
data 为 { "list": ArticleItem[], "total": integer }，ArticleItem 字段：
| 响应字段 | 类型 | 说明 |
|---|---|---|
list[].id | integer | 文章 ID |
list[].category_id | integer | 所属分类 ID |
list[].category | object | 关联分类对象（id/name/slug） |
list[].title | string | 文章标题，最长 200 字符 |
list[].slug | string | 唯一文章标识，最长 128 字符 |
list[].summary | string | 文章摘要，最长 500 字符 |
list[].cover | string | 封面相对路径 |
list[].cover_url | string | 封面完整访问地址 |
list[].status | integer | 1 草稿，2 已发布，3 已下线 |
list[].enable_status | integer | 1 启用，2 禁用 |
list[].view_count | integer | 真实阅读量 |
list[].virtual_view_count | integer | 后台配置的虚拟阅读量 |
list[].total_view_count | integer | 展示浏览量，真实与虚拟之和 |
list[].published_at | string/null | 最近发布时间 |
list[].created_at / updated_at | string | 创建 / 更新时间 |
文章详情
接口地址
text
GET /admin/plugin/news/article/detail?id=100接口说明
返回完整文章信息，包括富文本正文与关联分类。
接口参数说明
| Query 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 文章 ID |
响应参数说明
| 响应字段 | 类型 | 说明 |
|---|---|---|
data.id | integer | 文章 ID |
data.category_id | integer | 所属分类 ID |
data.category | object | 关联分类对象（id/name/slug） |
data.title | string | 文章标题，最长 200 字符 |
data.slug | string | 唯一文章标识，最长 128 字符 |
data.summary | string | 摘要，最长 500 字符 |
data.cover | string | 封面相对路径 |
data.cover_url | string | 封面完整访问地址 |
data.content | string | 富文本正文，客户端渲染需采用可信内容策略 |
data.status | integer | 1 草稿，2 已发布，3 已下线 |
data.enable_status | integer | 1 启用，2 禁用 |
data.view_count | integer | 真实阅读量 |
data.virtual_view_count | integer | 后台配置的虚拟阅读量 |
data.total_view_count | integer | 展示浏览量，真实与虚拟之和 |
data.published_at | string/null | 最近发布时间 |
data.created_at / data.updated_at | string | 创建 / 更新时间 |
保存文章
接口地址
text
POST /admin/plugin/news/article/save接口说明
新增文章始终保存为草稿；修改文章不会隐式改变当前发布状态。文章创建后 slug 不可变。封面可提交相对路径或当前存储域名下的完整地址，后端统一转为相对路径保存。slug 受唯一索引保护。
接口参数说明
| Body 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 文章 ID，新增传 0 |
category_id | integer | 是 | 所属分类 ID |
title | string | 是 | 标题，最长 200 字符 |
slug | string | 是 | 唯一标识，创建后不可变 |
summary | string | 否 | 摘要，最长 500 字符 |
cover | string | 否 | 封面文件地址 |
content | string | 否 | 富文本正文 |
enable_status | integer | 否 | 1 启用，2 禁用 |
virtual_view_count | integer | 否 | 虚拟阅读量 |
响应示例
json
{
"code": 0,
"msg": "success",
"data": {
"id": 100,
"title": "新闻插件正式发布",
"slug": "news-plugin-release",
"status": 1,
"cover_url": "https://static.example.com/uploads/2026/09/news-cover.webp"
}
}响应参数说明
| 响应字段 | 类型 | 说明 |
|---|---|---|
data.id | integer | 文章 ID |
data.category_id | integer | 所属分类 ID |
data.category | object | 关联分类对象（id/name/slug） |
data.title | string | 文章标题，最长 200 字符 |
data.slug | string | 唯一文章标识，最长 128 字符 |
data.summary | string | 摘要，最长 500 字符 |
data.cover | string | 封面相对路径 |
data.cover_url | string | 封面完整访问地址 |
data.content | string | 富文本正文，客户端渲染需采用可信内容策略 |
data.status | integer | 1 草稿，2 已发布，3 已下线 |
data.enable_status | integer | 1 启用，2 禁用 |
data.view_count | integer | 真实阅读量 |
data.virtual_view_count | integer | 后台配置的虚拟阅读量 |
data.total_view_count | integer | 展示浏览量，真实与虚拟之和 |
data.published_at | string/null | 最近发布时间 |
data.created_at / data.updated_at | string | 创建 / 更新时间 |
发布或下线文章
接口地址
text
POST /admin/plugin/news/article/status接口说明
status 传 2 发布（同时刷新 published_at 为当前时间），传 3 下线（保留原发布时间）。重复发布刷新发布时间，重复下线保持下线状态。
接口参数说明
| Body 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 文章 ID |
status | integer | 是 | 2 发布，3 下线 |
响应示例
json
{ "code": 0, "msg": "success", "data": null }响应参数说明
成功时 data 为 null。
删除文章
接口地址
text
POST /admin/plugin/news/article/delete接口说明
软删除文章，不物理移除数据库记录与已上传封面。重复删除返回「文章不存在」。
接口参数说明
| Body 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 文章 ID |
响应示例
json
{ "code": 0, "msg": "success", "data": null }响应参数说明
成功时 data 为 null。
用户端公开接口
公开接口无需 Token。调用方应在网关层结合部署规模设置限流；分页最大 100 条，禁止通过大分页抓取全部文章。
启用分类列表
接口地址
text
GET /api/plugin/news/categories接口说明
返回全部启用状态的分类，无分页。
接口参数说明
无请求参数。
响应示例
json
{
"code": 0,
"msg": "success",
"data": [
{ "id": 12, "name": "公司新闻", "slug": "company" }
]
}响应参数说明
| 响应字段 | 类型 | 说明 |
|---|---|---|
data[].id | integer | 分类 ID |
data[].name | string | 分类名称 |
data[].slug | string | 分类标识 |
已发布文章列表
接口地址
text
GET /api/plugin/news/articles接口说明
仅返回已发布且启用的文章，按 sort、published_at、id 倒序排列，不返回正文 content。
接口参数说明
| Query 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
category_slug | string | 否 | 启用分类的稳定标识 |
keyword | string | 否 | 标题关键字，最长 100 字符 |
page | integer | 否 | 页码，默认 1 |
page_size | integer | 否 | 每页数量，最大 100 |
响应示例
json
{
"code": 0,
"msg": "success",
"data": {
"list": [
{
"id": 100,
"category": { "id": 12, "name": "公司新闻", "slug": "company" },
"title": "新闻插件正式发布",
"slug": "news-plugin-release",
"summary": "新闻资讯插件 1.1.0 发布说明",
"cover_url": "https://static.example.com/uploads/2026/09/news-cover.webp",
"total_view_count": 201,
"published_at": "2026-09-24T18:30:00+08:00"
}
],
"total": 1
}
}响应参数说明
data 为 { "list": ArticleItem[], "total": integer }：
| 响应字段 | 类型 | 说明 |
|---|---|---|
data.list[].id | integer | 文章 ID |
data.list[].category_id | integer | 所属分类 ID |
data.list[].category | object | 关联分类对象（id/name/slug） |
data.list[].title | string | 文章标题，最长 200 字符 |
data.list[].slug | string | 唯一文章标识，最长 128 字符 |
data.list[].summary | string | 摘要，最长 500 字符 |
data.list[].cover | string | 封面相对路径 |
data.list[].cover_url | string | 封面完整访问地址 |
data.list[].status | integer | 1 草稿，2 已发布，3 已下线 |
data.list[].enable_status | integer | 1 启用，2 禁用 |
data.list[].view_count | integer | 真实阅读量 |
data.list[].virtual_view_count | integer | 后台配置的虚拟阅读量 |
data.list[].total_view_count | integer | 展示浏览量，真实与虚拟之和 |
data.list[].published_at | string/null | 最近发布时间 |
data.total | integer | 数据总数 |
用户端列表不返回正文 content 字段。
已发布文章详情
接口地址
text
GET /api/plugin/news/articles/:slug接口说明
按文章标识返回已发布且启用的文章详情。每次成功查询会在事务中原子累加真实浏览量（view_count + 1），客户端重试会再次计数，该副作用不具备幂等性。
接口参数说明
| Path 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
slug | string | 是 | 文章稳定标识，最长 128 字符 |
响应示例
json
{
"code": 0,
"msg": "success",
"data": {
"id": 100,
"category_id": 12,
"category": { "id": 12, "name": "公司新闻", "slug": "company" },
"title": "新闻插件正式发布",
"slug": "news-plugin-release",
"summary": "新闻资讯插件 1.1.0 发布说明",
"cover": "uploads/2026/09/news-cover.webp",
"cover_url": "https://static.example.com/uploads/2026/09/news-cover.webp",
"content": "<p>正文内容</p>",
"view_count": 101,
"virtual_view_count": 100,
"total_view_count": 201,
"published_at": "2026-09-24T18:30:00+08:00"
}
}响应参数说明
| 响应字段 | 类型 | 说明 |
|---|---|---|
data.id | integer | 文章 ID |
data.category_id | integer | 所属分类 ID |
data.category | object | 关联分类对象（id/name/slug） |
data.title | string | 文章标题，最长 200 字符 |
data.slug | string | 唯一文章标识，最长 128 字符 |
data.summary | string | 摘要，最长 500 字符 |
data.cover | string | 封面相对路径 |
data.cover_url | string | 封面完整访问地址 |
data.content | string | 富文本正文，客户端渲染需采用可信内容策略 |
data.status | integer | 1 草稿，2 已发布，3 已下线 |
data.enable_status | integer | 1 启用，2 禁用 |
data.view_count | integer | 真实阅读量 |
data.virtual_view_count | integer | 后台配置的虚拟阅读量 |
data.total_view_count | integer | 展示浏览量，真实与虚拟之和 |
data.published_at | string/null | 最近发布时间 |
data.created_at / data.updated_at | string | 创建 / 更新时间 |