整体架构与设计决策

Nex 致力于提供一种极致高效、适合 AI 辅助开发的 Web 架构。理解其内部运行机制将有助于你构建更健壮的应用。

1. 请求处理流程

每一个进入 Nex 应用的请求都会经过以下核心组件：

1. Bandit / Cowboy (Web Server)：底层高性能 Web 服务器接收原始 TCP/HTTP 请求。
2. Nex.Router (Plug.Router)：解析基础路径，区分内置端点（如热重载）和业务逻辑。
3. Nex.Handler (核心调度器)：
   • 上下文准备：初始化 Nex.Req，清理进程字典。
   • 安全校验：自动进行 CSRF 验证（非 GET 请求）。
   • 路由分发：根据 RouteDiscovery 的解析结果，分发至 Api 或 Pages。
   • 状态关联：从 Header 提取 page_id 并关联 Nex.Store。
   • 结果转换：将业务逻辑返回的 HEEx、Map 或指令转换为标准的 HTTP 响应。

2. 编译时魔法：use Nex

当你编写 use Nex 时，框架在后台执行了以下操作：

• 自动导入：导入 Phoenix.Component（HEEx 引擎）、Nex.CSRF（安全辅助）以及核心响应函数。
• 属性注入：自动为模块添加必要的元数据，方便 RouteDiscovery 进行扫描。
• 开发辅助：在开发环境下，注入热重载所需的元数据。

3. 路由发现机制 (RouteDiscovery)

Nex 不使用传统的路由表文件，而是采用 动态扫描 + 缓存 的机制：

• 扫描规则：启动时扫描 src/pages 和 src/api 下的所有 .ex 文件。
• 优先级算法：
  1. 静态路径（如 new.ex） > 动态路径（如 [id].ex）。
  2. 参数数量越少，优先级越高。
  3. 路径深度越深，匹配越精确。
• 热重载支持：在开发模式下，文件变动会自动触发缓存清除，下次请求将重新扫描，实现秒级热更新。

4. 核心设计决策

为什么选择基于 ETS 的 Store？

• 性能：避免了数据库 IO 开销，支持极高频的实时交互。
• 并发：得益于 BEAM 的并发模型，每个用户的状态互不干扰。
• 简化逻辑：开发者无需管理会话同步，只需 get 和 put。

为什么强制 JSON API 规范？

• 类型安全：确保所有接口返回一致的 JSON 结构。
• DX (开发者体验)：在出错时提供精准的修复引导，而不是让开发者去翻源代码。

为什么押注声明式交互？

• 降低心智负担：现代 Web 开发被前端工程化和状态同步搞得过于复杂。我们押注声明式交互（如 HTMX）能够覆盖 90% 的交互需求，让开发者重新专注于业务逻辑而非胶水代码。