lq/nl_cms-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
nl_cms-api/接口文档.md

643 lines
12 KiB
Go
Raw Permalink Normal View History

第一版完成
2025-07-29 12:45:07 +08:00
# 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动画 ✅
- **响应式**: 移动端适配 + 断点设计 ✅
---
## 联系方式
如有问题，请联系开发团队。
Reference in New Issue Copy Permalink