核心架构

说明 Elpis 作为框架与 Demo 双身份时的路径解析、资源加载与中间件注册方式。

概述

Elpis 是基于 Vue 3 + Koa 2 的约定式全栈框架。对外通过 serverStart 启动；对内由一组 loader 扫描目录，将 controller、service、router、middleware、extend、config 挂载到同一 app 实例。

约定目录结构以减少样板代码；业务同名资源可覆盖框架默认实现。

baseDir 解析

项目根目录取自进程工作目录：

app.baseDir = process.cwd()
app.businessPath = path.resolve(app.baseDir, './app')

业务项目需将 app/、config/、model/ 置于 process.cwd() 下。本地开发应在仓库根目录执行 npm run dev。

框架 / 业务双源

Loader 先扫描框架内目录，再扫描 app.businessPath（即 {cwd}/app）。同名资源由业务侧覆盖，便于在升级框架包时保留业务定制。

  • 本仓库 Demo：业务路径与框架 app 为同一目录。
  • 业务项目依赖 @xugy_949/elpis：在业务仓库根目录启动，业务 app/ 叠加于框架之上。

中间件注册顺序

elpis-core/index.js 先加载框架全局中间件（基于 __dirname），再按需加载业务全局中间件：

// 框架：基于 __dirname
elpisMiddlewarePath = path.resolve(__dirname, '../app/middleware.js')
require(elpisMiddlewarePath)(app)

// 业务：基于 businessPath（= cwd/app）
businessMiddlewarePath = path.resolve(app.businessPath + '/middleware.js')
if (businessMiddlewarePath !== elpisMiddlewarePath) {
  require(businessMiddlewarePath)(app)
}

本仓库自运行时两条路径相同，将跳过第二次 require，避免重复注册 koa-nunjucks（ctx.render）。加载异常由 try/catch 捕获并输出错误信息。

约定式加载器

elpis-core/loader/* 按目录扫描并挂载：

  • middleware → 路由级中间件
  • router-schema → Ajv 参数校验 schema
  • service / controller
  • config → 四层合并结果 app.config
  • extend → 扩展 app / context
  • router → 最后注册，确保前置能力已就绪

四层配置合并

  1. 框架 config.default.js
  2. 业务 config.default.js
  3. 框架 config.{env}.js
  4. 业务 config.{env}.js（最高优先级）

环境由 _ENV 指定：local / beta / production。若不存在对应环境配置文件，将使用空对象占位。

目录结构

elpis/
├── server.js          # 入口
├── elpis-core/        # 启动与 loaders
├── config/            # 框架配置
├── app/               # 框架能力与 Demo 业务
│   ├── middleware.js
│   ├── controller/ service/ router/ ...
│   └── pages/         # Vue MPA
└── model/             # Dashboard / Project