lq/nl_cms-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
nl_cms-api/接口文档.md
liqi 7fd39fb409 第一版完成
2025-07-29 12:45:07 +08:00

12 KiB
Raw Permalink Blame History

CMS API 接口文档

概述

本文档描述了企业级官网+CMS内容管理系统的RESTful API接口规范，基于GoFrame框架开发。

基本信息

  • 服务地址: http://localhost:10861
  • API版本: v1
  • 数据格式: JSON
  • 字符编码: UTF-8
  • 开发状态: 已完成核心功能开发和测试
  • 最后更新: 2024-01-15

通用响应格式

所有API接口均返回统一的JSON格式：

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

状态码说明

状态码 说明
200 请求成功
400 请求参数错误
401 未授权访问
403 权限不足
404 资源不存在
500 服务器内部错误

分页响应格式

{
  "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

请求参数: 无

响应示例:

{
  "status": "ok",
  "message": "CMS API服务运行正常"
}

2. 用户管理

2.1 用户登录

接口地址: POST /api/v1/user/login

请求参数:

{
  "account": "admin",
  "password": "123456"
}

参数说明:

参数 类型 必填 说明
account string 是 用户账号
password string 是 登录密码

响应示例:

{
  "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

请求参数:

{
  "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}

响应示例:

{
  "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}

请求参数:

{
  "nick_name": "新昵称",
  "email": "new@example.com",
  "avatar": "http://example.com/avatar.jpg"
}

3. 管理员接口

3.1 管理员登录

接口地址: POST /api/v1/admin/login

请求参数:

{
  "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

响应示例:

{
  "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 否 是否置顶

响应示例:

{
  "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}

响应示例:

{
  "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

请求参数:

{
  "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

请求参数:

{
  "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 是 上传的文件

响应示例:

{
  "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

响应示例:

{
  "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}

请求参数:

{
  "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 启动命令

# 开发环境启动
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 View Git Blame Copy Permalink