# 框架介绍

# 概述

DJ-Admin 是一款强大且稳定的 Admin 框架，提供开箱即用的管理系统解决方案。它封装了鉴权、权限管理、动态路由、列显隐可控组件、分页封装、请求拦截、上传下载等常见功能，减少重复开发成本，提高开发效率。

此外，DJ-Admin 的核心优势在于 高度封装的 CRUD 组件，采用 📊 数据驱动 设计，使开发者仅需配置 API 和参数即可快速生成管理页面，确保高效性和稳定性。

# 设计理念

DJ-Admin 旨在降低开发成本，提高代码复用性，并确保系统功能完整性和稳定性。主要特点包括：

基于成熟的 Admin 框架：构建于优秀的 Admin 系统方案，根据业务需求优化。
模块化设计：store、routes、api 等模块独立管理，确保结构清晰。
数据驱动：采用 API 配置化管理 CRUD 组件，减少代码量，提高开发效率。
灵活扩展：框架设计规范、灵活，可根据需求扩展功能。
功能稳定：不仅是效率的提升，更是系统稳定性的保障。

# 基础框架

在市面上众多 Admin 框架中，我们选择了 Vab-Admin-Plus (opens new window) 作为基础框架，并对比了其他优秀的 Admin 解决方案，如 Vue-Element-Admin (opens new window)、Vue-Admin-Better (opens new window)、Vue-Vben-Admin (opens new window)，最终决定基于 Vab-Admin-Plus 进行二次封装和优化，以更好地适配业务需求。

注意：Vab-Admin-Plus 需购买授权，本框架仅供公司内部使用，禁止擅自传播或商用，否则所有法律责任由使用者自行承担，公司以及实际购买者（*建）概不负责。

# 核心功能

DJ-Admin 除继承基础框架的众多插件模块，最核心的设计是围绕 CRUD 组件和数据驱动 进行了深度优化。

# `CRUD` 组件封装

在 element-plus (opens new window) 的基础上，封装了一套功能强大的 CRUD 组件，包括：

表单 （Form）：支持 输入框（Input）、选择器（Select）、开关（Switch） 等常规表单组件。
分页 （Pagination）：支持前端分页、后端分页两种模式。
搜索 （Search）：提供多种搜索方式，如单字段搜索、组合搜索等。
工具类 （Utils）：封装了一些常用的工具函数，简化开发流程。
弹窗表单 （Modal Form）：支持弹窗式表单输入，优化用户体验。
动态表单 （Dynamic Form）：支持根据数据结构自动渲染表单字段。

CRUD 组件采用高度配置化设计，开发者可以通过配置 API 地址、字段映射等方式快速生成管理界面。

# 数据驱动设计

DJ-Admin 采用数据驱动的设计方式，核心思路是通过 API 配置化 控制 CRUD 组件的行为，如：

API 绑定：提供标准的 API 配置格式，使组件能够自动绑定增删改查接口。
字段映射：允许开发者自定义字段名称、数据格式等。
权限控制：基于用户角色动态显示或隐藏 CRUD 操作。

# 代码示例

让我们通过代码直观体验 DJ-Admin 的强大功能，构建一个包含 搜索栏、分页、新增、编辑 和 删除 以及表单验证、按钮权限 的业务页面。

<template>
  <crud v-model="data.form" :config="config" :api="api" :handle="handle" />
</template>

<script setup>
import api from "@/api/business/QA"; // 引入业务 API
import main from "./config.main"; // 引入配置文件
const { proxy } = getCurrentInstance();

const data = reactive({
  form: {} // 表单数据
});

// 创建配置
const config = proxy.$createConfig(main());

// 定义函数
const handle = {
  init() {},
  // 列表数据处理, 灵活的处理不同接口风格的返回数据
  listAfter({ data: { total, data } }) {
    return { total, data };
  }
};
</script>

<style scoped></style>

import createApi from "@/api"; // 引入 API 封装
const { get, post, put, del } = createApi("/permission"); // 创建 API 实例

export default {
  // 业务 API
  // 业务 API 的接口名称需固定, 如: list, add, edit, del
  /** CRUD ---------- */
  list: (data) => get(``, data), // 列表数据
  add: (data) => post(``, data), // 新增数据
  edit: (id, data) => put(`/${id}`, data), // 编辑数据
  del: (id) => del(`/${id}`) // 删除数据
  /** Expand -------- */
};

import { PERMISSION } from "@/utils/pattern"; // 引入工具类中的权限验证规则

export default ({ someFunction }) => ({
  idKey: "id", // 主键字段
  default: {}, // 默认数据
  form: {
    // 定义验证规则
    rules: {
      title: [{}], // 默认空验证可省略多余字段
      name: [{}, { pattern: PERMISSION, message: "请输入正确的角色标识" }] // 自定义验证规则
    }
  },
  items: [
    { hideSearch: true, hideForm: true, field: { prop: "id", label: "ID" } },
    { field: { prop: "title", label: "角色名称" } },
    {
      field: {
        prop: "name",
        label: "角色标识",
        help: "允许输入 2-64 个字符，且必须以字母开头，支持字母数字下划线小数点"
      }
    },
    {
      type: "el-date-picker",
      hideForm: true,
      field: { prop: "created_at", label: "创建时间", minWidth: 180 }
    }
  ],
  menu: [{ type: "add", permission: "role.create" }],
  operate: [{ type: "edit", permission: "role.edit" }]
});

以上代码展示了如何使用 DJ-Admin 的 CRUD 组件，以最少的代码实现完整的业务功能。

后续文档将深入介绍 CRUD 组件的详细配置及更多高级功能。

# ?. why

# `CRUD` 组件的必要性

市面上有许多现成的框架，为什么还需要自定义 CRUD 组件呢？主要原因在于现有框架无法很好地满足实际需求，主要体现在以下几点：

只有基础面板的 Admin 系统： 通常仅提供布局和基础组件，或简单调整了登录页面和菜单栏，缺乏深入的业务逻辑封装。
与后端强耦合的系统： 这类框架对后端接口存在强耦合，必须依赖配套的后端支持。否则，进行框架的修改和适配将变得极其复杂且低效。
类似 Avue 的高级封装框架： 虽然对表格、表单等组件进行了高级封装，但其 API 设计复杂，需要学习大量自定义文档和属性，不仅增加了学习成本，还限制了框架的灵活性，难以实现定制功能。此外，过度设计也会导致 Bug 的产生。

DJ-Admin 的 CRUD 组件旨在解决上述问题。除必要的配置属性外，其他表单、表格相关属性完全与 Element 保持一致，学习成本低。设计上，提供高度灵活性，通过 slot 实现高度自定义，并兼容 Element 自身的 slot，极大提升开发效率。这使得 CRUD 组件在高度集成的同时，仍具备灵活定制能力。

# 不使用 `npm` 包的原因

为什么不将 CRUD 组件封装为 npm 插件包去使用？

开源限制： 将 CRUD 封装为 npm 包意味着需要半开源，无法继续使用公司自建的 GitLab 等私有仓库。
个性化配置： CRUD 组件介于插件与应用之间，封装为插件后，个性化配置和修改将变得复杂。
自定义需求： 直接复制到项目中使用，可随时修改源码，满足自定义需求。

效果展示 →