# 新闻分类器后端 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 | 初始版本 |