643 lines
12 KiB
Go
643 lines
12 KiB
Go
# CMS API 接口文档
|
||
|
||
## 概述
|
||
|
||
本文档描述了企业级官网+CMS内容管理系统的RESTful API接口规范，基于GoFrame框架开发。
|
||
|
||
### 基本信息
|
||
|
||
- **服务地址**: http://localhost:10861
|
||
- **API版本**: v1
|
||
- **数据格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
- **开发状态**: 已完成核心功能开发和测试
|
||
- **最后更新**: 2024-01-15
|
||
|
||
### 通用响应格式
|
||
|
||
所有API接口均返回统一的JSON格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 状态码说明
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 请求成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未授权访问 |
|
||
| 403 | 权限不足 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
### 分页响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"list": [],
|
||
"total": 100,
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total_pages": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
## 认证机制
|
||
|
||
### JWT Token认证
|
||
|
||
- 登录成功后获取token
|
||
- 请求头中携带：`Authorization: Bearer {token}`
|
||
- Token有效期：2小时
|
||
|
||
## API接口
|
||
|
||
### 1. 健康检查
|
||
|
||
#### 1.1 服务状态检查
|
||
|
||
**接口地址**: `GET /health`
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"message": "CMS API服务运行正常"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 用户管理
|
||
|
||
### 2.1 用户登录
|
||
|
||
**接口地址**: `POST /api/v1/user/login`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"account": "admin",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| account | string | 是 | 用户账号 |
|
||
| password | string | 是 | 登录密码 |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登录成功",
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"expires_in": 7200,
|
||
"user": {
|
||
"id": 1,
|
||
"account": "admin",
|
||
"nick_name": "管理员",
|
||
"email": "admin@example.com",
|
||
"avatar": "",
|
||
"balance": 0,
|
||
"role_id": 1,
|
||
"status": 0
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 用户注册
|
||
|
||
**接口地址**: `POST /api/v1/user/register`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"account": "testuser",
|
||
"nick_name": "测试用户",
|
||
"email": "test@example.com",
|
||
"password": "123456",
|
||
"avatar": "",
|
||
"role_id": 2
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| account | string | 是 | 用户账号(3-32位) |
|
||
| nick_name | string | 是 | 用户昵称(2-64位) |
|
||
| email | string | 是 | 邮箱地址 |
|
||
| password | string | 是 | 登录密码(6-32位) |
|
||
| avatar | string | 否 | 头像URL |
|
||
| role_id | int | 否 | 角色ID |
|
||
|
||
### 2.3 获取用户信息
|
||
|
||
**接口地址**: `GET /api/v1/user/profile`
|
||
|
||
**请求头**: `Authorization: Bearer {token}`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"id": 1,
|
||
"account": "admin",
|
||
"nick_name": "管理员",
|
||
"email": "admin@example.com",
|
||
"avatar": "",
|
||
"balance": 0,
|
||
"role_id": 1,
|
||
"status": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.4 更新用户信息
|
||
|
||
**接口地址**: `PUT /api/v1/user/profile`
|
||
|
||
**请求头**: `Authorization: Bearer {token}`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"nick_name": "新昵称",
|
||
"email": "new@example.com",
|
||
"avatar": "http://example.com/avatar.jpg"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 管理员接口
|
||
|
||
### 3.1 管理员登录
|
||
|
||
**接口地址**: `POST /api/v1/admin/login`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"account": "admin",
|
||
"password": "admin123"
|
||
}
|
||
```
|
||
|
||
### 3.2 用户管理
|
||
|
||
#### 3.2.1 获取用户列表
|
||
|
||
**接口地址**: `GET /api/v1/admin/users`
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认10 |
|
||
| keyword | string | 否 | 搜索关键词 |
|
||
| status | int | 否 | 用户状态 |
|
||
| role_id | int | 否 | 角色ID |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"account": "admin",
|
||
"nick_name": "管理员",
|
||
"email": "admin@example.com",
|
||
"status": 0,
|
||
"created_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total_pages": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3.2.2 创建用户
|
||
|
||
**接口地址**: `POST /api/v1/admin/users`
|
||
|
||
#### 3.2.3 获取用户详情
|
||
|
||
**接口地址**: `GET /api/v1/admin/users/{id}`
|
||
|
||
#### 3.2.4 更新用户
|
||
|
||
**接口地址**: `PUT /api/v1/admin/users/{id}`
|
||
|
||
#### 3.2.5 删除用户
|
||
|
||
**接口地址**: `DELETE /api/v1/admin/users/{id}`
|
||
|
||
---
|
||
|
||
## 4. 文章管理
|
||
|
||
### 4.1 公开接口
|
||
|
||
#### 4.1.1 获取文章列表
|
||
|
||
**接口地址**: `GET /api/v1/public/articles`
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认10 |
|
||
| keyword | string | 否 | 搜索关键词 |
|
||
| category_id | int | 否 | 分类ID |
|
||
| is_featured | int | 否 | 是否推荐 |
|
||
| is_top | int | 否 | 是否置顶 |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"title": "文章标题",
|
||
"summary": "文章摘要",
|
||
"cover_image": "封面图片URL",
|
||
"author": "作者",
|
||
"view_count": 100,
|
||
"like_count": 10,
|
||
"is_featured": 1,
|
||
"is_top": 0,
|
||
"published_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total_pages": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.1.2 获取文章详情
|
||
|
||
**接口地址**: `GET /api/v1/public/articles/{id}`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"id": 1,
|
||
"title": "文章标题",
|
||
"content": "文章内容",
|
||
"summary": "文章摘要",
|
||
"cover_image": "封面图片URL",
|
||
"author": "作者",
|
||
"view_count": 100,
|
||
"like_count": 10,
|
||
"tags": "标签1,标签2",
|
||
"is_featured": 1,
|
||
"is_top": 0,
|
||
"published_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.2 管理接口
|
||
|
||
#### 4.2.1 获取文章列表
|
||
|
||
**接口地址**: `GET /api/v1/admin/articles`
|
||
|
||
#### 4.2.2 创建文章
|
||
|
||
**接口地址**: `POST /api/v1/admin/articles`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"title": "文章标题",
|
||
"content": "文章内容",
|
||
"summary": "文章摘要",
|
||
"cover_image": "封面图片URL",
|
||
"category_id": 1,
|
||
"tags": "标签1,标签2",
|
||
"is_published": 1,
|
||
"is_featured": 0,
|
||
"is_top": 0,
|
||
"published_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
```
|
||
|
||
#### 4.2.3 更新文章
|
||
|
||
**接口地址**: `PUT /api/v1/admin/articles/{id}`
|
||
|
||
#### 4.2.4 删除文章
|
||
|
||
**接口地址**: `DELETE /api/v1/admin/articles/{id}`
|
||
|
||
---
|
||
|
||
## 5. 新闻管理
|
||
|
||
### 5.1 公开接口
|
||
|
||
#### 5.1.1 获取新闻列表
|
||
|
||
**接口地址**: `GET /api/v1/public/news`
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认10 |
|
||
| keyword | string | 否 | 搜索关键词 |
|
||
| category | string | 否 | 新闻分类 |
|
||
| is_featured | int | 否 | 是否推荐 |
|
||
|
||
#### 5.1.2 获取新闻详情
|
||
|
||
**接口地址**: `GET /api/v1/public/news/{id}`
|
||
|
||
### 5.2 管理接口
|
||
|
||
#### 5.2.1 获取新闻列表
|
||
|
||
**接口地址**: `GET /api/v1/admin/news`
|
||
|
||
#### 5.2.2 创建新闻
|
||
|
||
**接口地址**: `POST /api/v1/admin/news`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"title": "新闻标题",
|
||
"content": "新闻内容",
|
||
"summary": "新闻摘要",
|
||
"cover_image": "封面图片URL",
|
||
"category": "新闻分类",
|
||
"source": "新闻来源",
|
||
"author": "作者",
|
||
"is_published": 1,
|
||
"is_featured": 0,
|
||
"is_top": 0,
|
||
"published_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
```
|
||
|
||
#### 5.2.3 更新新闻
|
||
|
||
**接口地址**: `PUT /api/v1/admin/news/{id}`
|
||
|
||
#### 5.2.4 删除新闻
|
||
|
||
**接口地址**: `DELETE /api/v1/admin/news/{id}`
|
||
|
||
---
|
||
|
||
## 6. 附件管理
|
||
|
||
### 6.1 获取附件列表
|
||
|
||
**接口地址**: `GET /api/v1/admin/attachments`
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认10 |
|
||
| file_type | string | 否 | 文件类型 |
|
||
| keyword | string | 否 | 搜索关键词 |
|
||
|
||
### 6.2 上传附件
|
||
|
||
**接口地址**: `POST /api/v1/admin/attachments/upload`
|
||
|
||
**请求类型**: `multipart/form-data`
|
||
|
||
**请求参数**:
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| file | file | 是 | 上传的文件 |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "上传成功",
|
||
"data": {
|
||
"id": 1,
|
||
"original_name": "example.jpg",
|
||
"file_name": "20240101_example.jpg",
|
||
"file_path": "/uploads/20240101_example.jpg",
|
||
"file_url": "http://localhost:10861/uploads/20240101_example.jpg",
|
||
"file_size": 1024,
|
||
"file_type": "image/jpeg",
|
||
"file_ext": "jpg"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.3 获取附件详情
|
||
|
||
**接口地址**: `GET /api/v1/admin/attachments/{id}`
|
||
|
||
### 6.4 删除附件
|
||
|
||
**接口地址**: `DELETE /api/v1/admin/attachments/{id}`
|
||
|
||
---
|
||
|
||
## 7. 系统配置
|
||
|
||
### 7.1 获取公开配置
|
||
|
||
**接口地址**: `GET /api/v1/public/configs`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"config_key": "site_name",
|
||
"config_value": "CMS系统",
|
||
"config_desc": "网站名称",
|
||
"group_name": "基础配置"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 7.2 获取配置列表
|
||
|
||
**接口地址**: `GET /api/v1/admin/configs`
|
||
|
||
### 7.3 更新配置
|
||
|
||
**接口地址**: `PUT /api/v1/admin/configs/{id}`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"config_value": "新的配置值",
|
||
"config_desc": "配置描述"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 错误码说明
|
||
|
||
### 8.1 通用错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未授权访问 |
|
||
| 403 | 权限不足 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
### 8.2 业务错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1001 | 用户名或密码错误 |
|
||
| 1002 | 账号已存在 |
|
||
| 1003 | 邮箱已存在 |
|
||
| 1004 | 用户不存在 |
|
||
| 1005 | 账号已被冻结 |
|
||
| 1006 | 账号已被封号 |
|
||
| 1007 | 账号已注销 |
|
||
| 2001 | 文章不存在 |
|
||
| 2002 | 文章已发布，无法删除 |
|
||
| 3001 | 新闻不存在 |
|
||
| 4001 | 附件不存在 |
|
||
| 4002 | 文件上传失败 |
|
||
| 4003 | 文件类型不支持 |
|
||
| 4004 | 文件大小超出限制 |
|
||
| 5001 | 配置不存在 |
|
||
|
||
---
|
||
|
||
## 9. 开发说明
|
||
|
||
### 9.1 环境要求
|
||
|
||
- Go 1.21+
|
||
- MySQL 5.7+
|
||
- Redis 6.0+
|
||
|
||
### 9.2 启动命令
|
||
|
||
```bash
|
||
# 开发环境启动
|
||
gf run main.go
|
||
|
||
# 生产环境启动
|
||
go build -o cms-api main.go
|
||
./cms-api
|
||
```
|
||
|
||
### 9.3 配置文件
|
||
|
||
配置文件位置：`config/config.yaml`
|
||
|
||
主要配置项：
|
||
- 服务端口：10861
|
||
- 数据库连接
|
||
- Redis连接
|
||
- JWT密钥
|
||
- 文件上传配置
|
||
|
||
### 9.4 数据库初始化
|
||
|
||
执行SQL文件：`database_complete.sql`
|
||
|
||
---
|
||
|
||
## 10. 更新日志
|
||
|
||
### v1.0.0 (2024-01-01)
|
||
- ✅ 初始版本发布
|
||
- ✅ 完成用户管理功能
|
||
- ✅ 完成文章管理功能
|
||
- ✅ 完成新闻管理功能
|
||
- ✅ 完成附件管理功能
|
||
- ✅ 完成系统配置功能
|
||
- ✅ 完成管理员认证系统
|
||
- ✅ 完成权限管理功能
|
||
- ✅ 完成合作伙伴管理
|
||
- ✅ 完成联系我们管理
|
||
- ✅ 完成数据库设计和优化
|
||
- ✅ 完成API接口开发和测试
|
||
- ✅ 完成JWT认证中间件
|
||
- ✅ 完成CORS跨域处理
|
||
- ✅ 完成响应统一格式化
|
||
|
||
### 项目完成状态
|
||
- **后端开发**: ✅ 已完成
|
||
- **数据库设计**: ✅ 已完成
|
||
- **API接口**: ✅ 已完成
|
||
- **认证系统**: ✅ 已完成
|
||
- **权限管理**: ✅ 已完成
|
||
- **文档编写**: ✅ 已完成
|
||
- **测试验证**: ✅ 已完成
|
||
- **前端UI设计**: ✅ 已完成 (科技感UI设计方案)
|
||
- **技术实现指南**: ✅ 已完成
|
||
- **项目实施计划**: ✅ 已完成
|
||
|
||
### 前端开发状态
|
||
- **UI设计方案**: ✅ 已完成 - 科技感蓝紫渐变主题
|
||
- **设计原型说明**: ✅ 已完成 - 详细组件规范
|
||
- **技术实现指南**: ✅ 已完成 - Vue3+TailwindCSS实现
|
||
- **项目实施计划**: ✅ 已完成 - 7阶段开发计划
|
||
- **快速开始指南**: ✅ 已完成 - 30分钟快速上手
|
||
- **项目总结报告**: ✅ 已完成 - 完整价值分析
|
||
|
||
### 技术栈整合
|
||
- **后端**: GoFrame + MySQL + Redis + JWT ✅
|
||
- **前端**: Vue3 + TailwindCSS + Ant Design Vue + Pinia ✅
|
||
- **UI风格**: 科技感蓝紫渐变 + 玻璃拟态效果 ✅
|
||
- **动画**: AOS滚动动画 + 自定义CSS动画 ✅
|
||
- **响应式**: 移动端适配 + 断点设计 ✅
|
||
|
||
---
|
||
|
||
## 联系方式
|
||
|
||
如有问题，请联系开发团队。 |