@

目录

引言

Aifei 是面向未来的 AI 编程框架，旨在以“Just Service”开发范式降低工程复杂度，提升研发效率与系统稳定性。框架通过模块化设计与插件化能力，提供高性能 Web 服务器、智能 ORM、模板引擎与 AOP 支持，形成从请求处理到数据持久化的完整闭环。其核心理念强调“约定优于配置、扫描优于硬编码、代理优于侵入”，在保证易用性的同时兼顾性能与可扩展性。

项目结构

Aifei 采用多模块 Maven 结构，父工程统一管理版本与依赖，子模块按职责拆分，形成清晰的边界与复用路径：

  • aifei：核心内核（启动、配置、路由、处理器链、插件）
  • aifei-undertow：基于 Undertow 的高性能服务器集成
  • aifei-enjoy：轻量级模板引擎
  • aifei-db：智能 ORM 与 SQL 执行器
  • aifei-json、aifei-log、aifei-proxy：配套工具与扩展模块
  • aifei-all：聚合打包模块
graph TB subgraph "父工程" P["aifei-parent<br/>统一版本与依赖"] end subgraph "核心模块" CORE["aifei<br/>核心内核"] UDT["aifei-undertow<br/>Undertow 服务器"] ENJ["aifei-enjoy<br/>模板引擎"] DB["aifei-db<br/>智能 ORM"] JSON["aifei-json<br/>JSON 工具"] LOG["aifei-log<br/>日志抽象"] PRX["aifei-proxy<br/>代理工厂"] ALL["aifei-all<br/>聚合打包"] end P --> CORE P --> UDT P --> ENJ P --> DB P --> JSON P --> LOG P --> PRX P --> ALL CORE --> UDT CORE --> ENJ CORE --> DB CORE --> PRX CORE --> LOG CORE --> JSON

