实体 @Entity

ACE ORM 采用编译期宏路线：使用 @Entity 装饰一个类后，编译器会在构建阶段自动生成对应的 Mapper（SQL 映射逻辑）和 Repository Bean，运行时无反射开销。

支持的数据库

数据库	driver 值	说明
SQLite	sqlite	嵌入式，无需独立服务
PostgreSQL	postgresql	推荐生产环境使用
MySQL	mysql	兼容 MariaDB

在 cjpm.toml 中配置数据源：

[package.dependencies]
ace_orm = { path = "ace-orm" }

[package.orm]
driver = "sqlite"
url    = "file:./data/app.db"

定义实体类

使用 @Entity["table_name"] 装饰类，指定对应的数据库表名。

package demo.model

import ace_orm.*

@Entity["tasks"]
public class Task {
    @Id[]
    public var id: Int64 = 0

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

    @Column[]
    public var priority: Int64 = 0

    @Column[]
    public var owner: String = ""
}

字段注解

@Id[] — 主键

标记自增主键字段，类型固定为 Int64。每个实体类有且只有一个 @Id 字段。

@Id[]
public var id: Int64 = 0

@Column[] — 普通列

默认列名与字段名相同。若需要自定义列名，传入字符串参数：

@Column[]
public var title: String = ""          // 列名 = "title"

@Column["created_at"]
public var createdAt: Int64 = 0        // 列名 = "created_at"

@ManyToOne — 多对一关联

声明外键关联，ACE ORM 会在查询时自动 JOIN：

package demo.model

import ace_orm.*

@Entity["tasks"]
public class Task {
    @Id[]
    public var id: Int64 = 0

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

    @ManyToOne
    public var assignee: Option<User> = None
}

关联加载

当前版本关联字段为懒加载，仅在显式访问时触发额外查询。后续版本将支持 @ManyToOne[fetch: "eager"]。

启动时自动建表

在 main.cj 中导入 ace_orm.*，DataSourceComponent 会在应用启动时检查并自动创建尚不存在的表：

package demo

import ace_framework.*
import ace_orm.*
import demo.model.*

main(): Int64 {
    let app = AceApplication()
    app.run()
    return 0
}

注意事项

• 自动建表仅在表不存在时执行 CREATE TABLE IF NOT EXISTS，不会自动执行 ALTER TABLE 迁移。
• 生产环境列变更请使用迁移脚本（计划中）手动管理。
• @Entity 类必须声明为 public class，字段也必须是 public var，宏才能访问其成员信息。

字段注解速查

注解	目标	说明
@Entity["table"]	类	映射到数据库表，生成 Repository
@Id[]	字段	自增主键，类型为 Int64
@Column[]	字段	普通列，列名=字段名
@Column["alias"]	字段	普通列，自定义列名
@ManyToOne	字段	多对一外键关联

勿在运行时动态创建实体

ACE ORM 的 Mapper 在编译期生成，所有 SQL 绑定是静态的。不要尝试在运行时用反射或 Any 类型绕过类型系统操作实体——这将导致不可预期的行为。