Skip to content

新闻资讯插件(news) ​

新闻资讯插件的接口文档,基于插件版本 0.0.1(核心版本 0.0.1)。管理端前缀 /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 为按当前存储配置补全的访问地址。

公开业务关联全部使用唯一 uid,用户端不返回数据库主键、会员 SN、账号、原始 IP 或登录凭据。用户端写接口从鉴权令牌取得会员身份,客户端不能提交会员标识。

广告配置接口(0.0.1) ​

新闻插件不重复维护第三方广告 ID,而是引用核心广告配置。核心广告必须绑定 news 插件,新闻投放配置负责设置其展示位置和独立启停状态。

广告最终展示需要同时满足以下条件:

  1. 新闻插件已启用;
  2. 核心广告状态为启用;
  3. 新闻投放配置状态为启用;
  4. 核心广告已绑定 news 插件;
  5. 当前请求的 X-Platform-Source 位于核心广告 platforms 中;
  6. 广告 ID 非空,展示位置与请求一致。

查询新闻广告配置 ​

text
GET /admin/plugin/news/advertisement/list

权限标识:GET:/admin/plugin/news/advertisement/list。请求无业务参数,按展示位置升序、配置 ID 倒序返回全部新闻投放配置。

响应示例:

json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 8,
      "advertisement_id": 12,
      "name": "微信新闻信息流",
      "ad_id": "adunit-xxxxxxxxxxxxxxxx",
      "format": 1,
      "platforms": [1],
      "status": 1,
      "description": "新闻列表与详情页信息流广告",
      "position": 2,
      "config_status": 1
    }
  ]
}
响应字段类型说明
data[].idinteger新闻广告投放配置 ID
data[].advertisement_idinteger引用的核心广告配置 ID
data[].namestring核心广告名称
data[].ad_idstring第三方广告平台 ID
data[].formatinteger广告形式:1 信息流、2 激励视频、3 弹窗
data[].platformsarray<integer>核心广告允许展示的平台
data[].statusinteger核心广告状态:1 启用、2 停用
data[].descriptionstring核心广告说明
data[].positioninteger新闻展示位置:1 新闻列表、2 新闻详情
data[].config_statusinteger新闻投放独立状态:1 启用、2 停用

查询可选广告 ​

text
GET /admin/plugin/news/advertisement/options

权限标识:GET:/admin/plugin/news/advertisement/options。请求无业务参数,只返回已在核心广告模块绑定 news 插件的广告;核心广告停用时仍会返回并通过 status 标记,便于维护已有配置。

json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 12,
      "name": "微信新闻信息流",
      "ad_id": "adunit-xxxxxxxxxxxxxxxx",
      "format": 1,
      "platforms": [1],
      "status": 1,
      "description": "新闻列表与详情页信息流广告"
    }
  ]
}

新增或修改新闻广告配置 ​

text
POST /admin/plugin/news/advertisement/save

权限标识:POST:/admin/plugin/news/advertisement/save。

Body 参数类型必填说明
idinteger否新增传 0 或不传,修改时传新闻投放配置 ID
advertisement_idinteger是核心广告配置 ID,必须已经绑定 news 插件
positioninteger是展示位置:1 新闻列表、2 新闻详情
statusinteger是新闻投放独立状态:1 启用、2 停用
json
{
  "id": 0,
  "advertisement_id": 12,
  "position": 2,
  "status": 1
}

成功响应:

json
{ "code": 0, "msg": "success" }

同一核心广告不能重复配置到同一个展示位置。新增和修改都会校验核心广告是否绑定 news 插件。

删除新闻广告配置 ​

text
POST /admin/plugin/news/advertisement/delete

权限标识:POST:/admin/plugin/news/advertisement/delete。

Body 参数类型必填说明
idinteger是新闻广告投放配置 ID,必须大于 0

成功响应:

json
{ "code": 0, "msg": "success" }