图表来源

  • [pom.xml:16-25](file://pom.xml#L16-L25)
  • [aifei-undertow/pom.xml:7-28](file://aifei-undertow/pom.xml#L7-L28)
  • [aifei-enjoy/pom.xml:7-31](file://aifei-enjoy/pom.xml#L7-L31)
  • [aifei-db/pom.xml:7-38](file://aifei-db/pom.xml#L7-L38)

章节来源

  • [pom.xml:1-277](file://pom.xml#L1-L277)
<dependency>
    <groupId>cn.aifei</groupId>
    <artifactId>aifei-all</artifactId>
    <version>1.0.1</version>
</dependency>

核心组件

  • 启动入口与生命周期
    • Aifei：负责启动流程编排、命令行参数解析、插件启动与停止、Handler 链构建、服务器启动与停机钩子注册。
    • AifeiConfig：应用配置接口，提供 config(Settings)、config(Routes)、config(Plugins) 三类配置入口，以及 onStart/onStop 生命周期回调。
  • 路由与处理器
    • Router：基于注解扫描与手动注册的路由构建器，支持路径参数、命名参数、Action 重载与 ActionGroup 精确匹配。
    • Routes：对外暴露的路由配置门面，支持扫描与手动添加路由。
    • Handler：处理器抽象，采用 next 链式组合，支持跨层拦截与职责分离。
  • 服务器与插件
    • Server：服务器抽象，需持有下游 Dispatcher 并提供 start/stop。
    • Plugins：插件容器，集中管理插件生命周期。
  • AOP 与代理
    • Aop：便捷的依赖注入与对象创建入口，结合 ProxyFactory 实现业务层 AOP 代理。
  • 模板引擎
    • Engine：模板引擎核心，支持多引擎实例、共享函数/方法、指令扩展、开发模式热加载与压缩优化。
  • ORM
    • AifeiDao：面向 Row/Model 的链式 SQL DSL，内置 insert/update/delete/find/query/paginate 等丰富能力。

章节来源

  • [Aifei.java:46-95](file://aifei/src/main/java/cn/aifei/core/Aifei.java#L46-L95)
  • [AifeiConfig.java:25-51](file://aifei/src/main/java/cn/aifei/config/AifeiConfig.java#L25-L51)
  • [Router.java:60-131](file://aifei/src/main/java/cn/aifei/router/Router.java#L60-L131)
  • [Routes.java:38-88](file://aifei/src/main/java/cn/aifei/config/Routes.java#L38-L88)
  • [Handler.java:22-27](file://aifei/src/main/java/cn/aifei/core/Handler.java#L22-L27)
  • [Server.java:22-38](file://aifei/src/main/java/cn/aifei/server/Server.java#L22-L38)
  • [Plugins.java:26-41](file://aifei/src/main/java/cn/aifei/config/Plugins.java#L26-L41)
  • [Aop.java:89-118](file://aifei/src/main/java/cn/aifei/aop/Aop.java#L89-L118)
  • [Engine.java:51-114](file://aifei-enjoy/src/main/java/cn/aifei/enjoy/Engine.java#L51-L114)
  • [AifeiDao.java:39-115](file://aifei-db/src/main/java/cn/aifei/db/core/AifeiDao.java#L39-L115)

架构总览

Aifei 的整体架构围绕“启动器 → 配置 → 路由 → 处理器链 → 服务器”的主线展开，配合 AOP、ORM、模板引擎与插件系统，形成高内聚、低耦合的模块化体系。

graph TB A["应用入口<br/>Aifei.start(...)"] --> B["配置阶段<br/>AifeiConfig.config(...)"] B --> C["路由构建<br/>Router.scan/add"] B --> D["插件装载<br/>Plugins.start()"] C --> E["处理器链<br/>Handler.next 链"] E --> F["服务器启动<br/>Server.start()"] F --> G["请求处理<br/>Dispatcher/Router/Handler"] G --> H["AOP/拦截器<br/>Aop/Interceptor"] G --> I["模板渲染<br/>Engine"] G --> J["数据访问<br/>AifeiDao/Db"] D --> K["生命周期回调<br/>onStart/onStop"]

图表来源

  • [Aifei.java:46-95](file://aifei/src/main/java/cn/aifei/core/Aifei.java#L46-L95)
  • [AifeiConfig.java:30-50](file://aifei/src/main/java/cn/aifei/config/AifeiConfig.java#L30-L50)
  • [Router.java:156-170](file://aifei/src/main/java/cn/aifei/router/Router.java#L156-L170)
  • [Handler.java:22-27](file://aifei/src/main/java/cn/aifei/core/Handler.java#L22-L27)
  • [Server.java:27-37](file://aifei/src/main/java/cn/aifei/server/Server.java#L27-L37)
  • [Engine.java:186-206](file://aifei-enjoy/src/main/java/cn/aifei/enjoy/Engine.java#L186-L206)
  • [AifeiDao.java:309-317](file://aifei-db/src/main/java/cn/aifei/db/core/AifeiDao.java#L309-L317)

详细组件分析

启动与生命周期（Aifei 与 AifeiConfig）

  • 启动流程要点
    • 命令行参数解析：以“--”开头的参数转换为系统属性，支持开关型与键值型。
    • 配置阶段：回调 AifeiConfig 的 config(Settings/Routes/Plugins)。
    • 插件启动：依次调用 Plugins 中每个插件的 start，异常即终止启动。
    • Handler 链构建：将 List 逆序串联为 next 链。
    • 服务器启动：初始化 Dispatcher 并启动 Server。
    • 停机钩子：Runtime.addShutdownHook 调用 stop，依次停止 Server、onStop、Plugins。
  • 生命周期回调
    • onStart：所有配置与插件准备完成后回调，可使用插件能力。
    • onStop：服务器关闭之后、插件关闭之前回调。
sequenceDiagram participant App as "应用" participant A as "Aifei" participant Cfg as "AifeiConfig" participant Plg as "Plugins" participant H as "Handler链" participant S as "Server" App->>A : 调用 start(aifeiConfig, args) A->>A : 解析命令行参数为系统属性 A->>Cfg : config(Settings/Routes/Plugins) A->>Plg : start() A->>H : 构建 Handler.next 链 A->>S : init(H) + start() Note over A,S : 进程退出时触发停机钩子 A->>S : stop() A->>Cfg : onStop() A->>Plg : stop()

图表来源

  • [Aifei.java:46-95](file://aifei/src/main/java/cn/aifei/core/Aifei.java#L46-L95)
  • [AifeiConfig.java:30-50](file://aifei/src/main/java/cn/aifei/config/AifeiConfig.java#L30-L50)
  • [Plugins.java:30-40](file://aifei/src/main/java/cn/aifei/config/Plugins.java#L30-L40)

章节来源

  • [Aifei.java:46-198](file://aifei/src/main/java/cn/aifei/core/Aifei.java#L46-L198)
  • [AifeiConfig.java:25-51](file://aifei/src/main/java/cn/aifei/config/AifeiConfig.java#L25-L51)
  • [Plugins.java:26-41](file://aifei/src/main/java/cn/aifei/config/Plugins.java#L26-L41)

路由与处理器（Router 与 Handler）

  • 路由扫描与构建
    • 支持类级 @Path 与方法级 @Path，支持入口方法兼容（默认 index）。
    • 支持 Routes 级拦截器优先于全局拦截器。
    • 支持手动添加路由与重复扫描去重。
    • 支持 Action 重载与 ActionGroup，按参数数量与匹配严格度选择最终 Action。
  • 请求匹配与参数提取
    • 路径参数参与匹配；命名参数可缺省，但需满足存在性校验。
    • 对 ActionGroup 进行参数精确匹配，优先匹配参数数量多的 Action，避免误匹配。
  • 处理器链
    • Handler 抽象定义 handle(path, input, output)；通过 next 串联，形成可插拔的处理管线。
flowchart TD Start(["请求进入"]) --> Match["Router.getAction(path,input)"] Match --> Found{"命中 Action？"} Found --> |否| NotFound["返回未命中"] Found --> |是| Act["获取 Action 与参数"] Act --> ParamMatch{"参数匹配通过？"} ParamMatch --> |否| NotFound ParamMatch --> |是| Chain["Handler.next 链处理"] Chain --> Done(["完成"])

图表来源

  • [Router.java:355-414](file://aifei/src/main/java/cn/aifei/router/Router.java#L355-L414)
  • [Handler.java:22-27](file://aifei/src/main/java/cn/aifei/core/Handler.java#L22-L27)

章节来源

  • [Router.java:60-443](file://aifei/src/main/java/cn/aifei/router/Router.java#L60-L443)
  • [Routes.java:38-88](file://aifei/src/main/java/cn/aifei/config/Routes.java#L38-L88)
  • [Handler.java:22-27](file://aifei/src/main/java/cn/aifei/core/Handler.java#L22-L27)

服务器与插件（Server 与 Plugins）

  • Server 接口
    • init(Dispatcher)：持有下游调度器。
    • start()/stop()：启动与停止。
  • Plugins 容器
    • add(Plugin)：注册插件。
    • 生命周期：集中启动与停止，异常时记录日志并终止启动。

章节来源

  • [Server.java:22-38](file://aifei/src/main/java/cn/aifei/server/Server.java#L22-L38)
  • [Plugins.java:26-41](file://aifei/src/main/java/cn/aifei/config/Plugins.java#L26-L41)

AOP 与代理（Aop 与 ProxyFactory）

  • Aop 便捷入口
    • Aop.get(Class)/get(name)：创建并注入依赖。
    • Aop.inject(Object)：对已有对象进行依赖注入。
    • 与 Singleton/Before 注解配合，实现业务层 AOP 代理。
  • ProxyFactory
    • 业务层代理工厂接口，结合 AopKit 实现对象创建与代理。

章节来源

  • [Aop.java:89-118](file://aifei/src/main/java/cn/aifei/aop/Aop.java#L89-L118)
  • [ProxyFactory.java:22-24](file://aifei/src/main/java/cn/aifei/proxy/ProxyFactory.java#L22-L24)

模板引擎（Engine）

  • 多引擎实例与共享对象
    • 支持 main 引擎与自定义引擎实例，共享函数/方法、枚举、指令扩展。
  • 开发模式与缓存
    • devMode 下模板热加载；String 模板缓存可按需开启。
  • 输出与编码
    • 支持自定义 EncoderFactory（含 JDK 编码器）与缓冲区大小配置。
  • 压缩与极速模式
    • 可开启 Compressor 压缩静态内容；支持极速模式减少反射调用。

章节来源

  • [Engine.java:51-789](file://aifei-enjoy/src/main/java/cn/aifei/enjoy/Engine.java#L51-L789)

ORM（AifeiDao）

  • 链式 DSL 与类型安全
    • insert/update/delete/find/query/paginate/forEach 等丰富 API。
    • 支持 Enjoy SQL 语法与 sqlId 缓存，提升性能与可维护性。
  • 参数与类型转换
    • 内置多种 queryXxx 类型转换方法，简化结果处理。
  • 分页与大数据遍历
    • 支持分页与分页遍历，适合大数据场景。

章节来源

  • [AifeiDao.java:39-849](file://aifei-db/src/main/java/cn/aifei/db/core/AifeiDao.java#L39-L849)

依赖分析

  • 模块间依赖
    • aifei-undertow 依赖 aifei 与 Undertow 核心。
    • aifei-enjoy 依赖 aifei 与模板相关组件。
    • aifei-db 依赖 aifei 与 aifei-enjoy，并可选引入 Druid/HikariCP。
  • 依赖管理
    • 父工程统一管理版本与插件，确保模块一致性。
graph LR CORE["aifei"] --> UDT["aifei-undertow"] CORE --> ENJ["aifei-enjoy"] CORE --> DB["aifei-db"] DB -. optional .-> DR["Druid"] DB -. optional .-> HK["HikariCP"] UDT --> UT["Undertow-core"]

图表来源

  • [aifei-undertow/pom.xml:19-28](file://aifei-undertow/pom.xml#L19-L28)
  • [aifei-enjoy/pom.xml:19-31](file://aifei-enjoy/pom.xml#L19-L31)
  • [aifei-db/pom.xml:19-38](file://aifei-db/pom.xml#L19-L38)

章节来源

  • [pom.xml:75-153](file://pom.xml#L75-L153)
  • [aifei-undertow/pom.xml:19-28](file://aifei-undertow/pom.xml#L19-L28)
  • [aifei-enjoy/pom.xml:19-31](file://aifei-enjoy/pom.xml#L19-L31)
  • [aifei-db/pom.xml:19-38](file://aifei-db/pom.xml#L19-L38)

性能考量

  • 路由匹配优化
    • 路径参数参与匹配，命名参数可缺省；ActionGroup 严格按参数数量与存在性匹配，避免误匹配带来的额外开销。
  • 处理器链与 AOP
    • Handler.next 链式组合，减少分支判断；AOP 代理在对象创建阶段生效，避免运行期反射开销。
  • 模板引擎
    • 生产模式禁用热加载，String 模板缓存可按需开启；支持压缩与极速模式，降低 I/O 与反射成本。
  • ORM
    • Enjoy SQL 与 sqlId 缓存；分页与大数据遍历 API 降低内存压力；类型转换方法减少二次封装。

故障排查指南

  • 启动失败
    • 未配置 Server 或未配置 Handler：检查 AifeiConfig 的 config(Settings) 与 config(Routes) 是否正确设置。
    • 插件启动异常：查看插件 start 抛出的异常并定位具体插件。
  • 路由冲突
    • 未启用 Action 重载导致冲突：在 Routes 中启用 setActionOverload(true)，或调整 @Path 与方法签名。
    • 参数匹配失败：确认路径参数数量与命名参数存在性满足 Action 要求。
  • 模板问题
    • 开发模式下模板未热加载：确认 devMode 已开启且模板文件未被缓存。
    • 编码异常：切换至 JDK 编码器工厂以支持更广泛的字符集。
  • ORM 问题
    • SQL 参数不匹配：检查 Enjoy SQL 中 #para 与问号占位符数量与顺序。
    • 分页统计异常：自定义 TotalRows 实现或清理 order by 导致的统计偏差。

章节来源

  • [Aifei.java:66-72](file://aifei/src/main/java/cn/aifei/core/Aifei.java#L66-L72)
  • [Aifei.java:162-181](file://aifei/src/main/java/cn/aifei/core/Aifei.java#L162-L181)
  • [Router.java:313-334](file://aifei/src/main/java/cn/aifei/router/Router.java#L313-L334)
  • [Engine.java:532-543](file://aifei-enjoy/src/main/java/cn/aifei/enjoy/Engine.java#L532-L543)
  • [AifeiDao.java:309-317](file://aifei-db/src/main/java/cn/aifei/db/core/AifeiDao.java#L309-L317)

结论

Aifei 以“Just Service”为核心开发范式，通过模块化与插件化设计，将高性能 Web 服务器、智能 ORM、模板引擎与 AOP 能力整合为一体。其路由与处理器链设计兼顾性能与可扩展性，AOP 与 ORM 提供简洁而强大的开发体验。对于追求高效、稳定与可演进性的团队，Aifei 提供了从请求到数据的全栈解决方案。
Aifei Dev 开发者联盟