elpis-core:基于 Koa 的轻量级 Web 应用框架

手搓elpis引擎前：先搞懂 Egg.js 与 Koa 的核心逻辑

在前端工程化与 Node.js 后端开发深度融合的今天，企业级应用对框架的 "规范性""可扩展性" 和 "开箱即用能力" 要求越来越高。而 Egg.js 正是为解决这一需求而生 ------ 它并非从零构建，而是站在 Koa 这个 "轻量级框架巨人" 的肩膀上，通过约定优于配置的设计思想，封装出一套适合企业级开发的完整解决方案。

在动手搓一个简易版 Egg.js 前，我们必须先理清两个核心问题：Koa 是如何实现 "轻量运行" 的？Egg.js 又在 Koa 基础上做了哪些 "企业级增强"？这篇文章会先带你吃透这两个框架的核心流程与思想，为后续的 "手搓实践" 打下基础。

一、先懂基石：Koa 的核心运行流程

Egg.js 基于 Koa 构建，本质是 Koa 的 "增强版"。要理解 Egg.js，必须先搞懂 Koa 最核心的 "中间件洋葱模型" 与 "请求处理流程"------ 这是 Koa 所有能力的基础。

1. Koa 是什么？------ 轻量、灵活的 Node.js 框架

Koa 是由 Express 原团队开发的 Node.js Web 框架，核心定位是 "轻量级中间件框架"：它本身只提供最基础的 HTTP 服务能力（如创建服务、解析请求、处理响应） ，没有内置路由、模板引擎等功能，但通过 中间件机制 让开发者可以灵活扩展功能。

用一句话概括 Koa 的特点： "小而美，靠中间件生态打天下" 。

2. Koa 核心：中间件洋葱模型

Koa 最标志性的设计是 "中间件洋葱模型"，这也是它与 Express 中间件机制的核心区别。我们通过一个例子先直观感受：

js 复制代码

const Koa = require('koa');
const app = new Koa();

// 中间件1
app.use(async (ctx, next) => {
  console.log('中间件1：开始');
  await next(); // 调用下一个中间件
  console.log('中间件1：结束');
});

// 中间件2
app.use(async (ctx, next) => {
  console.log('中间件2：开始');
  await next(); // 调用下一个中间件
  console.log('中间件2：结束');
});

// 业务处理（最后一个"中间件"）
app.use(async (ctx) => {
  console.log('业务处理：返回响应');
  ctx.body = 'Hello Koa';
});

app.listen(3000);

当客户端发起请求时，控制台输出顺序是：

中间件1：开始 → 中间件2：开始 → 业务处理：返回响应 → 中间件2：结束 → 中间件1：结束

这个流程就像 "剥洋葱"：

进入阶段：请求从外层中间件（中间件 1）依次进入内层中间件（中间件 2 → 业务处理）；
退出阶段：业务处理完成后，响应从内层中间件（业务处理 → 中间件 2）依次回传外层中间件（中间件 1），最终返回给客户端。

而实现这一模型的核心是 next() 函数 ------ 它是一个异步函数，通过 await next() 可以 "暂停当前中间件"，等待后续中间件执行完成后，再继续执行当前中间件的剩余逻辑。

3. Koa 完整请求处理流程（极简版）

Koa 处理一个 HTTP 请求的完整流程：

关键说明：

ctx 对象 ：Koa 封装了 Node.js 原生的 req（请求对象）和 res（响应对象），提供了 ctx.request（请求信息）、ctx.response（响应信息）、ctx.body（设置响应内容）等便捷 API，简化开发；

中间件链 ：所有通过 app.use() 注册的中间件，会按注册顺序组成一条 "中间件链"，请求会沿着这条链按洋葱模型流转；

路由与中间件的关系：路由不是独立的一层，而是作为中间件存在，请求先进入应用级中间件，然后到达路由匹配中间件

无内置功能 ：Koa 本身不处理路由（需用 koa-router 中间件）、不处理静态资源（需用 koa-static 中间件），所有额外功能都靠中间件扩展。

二、再看增强：Egg.js 的核心思想与运行流程

koa 的 "轻量灵活" 是优势，但也带来了一个问题：企业级开发中，团队需要花大量时间约定 "目录结构""编码规范""中间件使用规则"------ 比如 "路由放哪？""服务逻辑放哪？""配置怎么管理？"。

而 Egg.js 的核心目标就是解决这个问题：在 Koa 基础上，通过 "约定优于配置" 的思想，提供一套标准化的企业级开发方案，让团队不用再纠结 "规范"，专注业务开发。

1. Egg.js 核心思想：约定优于配置

这是 Egg.js 最核心的设计哲学，简单理解就是：

约定：Egg.js 预先定义好一套 "目录结构" 和 "功能映射规则"，比如 "路由定义在 app/router.js""业务逻辑写在 app/controller""服务逻辑写在 app/service"；
配置：如果团队需要自定义某些规则（如修改配置文件路径、调整中间件顺序），也可以通过配置文件覆盖约定，兼顾 "标准化" 和 "灵活性"。

