196 lines
3.9 KiB
Plaintext
196 lines
3.9 KiB
Plaintext
|
新闻资讯模块接口文档
|
|||
|
|
================
|
|||
|
|
|
|||
|
|
基础信息
|
|||
|
|
-------
|
|||
|
|
- 基础路径: /api/v1/news
|
|||
|
|
- 请求方式: REST
|
|||
|
|
- 数据格式: JSON
|
|||
|
|
- 认证方式: Bearer Token
|
|||
|
|
|
|||
|
|
数据结构
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
News 新闻对象:
|
|||
|
|
{
|
|||
|
|
id: number, // 新闻ID
|
|||
|
|
title: string, // 标题
|
|||
|
|
summary: string, // 摘要
|
|||
|
|
content: string, // 内容
|
|||
|
|
image: string, // 封面图片
|
|||
|
|
category: string, // 分类
|
|||
|
|
time: string, // 发布时间
|
|||
|
|
views: number, // 浏览量
|
|||
|
|
source: string, // 来源
|
|||
|
|
tags: string[], // 标签
|
|||
|
|
status: string // 状态(published/draft)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
NewsCategory 分类对象:
|
|||
|
|
{
|
|||
|
|
value: string, // 分类值
|
|||
|
|
label: string, // 分类名称
|
|||
|
|
count: number // 新闻数量
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
NewsComment 评论对象:
|
|||
|
|
{
|
|||
|
|
id: number, // 评论ID
|
|||
|
|
newsId: number, // 新闻ID
|
|||
|
|
userId: number, // 用户ID
|
|||
|
|
userName: string, // 用户名
|
|||
|
|
content: string, // 评论内容
|
|||
|
|
time: string, // 评论时间
|
|||
|
|
likes: number, // 点赞数
|
|||
|
|
replies?: NewsComment[] // 回复列表
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
API 接口
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
1. 获取新闻列表
|
|||
|
|
GET /api/v1/news
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| category | string | 否 | 新闻分类 |
|
|||
|
|
| page | number | 否 | 页码，默认1 |
|
|||
|
|
| size | number | 否 | 每页数量，默认10 |
|
|||
|
|
| keyword | string | 否 | 搜索关键词 |
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"total": 100,
|
|||
|
|
"records": [
|
|||
|
|
{
|
|||
|
|
"id": 1,
|
|||
|
|
"title": "老年人健康管理新政策出台",
|
|||
|
|
"summary": "国家发布新政策，加强老年人健康管理服务...",
|
|||
|
|
"image": "https://example.com/news1.jpg",
|
|||
|
|
"category": "policy",
|
|||
|
|
"time": "2024-03-20 10:30",
|
|||
|
|
"views": 1234,
|
|||
|
|
"source": "健康时报",
|
|||
|
|
"tags": ["政策", "健康", "养老"],
|
|||
|
|
"status": "published"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
2. 获取新闻详情
|
|||
|
|
GET /api/v1/news/{id}
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
// 新闻详细信息
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
3. 获取新闻分类
|
|||
|
|
GET /api/v1/news/categories
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"value": "policy",
|
|||
|
|
"label": "政策新闻",
|
|||
|
|
"count": 128
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
4. 获取热门新闻
|
|||
|
|
GET /api/v1/news/hot
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| limit | number | 否 | 返回数量，默认5 |
|
|||
|
|
|
|||
|
|
5. 更新浏览量
|
|||
|
|
POST /api/v1/news/{id}/view
|
|||
|
|
|
|||
|
|
6. 获取新闻评论
|
|||
|
|
GET /api/v1/news/{id}/comments
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"id": 1,
|
|||
|
|
"newsId": 1,
|
|||
|
|
"userId": 10001,
|
|||
|
|
"userName": "张三",
|
|||
|
|
"content": "政策很实用",
|
|||
|
|
"time": "2024-03-20 11:00",
|
|||
|
|
"likes": 12,
|
|||
|
|
"replies": []
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
7. 添加评论
|
|||
|
|
POST /api/v1/news/{id}/comments
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
{
|
|||
|
|
"content": "评论内容",
|
|||
|
|
"parentId": null // 回复其他评论时设置
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
8. 点赞评论
|
|||
|
|
POST /api/v1/news/comments/{id}/like
|
|||
|
|
|
|||
|
|
9. 获取相关新闻
|
|||
|
|
GET /api/v1/news/{id}/related
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| limit | number | 否 | 返回数量，默认3 |
|
|||
|
|
|
|||
|
|
10. 订阅主题
|
|||
|
|
POST /api/v1/news/subscribe
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
{
|
|||
|
|
"topics": ["health", "policy"]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
11. 获取订阅推送
|
|||
|
|
GET /api/v1/news/subscribed
|
|||
|
|
|
|||
|
|
错误码说明
|
|||
|
|
--------
|
|||
|
|
| 错误码 | 说明 |
|
|||
|
|
| 200 | 成功 |
|
|||
|
|
| 400 | 请求参数错误 |
|
|||
|
|
| 401 | 未授权 |
|
|||
|
|
| 403 | 禁止访问 |
|
|||
|
|
| 404 | 资源不存在 |
|
|||
|
|
| 500 | 服务器内部错误 |
|
|||
|
|
|
|||
|
|
注意事项
|
|||
|
|
-------
|
|||
|
|
1. 新闻内容支持富文本格式
|
|||
|
|
2. 图片URL需要进行防盗链处理
|
|||
|
|
3. 评论支持多级回复
|
|||
|
|
4. 缓存策略：
|
|||
|
|
- 新闻列表缓存：5分钟
|
|||
|
|
- 新闻详情缓存：10分钟
|
|||
|
|
- 热门新闻缓存：1小时
|
|||
|
|
- 分类列表缓存：1天
|
|||
|
|
5. 访问频率限制：
|
|||
|
|
- 获取列表：10次/分钟
|
|||
|
|
- 发表评论：2次/分钟
|
|||
|
|
- 点赞操作：5次/分钟
|