| Attribute | 用途 | 必要性 |
|---|---|---|
[ActiveRecord] | 類別層級，指定資料表名、Schema、代理介面等 | ✅ 必須 |
[PrimaryKey] | 主鍵映射，支援多種生成策略 | ✅ 必須 |
[CompositeKey] | 複合主鍵（需配合自訂 Key 類別） | 視需求 |
[Property] | 屬性映射，支援欄位名、型別、長度、Nullability 等 | ✅ 常用 |
[Field] | 直接映射私有欄位（不經 Property） | 較少用 |
[Nested] | 巢狀物件/值物件映射至同一資料表 | 視需求 |
[ActiveRecord("Blogs")] // 指定資料表名
[ActiveRecord(Table = "Blogs", Schema = "dbo", Lazy = true)]
public class Blog : ActiveRecordBase { ... }| 屬性 | 說明 |
|---|---|
| Table | 資料表名，預設類別名 |
| Schema | 資料庫 Schema |
| Lazy | 類別層級延遲載入（需配合 Proxy 介面） |
| DiscriminatorColumn/Type/Value | 繼承映射判別欄位設定 |
| Where | 固定過濾條件（如軟刪除 IsDeleted = 0） |
[PrimaryKey(PrimaryKeyType.Native, "blog_id")] // 推薦：跨資料庫自動選擇
[PrimaryKey(PrimaryKeyType.Identity, "blog_id")] // SQL Server/MySQL 自增
[PrimaryKey(PrimaryKeyType.Sequence, "blog_id", SequenceName = "seq_blog")] // Oracle/PostgreSQL Sequence
[PrimaryKey(PrimaryKeyType.GuidComb)] // GuidComb：有序 GUID，效能優於隨機 GUID
[PrimaryKey(PrimaryKeyType.Assigned)] // 應用程式自行指派| 策略 | 適用資料庫 | 特點 |
|---|---|---|
| Native | 全部 | 自動選擇 Identity/Sequence/HiLo，最通用 |
| Identity | SQL Server, MySQL, PostgreSQL | 資料庫自增欄位 |
| Sequence | Oracle, PostgreSQL, DB2 | Sequence 物件 |
| HiLo / SeqHiLo | 全部 | 高低位演算法，減少資料庫往返 |
| Guid / GuidComb | 全部 | 全域唯一，GuidComb 適合叢集索引 |
| Assigned | 全部 | 業務鍵（如員工編號） |
[Property("blog_name")] // 指定欄位名
[Property(Column = "blog_name", Length = 50, NotNull = true, Unique = true)]
[Property(ColumnType = "StringClob")] // 大文字欄位 (CLOB/TEXT)
[Property(Formula = "(SELECT COUNT(*) FROM Posts WHERE post_blogid = blog_id)")] // 計算欄位，不對應實體欄位
[Property(Update = false, Insert = false)] // 唯讀欄位（如 Formula 或資料庫觸發器維護）繞過 Property，直接映射 private 欄位，適合不想暴露 Setter 的領域模型：
[Field("blog_name")] private string _name;
[Field] private DateTime _created; // 欄位名同屬性名需建立可序列化、實作 Equals/GetHashCode 的 Key 類別：
[CompositeKey, Serializable]
public class OrderItemKey {
[KeyProperty] public virtual int OrderId { get; set; }
[KeyProperty] public virtual int ProductId { get; set; }
public override bool Equals(object obj) { /* 比較 OrderId + ProductId */ }
public override int GetHashCode() { return OrderId ^ ProductId; }
}
[ActiveRecord("OrderItems")]
public class OrderItem : ActiveRecordBase {
[PrimaryKey] public OrderItemKey Id { get; set; }
// ...
}將相關欄位組合為獨立類別，映射至同一資料表：
[ActiveRecord("Companies")]
public class Company : ActiveRecordBase {
[Nested] public PostalAddress Address { get; set; }
}
public class PostalAddress {
[Property] public string Street { get; set; }
[Property] public string City { get; set; }
[Property] public string State { get; set; }
[Property] public string ZipCode { get; set; }
}
// 對應 Companies 資料表：Street, City, State, ZipCode 欄位優點：領域模型更豐富、封裝地址驗證邏輯、可複用於多個實體。
[Version] / [Timestamp]：樂觀鎖定版本控制[JoinedTable] / [JoinedKey]：繼承映射（Table-per-Subclass）[Any] / [Any.MetaType]：多型關聯（Polymorphic Association）ActiveRecord 透過屬性提供豐富映射能力，核心在於 ActiveRecord、PrimaryKey、Property 三大支柱。掌握主鍵策略選擇、Property 細粒度控制、Nested 值物件封裝，能構建清晰對應資料庫又富含領域邏輯的實體模型。複合主鍵雖罕用但需正確實作 Equals/GetHashCode 避免快取異常。