该接口软删除新闻投放配置,不删除核心广告。

用户端查询可展示广告 ​

text
GET /api/plugin/news/advertisements?position=2

该接口属于公开接口,不需要登录,但必须携带用户端平台请求头:

Header必填说明
X-Platform-Source是当前平台来源,取值与注册来源枚举一致
X-App-Version否当前客户端版本,供后续兼容和灰度使用
Query 参数类型必填说明
positioninteger是1 新闻列表、2 新闻详情

响应只返回客户端渲染广告所需字段,不返回投放配置主键、平台集合、插件关系或状态字段:

json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 12,
      "name": "微信新闻信息流",
      "ad_id": "adunit-xxxxxxxxxxxxxxxx",
      "format": 1,
      "description": "新闻列表与详情页信息流广告"
    }
  ]
}
响应字段类型说明
data[].idinteger核心广告配置 ID,仅用于当前页面渲染键值
data[].namestring广告名称
data[].ad_idstring当前平台广告组件使用的广告 ID
data[].formatinteger广告形式:1 信息流、2 激励视频、3 弹窗
data[].descriptionstring广告展示说明

没有符合条件的广告时返回空数组,广告读取失败不应阻塞新闻列表或文章详情加载。

v0.1.2 管理端复用资讯 ​

文章列表提供“复用资讯”图标操作,点击后进入独立新增页面。该功能不增加专用后端接口,而是先调用 GET /admin/plugin/news/article/detail?id={id} 读取源资讯,再以 id=0 调用 POST /admin/plugin/news/article/save 创建新资讯。

复用页面会预填分类、标题、摘要、作者、来源、封面、正文、启用状态和排序;标题追加“(复用)”以提醒编辑人员确认。数据库主键、文章 UID、发布状态、发布时间、真实阅读、虚拟阅读、点赞、收藏、分享和评论均不会继承。

新文章标识采用约 11 位短格式 n + 6 位时间片 + 4 位随机值,例如 n4k8x2a7b3c。保存前可以修改,服务端仍执行格式校验和唯一性校验,保存后不可修改。复用入口沿用文章详情和保存文章权限,不增加新的权限节点。

v0.1.0 互动接口 ​

用户端公开读取 ​

方法地址说明
GET/api/plugin/news/article/comments?article_uid=xxx已展示一级评论分页,page_size 最大 50
GET/api/plugin/news/comment/replies?comment_uid=xxx指定一级评论下的已展示回复分页

评论响应仅包含 uid、昵称、头像地址、被回复昵称、内容、图片地址、点赞数、回复数和创建时间。

用户端登录后写入 ​

方法地址说明
POST/api/auth/plugin/news/article/comment发表一级评论,Body 携带 article_uid
POST/api/auth/plugin/news/comment/reply回复评论,Body 携带 comment_uid
POST / DELETE/api/auth/plugin/news/article/like点赞或取消文章点赞,Body 携带 article_uid
POST / DELETE/api/auth/plugin/news/comment/like点赞或取消评论点赞,Body 携带 comment_uid
GET/api/auth/plugin/news/article/interaction?article_uid=xxx当前会员文章点赞状态
POST/api/auth/plugin/news/article/share记录分享发起

评论请求字段为 content、最多 3 项的 images 相对路径和必填 request_uid。分享请求字段为 request_uid 与 share_channel;渠道 1 微信好友、2 微信朋友圈、3 系统分享、4 复制链接。request_uid 用于幂等控制。

管理端评论维护 ​

方法地址说明
GET/admin/plugin/news/article/comment/list一级评论分页
GET/admin/plugin/news/article/comment/replies一级评论下的回复分页
POST/admin/plugin/news/article/comment/status设置评论为显示或关闭

状态请求示例:{ "comment_uid": "cf12345678", "status": 2 },状态只允许 2 显示或 3 关闭。管理端返回昵称、头像、脱敏账号和脱敏 IP,不返回会员 SN 与数据库主键。评论状态和展示计数在同一数据库事务更新。

