1082 lines
18 KiB
Markdown
1082 lines
18 KiB
Markdown
# 新闻分类器后端 API 文档
|
||
|
||
## 基础信息
|
||
|
||
- **Base URL**: `http://localhost:8080`
|
||
- **API 版本**: v1
|
||
- **响应格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
|
||
---
|
||
|
||
## 统一响应格式
|
||
|
||
所有接口返回统一的 `RestBean` 格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 状态码说明
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 操作成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证（需要登录） |
|
||
| 403 | 无权限访问 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
### 预定义状态码（RestCode）
|
||
|
||
| code | message | 说明 |
|
||
|------|---------|------|
|
||
| 200 | 操作成功 | SUCCESS |
|
||
| 400 | 请求参数错误 | FAILURE |
|
||
| 401 | 请先登录 | - |
|
||
| 403 | 无权限访问 | - |
|
||
| 404 | 数据不存在 | DATA_NOT_FOUND |
|
||
| 500 | 服务端错误 | SYSTEM_ERROR |
|
||
| 10001 | 用户名或密码错误 | USERNAME_OR_PASSWORD_ERROR |
|
||
| 10002 | Token已过期 | TOKEN_EXPIRE |
|
||
|
||
---
|
||
|
||
## 认证说明
|
||
|
||
### Token 认证
|
||
|
||
需要认证的接口需要在请求头中携带 Token：
|
||
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
### Token 获取
|
||
|
||
通过登录接口获取，参见 [用户登录](#32-用户登录)
|
||
|
||
---
|
||
|
||
# 一、用户接口
|
||
|
||
## Base Path: `/api/v1/user`
|
||
|
||
## 3.1 用户注册
|
||
|
||
**接口地址**: `POST /api/v1/user/register`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| username | String | 是 | 用户名（唯一，50字符以内） |
|
||
| password | String | 是 | 密码 |
|
||
| email | String | 是 | 邮箱（唯一） |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "123456",
|
||
"email": "test@example.com"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "用户名已被使用",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.2 用户登录
|
||
|
||
**接口地址**: `POST /api/v1/user/login`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| username | String | 是 | 用户名 |
|
||
| password | String | 是 | 密码 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "用户不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 10001,
|
||
"message": "用户名或密码错误",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 403,
|
||
"message": "用户已被禁用",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.3 获取用户信息
|
||
|
||
**接口地址**: `GET /api/v1/user/info`
|
||
|
||
**是否需要认证**: 是
|
||
|
||
**请求头**:
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "testuser",
|
||
"email": "test@example.com",
|
||
"status": 1,
|
||
"createdAt": "2024-01-01T10:00:00",
|
||
"updatedAt": "2024-01-01T10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 二、分类管理接口
|
||
|
||
## Base Path: `/api/v1/categories`
|
||
|
||
**说明**: 所有分类接口均无需认证，公开访问
|
||
|
||
---
|
||
|
||
## 2.1 获取所有分类
|
||
|
||
**接口地址**: `GET /api/v1/categories`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"name": "娱乐",
|
||
"newsCount": null
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "体育",
|
||
"newsCount": null
|
||
},
|
||
{
|
||
"id": 3,
|
||
"name": "财经",
|
||
"newsCount": null
|
||
},
|
||
{
|
||
"id": 4,
|
||
"name": "科技",
|
||
"newsCount": null
|
||
},
|
||
{
|
||
"id": 5,
|
||
"name": "军事",
|
||
"newsCount": null
|
||
},
|
||
{
|
||
"id": 6,
|
||
"name": "汽车",
|
||
"newsCount": null
|
||
},
|
||
{
|
||
"id": 7,
|
||
"name": "政务",
|
||
"newsCount": null
|
||
},
|
||
{
|
||
"id": 8,
|
||
"name": "健康",
|
||
"newsCount": null
|
||
},
|
||
{
|
||
"id": 9,
|
||
"name": "AI",
|
||
"newsCount": null
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2.2 获取分类及新闻数量
|
||
|
||
**接口地址**: `GET /api/v1/categories/with-count`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"name": "娱乐",
|
||
"newsCount": 152
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "体育",
|
||
"newsCount": 89
|
||
},
|
||
{
|
||
"id": 4,
|
||
"name": "科技",
|
||
"newsCount": 234
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2.3 获取分类详情
|
||
|
||
**接口地址**: `GET /api/v1/categories/{id}`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Integer | 是 | 分类ID |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"id": 4,
|
||
"name": "科技",
|
||
"newsCount": null
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "数据不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2.4 创建分类
|
||
|
||
**接口地址**: `POST /api/v1/categories`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| name | String | 是 | 分类名称（唯一，50字符以内） |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"name": "游戏"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"id": 10,
|
||
"name": "游戏",
|
||
"newsCount": null
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "分类名称已存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2.5 更新分类
|
||
|
||
**接口地址**: `PUT /api/v1/categories/{id}`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Integer | 是 | 分类ID |
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| name | String | 是 | 分类名称 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"name": "电竞游戏"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"id": 10,
|
||
"name": "电竞游戏",
|
||
"newsCount": null
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2.6 删除分类
|
||
|
||
**接口地址**: `DELETE /api/v1/categories/{id}`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Integer | 是 | 分类ID |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 三、新闻管理接口
|
||
|
||
## Base Path: `/api/v1/news`
|
||
|
||
**说明**: 所有新闻接口均无需认证，公开访问
|
||
|
||
---
|
||
|
||
## 3.1 获取新闻列表
|
||
|
||
**接口地址**: `GET /api/v1/news/list`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**查询参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| page | Integer | 否 | 1 | 页码 |
|
||
| size | Integer | 否 | 20 | 每页大小 |
|
||
| categoryId | Integer | 否 | - | 分类ID筛选 |
|
||
| source | String | 否 | - | 来源筛选（如：网易、36kr） |
|
||
| keyword | String | 否 | - | 搜索关键词（标题或内容） |
|
||
| sortBy | String | 否 | createdAt | 排序字段 |
|
||
| sortOrder | String | 否 | DESC | 排序方向（ASC/DESC） |
|
||
|
||
**请求示例**:
|
||
```
|
||
GET /api/v1/news/list?page=1&size=10&categoryId=4&source=网易
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 1,
|
||
"url": "https://news.example.com/tech/001",
|
||
"title": "AI技术突破：新一代大语言模型发布",
|
||
"categoryId": 9,
|
||
"categoryName": "AI",
|
||
"publishTime": "2024-01-15 10:30:00",
|
||
"author": "张三",
|
||
"source": "网易",
|
||
"content": "正文内容...",
|
||
"createdAt": "2024-01-15 11:00:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"url": "https://news.example.com/tech/002",
|
||
"title": "量子计算取得重大进展",
|
||
"categoryId": 4,
|
||
"categoryName": "科技",
|
||
"publishTime": "2024-01-15 09:00:00",
|
||
"author": "李四",
|
||
"source": "36kr",
|
||
"content": "正文内容...",
|
||
"createdAt": "2024-01-15 10:00:00"
|
||
}
|
||
],
|
||
"total": 156,
|
||
"page": 1,
|
||
"size": 10,
|
||
"pages": 16
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.2 获取新闻详情
|
||
|
||
**接口地址**: `GET /api/v1/news/{id}`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 新闻ID |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"id": 1,
|
||
"url": "https://news.example.com/tech/001",
|
||
"title": "AI技术突破：新一代大语言模型发布",
|
||
"categoryId": 9,
|
||
"categoryName": "AI",
|
||
"publishTime": "2024-01-15 10:30:00",
|
||
"author": "张三",
|
||
"source": "网易",
|
||
"content": "完整的正文内容...",
|
||
"createdAt": "2024-01-15 11:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.3 创建新闻
|
||
|
||
**接口地址**: `POST /api/v1/news`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| url | String | 是 | 新闻URL（唯一，500字符以内） |
|
||
| title | String | 是 | 标题（255字符以内） |
|
||
| categoryId | Integer | 否 | 分类ID |
|
||
| publishTime | LocalDateTime | 否 | 发布时间 |
|
||
| author | String | 否 | 作者 |
|
||
| source | String | 否 | 来源（如：网易、36kr） |
|
||
| content | String | 是 | 正文内容 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"url": "https://news.example.com/tech/003",
|
||
"title": "5G网络建设加速推进",
|
||
"categoryId": 4,
|
||
"publishTime": "2024-01-16T08:00:00",
|
||
"author": "王五",
|
||
"source": "36kr",
|
||
"content": "完整的新闻正文内容..."
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"id": 3,
|
||
"url": "https://news.example.com/tech/003",
|
||
"title": "5G网络建设加速推进",
|
||
"categoryId": 4,
|
||
"categoryName": "科技",
|
||
"publishTime": "2024-01-16 08:00:00",
|
||
"author": "王五",
|
||
"source": "36kr",
|
||
"content": "完整的新闻正文内容...",
|
||
"createdAt": "2024-01-16 09:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "该URL的新闻已存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "指定的分类不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.4 更新新闻
|
||
|
||
**接口地址**: `PUT /api/v1/news`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 新闻ID |
|
||
| title | String | 否 | 标题 |
|
||
| categoryId | Integer | 否 | 分类ID |
|
||
| publishTime | LocalDateTime | 否 | 发布时间 |
|
||
| author | String | 否 | 作者 |
|
||
| source | String | 否 | 来源 |
|
||
| content | String | 否 | 正文内容 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"id": 3,
|
||
"title": "5G网络建设加速推进（更新）",
|
||
"categoryId": 9
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"id": 3,
|
||
"url": "https://news.example.com/tech/003",
|
||
"title": "5G网络建设加速推进（更新）",
|
||
"categoryId": 9,
|
||
"categoryName": "AI",
|
||
"publishTime": "2024-01-16 08:00:00",
|
||
"author": "王五",
|
||
"source": "36kr",
|
||
"content": "完整的新闻正文内容...",
|
||
"createdAt": "2024-01-16 09:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.5 删除新闻
|
||
|
||
**接口地址**: `DELETE /api/v1/news/{id}`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 新闻ID |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.6 批量删除新闻
|
||
|
||
**接口地址**: `DELETE /api/v1/news/batch`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| - | Array[Long] | 是 | 新闻ID列表 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
[1, 2, 3, 4, 5]
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.7 搜索新闻
|
||
|
||
**接口地址**: `GET /api/v1/news/search`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**查询参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| keyword | String | 是 | - | 搜索关键词 |
|
||
| page | Integer | 否 | 1 | 页码 |
|
||
| size | Integer | 否 | 20 | 每页大小 |
|
||
|
||
**请求示例**:
|
||
```
|
||
GET /api/v1/news/search?keyword=AI&page=1&size=10
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 1,
|
||
"url": "https://news.example.com/tech/001",
|
||
"title": "AI技术突破：新一代大语言模型发布",
|
||
"categoryId": 9,
|
||
"categoryName": "AI",
|
||
"publishTime": "2024-01-15 10:30:00",
|
||
"author": "张三",
|
||
"source": "网易",
|
||
"content": "正文内容...",
|
||
"createdAt": "2024-01-15 11:00:00"
|
||
}
|
||
],
|
||
"total": 23,
|
||
"page": 1,
|
||
"size": 10,
|
||
"pages": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.8 按分类获取新闻
|
||
|
||
**接口地址**: `GET /api/v1/news/category/{categoryId}`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| categoryId | Integer | 是 | 分类ID |
|
||
|
||
**查询参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| page | Integer | 否 | 1 | 页码 |
|
||
| size | Integer | 否 | 20 | 每页大小 |
|
||
|
||
**请求示例**:
|
||
```
|
||
GET /api/v1/news/category/4?page=1&size=10
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 2,
|
||
"url": "https://news.example.com/tech/002",
|
||
"title": "量子计算取得重大进展",
|
||
"categoryId": 4,
|
||
"categoryName": "科技",
|
||
"publishTime": "2024-01-15 09:00:00",
|
||
"author": "李四",
|
||
"source": "36kr",
|
||
"content": "正文内容...",
|
||
"createdAt": "2024-01-15 10:00:00"
|
||
}
|
||
],
|
||
"total": 89,
|
||
"page": 1,
|
||
"size": 10,
|
||
"pages": 9
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.9 获取最新新闻
|
||
|
||
**接口地址**: `GET /api/v1/news/latest`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**查询参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| page | Integer | 否 | 1 | 页码 |
|
||
| size | Integer | 否 | 20 | 每页大小 |
|
||
|
||
**请求示例**:
|
||
```
|
||
GET /api/v1/news/latest?page=1&size=10
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 10,
|
||
"url": "https://news.example.com/latest/001",
|
||
"title": "今日要闻汇总",
|
||
"categoryId": null,
|
||
"categoryName": null,
|
||
"publishTime": "2024-01-16 12:00:00",
|
||
"author": "编辑",
|
||
"source": "网易",
|
||
"content": "正文内容...",
|
||
"createdAt": "2024-01-16 12:30:00"
|
||
}
|
||
],
|
||
"total": 1234,
|
||
"page": 1,
|
||
"size": 10,
|
||
"pages": 124
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3.10 获取新闻统计数据
|
||
|
||
**接口地址**: `GET /api/v1/news/statistics`
|
||
|
||
**是否需要认证**: 否
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"totalNews": 5678,
|
||
"categoryStats": {
|
||
"娱乐": 1234,
|
||
"体育": 890,
|
||
"财经": 756,
|
||
"科技": 1523,
|
||
"军事": 456,
|
||
"汽车": 234,
|
||
"政务": 123,
|
||
"健康": 345,
|
||
"AI": 117
|
||
},
|
||
"sourceStats": {
|
||
"网易": 3456,
|
||
"36kr": 2222
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 四、数据模型
|
||
|
||
## 4.1 RestBean<T>
|
||
|
||
通用响应封装类。
|
||
|
||
```typescript
|
||
{
|
||
code: number, // 状态码
|
||
message: string, // 提示消息
|
||
data: T // 返回数据
|
||
}
|
||
```
|
||
|
||
## 4.2 PageResult<T>
|
||
|
||
分页结果封装类。
|
||
|
||
```typescript
|
||
{
|
||
records: T[], // 数据列表
|
||
total: number, // 总记录数
|
||
page: number, // 当前页
|
||
size: number, // 每页大小
|
||
pages: number // 总页数
|
||
}
|
||
```
|
||
|
||
## 4.3 UserDto
|
||
|
||
用户数据传输对象。
|
||
|
||
```typescript
|
||
{
|
||
id?: number, // 用户ID
|
||
username: string, // 用户名
|
||
email: string, // 邮箱
|
||
password?: string, // 密码（注册/登录时需要）
|
||
status?: number, // 状态（1=正常 0=禁用）
|
||
createdAt?: string, // 创建时间
|
||
updatedAt?: string // 更新时间
|
||
}
|
||
```
|
||
|
||
## 4.4 CategoryDto
|
||
|
||
分类数据传输对象。
|
||
|
||
```typescript
|
||
{
|
||
id: number, // 分类ID
|
||
name: string, // 分类名称
|
||
newsCount?: number // 该分类下的新闻数量
|
||
}
|
||
```
|
||
|
||
## 4.5 NewsDto
|
||
|
||
新闻数据传输对象。
|
||
|
||
```typescript
|
||
{
|
||
id: number, // 新闻ID
|
||
url: string, // 新闻URL
|
||
title: string, // 标题
|
||
categoryId: number, // 分类ID
|
||
categoryName: string, // 分类名称
|
||
publishTime: string, // 发布时间
|
||
author: string, // 作者
|
||
source: string, // 来源（网易/36kr）
|
||
content: string, // 正文内容
|
||
createdAt: string // 入库时间
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 五、常见错误
|
||
|
||
## 5.1 参数校验错误
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "分类名称不能为空",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 5.2 资源不存在
|
||
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "数据不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 5.3 服务器错误
|
||
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "服务端错误",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 六、接口调试
|
||
|
||
## 6.1 Swagger UI
|
||
|
||
启动项目后访问：`http://localhost:8080/swagger-ui.html`
|
||
|
||
在 Swagger UI 中可以直接测试所有接口。
|
||
|
||
## 6.2 cURL 示例
|
||
|
||
### 用户注册
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/user/register \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"username":"test","password":"123456","email":"test@example.com"}'
|
||
```
|
||
|
||
### 用户登录
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/user/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"username":"test","password":"123456"}'
|
||
```
|
||
|
||
### 获取新闻列表
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/v1/news/list?page=1&size=10"
|
||
```
|
||
|
||
### 创建新闻
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/news \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"url":"https://example.com/news/001",
|
||
"title":"测试新闻",
|
||
"categoryId":4,
|
||
"content":"这是新闻正文内容"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
# 附录
|
||
|
||
## 初始分类数据
|
||
|
||
| ID | 名称 |
|
||
|----|------|
|
||
| 1 | 娱乐 |
|
||
| 2 | 体育 |
|
||
| 3 | 财经 |
|
||
| 4 | 科技 |
|
||
| 5 | 军事 |
|
||
| 6 | 汽车 |
|
||
| 7 | 政务 |
|
||
| 8 | 健康 |
|
||
| 9 | AI |
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| v1.0 | 2024-01-16 | 初始版本 |
|