字典管理系统API接口文档

概述

字典管理系统提供字典类型和字典项的管理功能，支持树形结构展示、增删改查、批量操作等功能。

基础信息

基础路径: /api/v1
认证方式: Bearer Token
响应格式: JSON

通用响应格式

{
  "code": "000000",
  "message": "成功",
  "data": {},
  "timestamp": "2026-02-22T10:00:00.000Z"
}

错误码说明

000000: 成功
100001: 参数验证失败
200002: 令牌失效
300001: 资源不存在
400001: 业务逻辑错误
500001: 服务器内部错误

字典类型管理接口

1. 获取字典类型树形结构

获取所有字典类型的树形结构，用于左侧树形展示。

接口地址: GET /api/v1/dict/category/tree

请求头:

Authorization: Bearer {token}

响应示例:

{
  "code": "000000",
  "message": "成功",
  "data": [
    {
      "category_id": "file_type",
      "category_name": "文件类型枚举定义",
      "parent_field": "0",
      "children": []
    },
    {
      "category_id": "professional_type",
      "category_name": "专业类型枚举定义",
      "parent_field": "0",
      "children": []
    }
  ],
  "timestamp": "2026-02-22T10:00:00.000Z"
}

2. 获取字典类型列表（分页）

获取字典类型列表，支持关键字搜索和分页。

接口地址: POST /api/v1/dict/category/list

请求头:

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

请求参数:

{
  "keyword": "文件",
  "page": 1,
  "page_size": 10
}

参数说明: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | keyword | string | 否 | 关键字搜索（搜索类型名称和编号） | | page | int | 是 | 页码，从1开始 | | page_size | int | 是 | 每页数量，1-100 |

响应示例:

{
  "code": "000000",
  "message": "成功",
  "data": {
    "list": [
      {
        "category_id": "file_type",
        "category_no": "file_type",
        "category_name": "文件类型枚举定义",
        "category_desc": "文件类型枚举定义",
        "parent_field": "0",
        "category_level": "1",
        "del_flag": "0",
        "created_by": "user_id",
        "created_time": "2026-02-22T10:00:00",
        "updated_by": "user_id",
        "updated_time": "2026-02-22T10:00:00",
        "created_by_name": "管理员",
        "updated_by_name": "管理员"
      }
    ],
    "total": 8,
    "page": 1,
    "page_size": 10
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}

3. 获取字典类型详情

根据ID获取字典类型详细信息。

接口地址: GET /api/v1/dict/category/{category_id}

请求头:

Authorization: Bearer {token}

路径参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | category_id | string | 是 | 字典类型ID |

响应示例:

{
  "code": "000000",
  "message": "成功",
  "data": {
    "category_id": "file_type",
    "category_no": "file_type",
    "category_name": "文件类型枚举定义",
    "category_desc": "文件类型枚举定义",
    "parent_field": "0",
    "category_level": "1",
    "del_flag": "0",
    "created_by": "user_id",
    "created_time": "2026-02-22T10:00:00",
    "updated_by": "user_id",
    "updated_time": "2026-02-22T10:00:00",
    "created_by_name": "管理员",
    "updated_by_name": "管理员"
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}

4. 创建字典类型

创建新的字典类型。

接口地址: POST /api/v1/dict/category

请求头:

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

请求参数:

{
  "category_no": "custom_type",
  "category_name": "自定义类型",
  "category_desc": "自定义类型说明",
  "parent_field": "0",
  "category_level": "1"
}

参数说明: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | category_no | string | 否 | 字典类型编号，最大512字符 | | category_name | string | 是 | 字典类型名称，最大512字符 | | category_desc | string | 否 | 字典类型备注，最大512字符 | | parent_field | string | 否 | 父节点ID，默认"0"表示根节点 | | category_level | string | 否 | 字典层级 |

响应示例:

{
  "code": "000000",
  "message": "字典类型创建成功",
  "data": {
    "category_id": "uuid-generated-id"
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}

5. 更新字典类型

更新字典类型信息。

接口地址: PUT /api/v1/dict/category/{category_id}

请求头:

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

路径参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | category_id | string | 是 | 字典类型ID |

请求参数:

{
  "category_name": "更新后的类型名称",
  "category_desc": "更新后的说明"
}

参数说明: 所有字段均为可选，只更新提供的字段

响应示例:

{
  "code": "000000",
  "message": "字典类型更新成功",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}

6. 删除字典类型

删除字典类型（逻辑删除）。

接口地址: DELETE /api/v1/dict/category/{category_id}

请求头:

Authorization: Bearer {token}

路径参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | category_id | string | 是 | 字典类型ID |

响应示例:

{
  "code": "000000",
  "message": "字典类型删除成功",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}

注意事项:

如果字典类型下有子节点，无法删除
如果字典类型下有字典项，无法删除

字典项管理接口

1. 获取字典项列表（分页）

获取字典项列表，支持按字典类型、关键字、启用状态筛选。

接口地址: POST /api/v1/dict/item/list

请求头:

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

请求参数:

{
  "category_id": "file_type",
  "keyword": "标准",
  "enable_flag": "1",
  "page": 1,
  "page_size": 10
}

参数说明: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | category_id | string | 否 | 字典类型ID | | keyword | string | 否 | 关键字搜索（搜索名称、值、备注） | | enable_flag | string | 否 | 启用状态：1启用，0禁用 | | page | int | 是 | 页码，从1开始 | | page_size | int | 是 | 每页数量，1-100 |

响应示例:

{
  "code": "000000",
  "message": "成功",
  "data": {
    "list": [
      {
        "dict_id": 1,
        "dict_name": "国家标准",
        "dict_value": "GB",
        "dict_desc": "National Standard",
        "category_id": "file_type",
        "category_name": "文件类型枚举定义",
        "enable_flag": "1",
        "del_flag": "0",
        "sort": 1,
        "created_by": "user_id",
        "created_time": "2026-02-22T10:00:00",
        "updated_by": "user_id",
        "updated_time": "2026-02-22T10:00:00",
        "created_by_name": "管理员",
        "updated_by_name": "管理员"
      }
    ],
    "total": 12,
    "page": 1,
    "page_size": 10
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}

2. 获取字典项详情

根据ID获取字典项详细信息。

接口地址: GET /api/v1/dict/item/{dict_id}

请求头:

Authorization: Bearer {token}

路径参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | dict_id | int | 是 | 字典项ID |

响应示例:

{
  "code": "000000",
  "message": "成功",
  "data": {
    "dict_id": 1,
    "dict_name": "国家标准",
    "dict_value": "GB",
    "dict_desc": "National Standard",
    "category_id": "file_type",
    "category_name": "文件类型枚举定义",
    "enable_flag": "1",
    "del_flag": "0",
    "sort": 1,
    "created_by": "user_id",
    "created_time": "2026-02-22T10:00:00",
    "updated_by": "user_id",
    "updated_time": "2026-02-22T10:00:00",
    "created_by_name": "管理员",
    "updated_by_name": "管理员"
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}

3. 创建字典项

创建新的字典项。

接口地址: POST /api/v1/dict/item

请求头:

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

请求参数:

{
  "dict_name": "自定义项",
  "dict_value": "CUSTOM",
  "dict_desc": "Custom Item",
  "category_id": "file_type",
  "enable_flag": "1",
  "sort": 100
}

参数说明: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | dict_name | string | 是 | 字典名称，最大512字符 | | dict_value | string | 是 | 字典值，最大512字符 | | dict_desc | string | 否 | 字典备注，最大512字符 | | category_id | string | 是 | 字典类型ID | | enable_flag | string | 否 | 启用标志：1启用，0禁用，默认1 | | sort | int | 否 | 排序值 |

响应示例:

{
  "code": "000000",
  "message": "字典项创建成功",
  "data": {
    "dict_id": 100
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}

4. 更新字典项

更新字典项信息。

接口地址: PUT /api/v1/dict/item/{dict_id}

请求头:

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

路径参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | dict_id | int | 是 | 字典项ID |

请求参数:

{
  "dict_name": "更新后的名称",
  "dict_desc": "更新后的备注",
  "sort": 50
}

参数说明: 所有字段均为可选，只更新提供的字段

响应示例:

{
  "code": "000000",
  "message": "字典项更新成功",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}

5. 删除字典项

删除字典项（逻辑删除）。

接口地址: DELETE /api/v1/dict/item/{dict_id}

请求头:

Authorization: Bearer {token}

路径参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | dict_id | int | 是 | 字典项ID |

响应示例:

{
  "code": "000000",
  "message": "字典项删除成功",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}

6. 批量删除字典项

批量删除多个字典项（逻辑删除）。

接口地址: POST /api/v1/dict/item/batch-delete

请求头:

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

请求参数:

{
  "dict_ids": [1, 2, 3, 4, 5]
}

参数说明: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | dict_ids | array | 是 | 字典项ID列表 |

响应示例:

{
  "code": "000000",
  "message": "成功删除5个字典项",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}

7. 切换字典项启用状态

启用或禁用字典项。

接口地址: PUT /api/v1/dict/item/{dict_id}/toggle-status?enable_flag={flag}

请求头:

Authorization: Bearer {token}

路径参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | dict_id | int | 是 | 字典项ID |

查询参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | enable_flag | string | 是 | 启用标志：1启用，0禁用 |

响应示例:

{
  "code": "000000",
  "message": "字典项启用成功",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}

使用示例

Python示例

import requests

# 基础配置
BASE_URL = "http://localhost:8000/api/v1"
TOKEN = "your_access_token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# 1. 获取字典类型树
response = requests.get(f"{BASE_URL}/dict/category/tree", headers=headers)
print(response.json())

# 2. 获取字典项列表
data = {
    "category_id": "file_type",
    "page": 1,
    "page_size": 10
}
response = requests.post(f"{BASE_URL}/dict/item/list", headers=headers, json=data)
print(response.json())

# 3. 创建字典项
data = {
    "dict_name": "测试项",
    "dict_value": "TEST",
    "dict_desc": "Test Item",
    "category_id": "file_type",
    "enable_flag": "1",
    "sort": 100
}
response = requests.post(f"{BASE_URL}/dict/item", headers=headers, json=data)
print(response.json())

JavaScript示例

const BASE_URL = "http://localhost:8000/api/v1";
const TOKEN = "your_access_token";

const headers = {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json"
};

// 1. 获取字典类型树
fetch(`${BASE_URL}/dict/category/tree`, { headers })
    .then(res => res.json())
    .then(data => console.log(data));

// 2. 获取字典项列表
fetch(`${BASE_URL}/dict/item/list`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        category_id: "file_type",
        page: 1,
        page_size: 10
    })
})
    .then(res => res.json())
    .then(data => console.log(data));

// 3. 创建字典项
fetch(`${BASE_URL}/dict/item`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        dict_name: "测试项",
        dict_value: "TEST",
        dict_desc: "Test Item",
        category_id: "file_type",
        enable_flag: "1",
        sort: 100
    })
})
    .then(res => res.json())
    .then(data => console.log(data));

注意事项

所有接口都需要Bearer Token认证
字典类型ID使用字符串类型，字典项ID使用整数类型
删除操作均为逻辑删除，不会物理删除数据
创建人、修改人、创建时间、修改时间由系统自动维护
字典项按sort字段升序排序，sort相同时按dict_id升序
字段长度限制需严格遵守，避免数据库异常

字典管理API接口.md 14 KB 永久链接 文件历史 原始文件

字典管理系统API接口文档

概述

基础信息

通用响应格式

错误码说明

字典类型管理接口

1. 获取字典类型树形结构

2. 获取字典类型列表（分页）

3. 获取字典类型详情

4. 创建字典类型

5. 更新字典类型

6. 删除字典类型

字典项管理接口

1. 获取字典项列表（分页）

2. 获取字典项详情

3. 创建字典项

4. 更新字典项

5. 删除字典项

6. 批量删除字典项

7. 切换字典项启用状态

使用示例

Python示例

JavaScript示例

注意事项

字典管理API接口.md 14 KB

永久链接文件历史原始文件