Elpis全栈框架开发总结

框架概述

Elpis 是一个基于 Koa + Vue 的全栈框架，它不仅仅是一个简单的服务端框架，而是一个完整的业务开发解决方案。框架的核心理念是通过 DSL（领域特定语言）驱动业务开发，实现配置化、标准化和自动化。

核心特点

1. DSL 驱动架构：通过声明式配置定义业务模型、页面结构和交互逻辑
2. 全栈一体化：前后端共享类型定义和业务模型，保证类型安全
3. 多页面架构：支持独立打包、部署的多页面应用
4. 插件化设计：控制器、服务、中间件等都采用模块化设计
5. 工程化完善：集成了完整的开发工具链和规范体系
6. 业务模块自动加载：基于约定自动加载对应目录下的模块

架构设计

服务端架构

src/
├── core/                   # 框架核心
│   ├── core.ts            # 核心类，负责应用初始化
│   ├── loader/            # 加载器系统
│   │   ├── config.ts      # 配置加载器
│   │   ├── controller.ts  # 控制器加载器
│   │   ├── service.ts     # 服务加载器
│   │   ├── middleware.ts  # 中间件加载器
│   │   ├── router.ts      # 路由加载器
│   │   └── routerSchema.ts # 路由验证加载器
│   └── types/             # 核心类型定义
│
├── app/                    # 应用层
│   ├── controller/        # 控制器层
│   │   ├── base.ts       # 基础控制器类
│   │   ├── project.ts    # 项目管理控制器
│   │   └── view.ts       # 视图控制器
│   ├── service/           # 服务层
│   ├── middleware/        # 中间件
│   ├── model/            # DSL 模型定义
│   ├── router/           # 路由配置
│   └── bundler/          # 打包配置（当前为 Webpack）

前端架构

app/pages/
├── common/                # 公共模块
│   ├── components/       # 通用组件
│   ├── composables/      # 组合式函数
│   ├── store/           # 状态管理
│   └── utils/           # 工具函数
│
├── dashboard/           # 主应用
│   ├── dashboard.vue   # 入口组件
│   ├── widgets/        # 业务组件
│   │   ├── schemaView/ # Schema 驱动的视图
│   │   ├── siderView/  # 侧边栏视图
│   │   └── iframeView/ # iframe 视图
│   └── routes.ts       # 路由配置

业务目录结构

businessDir/
├── model/              # 业务模型定义
│   ├── business/      # 电商业务模型
│   │   ├── model.ts   # 主模型
│   │   └── project/   # 子项目
│   │       ├── taobao.ts
│   │       └── pdd.ts
│   └── course/        # 课程业务模型
│       ├── model.ts
│       └── project/
│           ├── bilibili.ts
│           └── douyin.ts
├── controller/        # 业务控制器
├── service/          # 业务服务
├── router/           # 业务路由
└── middleware/       # 业务中间件

核心特性详解

DSL 系统设计

DSL 系统是整个框架的核心点，它通过声明式配置驱动整个业务系统：

// DSL 模型定义示例
interface Model {
  key: string              // 模型唯一标识
  name: string            // 模型名称
  headerMenu: MenuItem[]  // 菜单配置
  schema: {              // 数据结构定义
    type: 'object'
    properties: {
      [key: string]: SchemaProperty
    }
  }
}

// 属性定义
interface SchemaProperty {
  label: string
  type: 'string' | 'number' | 'boolean'
  searchOption?: SearchOption    // 搜索配置
  formOption?: FormOption        // 表单配置
  tableOption?: TableOption      // 表格配置
  componentOption?: ComponentOption // 组件配置
}

DSL 的作用范围：

• 业务模型定义：定义实体的属性、类型、验证规则
• 页面结构生成：自动生成表格、表单、搜索等UI组件
• API 接口映射：自动创建 CRUD 接口
• 组件行为定义：通过 DSL 配置组件的交互行为

动态组件机制

框架实现了一套完整的动态组件系统，支持通过 DSL 配置驱动组件的创建和交互：

// 组件映射表
export const componentsMap = {
  createForm: {
    component: defineAsyncComponent(() => import('./createForm/index.vue')),
    isDialog: true,  // 标识为弹窗组件
  },
  editForm: {
    component: defineAsyncComponent(() => import('./editForm/index.vue')),
    isDialog: true,
  },
  detailPanel: {
    component: defineAsyncComponent(() => import('./detailPanel/index.vue')),
    isDialog: true,
  }
}

// 通过 DSL 配置调用组件
{
  name: '新增',
  eventKey: 'showComponent',
  eventOption: {
    componentName: 'createForm',  // 指定要打开的组件
  },
}

中间件系统

框架采用了中间件系统，支持灵活的中间件组合：

// 错误处理中间件链
const errorHandlerChain = new ResponsibilityChain()
  .add(templateRenderErrorHandler)
  .add(requestErrorHandler)
  .handle(app, ctx, err)

// 参数验证中间件链
const schemaValidateChain = new ResponsibilityChain()
  .add(validateParams)
  .add(validateQuery)
  .add(validateBody)
  .handle(ctx, schema)

内置中间件：

• errorHandler：统一错误处理
• apiParamsVerify：API 参数验证
• apiSignVerify：API 签名验证
• injectProjectParams：项目参数注入
• matchRouter：路由匹配

类型安全体系

通过 TypeScript 实现全栈类型安全：

// 共享类型定义
export interface SchemaProperty {
  label: string
  type: 'string' | 'number' | 'boolean'
  searchOption?: SearchOption
  formOption?: FormOption
  tableOption?: TableOption
}

工程化实践

当前构建系统（Webpack）

