快速开始
本节带你在 5 分钟内完成环境准备、项目创建、编写第一个接口并验证运行。
环境准备
ACE 需要以下运行环境：
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| 仓颉编译器（cjc） | ≥ 1.1.0 | 官网下载或华为开发者套件 |
| cjpm | 随 cjc 附带 | 仓颉包管理工具 |
| 平台 | macOS arm64 / Linux aarch64 | x86_64 暂未正式支持 |
| OpenSSL | 3.x | stdx TLS 依赖（macOS 用 brew install openssl@3） |
安装完成后验证：
cjc --version # 应输出 cjc 1.1.0-alpha 或更高
cjpm --versionmacOS 26 用户注意
macOS 26 的系统 SDK 与 cjc 自带 LLD 存在不兼容，必须在 env.sh 中将 SDKROOT 指向 MacOSX15.sdk。项目模板已内置此绕过，source scripts/env.sh 会自动处理。
创建新项目
使用 ace-cli 脚手架一键生成项目骨架：
ace new myapp
cd myapp生成的目录结构如下：
myapp/
├── cjpm.toml # workspace 根配置
├── scripts/
│ └── env.sh # 环境变量设置（每次构建前 source）
├── config/
│ ├── application.toml # 基础配置
│ └── application.dev.toml # 开发环境覆盖
├── src/
│ ├── main.cj # 应用入口
│ ├── controller/
│ │ └── hello_controller.cj
│ └── service/
│ └── hello_service.cj
└── test/
└── hello_controller_test.cj手动创建
如果 ace-cli 尚未发布，可克隆 examples/hello-api 目录作为起点，修改 cjpm.toml 中的包名。
配置文件说明
编辑 config/application.toml，核心字段：
[server]
host = "0.0.0.0" # 监听地址
port = 8080 # 监听端口
[ace]
env = "dev" # 激活环境，对应 application.{env}.toml
[log]
level = "info" # trace / debug / info / warn / error
format = "simple" # simple（开发）/ json（生产）/ text
[database]
url = "sqlite://./data/app.db"| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
server.host | String | "0.0.0.0" | HTTP 监听地址 |
server.port | Int | 8080 | HTTP 监听端口 |
ace.env | String | "dev" | 激活的配置环境 |
log.level | String | "info" | 日志级别 |
log.format | String | "simple" | 日志输出格式 |
多环境配置会合并：application.toml 为基础，application.{env}.toml 中同名字段覆盖基础值。
编写第一个接口
打开 src/controller/hello_controller.cj，写入以下内容：
package myapp.controller
import ace_framework.*
import ace_framework.web.*
@Controller["/api"]
public class HelloController {
@Inject
private let helloService: HelloService
// GET /api/hello
@Get["/hello"]
public func hello(): String {
return helloService.greeting("World")
}
// GET /api/hello/:name
@Get["/hello/:name"]
public func helloName(@PathParam name: String): String {
return helloService.greeting(name)
}
// POST /api/echo
@Post["/echo"]
public func echo(@Body payload: EchoRequest): EchoResponse {
return EchoResponse(message: payload.message, length: payload.message.size)
}
}新建 src/service/hello_service.cj：
package myapp.service
import ace_framework.*
@Service
public class HelloService {
public func greeting(name: String): String {
return "Hello, ${name}! Powered by ACE Framework."
}
}定义请求 / 响应数据类（src/model/echo.cj）：
package myapp.model
public struct EchoRequest {
public let message: String
}
public struct EchoResponse {
public let message: String
public let length: Int64
}最后编辑 src/main.cj 启动应用：
package myapp
import ace_framework.*
import ace_http.*
main(): Int64 {
let app = AceApplication.create()
app.listen()
return 0
}@Inject 是如何工作的
@Inject 宏在编译期展开为构造函数参数注入代码，框架在启动时从 IoC 容器查找已注册的 HelloService 实例并传入 HelloController。不存在运行时反射，可以通过 cjc --debug-macro 查看展开后的代码。
构建与运行
每次打开新终端都必须先执行：
source scripts/env.sh然后构建并运行：
cjpm build
cjpm run看到如下输出说明启动成功：
[ACE] Server listening on http://0.0.0.0:8080
[ACE] Environment: dev
[ACE] 3 routes registered忘记 source env.sh
如果看到链接错误（ld: library not found）或 TLS 崩溃，99% 原因是忘记执行 source scripts/env.sh。
验证接口
打开新终端，用 curl 测试：
# 基础 Hello World
curl http://127.0.0.1:8080/api/hello
# 输出: Hello, World! Powered by ACE Framework.
# 路径参数
curl http://127.0.0.1:8080/api/hello/ACE
# 输出: Hello, ACE! Powered by ACE Framework.
# POST JSON
curl -X POST http://127.0.0.1:8080/api/echo \
-H "Content-Type: application/json" \
-d '{"message": "你好，仓颉"}'
# 输出: {"message":"你好，仓颉","length":9}运行单元测试
cjpm test测试输出
单测默认捕获 println，调试时加 --no-capture-output：
cjpm test --no-capture-output下一步
恭喜！你已经跑通了第一个 ACE 应用。接下来可以：