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次/分钟 |