@lucky-lq/elpis

v1.0.0

Published

10 days ago

> 一份 JSON 配置 + 一组 RESTful API = 一个可复用的后台模块

0High
0Medium
0Low

lucky-lq

Elpis

一份 JSON 配置 + 一组 RESTful API = 一个可复用的后台模块

项目简介

Elpis 是一个配置驱动的企业级中后台脚手架，基于 Koa 2 + Vue 3 + Element Plus + Webpack 实现。

它的目标不是只做一个后台页面，而是提供一套可以复用的中后台平台能力：

后端提供 BFF、页面入口渲染、配置聚合、参数校验和接口签名校验
前端通过菜单配置和 Schema 配置动态渲染页面
模型层通过 model + project 的继承机制实现多业务、多项目复用

整体上，Elpis 解决的是“同类后台系统大量重复开发”的问题。

核心能力

配置驱动：通过 model/ 中的配置生成后台菜单、搜索区、表格和弹窗组件
BFF + SPA：同仓库管理 Koa 服务端和 Vue 前端，减少接口和页面联调成本
模型继承：支持领域模型与项目配置分层定义，按 key 合并数组配置
Schema 渲染：同一份 schema 可拆分为 table、search、form、view 等多种消费方式
可扩展：支持页面组件、表单控件、schema 组件、loader 等多层扩展
工程化：提供 dev/prod 前端构建、服务端启动、接口测试与 lint

技术栈

Server: koa koa-router koa-bodyparser koa-nunjucks-2
Frontend: vue@3 element-plus pinia vue-router
Build: webpack@5 vue-loader webpack-dev-middleware webpack-hot-middleware
Validation & Infra: ajv lodash md5 log4js
Test: mocha supertest

架构概览

┌────────────────────────────────────────────────────┐
│ widgets / common                                  │
│ schema-table / schema-search-bar / schema-form    │
├────────────────────────────────────────────────────┤
│ pages                                              │
│ dashboard / project-list / page1                  │
├────────────────────────────────────────────────────┤
│ elpis-core                                         │
│ loader / BFF / SSR page entry render              │
├────────────────────────────────────────────────────┤
│ model                                              │
│ 领域模型(model) + 项目配置(project)                │
└────────────────────────────────────────────────────┘

分层职责

elpis-core/ 负责 Koa 实例初始化、loader、配置装配和服务启动
app/ 业务运行目录，包含 controller、service、middleware、router、pages、widgets
model/ 定义后台模块的配置模型和项目差异配置
docs/ 架构说明和配置规范草稿

目录结构

Elpis/
├── elpis-core/
│   ├── index.js
│   └── loader/
├── app/
│   ├── controller/
│   ├── middleware/
│   ├── pages/
│   ├── router/
│   ├── router-schema/
│   ├── service/
│   ├── view/
│   └── webpack/
├── model/
│   ├── index.js
│   └── buiness/
│       ├── model.js
│       └── project/
├── docs/
└── index.js

快速开始

1. 安装依赖

npm install

2. 启动服务端

npm run dev

默认会启动 Koa 服务，端口为 9090。

3. 启动前端开发构建

npm run build:dev

该命令会启动 Webpack Dev Middleware 对应的开发服务，用于生成 .tpl 模板和前端资源。

4. 生产构建

npm run build:prod

5. 测试与检查

npm run lint
npm test

运行方式

Elpis 对外暴露两类核心能力：

1. 服务端启动

入口文件：index.js

const { serverStart } = require('@lucky-lq/elpis');

serverStart({
  name: 'Elpis',
  homePage: '/view/project-list',
});

2. 前端构建

const { frontendBuild } = require('@lucky-lq/elpis');

frontendBuild(process.env._ENV);

后端设计

`elpis-core` 启动流程

elpis-core/index.js 会依次完成以下动作：

创建 Koa 实例
初始化环境变量
加载 middleware
加载 router-schema
加载 controller
加载 service
加载 config
加载 extend
执行业务根目录 app/middleware.js
加载 router
启动服务

