分类接口

分类管理相关的 API 接口文档。

获取分类列表

接口信息

GET /api/categories
Authorization: Bearer {token}

请求参数

参数	类型	必填	说明
parent_id	integer	否	父分类ID，0为顶级分类
site_id	integer	否	站点ID
status	integer	否	状态（0禁用/1启用）
tree	boolean	否	是否返回树形结构

响应示例

平铺列表

{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "技术博客",
      "alias": "tech",
      "parent_id": 0,
      "icon": "fa fa-code",
      "cover": "https://example.com/covers/tech.jpg",
      "description": "技术相关文章",
      "seo_title": "技术博客",
      "seo_keywords": "技术,编程,开发",
      "seo_description": "最新技术文章分享",
      "sort": 1,
      "status": 1,
      "article_count": 128,
      "create_time": "2024-01-01 00:00:00"
    }
  ]
}

树形结构（tree=true）

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "技术博客",
      "alias": "tech",
      "children": [
        {
          "id": 2,
          "name": "前端开发",
          "alias": "frontend",
          "children": []
        },
        {
          "id": 3,
          "name": "后端开发",
          "alias": "backend",
          "children": []
        }
      ]
    }
  ]
}

获取分类详情

接口信息

GET /api/categories/{id}
Authorization: Bearer {token}

响应示例

{
  "code": 200,
  "data": {
    "id": 1,
    "name": "技术博客",
    "alias": "tech",
    "parent_id": 0,
    "parent": null,
    "icon": "fa fa-code",
    "cover": "https://example.com/covers/tech.jpg",
    "description": "技术相关文章",
    "seo_title": "技术博客 - CarefreeCMS",
    "seo_keywords": "技术,编程,开发",
    "seo_description": "最新技术文章分享",
    "template": "default/category.html",
    "is_nav": 1,
    "external_link": "",
    "sort": 1,
    "status": 1,
    "article_count": 128,
    "create_time": "2024-01-01 00:00:00",
    "update_time": "2024-01-15 10:30:00"
  }
}

创建分类

接口信息

POST /api/categories
Authorization: Bearer {token}
Content-Type: application/json

请求参数

参数	类型	必填	说明
name	string	是	分类名称
alias	string	否	英文别名，留空自动生成
parent_id	integer	否	父分类ID，默认0
icon	string	否	图标
cover	string	否	封面图片URL
description	string	否	描述
seo_title	string	否	SEO标题
seo_keywords	string	否	SEO关键词
seo_description	string	否	SEO描述
template	string	否	模板文件
is_nav	integer	否	是否显示在导航（0/1）
external_link	string	否	外部链接
sort	integer	否	排序，默认0
status	integer	否	状态（0/1），默认1

请求示例

{
  "name": "Vue.js 教程",
  "alias": "vue-tutorial",
  "parent_id": 2,
  "icon": "fa fa-vuejs",
  "description": "Vue.js 框架学习教程",
  "seo_title": "Vue.js 教程 - 前端开发",
  "seo_keywords": "Vue.js,Vue3,教程",
  "seo_description": "从入门到精通的 Vue.js 学习教程",
  "is_nav": 1,
  "sort": 10,
  "status": 1
}

响应示例

{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 10,
    "name": "Vue.js 教程",
    "alias": "vue-tutorial",
    "create_time": "2024-01-15 14:30:00"
  }
}

更新分类

接口信息

PUT /api/categories/{id}
Authorization: Bearer {token}
Content-Type: application/json

请求参数

与创建分类相同，所有字段可选。

响应示例

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 10,
    "name": "Vue.js 完整教程",
    "update_time": "2024-01-15 15:20:00"
  }
}

删除分类

接口信息

DELETE /api/categories/{id}
Authorization: Bearer {token}

请求参数

参数	类型	必填	说明
cascade	boolean	否	是否级联删除子分类，默认false
article_action	string	否	文章处理方式：move(移动)或delete(删除)
target_category_id	integer	否	目标分类ID（article_action=move时必填）

响应示例

{
  "code": 200,
  "message": "删除成功"
}

移动分类

接口信息

POST /api/categories/{id}/move
Authorization: Bearer {token}
Content-Type: application/json

请求参数

参数	类型	必填	说明
parent_id	integer	是	新的父分类ID
sort	integer	否	新的排序值

请求示例

{
  "parent_id": 5,
  "sort": 10
}

响应示例

{
  "code": 200,
  "message": "移动成功"
}

批量操作

批量更新状态

PUT /api/categories/batch
Authorization: Bearer {token}
Content-Type: application/json

请求示例

{
  "ids": [1, 2, 3],
  "data": {
    "status": 1
  }
}

批量删除

DELETE /api/categories/batch
Authorization: Bearer {token}
Content-Type: application/json

请求示例

{
  "ids": [1, 2, 3],
  "cascade": false,
  "article_action": "move",
  "target_category_id": 10
}

获取分类文章

接口信息

GET /api/categories/{id}/articles
Authorization: Bearer {token}

请求参数

参数	类型	必填	说明
page	integer	否	页码，默认1
page_size	integer	否	每页数量，默认20
sort	string	否	排序字段
order	string	否	排序方式（asc/desc）

响应示例

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": 1,
        "title": "Vue 3 入门教程",
        "summary": "本文介绍 Vue 3 的基础知识...",
        "cover": "https://example.com/covers/vue3.jpg",
        "view_count": 1234,
        "create_time": "2024-01-15 10:00:00"
      }
    ],
    "total": 128,
    "page": 1,
    "page_size": 20
  }
}

代码示例

JavaScript

import axios from 'axios'

// 获取分类树
const getCategoryTree = async () => {
  const res = await axios.get('/api/categories', {
    params: { tree: true },
    headers: {
      Authorization: `Bearer ${localStorage.getItem('token')}`
    }
  })
  return res.data.data
}

// 创建分类
const createCategory = async (data) => {
  const res = await axios.post('/api/categories', data, {
    headers: {
      Authorization: `Bearer ${localStorage.getItem('token')}`
    }
  })
  return res.data
}

// 更新分类
const updateCategory = async (id, data) => {
  const res = await axios.put(`/api/categories/${id}`, data, {
    headers: {
      Authorization: `Bearer ${localStorage.getItem('token')}`
    }
  })
  return res.data
}

// 删除分类
const deleteCategory = async (id) => {
  const res = await axios.delete(`/api/categories/${id}`, {
    headers: {
      Authorization: `Bearer ${localStorage.getItem('token')}`
    }
  })
  return res.data
}

PHP

<?php
$token = 'YOUR_JWT_TOKEN';

// 获取分类列表
$url = 'http://your-domain.com/api/categories?tree=true';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
]);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);

// 创建分类
$url = 'http://your-domain.com/api/categories';
$data = [
    'name' => 'Vue.js 教程',
    'alias' => 'vue-tutorial',
    'parent_id' => 2,
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token,
]);
$response = curl_exec($ch);
curl_close($ch);

错误处理

常见错误

400 参数错误

{
  "code": 400,
  "message": "分类名称不能为空"
}

404 分类不存在

{
  "code": 404,
  "message": "分类不存在"
}

422 验证失败

{
  "code": 422,
  "message": "数据验证失败",
  "errors": {
    "name": ["分类名称不能为空"],
    "alias": ["别名格式不正确"]
  }
}

409 冲突

{
  "code": 409,
  "message": "分类别名已存在"
}