01 · 框架介绍

ACE 是什么

ACE 是用仓颉语言编写的服务端框架。底层是 Koa 式的洋葱中间件内核，向上提供一整套声明式开发范式（IoC 容器、路由、参数绑定、校验、序列化、AOP、调度、安全、ORM），并内置智能体（Agent）运行时。

一个最小的 ACE 应用：

@Service
public class Greeter {
    public func hi(name: String): String { "Hello, ${name}!" }
}

@Controller["/api"]
public class HelloController {
    @Inject var greeter: Greeter

    @Get["/hello/:name"]
    public func hello(name: String): String { greeter.hi(name) }
}

main() { AceApplication.run("0.0.0.0", 8080) }   // IoC 自装配 + 路由 + 中间件,一行启动

设计理念

1. 零运行时反射

依赖装配、路由注册、参数绑定、AOP 织入、ORM 元数据——全部由编译期宏生成等价的显式代码，运行时无反射开销，AOT 友好。生成的代码可用 cjc --debug-macro 审计。

机制核心：@Service/@Controller/@Entity 等宏在类旁生成顶层 let __ace_reg_X = registerXxx(...)，其初始化器在程序启动期自动执行完成自注册——无反射、无运行时枚举扫描。

重要推论：自注册靠「包被 import 时执行顶层 let」触发。因此 main 所在文件必须 import 所有含 @Controller/@Service/@Entity/@Component 的包，否则它们不会被装配。

2. 小而组合，能力皆中间件

每个能力是一个可单独引入的 module（ace-web、ace-router、ace-security、ace-orm……）。纯内核（ace-web/ace-router/ace-bodyparser）不依赖 stdx，可独立构建/单测；声明层（ace-framework-runtime 起，JSON 工具基于 stdx.encoding.json）、HTTP 适配、安全、智能体层依赖 stdx。

3. 单体到微服务统一

业务面向接口编程，改装配即可从单体演进到微服务（ace-rpc 进程内/远程透明切换）。

架构分层

请求自底向上穿过这些层：

                    ┌─────────────────────────────────────────┐
   声明式宏层        │  @Controller @Service @Inject @Get @Dto   │  编译期生成等价显式代码
 (ace-framework)    │  @Entity @Transactional @Cacheable …      │
                    └───────────────────┬─────────────────────┘
                                        │ 生成
                    ┌───────────────────▼─────────────────────┐
   运行时 / 中间件    │  IoC 容器 · 路由 · 校验 · 序列化 · 调度 · 组件 │
 (runtime/web/...)  │  洋葱内核 App / Context / compose          │
                    └───────────────────┬─────────────────────┘
                                        │
   HTTP 适配         │  ace-http: stdx.net.http ←→ ace-web.Context │  唯一接触 stdx 网络的层
                    └───────────────────┬─────────────────────┘
                                        │
                              stdx.net.http 服务端

请求生命周期

stdx.net.http 收到请求
  → ace-http 的 catch-all 分发器（所有路径交同一入口）
  → 构造 ace-web.Context（method/path/headers/query/rawBody）
  → RequestContextHolder.set(ctx)        ← 绑定当前协程的请求上下文
  → 跑 App 洋葱中间件链（compose）：
       requestLog → cors → health → openapi/docs
        → 用户中间件（@Middleware，按 order）→ rangeHandler → 路由
        → 命中的控制器方法（参数由宏从 Context 绑定）
  → 按 ctx.responseBody() 写回响应（文本 / 二进制 / chunked 流式）
  → finally: RequestContextHolder.clear()

异常由 App 顶层兜底：@Catch 异常过滤器优先，否则 jsonErrorHandler 输出 {"error":...}。

模块全景

模块	职责	依赖 stdx
ace-web	洋葱内核（App/Context/compose/ResponseBody）+ JSON 解析/序列化、查询解析、校验、SSE/Range	否
ace-router	路由中间件，完整 path-to-regexp 规则（:id/*rest/内联正则等）	否
ace-bodyparser	请求体解析（urlencoded、multipart/form-data）	否
ace-http	接入 stdx.net.http 的服务端适配器 + TLS	是
ace-framework/ace-framework-macros	声明式宏（编译期代码生成）	否
ace-framework/ace-framework-runtime	IoC 容器、路由注册表、组件、配置、AOP 后端、调度、可观测原语	否
ace-framework/ace-framework	facade（统一再导出）	否
ace-framework/ace-framework-boot	AceApplication 启动入口（装配 + 监听 + 生命周期）	仅此
ace-security	JWT 认证 + 授权 guard + 安全头/CSRF/限流	是
ace-orm / ace-orm-macros	零反射 ORM（SQLite/PostgreSQL/MySQL，@Entity/@Transactional/关系/迁移）	是
ace-agent / ace-agent-claude	智能体运行时 / Claude 报文构造	claude 层
ace-rpc / ace-autopilot / ace-observability	微服务透明切换 / 控制面 / 指标日志	否

与 Spring Boot / MidwayJS 的对应

概念	Spring Boot	MidwayJS	ACE
依赖注入	@Autowired	@Inject	@Inject / 构造器注入
控制器	@RestController	@Controller	@Controller
路由	@GetMapping	@Get	@Get
请求体	@RequestBody	@Body	名为 body 的参数 + @Dto
作用域 Bean	@Scope	@Scope	@Service(单例)/@Prototype
拦截器/中间件	Interceptor	Middleware	@Middleware / 洋葱
可插拔扩展	Starter / AutoConfiguration	Component	@Component
SSE	SseEmitter	ctx.body = stream	返回 SseStream
当前请求	RequestContextHolder（ThreadLocal）	@Inject ctx（请求作用域）	RequestContextHolder（协程本地）/ @Inject ctx 活属性

下一章：快速开始。