互动接口具备 Redis 频率限制、数据库唯一索引、幂等请求标识和原子计数。评论默认状态为 1 待审核,审核显示后才进入用户端公开列表。

管理端分类接口 ​

分类列表 ​

接口地址 ​

text
GET /admin/plugin/news/category/list

接口说明 ​

分页返回新闻分类,支持按名称或标识搜索。

接口参数说明 ​

Query 参数类型必填说明
keywordstring否匹配分类名称或标识,最长 64 字符
statusinteger否1 启用,2 停用
pageinteger否页码,默认 1
page_sizeinteger否每页数量,最大 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[].idinteger分类 ID
list[].namestring分类名称,最长 64 字符
list[].slugstring唯一分类标识,最长 64 字符
list[].sortinteger排序值,越大越靠前
list[].statusinteger1 启用,2 停用
list[].remarkstring分类备注
list[].created_atstring创建时间
totalinteger数据总数

保存分类 ​

接口地址 ​

text
POST /admin/plugin/news/category/save

接口说明 ​

新增时 id 传 0,修改时传现有分类 ID。管理端新增页面会自动生成标识,保存前允许修改;分类创建后 slug 不可变,修改请求中的该字段不会覆盖数据库原值。slug 受数据库唯一索引保护,并发提交相同标识只会有一个请求成功。

接口参数说明 ​

Body 参数类型必填说明
idinteger是分类 ID,新增传 0
namestring是分类名称,最长 64 字符
slugstring是唯一标识,创建后不可变
sortinteger否排序值,越大越靠前
statusinteger否1 启用,2 停用
remarkstring否分类备注

响应示例 ​

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.idinteger分类 ID
data.namestring分类名称,最长 64 字符
data.slugstring唯一分类标识,最长 64 字符
data.sortinteger排序值,越大越靠前
data.statusinteger1 启用,2 停用
data.remarkstring分类备注
data.created_atstring创建时间

常见失败:分类标识已存在、修改对象不存在、字段不符合长度或枚举约束。

删除分类 ​

接口地址 ​

text
POST /admin/plugin/news/category/delete

接口说明 ​

删除分类。接口在事务中检查文章引用;分类下存在未删除文章时拒绝删除。重复删除返回「分类不存在」,不作为幂等成功处理。

接口参数说明 ​

Body 参数类型必填说明
idinteger是分类 ID

响应示例 ​

json
{ "code": 0, "msg": "success", "data": null }

响应参数说明 ​

成功时 data 为 null。

管理端文章接口 ​

文章列表 ​

接口地址 ​

text
GET /admin/plugin/news/article/list

接口说明 ​

分页返回文章,分类通过预加载返回,支持分类、状态与启用状态筛选。

接口参数说明 ​

Query 参数类型必填说明
keywordstring否匹配标题或文章标识,最长 200 字符
category_idinteger否分类 ID
statusinteger否1 草稿,2 已发布,3 已下线
enable_statusinteger否1 启用,2 禁用
pageinteger否页码,默认 1
page_sizeinteger否每页数量,最大 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 发布说明",
        "author": "编辑部",
        "source_name": "项目官网",
        "source_url": "https://www.tutudati.com/news/plugin-release",
        "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[].idinteger文章 ID
list[].category_idinteger所属分类 ID
list[].categoryobject关联分类对象(id/name/slug)
list[].titlestring文章标题,最长 200 字符
list[].slugstring唯一文章标识,最长 128 字符
list[].summarystring文章摘要,最长 500 字符
list[].authorstring文章作者,最长 100 字符
list[].source_namestring来源平台名称,最长 100 字符
list[].source_urlstring来源外链,仅支持 HTTP/HTTPS
list[].coverstring封面相对路径
list[].cover_urlstring封面完整访问地址
list[].statusinteger1 草稿,2 已发布,3 已下线
list[].enable_statusinteger1 启用,2 禁用
list[].view_countinteger真实阅读量
list[].virtual_view_countinteger后台配置的虚拟阅读量
list[].total_view_countinteger展示浏览量,真实与虚拟之和
list[].published_atstring/null最近发布时间
list[].created_at / updated_atstring创建 / 更新时间