举个最直观的例子：在 Koa 中，你可以把路由写在任何地方，但在 Egg.js 中，路由必须定义在 app/router.js------ 这就是 "约定"，团队所有人都按这个规则写，代码结构自然统一。

2. Egg.js 对 Koa 的核心增强点

Egg.js 并非替换 Koa，而是在 Koa 基础上做了上层封装，核心增强可以概括为 4 点：

增强维度	Koa 现状	Egg.js 增强方案	解决的企业级问题
目录结构	无约定，开发者自由组织	标准化目录（app/controller、app/service 等）	统一团队代码结构，降低协作成本
功能模块	需手动集成中间件（路由、ORM 等）	内置核心模块（路由、配置、日志、ORM 等）	开箱即用，减少重复集成工作
生命周期管理	无统一的应用启动 / 关闭生命周期	提供完整生命周期钩子（didLoad、willReady 等）	方便管理 "应用启动时初始化数据库" 等场景
扩展性	中间件扩展，无插件机制	插件机制（Plugin）+ 框架继承	支持业务模块复用（如封装 "用户认证插件"）

三、 Koa 与 Egg.js 的核心逻辑链

看到这里，我们应该能理清两者的关系了：

基石：Koa 提供 "中间件洋葱模型" 和 "基础 HTTP 处理能力"，是 Egg.js 的底层框架；
增强：Egg.js 在 Koa 基础上，通过 "约定优于配置" 提供标准化目录、内置核心模块、完善生命周期，解决企业级开发的 "规范" 和 "效率" 问题；
本质：Egg.js 不是 "取代 Koa"，而是 "封装 Koa"，让 Koa 更适合大规模、多团队的企业级应用开发。

理解了这个逻辑链，接下来我们就可以动手 "手搓简易版 Egg.js" 了 ------ 核心思路就是：先搭建 Koa 基础框架，再逐步添加 "标准化目录""路由映射""Controller/Service 分层" 等 Egg.js 核心特性，一步步还原 Egg.js 的设计思路。

elpis 服务引擎框架核心思路：简易版 Egg.js 的设计与实现

elpis 服务引擎框架（以下简称 elpis）是基于 Koa 打造的简易版 Egg.js，核心目标是落地 "约定优于配置" 的设计思想 ------ 通过标准化目录结构和自动化加载逻辑，让开发者无需关注基础框架搭建，只需按约定专注业务开发。

一、核心设计理念：约定优于配置

elpis 的核心逻辑可通过一句话概括： "约定目录结构，用引擎自动加载，开发者专注业务" 。

我们预先定义好 "路由、中间件、控制器" 等核心模块的存放位置（如路由放 app/router、控制器放 app/controller），再通过 elpis-core（引擎内核）自动扫描这些目录，将模块加载到 Koa 实例中。整个过程无需手动配置模块路径或注册逻辑，彻底简化基础开发流程。

下图直观展示了 elpis 的核心工作流（从 "约定目录" 到 "引擎加载" 再到 "服务运行"）：

二、标准化项目结构：约定目录即规则

elpis 严格定义了项目目录结构，每个目录对应固定功能模块，开发者只需按目录存放文件即可，无需额外配置。完整结构如下：

csharp 复制代码

elpis
  |-- app/                # 核心业务目录（按约定存放业务模块）
  |   |-- controller/     # 控制器层：处理请求、调用服务、返回响应
  |   |-- extend/         # 扩展层：全局能力扩展（如工具函数、API 增强）
  |   |-- middleware/     # 中间件层：局部中间件（如接口权限校验）
  |   |-- public/         # 静态资源层，静态文件
  |   |-- router/         # 路由层：定义"请求路径→控制器"映射
  |   |-- router-schema/  # 路由校验层：JSON-Schema 接口参数规则
  |   |-- service/        # 服务层：封装数据处理、第三方接口调用（供控制器复用）
  |   |-- middlewares.js  # 全局中间件配置：注册全链路生效的中间件
  |-- config/             # 配置目录（区分环境的差异化配置）
  |-- elpis-core/         # 引擎内核（核心能力：自动加载、环境适配）
  |   |-- loader/         # 加载器集合：对应各模块的自动加载逻辑
  |   |   |-- config.js   # 配置加载器：加载 config 目录配置
  |   |   |-- controller.js # 控制器加载器：加载 controller 模块
  |   |   |-- extend.js   # 扩展加载器：加载 extend 模块
  |   |   |-- middleware.js # 中间件加载器：加载 middleware 模块
  |   |   |-- router-schema.js # 路由校验加载器：加载 router-schema 规则
  |   |   |-- router.js   # 路由加载器：加载 router 模块
  |   |   |-- service.js  # 服务加载器：加载 service 模块
  |   |-- env.js          # 环境判断工具：区分本地/测试/生产环境
  |   |-- index.js        # 引擎入口：整合加载器、初始化 Koa 实例
  |-- index.js            # 项目入口：启动 elpis 引擎

