@[TOC](Aifei 编程框架项目概述)
引言
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
图表来源
章节来源
<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
- AifeiConfig.java:25-51
- Router.java:60-131
- Routes.java:38-88
- Handler.java:22-27
- Server.java:22-38
- Plugins.java:26-41
- Aop.java:89-118
- Engine.java:51-114
- AifeiDao.java:39-115
架构总览
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
- AifeiConfig.java:30-50
- Router.java:156-170
- Handler.java:22-27
- Server.java:27-37
- Engine.java:186-206
- AifeiDao.java:309-317
详细组件分析
启动与生命周期（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()
图表来源
章节来源
路由与处理器（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(["完成"])
图表来源
章节来源
服务器与插件（Server 与 Plugins）
- Server 接口
- init(Dispatcher)：持有下游调度器。
- start()/stop()：启动与停止。
- Plugins 容器
- add(Plugin)：注册插件。
- 生命周期：集中启动与停止，异常时记录日志并终止启动。
章节来源
AOP 与代理（Aop 与 ProxyFactory）
- Aop 便捷入口
- Aop.get(Class)/get(name)：创建并注入依赖。
- Aop.inject(Object)：对已有对象进行依赖注入。
- 与 Singleton/Before 注解配合，实现业务层 AOP 代理。
- ProxyFactory
- 业务层代理工厂接口，结合 AopKit 实现对象创建与代理。
章节来源
模板引擎（Engine）
- 多引擎实例与共享对象
- 支持 main 引擎与自定义引擎实例，共享函数/方法、枚举、指令扩展。
- 开发模式与缓存
- devMode 下模板热加载；String 模板缓存可按需开启。
- 输出与编码
- 支持自定义 EncoderFactory（含 JDK 编码器）与缓冲区大小配置。
- 压缩与极速模式
- 可开启 Compressor 压缩静态内容；支持极速模式减少反射调用。
章节来源
ORM（AifeiDao）
- 链式 DSL 与类型安全
- insert/update/delete/find/query/paginate/forEach 等丰富 API。
- 支持 Enjoy SQL 语法与 sqlId 缓存，提升性能与可维护性。
- 参数与类型转换
- 内置多种 queryXxx 类型转换方法，简化结果处理。
- 分页与大数据遍历
- 支持分页与分页遍历，适合大数据场景。
章节来源
依赖分析
- 模块间依赖
- 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"]
图表来源
章节来源
性能考量
- 路由匹配优化
- 路径参数参与匹配，命名参数可缺省；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 以“Just Service”为核心开发范式，通过模块化与插件化设计，将高性能 Web 服务器、智能 ORM、模板引擎与 AOP 能力整合为一体。其路由与处理器链设计兼顾性能与可扩展性，AOP 与 ORM 提供简洁而强大的开发体验。对于追求高效、稳定与可演进性的团队，Aifei 提供了从请求到数据的全栈解决方案。