文章详情 ​

接口地址 ​

text
GET /admin/plugin/news/article/detail?id=100

接口说明 ​

返回完整文章信息,包括富文本正文与关联分类。

接口参数说明 ​

Query 参数类型必填说明
idinteger是文章 ID

响应参数说明 ​

响应字段类型说明
data.idinteger文章 ID
data.category_idinteger所属分类 ID
data.categoryobject关联分类对象(id/name/slug)
data.titlestring文章标题,最长 200 字符
data.slugstring唯一文章标识,最长 128 字符
data.summarystring摘要,最长 500 字符
data.authorstring文章作者,最长 100 字符
data.source_namestring来源平台名称,最长 100 字符
data.source_urlstring来源外链,仅支持 HTTP/HTTPS
data.coverstring封面相对路径
data.cover_urlstring封面完整访问地址
data.contentstring富文本正文,客户端渲染需采用可信内容策略
data.statusinteger1 草稿,2 已发布,3 已下线
data.enable_statusinteger1 启用,2 禁用
data.view_countinteger真实阅读量
data.virtual_view_countinteger后台配置的虚拟阅读量
data.total_view_countinteger展示浏览量,真实与虚拟之和
data.published_atstring/null最近发布时间
data.created_at / data.updated_atstring创建 / 更新时间

保存文章 ​

接口地址 ​

text
POST /admin/plugin/news/article/save

接口说明 ​

新增文章始终保存为草稿;修改文章不会隐式改变当前发布状态。文章创建后 slug 不可变。封面可提交相对路径或当前存储域名下的完整地址,后端统一转为相对路径保存。slug 受唯一索引保护。

接口参数说明 ​

Body 参数类型必填说明
idinteger是文章 ID,新增传 0
category_idinteger是所属分类 ID
titlestring是标题,最长 200 字符
slugstring是唯一标识,创建后不可变
summarystring否摘要,最长 500 字符
authorstring否文章作者,最长 100 字符
source_namestring否来源平台名称,最长 100 字符
source_urlstring否来源外链,仅支持 HTTP/HTTPS,最长 1024 字符
coverstring否封面文件地址
contentstring否富文本正文
enable_statusinteger否1 启用,2 禁用
virtual_view_countinteger否虚拟阅读量

响应示例 ​

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.idinteger文章 ID
data.category_idinteger所属分类 ID
data.categoryobject关联分类对象(id/name/slug)
data.titlestring文章标题,最长 200 字符
data.slugstring唯一文章标识,最长 128 字符
data.summarystring摘要,最长 500 字符
data.authorstring文章作者,最长 100 字符
data.source_namestring来源平台名称,最长 100 字符
data.source_urlstring来源外链,仅支持 HTTP/HTTPS
data.coverstring封面相对路径
data.cover_urlstring封面完整访问地址
data.contentstring富文本正文,客户端渲染需采用可信内容策略
data.statusinteger1 草稿,2 已发布,3 已下线
data.enable_statusinteger1 启用,2 禁用
data.view_countinteger真实阅读量
data.virtual_view_countinteger后台配置的虚拟阅读量
data.total_view_countinteger展示浏览量,真实与虚拟之和
data.published_atstring/null最近发布时间
data.created_at / data.updated_atstring创建 / 更新时间

发布或下线文章 ​

接口地址 ​

text
POST /admin/plugin/news/article/status

接口说明 ​

status 传 2 发布(同时刷新 published_at 为当前时间),传 3 下线(保留原发布时间)。重复发布刷新发布时间,重复下线保持下线状态。

