序言

框架名称：GUIYUAN（归元）

  pie
    title 技术栈权重估计
    "前端 ( Vue3 + Element Plus )" : 40
    "后端 ( Node.js + Koa2 + log4js )" : 40
    "构建工具 ( Webpack5 )" : 10
    "数据库 ( MySQL )" : 10
  

行业现状与需求推倒

痛点与目标：

需求：

技术选型

业界方案调研

• 定制化能力薄得像纸，想加点个性就得推翻重来
• 不适合多客户交付场景，一个系统交给十个客户，能拧出十个分支
• 模块太多，真正用上的没几个，反而拖慢了交付
• 迭代一多，熵增爆表，越改越乱

• 配置自由度太高，非常复杂，学起来头大，用起来更大
• 若处理不好容易代码断代，此时对提效没有实质的提高，反而成了负担
• 通用配置场景搞得飞起，但碰上强业务领域（比如财务管理），就露馅了，感觉“工具箱里全是锤子，但现在我手里是一颗螺丝钉”。

我的方案

• 🧱粒子：算子服务-把系统拆成一个个原子级的算子服务（粒度够小，组合够灵）
• 🌀AOP领域模型-切面注入、职责解耦，模块化构建你的业务宇宙
• 🧩面向对象建站-按类建模块，按需装功能，像搭乐高一样做系统

架构设计

项目架构图

数据层

数据库选择

虽然我主力是 Node.js，MongoDB 和它天生是一对，“一个写得快，一个存得爽”，配合得堪称默契。但技术选型这事吧，不能只看“感情”，还得考虑“家世背景”——毕竟放眼市面上，大多数公司后端主力语言还是 Java、Go，这些语言对MySQL 的支持更成熟，生态更健全。
所以，权衡下来，MySQL 更适合作为团队未来技术迁移与栈转型的基石。它是数据库界的“老干部”，稳定、可靠、文档多、社区大，迁移起来省心，招人也更容易。

日志系统选择

日志这事，向来是“事后诸葛”的关键，出问题的时候靠它定位，没问题的时候靠它安神。对于 Node.js 项目，我选的是老牌选手 —— Log4js。
它虽然名字听着像 Java 家的远房亲戚，但其实在 Node 生态里也算是“德高望重”。配置灵活、输出丰富，支持分等级、按时间或文件大小分割，还能愉快地和各种日志中台打通。
一句话总结：Log4js 就像个靠谱的管家，默默记录项目的喜怒哀乐，关键时刻还能“翻旧账”，帮你把锅找对人😝。

BFF层

展示层

方案设计

DSL与总览图

DSL是一种专门为某个特定领域或问题域设计的编程语言。它的主要目的是提供一种简洁、易于使用和高效的方式来描述和解决特定领域的问题。本框架通过dsl ->解析器->模版页面
大致框架如下：其中绿色为自定义组件：可自行变动保证灵活性，蓝色部分为已设计部分：固定部分减少重复操作

