行业背景与痛点
企业级全栈应用开发长期面临框架分层混乱的问题。底层HTTP服务与前端构建工具绑定过深，业务扩展需要修改框架内核代码，每次框架升级都会导致业务代码兼容性问题。
很多全栈框架为了追求开箱即用的集成度，把业务代码和框架内核耦合在一起，业务模块无法独立剥离复用。不同业务团队基于同一框架开发时，经常出现API规范不统一、返回格式不一致、鉴权逻辑重复开发的问题。
部分传统全栈框架还在使用老旧的Koa内核，配合webpack打包前端资源，开发启动速度慢，热更新体验差，无法适配现代TypeScript全栈开发的需求，迁移成本极高。
项目概述
elpis是一个面向企业场景的全栈应用开发框架，核心定位是分离框架内核与业务代码，通过模块化注入的方式支持业务扩展。框架内核统一提供底层能力，业务项目只需要专注于业务逻辑开发，不需要修改框架本身的代码。
该项目经历了大版本重构，从原有的Koa内核完全迁移到NestJS，同时保留了原有对外API的兼容性，降低了老版本业务项目的迁移成本。当前项目处于活跃维护状态，核心功能已经稳定，支持生产环境部署。
技术架构深度分析
技术选型思路
HTTP内核从Koa迁移到NestJS，是基于企业级开发的场景选择。NestJS原生支持TypeScript，自带模块化开发体系，集成了依赖注入、守卫、管道、过滤器等企业开发常用的能力，社区生态完善，开发人员上手成本低。
前端构建工具选择Vite，替代传统的webpack打包方案。Vite基于ESModule实现开发阶段的按需编译，项目启动速度和热更新速度比传统打包工具提升数倍，生产环境使用Rollup打包，输出产物体积更小，适配现代前端项目的开发需求。
架构设计逻辑
整体架构遵循「框架内核+业务模块」的分离设计，框架内核负责统一提供底层HTTP服务、配置管理、数据库连接、日志服务、前端构建、模板渲染这些通用能力，所有业务逻辑都以独立Nest Module的形式存在于业务项目中，框架启动时自动扫描注入业务模块。
这种设计的优势在于，框架升级不会影响业务代码，业务模块可以独立版本管理，不同业务项目可以复用同一套框架内核，只需要扩展自己的业务模块即可。同时兼容老版本项目的API规范，路径规则、状态码定义、Cookie行为都和老版本保持一致，老项目迁移只需要重新编译业务代码，不需要修改业务逻辑。
核心模块组织
框架内核所有代码统一归位到顶层app目录，与pages、vite、public、view等目录同级，结构清晰，开发者可以快速定位核心代码位置。app目录下按照功能划分不同子模块：main.ts是Nest启动入口，app.module.ts作为根模块注册配置和框架核心能力，elpis.module.ts负责聚合所有框架内置模块，完成业务模块扫描和兜底处理。
app/common目录统一存放全局的守卫、管道、异常过滤器、拦截器和静态资源兜底逻辑，保证全项目的API行为一致。app/extend目录存放数据库连接、日志服务这些可扩展的基础服务提供者，开发者可以根据自己的需求替换默认实现。app/modules存放框架内置的核心业务模块，比如项目管理、页面渲染模块，app/vite目录封装了Vite的开发服务和生产构建逻辑，对外暴露统一的调用接口。
核心功能详解
兼容式内核迁移
本次大版本重构删除了原有Koa内核和loader机制，框架和业务项目统一采用Nest Module的写法，但是对外暴露的serverStart和frontendBuild方法签名保持不变，默认服务端口仍然为8080。API路径规则、错误状态码定义、Cookie行为都和1.0版本完全一致，原有业务项目不需要修改业务代码即可完成框架升级，大幅降低了迁移成本。
业务模块自动扫描注入
框架启动时会自动扫描业务项目编译后dist/modules目录下的所有*.module.js文件，将业务模块注入到根模块中，最后加载兜底模块处理未匹配的路由。业务开发者只需要按照Nest Module的规范编写业务代码，打包后放在指定目录即可，不需要修改框架内核的模块注册代码，实现了框架与业务的完全解耦。
统一扩展能力接口
框架内置的数据库、日志等基础能力都以可注入Provider的形式提供，开发者可以在业务模块中替换默认实现，不需要修改框架内核代码。全局守卫、管道、异常过滤器统一在框架层面注册，保证所有业务API的行为一致，避免业务团队重复开发相同的逻辑，降低规范落地的成本。
一体化前后端构建
框架封装了Vite的开发启动和生产构建逻辑，对外暴露统一的frontendBuild方法，业务项目不需要单独配置Vite，只需要调用框架提供的方法即可完成前端资源构建。开发阶段支持Vite的热更新能力，生产构建输出优化后的静态资源，配合后端模板渲染，实现同构直出或者前后端混合渲染。
TypeScript类型增强
项目提供了专门的类型契约目录，针对Express的Request对象进行类型扩展，添加业务常用的projKey等属性，保证全栈开发过程中的类型安全，TypeScript编译器可以正确识别扩展属性，避免开发阶段的类型错误，提升大型项目的开发效率和代码健壮性。
AI能力预留扩展
框架内核已经预留了ai目录，规划集成Agent、MCP、RAG、Skill、Guardrail等AI相关能力，相关设计文档已经存放在sdd/part3-agent目录，后续版本会逐步开放核心能力，适配当前企业级AI应用开发的需求，开发者可以基于预留的扩展接口提前对接AI能力。
完善的开发联调支持
支持npm link方式进行本地联调，修改框架源码后可以直接在本地业务项目中验证效果，不需要发布版本，适合框架贡献者和深度定制开发者使用。框架自带回归测试用例，每次修改核心代码后可以快速验证兼容性，避免新功能引入线上问题。
项目地址：https://github.com/fsiaonma/elpis
⭐ Stars：550
🔍 来源：GitHub
elpis
微信扫一扫，打赏作者吧～
网友评论