接口参数说明 ​

Body 参数类型必填说明
idinteger是文章 ID
statusinteger是2 发布,3 下线

响应示例 ​

json
{ "code": 0, "msg": "success", "data": null }

响应参数说明 ​

成功时 data 为 null。

删除文章 ​

接口地址 ​

text
POST /admin/plugin/news/article/delete

接口说明 ​

软删除文章,不物理移除数据库记录与已上传封面。重复删除返回「文章不存在」。

接口参数说明 ​

Body 参数类型必填说明
idinteger是文章 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[].idinteger分类 ID
data[].namestring分类名称
data[].slugstring分类标识

已发布文章列表 ​

接口地址 ​

text
GET /api/plugin/news/articles

接口说明 ​

仅返回已发布且启用的文章,按 sort、published_at、id 倒序排列,不返回正文 content。

接口参数说明 ​

Query 参数类型必填说明
category_slugstring否启用分类的稳定标识
keywordstring否标题关键字,最长 100 字符
pageinteger否页码,默认 1
page_sizeinteger否每页数量,最大 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 发布说明",
        "author": "编辑部",
        "source_name": "项目官网",
        "source_url": "https://www.tutudati.com/news/plugin-release",
        "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[].idinteger文章 ID
data.list[].category_idinteger所属分类 ID
data.list[].categoryobject关联分类对象(id/name/slug)
data.list[].titlestring文章标题,最长 200 字符
data.list[].slugstring唯一文章标识,最长 128 字符
data.list[].summarystring摘要,最长 500 字符
data.list[].authorstring文章作者,最长 100 字符
data.list[].source_namestring来源平台名称,最长 100 字符
data.list[].source_urlstring来源外链,仅支持 HTTP/HTTPS
data.list[].coverstring封面相对路径
data.list[].cover_urlstring封面完整访问地址
data.list[].statusinteger1 草稿,2 已发布,3 已下线
data.list[].enable_statusinteger1 启用,2 禁用
data.list[].view_countinteger真实阅读量
data.list[].virtual_view_countinteger后台配置的虚拟阅读量
data.list[].total_view_countinteger展示浏览量,真实与虚拟之和
data.list[].published_atstring/null最近发布时间
data.totalinteger数据总数

用户端列表不返回正文 content 字段。

已发布文章详情 ​

接口地址 ​

text
GET /api/plugin/news/article/detail?slug=news-plugin-release

接口说明 ​

按文章标识返回已发布且启用的文章详情。每次成功查询会在事务中原子累加真实浏览量(view_count + 1),客户端重试会再次计数,该副作用不具备幂等性。

接口参数说明 ​

Query 参数类型必填说明
slugstring是文章稳定标识,最长 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 发布说明",
    "author": "编辑部",
    "source_name": "项目官网",
    "source_url": "https://www.tutudati.com/news/plugin-release",
    "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.idinteger文章 ID
data.category_idinteger所属分类 ID
data.categoryobject关联分类对象(id/name/slug)
data.titlestring文章标题,最长 200 字符
data.slugstring唯一文章标识,最长 128 字符
data.summarystring摘要,最长 500 字符
data.authorstring文章作者,最长 100 字符
data.source_namestring来源平台名称,最长 100 字符
data.source_urlstring来源外链,仅支持 HTTP/HTTPS
data.coverstring封面相对路径
data.cover_urlstring封面完整访问地址
data.contentstring富文本正文,客户端渲染需采用可信内容策略
data.statusinteger1 草稿,2 已发布,3 已下线
data.enable_statusinteger1 启用,2 禁用
data.view_countinteger真实阅读量
data.virtual_view_countinteger后台配置的虚拟阅读量
data.total_view_countinteger展示浏览量,真实与虚拟之和
data.published_atstring/null最近发布时间
data.created_at / data.updated_atstring创建 / 更新时间