服务端-BFF层方案设计

  flowchart LR
  A["`**项目文件** 
  按照约定存放在app根目录下的对应目录`"]
  B["`**elpis-core** 
  利用编写的 loader对项目文件进行解析 挂载到项目中`"]
  C["`**运行时** 
  middleware 
  router 
  config 
  controller 
  service 
  extend`"]
  A --> B --> C
  

展示层-前端架构设计

基于node.js实现服务器内核引擎

宏观角度

  flowchart TD
  BFF["BFF"]:::bff
  Access["接入层"]:::access
  Business["业务层"]:::business
  Service["服务层"]:::service

  BFF --> Access
  Access --> Business
  Business --> Service
  BFF --> Business
  BFF --> Service

  classDef bff stroke:#f66,stroke-width:2px,stroke-dasharray:5 5,color:#f66
  classDef access stroke:#f90,stroke-width:2px,stroke-dasharray:5 5,color:#f90
  classDef business stroke:#0c0,stroke-width:2px,stroke-dasharray:5 5,color:#0c0
  classDef service stroke:#09f,stroke-width:2px,stroke-dasharray:5 5,color:#f90
  

1. 接入层

• 接口路由处理，区分API请求，页面请求
• 路由规则校验：请求是否满足最基本的校验
• 路由中间件：是否携带所需的参数，认证是否通过等

2. 业务层

• controller 处理器
• env 环境区分
• config 全局变量提取
• extend 服务拓展插件
• schedule 定时任务
  3. 服务层
• service处理器，是跟数据层的交互

解析器

• router-loader 解析router请求文件
  • 页面请求，
  • API请求
• router-schema-loader:解析API参数类型校验文件
• middleware-loader: 解析自定义中间件文件
• controller-loader: 解析逻辑处理文件
• service-loader: 解析服务文件（日志，mysql,调用外部服务等）
• extend-loadr: 解析扩展文件
• config-loader: 解析配置文件

koa洋葱模型

业务逻辑前遵从：先用先处理
业务逻辑后遵从：后用先处理

Loader加载器详细实现

前面我们已经设计好了解析器的思路，接下来看看如何具体实现这些 loader，让”约定大于配置”真正落地。

  flowchart LR
  A[磁盘文件<br/>app/controller/*.js<br/>app/service/*.js<br/>app/router/*.js]
  B[Loader解析器<br/>controller-loader<br/>service-loader<br/>router-loader]
  C[运行时内存<br/>app.controller<br/>app.service<br/>app.router]
  A --> B --> C
  

Controller & Service Loader

这两个 loader 的核心逻辑一致，都是通过 glob 扫描目录下的所有 JS 文件，然后按路径层级自动挂载到 app 对象上。

核心特性：

• 自动扫描：使用 glob.sync 扫描 app/controller/**/*.js 和 app/service/**/*.js
• 路径映射：app/controller/user-info/login-controller.js → app.controller.userInfo.loginController
• 驼峰转换：自动将 - 和 _ 转为驼峰命名
• 类实例化：每个文件导出一个类，loader 自动 new 成实例

// app/controller/user/login.js
module.exports = (app) => {
  return class LoginController {
    async login(ctx) {
      // 使用 service
      const result = await app.service.user.login.doLogin(ctx.request.body)
      ctx.body = result
    }
  }
}

// 使用时：
router.post('/login', app.controller.user.login.login)

这样做的好处：

1. 不需要手动 require 导入
2. 目录结构即代码结构
3. 新增功能只需新建文件，框架自动识别

Router Loader

Router Loader 职责是注册所有路由规则，并兜底处理 404 情况。

// app/router/user.js
module.exports = (app, router) => {
  router.post('/api/user/login', app.controller.user.login.login)
  router.get('/api/user/info', app.controller.user.info.getInfo)
}

核心机制：

• 扫描 app/router/**/*.js 所有路由文件
• 每个文件接收 (app, router) 参数，自行注册路由
• 最后添加兜底路由 router.all('*') 重定向到首页，提升健壮性

Middleware & RouterSchema Loader

Middleware Loader：加载自定义中间件，支持在路由中按需使用

// app/middleware/auth.js
module.exports = (options) => {
  return async (ctx, next) => {
    // 鉴权逻辑
    if (!ctx.headers.token) {
      ctx.throw(401, 'Unauthorized')
    }
    await next()
  }
}

RouterSchema Loader：加载 API 参数校验规则，使用 ajv 进行 JSON Schema 校验

// app/router-schema/user.js
module.exports = {
  '/api/user/login': {
    type: 'object',
    required: ['username', 'password'],
    properties: {
      username: { type: 'string' },
      password: { type: 'string' }
    }
  }
}

Config & Extend Loader

Config Loader：加载不同环境的配置文件

// config/config.default.js  默认配置
// config/config.local.js    本地开发配置
// config/config.production.js  生产环境配置

Extend Loader：扩展 app 能力，比如数据库连接、日志工具等

// app/extend/logger.js
const log4js = require('log4js')
module.exports = (app) => {
  app.logger = log4js.getLogger()
}

GuiYuan-Core 启动流程

框架启动遵循固定的加载顺序，确保依赖关系正确：

  flowchart TD
  A[创建 Koa 实例] --> B[初始化环境配置 env]
  B --> C[加载 middleware 中间件]
  C --> D[加载 routerSchema 校验规则]
  D --> E[加载 controller 控制器]
  E --> F[加载 service 服务]
  F --> G[加载 config 配置]
  G --> H[加载 extend 扩展]
  H --> I[注册全局中间件 app/middleware.js]
  I --> J[加载 router 路由]
  J --> K[启动服务 app.listen]
  

// index.js 启动入口
const GuiYuanCore = require('./guiYuan-core')

GuiYuanCore.start({
  name: 'GuiYuan',
  homePage: '/'
})

启动时控制台输出：

-- [start] env: local
-- [start] load middleware done --
-- [start] load routerSchema done --
-- [start] load controller done --
-- [start] load service done --
-- [start] load config done --
-- [start] load extend done --
-- [start] global appMiddleware done --
-- [start] load router done --
Server is running on http://0.0.0.0:8080

前端工程化建设 - Webpack5 多入口架构

多页面应用架构设计

不同于单页应用（SPA），GUIYUAN 采用了多页面应用（MPA）架构，原因如下：

1. 多系统建设需求：一个平台可能包含多个独立子系统（用户中心、数据看板、配置中心等）
2. 按需加载：每个系统独立打包，避免首屏加载过大
3. 隔离性强：各系统间互不干扰，方便独立部署和维护

  flowchart LR
  A[app/pages] --> B[page1/entry.page1.js]
  A --> C[page2/entry.page2.js]
  A --> D[page3/entry.page3.js]
  B --> E[打包 → entry.page1.tpl]
  C --> F[打包 → entry.page2.tpl]
  D --> G[打包 → entry.page3.tpl]
  

约定式入口配置

框架通过 entry.*.js 命名约定自动识别入口文件：

app/pages/
├── page1/
│   ├── entry.page1.js   # 入口文件
│   ├── page1.vue
│   └── components/
├── page2/
│   ├── entry.page2.js
│   └── page2.vue
└── common/
    ├── curl.js
    └── utils.js

Webpack 配置中通过 glob 自动扫描：

// app/webpack/config/webpack.base.js
const pageEntries = {};
const entryList = path.resolve(process.cwd(), './app/pages/**/entry.*.js')
glob.sync(entryList).forEach((file) => {
  const entryName = path.basename(file, '.js')
  pageEntries[entryName] = file // entry.page1: './app/pages/page1/entry.page1.js'
})

这样新增页面时：

1. 创建 app/pages/new-page/entry.newPage.js
2. 重启 webpack，自动识别并打包
3. 无需手动修改 webpack 配置

Webpack 核心配置解析

1. 模块解析（Module Rules）

2. 别名配置（Alias）

简化导入路径，提升开发体验：

resolve: {
  alias: {
    $pages: path.resolve(process.cwd(), './app/pages'),
    $common: path.resolve(process.cwd(), './app/pages/common'),
    $store: path.resolve(process.cwd(), './app/pages/store'),
  }
}

// 使用示例：
import curl from '$common/curl.js'  // 代替 '../../../common/curl.js'

3. 代码分割优化（SplitChunks）

将代码拆分为三类，充分利用浏览器缓存：

  pie
    title 代码分割策略
    "vendor（第三方库）" : 40
    "common（公共模块）" : 20
    "entry.page（业务代码）" : 40
  

splitChunks: {
  cacheGroups: {
    vendor: { // 第三方依赖（vue、element-plus等）
      test: /[\\/]node_modules[\\/]/,
      name: 'vendor',
      priority: 20,  // 优先级最高
    },
    common: { // 项目公共模块（utils、components）
      name: 'common',
      minChunks: 2,  // 被引用 2 次以上才提取
      priority: 10,
    }
  }
}

优势：

• vendor.js：第三方库基本不变，浏览器长期缓存 ✅
• common.js：公共模块改动少，缓存命中率高 ✅
• entry.page.js：业务代码频繁更新，单独打包 ✅

4. 多入口 HTML 生成

使用 html-webpack-plugin 为每个入口生成独立的 .tpl 模板文件：

HtmlWebpackPluginList.push(
  new HtmlWebpackPlugin({
    filename: path.resolve(process.cwd(), './app/public/dist/', `${entryName}.tpl`),
    template: path.resolve(process.cwd(), './app/view/entry.tpl'),
    chunks: [entryName],  // 只注入当前入口的 JS/CSS
  })
)

生成的 .tpl 文件会被 Koa 通过 koa-nunjucks-2 渲染：

// app/router/page.js
router.get('/page1', async (ctx) => {
  await ctx.render('public/dist/entry.page1')  // 渲染 entry.page1.tpl
})

开发环境热更新配置

使用 webpack-dev-middleware + webpack-hot-middleware 实现热更新：

// app/webpack/dev.js
const express = require('express')
const webpack = require('webpack')
const devMiddleware = require('webpack-dev-middleware')
const hotMiddleware = require('webpack-hot-middleware')

const app = express()
const compiler = webpack(webpackConfig)

// 监控文件改动，实时编译
app.use(devMiddleware(compiler, {
  writeToDisk: (filePath) => filePath.endsWith('.tpl'),  // .tpl 文件落地磁盘
  publicPath: webpackConfig.output.publicPath,
}))

// 实现热更新（HMR）
app.use(hotMiddleware(compiler, {
  path: '/hmr',
}))

app.listen(3000, () => {
  console.log('Webpack DevServer 运行在 http://127.0.0.1:3000')
})

开发流程：

1. 启动后端服务：npm run dev（启动 Koa，监听 8080 端口）
2. 启动前端构建：npm run build:dev（启动 Webpack DevServer，监听 3000 端口）
3. 修改 .vue 或 .js 文件，浏览器自动热更新 🔥

环境配置管理

通过环境变量区分开发、测试、生产环境：

{
  "scripts": {
    "dev": "_ENV='local' nodemon ./index.js",
    "beta": "_ENV='beta' nodemon ./index.js",
    "prod": "_ENV='production' nodemon ./index.js",
    "build:dev": "node --max_old_space_size=4096 ./app/webpack/dev.js",
    "build:prod": "node ./app/webpack/prod.js"
  }
}

配置文件加载逻辑：

// guiYuan-core/loader/config.js
const env = process.env._ENV || 'local'
const defaultConfig = require(`${app.baseDir}/config/config.default.js`)
const envConfig = require(`${app.baseDir}/config/config.${env}.js`)

app.config = Object.assign({}, defaultConfig, envConfig)

前端技术栈总结

实战效果展示

目录结构一览

GuiYuan/
├── guiYuan-core/          # 框架核心引擎
│   ├── loader/           # 各类加载器
│   │   ├── router.js
│   │   ├── controller.js
│   │   ├── service.js
│   │   ├── middleware.js
│   │   ├── router-schema.js
│   │   ├── config.js
│   │   └── extend.js
│   ├── index.js          # 框架启动入口
│   └── env.js            # 环境配置管理
├── app/                  # 业务代码目录
│   ├── controller/       # 控制器层
│   ├── service/          # 服务层
│   ├── router/           # 路由层
│   ├── middleware/       # 自定义中间件
│   ├── router-schema/    # API 校验规则
│   ├── extend/           # 扩展功能
│   ├── pages/            # 前端页面
│   │   ├── page1/
│   │   │   ├── entry.page1.js
│   │   │   └── page1.vue
│   │   ├── common/       # 公共模块
│   │   └── store/        # 状态管理
│   ├── view/             # 模板文件
│   ├── public/           # 静态资源
│   └── webpack/          # Webpack 配置
│       ├── config/
│       │   ├── webpack.base.js
│       │   ├── webpack.dev.js
│       │   └── webpack.prod.js
│       ├── dev.js
│       └── prod.js
├── config/               # 环境配置
│   ├── config.default.js
│   ├── config.local.js
│   └── config.production.js
├── index.js              # 项目启动文件
└── package.json

核心优势总结

✅ 约定式开发：新建文件即生效,无需手动注册
✅ 模块化设计：controller/service/router 职责分明
✅ 多入口架构：支持多系统并行开发，按需加载
✅ 热更新开发：修改代码实时预览，开发效率提升 300%
✅ 代码分割优化：充分利用浏览器缓存，加载速度提升 50%
✅ 环境隔离：local/beta/production 配置分离，部署无忧
✅ TypeScript 支持：渐进式引入类型检查，代码更健壮
✅ 扩展性强：通过 extend 机制轻松集成日志、数据库、消息队列等

下一步规划

虽然 GUIYUAN 的基础建设已经完成，但要真正实现”归元”的愿景，还有很多路要走：

Phase 1 - 基础建设 ✅

• ✅ GuiYuan-Core 核心引擎
• ✅ Webpack 多入口工程化
• ✅ 约定式目录结构

Phase 2 - 能力沉淀 🚧

• 🔲 配置化页面生成系统
• 🔲 拖拽式组件编排
• 🔲 通用 CRUD 模板
• 🔲 数据库 ORM 封装（基于 Knex）
• 🔲 权限管理系统

Phase 3 - 平台化 🔮

• 🔲 多租户系统支持
• 🔲 插件市场机制
• 🔲 低代码 DSL 设计
• 🔲 可视化配置后台
• 🔲 CI/CD 自动化部署

结语

GUIYUAN 的诞生，源于对重复劳动的厌倦，也源于对更高效工作方式的向往。

这不仅仅是一个技术框架，更是一种**”让80%的事情归于平台，让20%的创造归于开发者”**的哲学。

路漫漫其修远兮，框架的完善需要时间的打磨和实战的检验。但至少，我们已经迈出了第一步——从0到1，从想法到落地。

接下来，就是在实际项目中不断迭代、优化、沉淀，让 GUIYUAN 真正成为那个能让开发者”佛系高效”的平台。

一切冗余，皆可归元。🌟