• Webpack 5：多页面打包配置
• 代码分割：vendors、common chunk 自动分离
• HMR：开发环境热更新
• CSS 处理：PostCSS + UnoCSS

开发工具链

• TypeScript：类型检查和自动生成类型定义
• ESLint：代码规范
• Nodemon：服务端热重载
• VitePress：自动生成 API 文档

实际应用场景

这个框架特别适合以下场景：

1. 企业管理系统：通过 DSL 快速构建各种管理模块
2. 多租户 SaaS 平台：支持项目级别的配置隔离
3. 低代码平台：DSL 天然支持可视化配置
4. 微前端架构：支持 iframe 和独立部署
5. 业务中台：统一的业务模型和组件体系

后续迭代方向

1. Vite 打包工具迁移

背景：Webpack 配置相对复杂，构建速度慢，并且对于现在的前端工具链来说已经落后。

Vite的优势：

• 极速的冷启动
• 即时的模块热更新
• 真正的按需编译
• 更简洁的配置
• 更先进的生态系统

2. 中间件系统重构

背景：当前中间件是内置的，开发者无法灵活选择和配置，例如api参数验证，api签名验证这些不应该有内置的预设 或者应该提供更好的配置来让开发者选择，并且现在耦合了一些业务代码之类的内容灵活度相对很差，。

实施方案例子： 可以参考vite的配置方式，将中间件配置放在elpis.config中，并且提供更好的配置来让开发者选择，开发者可以在config中配置 也可以选择放在bussiness文件夹中的middleware中来进行扩展。

// elpis.config.ts
import { defineConfig } from '@elpis/core'
import { 
  errorHandler,
  apiParamsVerify,
  apiSignVerify,
} from '@elpis/middlewares'

export default defineConfig({
  // 中间件配置
  middlewares: [
    // 内置中间件
    errorHandler(),
    cors({ origin: '*' }),
    
    // 条件中间件
    {
      path: '/api/*',
      use: [
        apiParamsVerify(),
        apiSignVerify({ 
          secret: process.env.API_SECRET 
        }),
        rateLimit({ 
          max: 100, 
          duration: 60000 
        })
      ]
    },
    
  ],
})

中间件插件系统：

// 中间件插件接口
interface ElpisMiddlewarePlugin {
  name: string
  middleware: Middleware | Middleware[]
  config?: MiddlewareConfig
  // 生命周期钩子
  beforeInstall?(app: ElpisCoreApp): void
  afterInstall?(app: ElpisCoreApp): void
}

// 使用示例
import { createMiddleware } from '@elpis/core'

export const authPlugin = createMiddlewarePlugin({
  name: 'elpis-auth',
  middleware: [
    jwtVerify(),
    roleCheck(),
    permissionCheck()
  ],
  config: {
    jwt: {
      secret: 'your-secret',
      expiresIn: '7d'
    }
  }
})

3. 自动类型生成系统

背景：businessDir 下的文件需要手动导入，缺少类型提示。

Vite 插件实现：

// @elpis/vite-plugin-auto-types
export function ElpisAutoTypesPlugin(options: PluginOptions): Plugin {
  return {
    name: 'elpis-auto-types',
    
    async buildStart() {
      // 扫描 businessDir
      const files = await scanBusinessDir(options.businessDir)
      
      // 生成类型定义
      const types = generateTypes(files)
      
      // 写入 auto-imports.d.ts
      await writeFile('elpis-types.d.ts', types)
    },
    
    // 监听文件变化
    async handleHotUpdate({ file, server }) {
      if (isBusinessFile(file)) {
        await updateTypes(file)
        server.ws.send({
          type: 'custom',
          event: 'elpis:types-updated'
        })
      }
    }
  }
}

// 生成的类型文件示例
declare module '@elpis/core' {
  // Controller 类型
  export interface Controllers {
    user: UserController
    order: OrderController
    product: ProductController
  }
  
  // Service 类型
  export interface Services {
    user: UserService
    order: OrderService
    product: ProductService
  }
}

4. AI 辅助开发

// AI 辅助功能
interface AIAssistant {
  // DSL 生成
  generateDSL: {
    fromDescription(desc: string): Promise<Model>
  }
  
}

// 使用示例
const ai = new AIAssistant()
const model = await ai.generateDSL.fromDescription(
  "创建一个电商订单管理系统，包含订单列表、创建订单、订单详情等功能"
)

5. 模块化重构

// 将框架拆分为独立包
packages/
├── @elpis/core           # 核心运行时
├── @elpis/cli            # 命令行工具
├── @elpis/vite-plugin    # Vite 插件
├── @elpis/middlewares    # 中间件集合
├── @elpis/components     # 组件库
├── @elpis/dsl            # DSL 解析器
├── @elpis/types          # 类型定义
└── @elpis/utils          # 工具函数

总结

Elpis 框架通过 DSL 驱动的架构设计，成功实现了业务开发的标准化和自动化 解决了传统开发中的重复劳动问题。

核心价值

• 开发效率提升：通过 DSL 配置快速生成业务功能
• 维护成本降低：统一的架构和规范减少了维护难度
• 扩展性良好：插件化设计支持灵活扩展
• 类型安全：全栈 TypeScript 保证代码质量
• 开发体验优秀： 按约定自动导入提供极致开发体验

技术亮点

1. DSL 驱动：将业务逻辑抽象为配置，大幅降低开发成本
2. 全栈类型安全：前后端共享类型定义，减少运行时错误
3. 灵活的中间件系统：支持用户自定义和组合中间件
4. 自动化程度高：从模型到 API、从配置到页面的全自动生成
5. 现代化工具链：Vite、TypeScript、Vue 3 等现代技术栈