ACE

Agent for Cangjie to Engine —— 用仓颉（Cangjie）编写的服务端框架。

角色对标 Spring Boot / MidwayJS，技术路线对标 Micronaut / Quarkus：编译期宏而非运行时反射。底层是 Koa 式洋葱中间件内核,向上提供声明式开发范式(IoC、路由、校验、序列化、AOP、调度、安全),并内置智能体运行时(既用于框架自调度,也供开发者构建智能体服务)。

设计理念

• 零运行时反射：依赖装配、路由注册、参数绑定、AOP 织入全部由编译期宏生成等价的显式代码(可 --debug-macro 审计),运行时无反射开销,AOT 友好。
• 小而组合：每个能力是一个可单独引入的 module,能力皆中间件;纯内核(ace-web/ace-router/ace-bodyparser)不依赖 stdx、可独立单测,声明层(ace-framework-runtime 起,JSON 基于 stdx.encoding.json)与 HTTP 适配/安全/智能体层依赖 stdx。
• 单体到微服务统一：业务面向接口,改装配即可从单体演进到微服务(ace-rpc 进程内透明切换已验证)。

能力一览

声明式核心(ace-framework,编译期宏)

• IoC 容器:@Service/@Prototype(单例/原型作用域)、构造器注入与字段 @Inject、Bean 生命周期 @PostConstruct/@PreDestroy(优雅停机)。
• 声明式路由:@Controller/@Get/@Post/@Put/@Delete/@Patch;路径参数 :id、查询参数(按约定推断)、String/Int64/Float64/Bool 类型化绑定。
• 请求体与序列化:@Dto(@Body 自动 JSON→DTO,返回 DTO 自动 DTO→JSON;零反射 JSON 解析器/序列化器)。
• 参数校验:@NotEmpty/@Email/@Size/@Min/@Max,失败自动 400 {"error":...}。
• AOP:@Timed(及复用同一织入内核的)@Cacheable(记忆化)、@Async(Future<T>)、@Scheduled(周期任务)。

中间件 / 运行时

• 洋葱内核 App/Context/compose;官方中间件 cors/requestLog/health/错误→JSON/rateLimit。
• 安全(ace-security):JWT(HS256,基于 stdx.crypto)、jwtAuth/requireRoles/authenticated 授权 guard。

智能体 / 微服务 / 控制面

• ace-agent:LLM 工具调用循环 + agent-as-a-service;ace-agent-claude:Claude Messages API 报文构造。
• ace-rpc:本地实现/远程代理透明切换。
• ace-autopilot:分级护栏控制面;ace-observability:请求/错误率/延迟指标。

模块

模块	职责	stdx
ace-web	洋葱内核(App/Context/compose)+ JSON 解析/序列化、查询解析、校验纯函数	无
ace-router	路由中间件,完整 path-to-regexp 规则	无
ace-bodyparser	请求解析(urlencoded、multipart/form-data)	无
ace-http	接入 stdx.net.http 的服务端适配器	有
ace-framework/*	声明式宏层:macros / runtime / facade / boot 四 module	runtime(JSON) + boot
ace-security	JWT 认证 + 授权 guard 中间件	有
ace-client / ace-websocket	HTTP 客户端 / WebSocket(独立组件,JSR356 式注解)	有
ace-agent / ace-agent-claude	智能体运行时 / Claude 报文	claude 层
ace-rpc / ace-autopilot / ace-observability	微服务统一 / 控制面 / 可观测	无

文档

完整开发者文档见 docs/：框架介绍 · 快速开始 · 核心内核 · IoC 与配置 · 控制器与路由 · 请求与响应 · AOP · 安全 · ORM · 组件扩展与封装 · 智能体运行时 · 测试与部署 · CRUD 教程 · 中间件与 HTTP 客户端 · WebSocket。

内部设计规格与路线图见 doc/。

快速开始

source scripts/env.sh   # 每个 shell 必做(本机构建环境,见 CLAUDE.md)
cjpm build
cjpm test               # 全 workspace 单测

声明式控制器(examples/web-server、examples/di-demo):

@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) }

    @Post["/users"]
    public func create(body: CreateUser): UserView {   // @Body 自动反序列化 + 校验;返回自动 JSON
        let v = UserView(); v.id = 1; v.label = body.name; v
    }
}

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

声明式标注速查

标注	作用
@Service / @Prototype / @Inject	注册 Bean(单例/原型)/ 注入依赖(构造器或字段)
@PostConstruct / @PreDestroy	Bean 构造后 / 优雅停机时回调
@Controller / @Get…@Patch	控制器 / 五种 HTTP 动词路由
@Dto	请求体反序列化 + 响应自动序列化
@NotEmpty/@Email/@Size/@Min/@Max	字段约束(失败 400)
@Timed/@Cacheable/@Async/@Scheduled	AOP:打点 / 记忆化 / 异步 / 定时

示例

• examples/hello-api — 最小探活
• examples/di-demo — IoC + 全套声明式特性(生命周期/校验/序列化/AOP/缓存/异步/调度)的集成验证
• examples/web-server — 真实 HTTP 控制器 + 内置智能体 /chat
• examples/auth-demo — JWT 认证 + 角色授权端到端

版本与 API 稳定性

遵循语义化版本。当前 0.x:API 尚未稳定,次版本可能含破坏性变更。

稳定性分级(进入 1.0 前逐步标注):

• Stable — 已冻结,破坏性变更走主版本。
• Experimental — 智能体运行时、ace-rpc 跨进程、ace-autopilot 等,可能调整。

1.0 目标:声明式核心(IoC/路由/校验/序列化/AOP/安全)API 冻结。

贡献

见 CONTRIBUTING.md。要点:每个能力做成可单独引入的 module;改代码后 cjpm test 保持全绿;声明式能力优先用宏生成、保留 --debug-macro 可审计;全局编码规范(不可变、小文件、错误处理)见 ~/.claude/rules/。

状态

声明式核心(IoC + 生命周期 + 路由 + 校验 + 序列化 + AOP)、中间件、安全(JWT + 安全头/CSRF/限流)、ORM(@Entity/@Transactional/关系/迁移,SQLite/PostgreSQL/MySQL)、HTTPS/TLS、流式响应(SSE/二进制/Range)、请求上下文持有者、智能体骨架、单体/微服务透明切换、控制面与可观测均已实现并通过测试。规划中(Experimental):真实 LLM HTTP 传输、ace-rpc 跨进程 HTTP。

需求与计划见 doc/roadmap-m12-plus.md 与 doc/blog-ace-technical-deep-dive.md；本机构建环境配置见 CLAUDE.md。