# SuperAdmin
**Repository Path**: hashan/admin-x
## Basic Information
- **Project Name**: SuperAdmin
- **Description**: SuperAdmin 是一款致力于解决前端 80%CRUD 重复性工作的后台管理系统模板。该模板基于 JsonSchema 对重复性页面进行描述，依据相关配置可自动完成 CRUD 工作，无需重复开发增删改查功能。
SuperAdmin 模板以若依管理系统为基础进行开发，具备无缝切换的特性，用户在自定义页面时，按照正常编写页面逻辑的方式操作即可。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-16
- **Last Updated**: 2026-01-26
## Categories & Tags
**Categories**: Uncategorized
**Tags**: 管理后台, Vue, superAdmin, 企业级管理后台
## README
# 🚀 SuperAdmin
**全栈管理后台模板 - 基于若依风格 + SuperElement CRUD 引擎**
[](https://vuejs.org/)
[](https://element-plus.org/)
[](https://koajs.com/)
[](https://nodejs.org/)
[](https://vitejs.dev/)
[](LICENSE)
**前后端分离 | 约定优于配置 | Schema 驱动 | 零配置 CRUD**
[快速开始](#-快速开始) • [项目结构](#-项目结构) • [后端配置](#-后端配置) • [前端配置](#-前端配置) • [Model 配置](#-model-配置) • [使用指南](#-使用指南)
---
## ✨ 特性
- 🎯 **前后端分离架构**：`super-node` 后端服务 + `super-ui` 前端应用，独立开发部署
- ⚡ **约定优于配置**：基于 `@hashan-cn/super-node-core` 引擎，自动加载 Controller/Service/Middleware
- 🎨 **若依风格兼容**：内置对若依菜单/路由/字典/分页风格的完整支持
- 🧩 **SuperElement CRUD 引擎**：通过 Schema 配置自动生成表格、表单、搜索，解决 80% 的 CRUD 工作
- 🔌 **插件化架构**：MySQL、Redis 等通过插件系统统一管理
- 📦 **多环境支持**：local / beta / production 环境配置自动切换
- 🛡️ **参数验证**：基于 AJV 的 Router Schema 自动参数校验
---
## 🛠️ 技术栈
### 后端 (super-node)
- **框架**: Koa 2.7.0
- **核心引擎**: @hashan-cn/super-node-core
- **数据库**: MySQL (knex), Redis
- **认证**: JWT (jsonwebtoken)
- **验证**: AJV (JSON Schema)
- **日志**: log4js
- **工具库**: lodash, moment, bcryptjs
### 前端 (super-ui)
- **框架**: Vue 3.3.4
- **UI 组件库**: Element Plus 2.3.7
- **状态管理**: Pinia 2.1.6
- **路由**: Vue Router 4.2.4
- **CRUD 引擎**: @hashan-cn/superElement
- **构建工具**: Vite 7.2.7
- **HTTP 客户端**: Axios
- **图表**: ECharts 5.5.0
---
## 📁 项目结构
```
SuperAdmin/
├── super-node/ # 🔧 后端服务
│ ├── app/
│ │ ├── controller/ # 控制器层
│ │ ├── service/ # 服务层
│ │ ├── middleware/ # 中间件
│ │ ├── router/ # 路由定义
│ │ ├── router-schema/ # 路由 Schema 验证
│ │ ├── plugins/ # 插件（MySQL, Redis）
│ │ ├── extend/ # 扩展
│ │ └── common/ # 公共工具
│ ├── config/ # 配置文件
│ │ ├── config.default.js
│ │ ├── config.local.js
│ │ ├── config.beta.js
│ │ ├── config.prod.js
│ │ └── plugin.js # 插件配置
│ ├── model/ # 数据模型
│ ├── test/ # 测试文件
│ └── index.js # 入口文件
│
├── super-ui/ # 🎨 前端应用
│ ├── src/
│ │ ├── api/ # API 接口
│ │ ├── assets/ # 静态资源
│ │ ├── common/ # 公共工具
│ │ ├── components/ # 组件
│ │ ├── Layout/ # 布局组件
│ │ ├── router/ # 路由配置
│ │ ├── store/ # 状态管理
│ │ ├── views/ # 页面视图
│ │ ├── superElementConfig/ # SuperElement 配置
│ │ │ ├── super-api.js # Model 获取 API
│ │ │ └── api-params-config.js # API 参数配置
│ │ └── main.js # 入口文件
│ ├── public/ # 公共静态资源
│ └── vite.config.js # Vite 配置
│
└── package/ # 📦 共享包
├── super-node-core/ # 后端核心引擎
└── superElement/ # 前端 CRUD 引擎
```
---
## 🎨 演示
## 🚀 快速开始
### 环境要求
- Node.js >= 14
- MySQL >= 5.7
- Redis >= 5.0
### 1️⃣ 克隆项目
```bash
git clone
cd SuperAdmin
```
### 2️⃣ 安装依赖
```bash
# 安装后端依赖
cd super-node
npm install
# 安装前端依赖
cd ../super-ui
npm install
```
### 3️⃣ 配置数据库
编辑 `super-node/config/config.local.js`：
```javascript
module.exports = {
mysql: {
host: '127.0.0.1',
port: 3306,
user: 'root',
password: 'your_password',
database: 'superadmin',
},
redis: {
host: '127.0.0.1',
port: 6379,
password: '',
db: 0,
},
};
```
### 4️⃣ 初始化数据库
执行 `sql/index.sql` 创建数据库表结构。
### 5️⃣ 启动项目
#### 启动后端
```bash
cd super-node
npm run dev
```
后端将运行在 `http://localhost:8080`
#### 启动前端
```bash
cd super-ui
npm run dev
```
前端将运行在 `http://localhost:3000`
### 6️⃣ 访问系统
打开浏览器访问：`http://localhost:3000`
默认账号密码请查看数据库或联系管理员。
---
## 🔧 后端配置
### Super-Node-Core 引擎
`super-node` 基于 `@hashan-cn/super-node-core` 引擎，采用**约定优于配置**的设计理念。
#### 核心特性
1. **自动加载模块**
- `app/controller/**/*.js` → `app.controller.xxx.yyy`
- `app/service/**/*.js` → `app.service.xxx.yyy`
- `app/middleware/**/*.js` → `app.middlewares.xxx.yyy`
- 支持目录 + 文件名自动驼峰转换
2. **多环境配置**
- `config/config.default.js` - 默认配置（必须）
- `config/config.local.js` - 本地环境
- `config/config.beta.js` - 测试环境
- `config/config.prod.js` - 生产环境
3. **插件系统**
- MySQL、Redis 等通过 `config/plugin.js` 配置
- 插件实例挂载到 `app.plugins.xxx` 和 `app.context.xxx`
#### 启动方式
```javascript
// super-node/index.js
const SuperNodeCore = require("@hashan-cn/super-node-core");
SuperNodeCore.start({
// 应用级别配置
homePage: '/', // 未匹配路由时的重定向首页
});
```
#### 环境变量
```bash
# 本地环境
set _ENV=local && npm run dev
# 测试环境
set _ENV=beta && npm run beta
# 生产环境
set _ENV=production && npm run prod
```
### 编写 Controller
```javascript
// app/controller/user/user-info.js
const BaseController = require('../base');
module.exports = (app) =>
class UserInfoController extends BaseController {
async list(ctx) {
const { page = 1, size = 10 } = ctx.query;
const data = await app.service.user.userInfo.getList(page, size);
this.success(ctx, data);
}
async detail(ctx) {
const { id } = ctx.params;
const data = await app.service.user.userInfo.getById(id);
this.success(ctx, data);
}
};
```
### 编写 Service
```javascript
// app/service/user/user-info.js
module.exports = (app) => {
return {
async getList(page, size) {
// 使用 app.plugins.mysql 进行数据库操作
const offset = (page - 1) * size;
const result = await app.plugins.mysql.query(
'SELECT * FROM users LIMIT ? OFFSET ?',
[size, offset]
);
return result;
},
async getById(id) {
const result = await app.plugins.mysql.query(
'SELECT * FROM users WHERE id = ?',
[id]
);
return result[0];
},
};
};
```
### 编写 Router
```javascript
// app/router/user.js
module.exports = (app, router) => {
// 列表接口
router.get('/api/user/list', async (ctx) => {
await app.controller.user.userInfo.list(ctx);
});
// 详情接口
router.get('/api/user/:id', async (ctx) => {
await app.controller.user.userInfo.detail(ctx);
});
};
```
### Router Schema 验证
```javascript
// app/router-schema/user.js
module.exports = {
'/api/user/:id': {
type: 'object',
properties: {
id: {
type: 'integer',
minimum: 1,
},
},
required: ['id'],
},
};
```
配合中间件 `app/middleware/api-params-verify.js` 使用，自动验证请求参数。
---
## 🎨 前端配置
### SuperElement CRUD 引擎
`super-ui` 使用 `@hashan-cn/superElement` 作为 CRUD 引擎，通过 Schema 配置自动生成表格、表单、搜索等功能。
#### 初始化引擎
在 `src/main.js` 中初始化：
```javascript
import { createApp } from 'vue';
import { createSchemaViewEngine } from '@hashan-cn/superElement';
import request from '@/common/request';
import { apiParamsConfig } from '@/superElementConfig/api-params-config';
import { getModelInfo } from '@/superElementConfig/super-api';
import pinia from '@/store';
const app = createApp(App);
app.use(pinia);
async function initApp() {
// 1. 获取后端返回的 Model 配置
const res = await getModelInfo();
if (!res || !res.success || !res.data) return;
const { menu } = res.data;
const models = menu; // Model 配置数组
// 2. 初始化 SuperElement 引擎
createSchemaViewEngine({
models, // Model 配置数组（必选）
request, // 请求函数（推荐传入项目封装的 request）
dictApi: '/system/dict/data/list', // 字典 API（可选）
apiParamsConfig, // API 参数配置（可选）
pinia, // Pinia 实例（可选）
});
app.mount('#app');
}
initApp();
```
#### 在路由中使用 SchemaView
```javascript
// src/router/index.js
import { SchemaView } from '@hashan-cn/superElement';
const routes = [
{
path: '/system/user',
component: SchemaView,
meta: {
title: '用户管理',
key: 'user', // 对应 Model 中的 key
},
},
];
```
---
## 📋 Model 配置
Model 配置是 SuperElement 的核心，通过后端返回的 Schema 配置，自动生成 CRUD 页面。
### Model 结构
后端需要返回如下结构的 Model 配置：
```javascript
{
key: 'user', // 唯一标识，对应路由 meta.key
title: '用户管理', // 页面标题
path: '/system/user', // 路由路径
component: 'schemaView', // 组件类型
schemaConfig: {
// 1. JSON Schema 定义
schema: {
type: 'object',
properties: {
userName: {
type: 'string',
label: '用户名',
// 表单配置
formOption: {
comType: 'input',
default: '',
rules: [
{ required: true, message: '用户名不能为空' },
],
},
// 搜索配置
searchOption: {
comType: 'input',
default: '',
},
// 表格配置
tableOption: {
visible: true,
width: 200,
sortable: true,
},
},
// ... 更多字段
},
required: ['userName'],
},
// 2. API 配置
api: {
list: '/api/user/list',
detail: '/api/user/:userId',
create: '/api/user',
update: '/api/user/:userId',
delete: '/api/user/:userId',
// params 函数无法 JSON 序列化，需在前端 apiParamsConfig 中配置
params: {},
},
// 3. 表格配置
tableConfig: {
comType: 'table',
// ... 其他表格配置
},
// 4. 搜索配置
searchConfig: {
// ... 搜索面板配置
},
// 5. 组件配置（弹窗等）
componentConfig: {
createForm: {
// 创建表单配置
},
editForm: {
// 编辑表单配置
},
},
},
}
```
### Schema Option 说明
#### formOption（表单配置）
```javascript
formOption: {
comType: 'input', // 组件类型：input, select, date-picker 等
default: '', // 默认值
rules: [ // 验证规则
{ required: true, message: '必填' },
{ min: 3, max: 20, message: '长度3-20' },
],
props: { // 组件 props
placeholder: '请输入用户名',
clearable: true,
},
}
```
#### searchOption（搜索配置）
```javascript
searchOption: {
comType: 'input', // 组件类型
default: '', // 默认值
props: { // 组件 props
placeholder: '搜索用户名',
},
}
```
#### tableOption（表格配置）
```javascript
tableOption: {
visible: true, // 是否显示
width: 200, // 列宽
sortable: true, // 是否可排序
fixed: 'left', // 固定列：left, right
components: { // 自定义单元格组件
comType: 'link',
props: {
label: '查看详情',
href: '$current', // $current 表示当前字段值
},
},
}
```
### API 参数配置
由于函数无法 JSON 序列化，API 的 `params` 函数需要在前端 `api-params-config.js` 中配置：
```javascript
// src/superElementConfig/api-params-config.js
export const apiParamsConfig = {
user: {
// 列表接口参数
list: (ctx) => ({
query: ctx.apiParams || {}, // 搜索参数
}),
// 详情接口参数
detail: (ctx) => ({
path: {
userId: ctx.row.userId ?? ctx.row.user_id,
},
}),
// 创建接口参数
create: (ctx) => ({
body: ctx.form || {},
}),
// 更新接口参数
update: (ctx) => ({
body: ctx.form || {},
}),
// 删除接口参数
delete: (ctx) => ({
path: {
userIds: ctx.row.userId ?? ctx.row.user_id,
},
}),
},
};
```
### 后端返回 Model 配置
后端需要在 `/api/project` 接口返回 Model 配置：
```javascript
// app/controller/project.js
module.exports = (app) =>
class ProjectController extends BaseController {
async index(ctx) {
const models = [
{
key: 'user',
title: '用户管理',
path: '/system/user',
component: 'schemaView',
schemaConfig: {
// ... Schema 配置
},
},
// ... 更多 Model
];
this.success(ctx, { menu: models });
}
};
```
---
## 📖 使用指南
### 创建新的 CRUD 页面
#### 1. 后端配置 Model
在 `app/controller/project.js` 中添加新的 Model 配置：
```javascript
{
key: 'product',
title: '产品管理',
path: '/system/product',
component: 'schemaView',
schemaConfig: {
schema: {
type: 'object',
properties: {
productName: {
type: 'string',
label: '产品名称',
formOption: {
comType: 'input',
default: '',
rules: [{ required: true, message: '产品名称不能为空' }],
},
searchOption: {
comType: 'input',
default: '',
},
tableOption: {
visible: true,
width: 200,
},
},
// ... 更多字段
},
},
api: {
list: '/api/product/list',
detail: '/api/product/:productId',
create: '/api/product',
update: '/api/product/:productId',
delete: '/api/product/:productId',
params: {},
},
},
}
```
#### 2. 前端配置 API 参数
在 `src/superElementConfig/api-params-config.js` 中添加：
```javascript
export const apiParamsConfig = {
// ... 其他配置
product: {
list: (ctx) => ({ query: ctx.apiParams || {} }),
detail: (ctx) => ({
path: { productId: ctx.row.productId ?? ctx.row.product_id },
}),
create: (ctx) => ({ body: ctx.form || {} }),
update: (ctx) => ({ body: ctx.form || {} }),
delete: (ctx) => ({
path: { productIds: ctx.row.productId ?? ctx.row.product_id },
}),
},
};
```
#### 3. 后端实现接口
创建 Controller、Service、Router：
```javascript
// app/controller/product/product-info.js
// app/service/product/product-info.js
// app/router/product.js
```
#### 4. 完成！
刷新页面，新的 CRUD 页面会自动生成。
### 自定义组件类型
SuperElement 支持扩展自定义组件类型，详见 [SuperElement 文档](./package/superElement/README.md)。
---
## 🔍 核心概念
### 后端核心点
1. **约定优于配置**
- 按照目录结构约定组织代码，引擎自动加载
- 文件名和目录名自动转换为驼峰命名
2. **插件系统**
- MySQL、Redis 等通过插件系统统一管理
- 插件实例挂载到 `app.plugins` 和 `app.context`
3. **多环境配置**
- 通过 `_ENV` 环境变量自动切换配置
- 支持 local / beta / production 三种环境
4. **参数验证**
- 基于 AJV 的 Router Schema 自动验证
- 配合中间件使用，自动拦截无效请求
### 前端核心点
1. **Schema 驱动**
- 通过后端返回的 Schema 配置自动生成页面
- 一次配置，自动生成表格、表单、搜索
2. **若依风格兼容**
- 内置对若依菜单/路由/字典/分页的完整支持
- 无缝集成若依生态
3. **组件化架构**
- SchemaView、SchemaForm、SchemaTable 等可单独使用
- 支持自定义模板页和组件扩展
---
## 📚 更多文档
- [后端核心引擎文档](./package/super-node-core/README.md)
- [SuperElement CRUD 引擎文档](./package/superElement/README.md)
---
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
---
## 📄 许可证
[ISC](LICENSE) © 2024 SuperAdmin
---
**如果这个项目对你有帮助，请给它一个 ⭐ Star！**
Made with ❤️ by [Hashan](https://gitee.com/hashan)