@lixinz/elpis-core

@lixinz/elpis-core

约定式低代码框架核心：Koa 后端运行时 + 前端 schema 引擎 + webpack 构建，一套 model 配置同时驱动 API 契约、表格 / 搜索 / 表单页面与多项目（project）继承。

• 后端：Koa + koa-router，基于目录约定的 loader（controller / service / middleware / router-schema / config / extend）
• 前端：Vue 3 + Element Plus，schema 驱动的表格、搜索栏、新增 / 编辑表单、详情抽屉
• 模型：JSON Schema 风格的 model 配置，支持 project 对 model 的字段级继承与覆盖
• 构建：开箱即用的 webpack dev-server / prod 构建工厂

环境要求

• Node.js >= 12
• 前端宿主工程需提供 peer 依赖：vue@^3、element-plus@^2、pinia@^2、vue-router@^4、axios@^0.19

安装

npm install @lixinz/elpis-core

快速开始

1. 应用入口 index.js

const ElpisCore = require('@lixinz/elpis-core')

ElpisCore.start({
    name: 'Elpis',
    homePage: '/view/project-list'
})

start(options) 可接受的参数：

启动时框架会按顺序加载：middleware → routerSchema → controller → service → config → extend → 中间件装配 → router，最后监听 PORT（默认 8080）。

2. 目录约定

my-app/
├─ index.js                     # 入口：ElpisCore.start()
├─ config/
│  ├─ config.default.js         # 默认配置
│  ├─ config.beta.js
│  └─ config.prod.js            # 由环境变量 _ENV 选择
├─ app/
│  ├─ controller/               # 业务控制器
│  ├─ service/                  # 业务服务
│  ├─ router/                   # 路由注册
│  ├─ router-schema/            # 接口参数契约（JSON Schema）
│  ├─ pages/                    # 业务页面（入口与页面壳）
│  └─ webpack/                  # 构建薄入口
└─ model/
   └─ <modelKey>/
      ├─ model.js               # 基础 model 配置
      └─ project/<projKey>.js   # 项目级覆盖（继承 model）

框架内置目录与业务目录合并加载，业务同名 key 覆盖框架。

3. Controller

继承框架 BaseController，使用 this.success / this.fail 统一响应结构：

module.exports = (app) => {
    const BaseController = require('@lixinz/elpis-core/app/controller/base')(app)
    return class ProductController extends BaseController {
        getList(ctx) {
            const list = [{ product_id: 1, product_name: '示例商品' }]
            this.success(ctx, list, { total: 1 })
        }
    }
}

统一响应体：

{ "success": true, "data": {}, "metadata": {} }

4. Router

module.exports = (app, router) => {
    const { product } = app.controller
    router.get('/api/proj/product/list', product.getList.bind(product))
}

5. 接口契约 router-schema

用 JSON Schema 声明各接口的 query / body，框架中间件会基于 ajv 做参数校验：

module.exports = {
    '/api/proj/product/list': {
        get: {
            query: {
                type: 'object',
                properties: {
                    page: { type: 'string' },
                    size: { type: 'string' }
                },
                required: ['page', 'size']
            }
        }
    }
}

6. Model 配置（驱动前端页面）

一个 model 描述菜单、接口与字段 schema；字段上的 tableOption / searchOption / createFormOption / editFormOption / detailPanelOption 分别决定该字段在表格、搜索栏、新增表单、编辑表单、详情面板中的呈现：

module.exports = {
    model: 'dashboard',
    name: '电商系统',
    menu: [{
        key: 'product',
        name: '商品管理',
        menuType: 'model',
        moduleType: 'schema',
        schemaConfig: {
            api: '/api/proj/product',
            schema: {
                type: 'object',
                properties: {
                    product_name: {
                        type: 'string',
                        label: '商品名称',
                        tableOption: { 'min-width': 200 },
                        searchOption: { comType: 'input' },
                        createFormOption: { comType: 'input' },
                        editFormOption: { comType: 'input' },
                        detailPanelOption: {}
                    }
                }
            }
        }
    }]
}

model/<modelKey>/project/<projKey>.js 可对 model 做字段级继承：同名字段递归覆盖、数组按 key 合并、缺失字段保留。

前端能力

框架内置页面模块（业务通过 webpack alias 引入，可在业务目录放置同名文件覆盖）：

• widgets/schema-table：schema 驱动表格
• widgets/schema-search-bar：schema 驱动搜索栏（input / select / dynamicSelect / dateRange）
• widgets/schema-form：schema 驱动表单（input / inputNumber / select）
• widgets/header-container、widgets/sider-container：布局容器
• schema-view/：整合搜索 + 表格 + 新增 / 编辑抽屉 + 详情抽屉的完整视图
• common/curl.js：统一请求封装
• store/：pinia（menu / project）

构建

业务侧 app/webpack 仅需薄入口，rootDir 传入业务工程根目录：

// app/webpack/dev.js
require('@lixinz/elpis-core/webpack/dev-server.js')(process.cwd())

// app/webpack/prod.js
require('@lixinz/elpis-core/webpack/build.js')(process.cwd())

也可直接使用配置工厂做自定义：

const { createDevConfig } = require('@lixinz/elpis-core/webpack/config/webpack.dev.js')
module.exports = createDevConfig(process.cwd())

内置中间件

• error-handler：统一异常捕获与响应
• api-sign-verify：接口签名校验（md5）
• api-params-verify：基于 router-schema 的参数校验
• project-handler：解析并注入当前 project（ctx.projKey）

业务可在 app/middleware.js 导出一个 (app) => {} 函数完全自定义装配；缺省时使用框架默认装配。

配置与环境

• 环境变量 _ENV 选择配置文件：local（默认）/ beta / prod
• PORT / IP 覆盖监听地址，默认 0.0.0.0:8080
• config/config.<env>.js 会被挂载到 app.config

目录总览（包内）

@lixinz/elpis-core
├─ index.js                 # start() 启动入口
├─ env.js                   # 环境解析
├─ loader/                  # 7 类目录加载器
├─ lib/model-loader.js      # model / project 继承解析
├─ app/
│  ├─ controller/           # base / project / view
│  ├─ service/              # base / project
│  ├─ middleware/           # 内置中间件
│  ├─ middleware.default.js # 默认中间件装配
│  ├─ extend/               # logger 等扩展
│  ├─ router/, router-schema/
│  └─ pages/                # schema 引擎、widgets、store、common
└─ webpack/                 # dev-server / build / 配置工厂

License

ISC