Loader 机制

Elpis 的 loader 基于目录约定工作。只要把文件放到约定目录下，就能自动挂载到 app 上。

| 目录 | 自动挂载结果 | | --- | --- | | app/controller/*.js | app.controller.* | | app/service/*.js | app.service.* | | app/middleware/*.js | app.middlewares.* | | app/router-schema/*.js | app.routerSchema | | app/extend/*.js | app.* | | app/router/*.js | 注册到 koa-router |

目前 loader 已按统一模式支持两层来源：

Elpis 内置 app/*
业务项目自身 app/*

加载顺序为先内置、后业务，业务侧可覆盖内置实现。

中间件链

业务根目录 app/middleware.js 负责组织全局中间件链：

koaStatic
  -> koaNunjucks
  -> bodyParser
  -> errorHandler
  -> apiSingVerify
  -> apiParamsVerify
  -> projectHandler
  -> business router

核心接口

GET /api/project 获取当前项目完整配置
GET /api/project/list 获取同 model 下的项目列表
GET /api/project/model_list 获取全部 model / project 结构
GET /view/:page 渲染对应页面模板并交给 SPA 接管

前端设计

页面启动

所有 SPA 页面通过 app/pages/boot.js 启动，统一注入：

Vue 3
Element Plus
Pinia
Vue Router

Dashboard 模板

Dashboard 是项目的核心模板页面，负责承载大部分配置驱动能力。

对应目录：

app/pages/dashboard/
app/pages/widgets/

其主要能力包括：

顶部菜单 + 侧边菜单动态渲染
Schema 搜索栏
Schema 表格
动态组件弹窗
iframe/custom/schema 三类模块切换

Schema-Driven UI

一份 schema 可以同时描述：

表格列展示
搜索栏控件
新增表单
编辑表单
查看详情

解析逻辑位于：

app/pages/dashboard/complex-view/schema-view/hook/schema.js

核心思路是根据字段上的不同 xxxOption 拆分出多个 DTO schema。

模型系统

`model + project` 继承结构

Elpis 使用模型层管理多项目复用：

model/
  buiness/
    model.js
    project/
      pdd.js
      jd.js
      taobao.js

model.js 定义领域级公共后台配置
project/*.js 定义某个项目对公共配置的覆盖和扩展

合并机制

model/index.js 会自动扫描 model/**/*.js，并对 project 配置做继承合并。

其中数组类型字段不会按下标合并，而是按 key 做智能合并，这一点对菜单和按钮配置很关键。

Dashboard Model 配置规范

下面这部分基于 docs/dashboard.model.js 整理，是 Dashboard 类型 model 的配置约定。

顶层字段

{
  model: 'dashboard',
  name: '',
  desc: '',
  icon: '',
  homePage: '',
  menu: []
}

字段含义：

model 模板类型。不同模板类型对应不同数据结构
name 项目或模型名称
desc 描述信息
icon 图标
homePage 首页路径，通常由 project 配置补充
menu 顶部菜单配置

Menu 结构

每个菜单项都遵循统一结构：

{
  key: '',
  name: '',
  menuType: '', // group / module
}

1. 分组菜单 `group`

{
  key: '',
  name: '',
  menuType: 'group',
  subMenu: [
    // 可递归 menuItem
  ]
}

2. 模块菜单 `module`

{
  key: '',
  name: '',
  menuType: 'module',
  moduleType: '', // sider / iframe / custom / schema
}

Module 类型说明

`moduleType === 'sider'`

用于带二级菜单的容器页：

{
  moduleType: 'sider',
  siderConfig: {
    menu: [
      // 二级菜单
    ]
  }
}

`moduleType === 'iframe'`

用于嵌入外部页面：

{
  moduleType: 'iframe',
  iframeConfig: {
    path: ''
  }
}

`moduleType === 'custom'`

用于跳转到自定义路由页面：