三、核心能力：elpis-core 自动加载器

elpis-core 是 elpis 的 "大脑"，通过一系列 "加载器（Loader）" 实现 "约定目录→自动加载" 的核心逻辑。每个加载器对应一个模块（如配置、控制器、中间件），负责扫描目录、解析文件、挂载到 Koa 实例上。

下面解析Config Loader加载器的实现：

Config Loader

作用：加载 config 目录下的配置文件，支持 "默认配置 + 环境配置" 覆盖逻辑，满足本地、测试、生产环境的差异化需求。

核心逻辑：

优先加载 config.default.js（默认配置，所有环境通用）；
根据当前环境（通过 env.js 判断）加载对应环境配置（如本地环境加载 config.local.js）；
环境配置覆盖默认配置，最终挂载到 app.config 上，供全局使用。

代码实现：

js 复制代码

const path = require("path");
const { sep } = path;

/**
 * Config Loader：环境差异化配置加载
 * @description 默认配置（config.default.js）为基础，环境配置（如config.local.js）覆盖默认配置
 * @param {Object} app - Koa 实例（elpis 增强版）
 * @支持环境：本地（local）、测试（beta）、生产（prod）
 */
module.exports = (app) => {
  // 1. 定位 config 目录路径
  const configPath = path.resolve(app.baseDir, `.${sep}config`);

  // 2. 加载默认配置（必选，无则打印警告）
  let defaultConfig = {};
  try {
    defaultConfig = require(path.resolve(configPath, `.${sep}config.default.js`));
  } catch (error) {
    console.log("[exception] 未找到默认配置文件：config.default.js");
  }

  // 3. 加载当前环境配置（可选，无则打印警告）
  let envConfig = {};
  try {
    if (app.env.isLocal()) {
      envConfig = require(path.resolve(configPath, `.${sep}config.local.js`));
    } else if (app.env.isBeta()) {
      envConfig = require(path.resolve(configPath, `.${sep}config.beta.js`));
    } else if (app.env.isProduction()) {
      envConfig = require(path.resolve(configPath, `.${sep}config.prod.js`));
    }
  } catch (error) {
    console.log(`[exception] 未找到当前环境配置文件（${app.env.getEnv()}）`);
  }

  // 4. 合并配置：环境配置覆盖默认配置，挂载到 app.config
  app.config = Object.assign({}, defaultConfig, envConfig);
};

除了上述 config loader加载器，elpis-core/loader 还包含多个核心加载器，各自负责特定模块的加载

四、加载顺序：loader执行优先级

js 复制代码

module.exports = {
  /**
   * 启动项目
   * @param {Object} options - 项目配置
   *
   */
  start(options = {}) {
    // 创建 koa 实例
    const app = new koa();
    //应用配置
    app.options = options;
    //基础路径
    app.baseDir = process.cwd();
    //业务文件路径
    app.businessPath = path.resolve(app.baseDir, `.${sep}app`);
    //初始化环境配置
    app.env = env();

    console.log(`-- [start] env: ${app.env.get()} --`);
    //加载middleware
    middlewareLoader(app);
    console.log(`-- [start] load middleware done --`);
    //加载routerSchema
    routerSchemaLoader(app);
    console.log(`-- [start] load routerSchema done --`);
    //加载controller
    controllerLoader(app);
    console.log(`-- [start] load controller done --`);
    //加载 service
    serviceLoader(app);
    console.log(`-- [start] load service done --`);
    //加载config
    configLoader(app);
    console.log(`-- [start] load config done --`);
    //加载extend
    extendLoader(app);
    console.log(`-- [start] load extend done --`);
    // 注册全局中间件
    try {
      require(`${app.businessPath}${sep}middleware.js`)(app);
      console.log(`-- [start] load appMiddleware done --`);
    } catch (error) {
      console.log(`[exception] there is no global middleware file.`);
    }
    //注册路由
    routerLoader(app);
    console.log(`-- [start] load router done --`);

    try {
      //启动服务
      const port = process.env.PORT || 8080;
      const host = process.env.HOST || "0.0.0.0";
      app.listen(port, host, () => {
        console.log(`Server is running at http://localhost:${port}`);
      });
    } catch (error) {
      console.error(error);
    }
  },
};

五、总结：elpis 框架的核心价值

elpis 作为简易版 Egg.js，通过 "约定目录 + 自动加载" 的设计，解决了 Koa 原生开发中的两个核心痛点：

消除 "配置混乱" ：无需手动配置模块路径、注册中间件，按目录约定即可自动加载；
降低 "协作成本" ：标准化目录结构让团队成员无需熟悉 "个人自定义配置"，快速上手业务开发。

本质上，elpis 是对 Koa 生态的 "上层封装"------ 保留 Koa 灵活的洋葱模型，同时通过 elpis-core 实现 "企业级开发所需的标准化能力"，让我们从 "基础搭建" 中解放出来，专注于业务逻辑本身。