CLI 命令参考

ace-cli 是 ACE Framework 的命令行工具，提供项目初始化和代码生成功能，帮助你快速搭建符合 ACE 规范的仓颉服务端项目。

安装

ace-cli 位于 workspace 的 tools/ace-cli 目录，需从源码编译安装：

# 每个 shell 必须先激活 ACE 构建环境
source scripts/env.sh

# 编译 ace-cli
cjpm build -m tools/ace-cli

# 将产物加入 PATH（可写入 ~/.zshrc 或 ~/.bashrc）
export PATH="$PWD/target/release/bin:$PATH"

# 验证安装
ace --version

提示

source scripts/env.sh 会同时设置 SDKROOT（指向 MacOSX15.sdk）和 DYLD_LIBRARY_PATH（含 openssl@3），是仓颉项目在 macOS 上链接成功的必要前提。

ace new

创建一个新的 ACE 项目，生成标准目录结构与配置文件。

ace new <appName>

示例：

ace new my-api

生成的目录结构如下：

my-api/
├── cjpm.toml                  # 包管理配置
├── config/
│   ├── config.default.toml    # 默认配置
│   └── config.prod.toml       # 生产环境配置
├── src/
│   ├── controller/            # 控制器目录
│   ├── service/               # 服务目录
│   └── middleware/            # 中间件目录
└── main.cj                    # 应用入口

生成的 main.cj 内容示例：

package my_api

import ace_framework.*
import ace_http.*

@main
func main(): Unit {
    let app = AceApplication.create()
    app.listen(8080)
}

注意

生成的 cjpm.toml 中依赖路径默认指向工作区 examples/ 目录下的相对路径，如需在独立目录使用，需手动修改 [dependencies] 中各 ace-* 包的 path 字段为实际路径。

ace g

代码生成子命令，支持控制器、服务、实体、中间件四种类型。命令格式：

ace g <type> <Name>

ace-cli 自动读取当前目录下的 cjpm.toml 获取包名，并将 PascalCase 的 <Name> 转换为 snake_case 文件名。

ace g controller

生成控制器文件，放置于 src/controller/ 目录。

ace g controller User
# 生成 src/controller/user_controller.cj

package my_api.controller

import ace_framework.*
import ace_framework.macros.*

@Controller["/users"]
public class UserController {

    @Inject
    var userService!: UserService

    @Get[""]
    func list(): Array<UserDTO> {
        return userService.findAll()
    }

    @Get["/:id"]
    func get(@PathParam id: Int64): UserDTO {
        return userService.findById(id)
    }

    @Post[""]
    func create(@Body dto: CreateUserDTO): UserDTO {
        return userService.create(dto)
    }
}

ace g service

生成服务文件，放置于 src/service/ 目录。

ace g service User
# 生成 src/service/user_service.cj

package my_api.service

import ace_framework.*
import ace_framework.macros.*

@Service
public class UserService {

    func findAll(): Array<UserDTO> {
        // TODO: 实现查询逻辑
        return Array<UserDTO>()
    }

    func findById(id: Int64): UserDTO {
        // TODO: 实现单条查询
        return UserDTO()
    }

    func create(dto: CreateUserDTO): UserDTO {
        // TODO: 实现创建逻辑
        return UserDTO()
    }
}

ace g entity

生成数据实体文件，放置于 src/domain/ 目录。

ace g entity User
# 生成 src/domain/user.cj

package my_api.domain

import ace_framework.macros.*

@Entity["users"]
public class User {

    @Id[]
    @Column["id"]
    public var id: Int64 = 0

    @Column["name"]
    public var name: String = ""

    @Column["email"]
    public var email: String = ""

    @Column["created_at"]
    public var createdAt: String = ""
}

提示

@Entity["tableName"] 中的表名默认与类名 snake_case 对应（如 UserProfile → user_profiles），也可显式指定。

ace g middleware

生成中间件文件，放置于 src/middleware/ 目录。

ace g middleware Auth
# 生成 src/middleware/auth_middleware.cj

package my_api.middleware

import ace_framework.*
import ace_framework.macros.*
import ace_web.*

@Middleware[10]
public class AuthMiddleware <: AceMiddleware {

    public func handle(ctx: Context, next: () -> Unit): Unit {
        let token = ctx.header("Authorization") ?? ""
        if token.isEmpty() {
            ctx.status = 401
            ctx.body = "Unauthorized"
            return
        }
        next()
    }
}

@Middleware[order] 中的 order 数值越小执行优先级越高。

ace --help

查看所有可用命令及选项：

ace --help
# 或简写
ace -h

输出示例：

ACE Framework CLI

Usage: ace <command> [options]

Commands:
  new <appName>         创建新的 ACE 项目
  g controller <Name>   生成控制器
  g service <Name>      生成服务
  g entity <Name>       生成实体
  g middleware <Name>   生成中间件

Options:
  -h, --help            显示帮助信息
  --version             显示版本号

文件监听开发模式

scripts/dev.sh 基于 fswatch 实现文件变更监听，自动触发重编译：

# 确保已安装 fswatch（macOS）
brew install fswatch

# 启动开发模式
./scripts/dev.sh

TIP

dev.sh 监听 src/ 目录下 .cj 文件变更，变更后自动执行 cjpm build && target/release/bin/<appName>，无需手动重启。

完整工作流示例

从零搭建一个带用户管理功能的 REST API：

# 1. 激活构建环境
source scripts/env.sh

# 2. 创建新项目
ace new user-api
cd user-api

# 3. 生成业务代码
ace g entity User
ace g service User
ace g controller User

# 4. 构建项目
cjpm build

# 5. 运行服务
./target/release/bin/user_api
# → 监听 http://localhost:8080

# 6. 开发模式（文件变更自动重编译）
cd ..  # 回到 workspace 根目录
./scripts/dev.sh

生成完成后，目录结构如下：

user-api/
├── cjpm.toml
├── config/
│   └── config.default.toml
├── src/
│   ├── controller/
│   │   └── user_controller.cj
│   ├── service/
│   │   └── user_service.cj
│   ├── domain/
│   │   └── user.cj
│   └── middleware/
└── main.cj

命令速查表

命令	说明	输出文件
ace new <appName>	创建新项目	完整项目目录
ace g controller <Name>	生成控制器	src/controller/<name>_controller.cj
ace g service <Name>	生成服务	src/service/<name>_service.cj
ace g entity <Name>	生成实体	src/domain/<name>.cj
ace g middleware <Name>	生成中间件	src/middleware/<name>_middleware.cj
ace --help	显示帮助	—

注意

运行任何 cjpm 或 ace 命令前，务必先执行 source scripts/env.sh，否则将因 SDK 路径缺失或 DYLD_LIBRARY_PATH 未设置导致构建或链接失败。