{
  moduleType: 'custom',
  customConfig: {
    path: ''
  }
}

`moduleType === 'schema'`

用于生成配置驱动的列表模块，是 Dashboard Model 中最核心的部分：

{
  moduleType: 'schema',
  schemaConfig: {
    api: '',
    schema: {},
    tableConfig: {},
    searchConfig: {},
    componentConfig: {}
  }
}

`schemaConfig` 结构说明

1. `api`

数据源接口地址，要求遵循 RESTful 风格。比如：

api: '/api/proj/product'

列表通常由前端补成：

${api}/list

2. `schema`

字段结构定义：

{
  type: 'object',
  properties: {
    fieldKey: {
      type: '',
      label: '',
      tableOption: {},
      searchOption: {},
      createFormOption: {},
      editFormOption: {},
      viewFormOption: {}
    }
  },
  required: []
}

字段级配置的核心含义：

type 字段类型
label 中文名称
tableOption 表格列配置，透传给 el-table-column
searchOption 搜索栏配置
createFormOption 新增表单控件配置
editFormOption 编辑表单控件配置
viewFormOption 查看详情时的展示配置

表格字段配置 `tableOption`

tableOption: {
  ...elTableColumnConfig,
  visiabled: true,
  toFixed: 1
}

常见用途：

控制列显示与否
设置列宽、固定列、tooltip
配置数字格式化保留位数

搜索字段配置 `searchOption`

searchOption: {
  ...elComponentConfig,
  comType: '',
  default: ''
}

comType 用于决定渲染哪种搜索组件，当前已支持：

input
select
date
daterange
datetime
datetimerange
time

表单字段配置

新增表单 `createFormOption`

createFormOption: {
  ...elComponentConfig,
  comType: '',
  visible: true,
  disabled: false,
  default: '',
  enumList: []
}

编辑表单 `editFormOption`

editFormOption: {
  ...elComponentConfig,
  comType: '',
  visible: true,
  disabled: false,
  default: '',
  enumList: []
}

查看表单 `viewFormOption`

viewFormOption: {
  visible: true,
  formatter: null
}

formatter 用于只读展示格式化：

formatter: (val, row) => ''

`tableConfig`

表格行为配置，主要包括头部按钮和行按钮。

tableConfig: {
  headerButtons: [],
  rowButtons: []
}

头部按钮

{
  label: '',
  eventKey: '',
  eventOption: {},
  ...elButtonConfig
}

行按钮

{
  label: '',
  eventKey: '',
  eventOption: {
    comName: '',
    params: {}
  },
  ...elButtonConfig
}

常见事件包括：

showComponent 打开配置组件弹窗
remove 删除数据项

`componentConfig`

用于定义 schema 模块关联的弹窗组件配置：

componentConfig: {
  createForm: {
    title: '',
    saveButText: ''
  },
  editForm: {
    mainKey: '',
    title: '',
    saveButText: ''
  },
  viewForm: {
    title: '',
    closeBtnText: ''
  }
}

扩展点

Elpis 提供多个业务侧可选扩展点。

前端扩展

app/pages/dashboard/router.js Dashboard 路由扩展
app/pages/dashboard/complex-view/schema-view/components/component-config.js Schema 组件扩展
app/pages/widgets/scheam-form/business-form-item-config.js 表单项控件扩展

后端扩展

业务侧可以通过以下目录扩展或覆盖内置能力：

app/controller
app/service
app/middleware
app/router
app/router-schema
app/extend

示例

可以参考：

这两份配置展示了：

如何定义一个 Dashboard 类型模型
如何在项目级别覆盖菜单名称、首页和模块配置

现状说明

当前仓库中已经实现的重点能力：

Schema Search Bar
Schema Table
Dashboard 模板页
项目切换页
Project 配置接口
Model / Project 自动扫描与继承合并

当前仓库中仍处于演进中的部分：

更多内置表单组件
更完整的 Schema Form 体系
更完善的业务扩展文档

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme