戰(zhàn)：用 `Ref`、`LazyRef` 與 `Loaded` 在編譯期杜絕“幽靈關(guān)聯(lián)“)
后端【免費(fèi)下載鏈接】mikro-ormTypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.項(xiàng)目地址https://gitcode.com/gh_mirrors/mi/mikro-orm點(diǎn)擊查看免費(fèi)下載本篇指南圍繞 MikroORM 7.1 版本文檔docs/versioned_docs/version-7.1/type-safe-relations.md展開(kāi)系統(tǒng)講解如何把實(shí)體關(guān)聯(lián)從運(yùn)行時(shí)才知道是否已加載的盲區(qū)提升為編譯期即可感知的類型安全體驗(yàn)。讀完你將掌握四種互相配合的工具——Reference包裝器、LazyRef類型級(jí)引用、Loaded類型與$同步訪問(wèn)器以及unref()/Loadable/ScalarReference等配套 API能夠?qū)懗鑫醇虞d即編譯報(bào)錯(cuò)、已加載即同步訪問(wèn)的實(shí)體層代碼。為什么關(guān)系需要類型安全在 MikroORM 中實(shí)體關(guān)系被映射為實(shí)體引用entity reference——即至少攜帶主鍵的實(shí)體實(shí)例該引用存放在 Identity Map 中因此同一份數(shù)據(jù)反復(fù)查詢得到的是同一個(gè)對(duì)象引用ManyToOne(() Author) author!: Author;問(wèn)題在于TypeScript 無(wú)法靜態(tài)判斷該關(guān)系是否已真正從數(shù)據(jù)庫(kù)加載。author屬性的類型永遠(yuǎn)是Author即使它只是一個(gè)只有主鍵、其余屬性未初始化的引用stubconst book await em.findOne(Book, 1); console.log(book.author instanceof Author); // true —— 是 Author 實(shí)例 console.log(wrap(book.author).isInitialized()); // false —— 但并未加載 console.log(book.author.name); // undefined —— Author 尚未加載這種看起來(lái)是實(shí)體、摸起來(lái)卻是空殼的關(guān)聯(lián)是運(yùn)行時(shí)錯(cuò)誤的溫床。為此 MikroORM 提供了一整套類型安全工具Reference包裝器把關(guān)系包裝成RefT顯式區(qū)分已加載/未加載狀態(tài)Loaded類型在類型層面追蹤哪些關(guān)系已被populate$訪問(wèn)器對(duì)已加載關(guān)系提供類型安全的同步訪問(wèn)。其類型核心定義位于 typings.ts運(yùn)行時(shí)包裝器實(shí)現(xiàn)在 Reference.ts。Reference包裝器Reference包裝一個(gè)實(shí)體引用并提供一組安全的訪問(wèn)方法方法說(shuō)明load()加載實(shí)體返回PromiseTload(prop)加載實(shí)體并返回指定屬性loadOrFail()加載實(shí)體找不到時(shí)拋出錯(cuò)誤行為同em.findOneOrFail()unwrap()返回底層實(shí)體不安全可能未初始化isInitialized()返回實(shí)體是否已加載getEntity()返回實(shí)體未初始化則拋出錯(cuò)誤getProperty(prop)返回屬性未初始化則拋出錯(cuò)誤$/get()同步訪問(wèn)僅在LoadedReference上可用從源碼看Reference類Reference.ts在構(gòu)造時(shí)會(huì)把實(shí)體的主鍵屬性通過(guò)Object.defineProperty復(fù)制到包裝器上這就是ref.id無(wú)需unwrap()即可直接讀取的原因同時(shí)$與get是定義在Reference.prototype上的取值器Reference.ts分別直接返回底層實(shí)體。定義引用屬性使用RefT類型加上ref: true選項(xiàng)來(lái)聲明引用屬性。MikroORM 7 支持defineEntity、reflect-metadata、ts-morph 等多種實(shí)體定義方式本文按官方文檔的四種 Tab 逐一給出方式一defineEntity class 組合import { defineEntity, p } from mikro-orm/core; const BookSchema defineEntity({ name: Book, properties: { id: p.integer().primary(), author: p.manyToOne(() Author).ref(), }, }); export class Book extends BookSchema.class {} BookSchema.setClass(Book);方式二純defineEntity無(wú) classimport { defineEntity, p } from mikro-orm/core; export const Book defineEntity({ name: Book, properties: { id: p.integer().primary(), author: () p.manyToOne(Author).ref(), }, });方式三reflect-metadata 裝飾器import { Entity, Ref, ManyToOne, PrimaryKey, ref } from mikro-orm/core; Entity() export class Book { PrimaryKey() id!: number; ManyToOne(() Author, { ref: true }) author: RefAuthor; constructor(author: Author) { this.author ref(author); } }方式四ts-morph無(wú)參數(shù)推斷的裝飾器寫(xiě)法import { Entity, Ref, ManyToOne, PrimaryKey, ref } from mikro-orm/core; Entity() export class Book { PrimaryKey() id!: number; ManyToOne() author: RefAuthor; constructor(author: Author) { this.author ref(author); } }使用引用未加載時(shí)Ref只暴露主鍵任何對(duì)非主鍵屬性的訪問(wèn)都會(huì)得到編譯錯(cuò)誤const book await em.findOne(Book, 1); // 引用尚未加載 book.author; // RefAuthor book.author.isInitialized(); // false book.author.id; // OK —— 主鍵永遠(yuǎn)可用 book.author.name; // TS 錯(cuò)誤 —— RefAuthor 上沒(méi)有 name // 加載引用 const author await book.author.load(); author.name; // OK —— 現(xiàn)在已加載 // 或者只加載并取出某個(gè)屬性 const name await book.author.load(name);當(dāng)關(guān)系被 populate 后你得到的是LoadedReference可以通過(guò)$同步訪問(wèn)const book await em.findOne(Book, 1, { populate: [author] }); book.author; // LoadedReferenceAuthor book.author.$.name; // OK —— 類型安全的同步訪問(wèn) book.author.get().name; // 同上另一種等價(jià)寫(xiě)法嚴(yán)格校驗(yàn)getEntity/getPropertyunwrap()是裸奔接口而getEntity()/getProperty()會(huì)在未初始化時(shí)拋錯(cuò)適合在需要強(qiáng)校驗(yàn)的場(chǎng)景使用const book await em.findOne(Book, 1); // 未初始化時(shí)拋錯(cuò) book.author.getEntity(); // Error: ReferenceAuthor not initialized book.author.getProperty(name); // Error: ReferenceAuthor not initialized // 先加載再同步訪問(wèn) await book.author.load(); book.author.getEntity().name; // OK book.author.getProperty(name); // OK對(duì)應(yīng)錯(cuò)誤信息由getEntity()在未初始化時(shí)拋出Reference.ts。與wrap(entity).init()總是從數(shù)據(jù)庫(kù)刷新不同Reference.load()只有當(dāng)實(shí)體不在 Identity Map 中時(shí)才會(huì)發(fā)起查詢——已加載則直接復(fù)用內(nèi)存中的對(duì)象見(jiàn) Reference.ts 中isInitialized()與refresh選項(xiàng)的分支邏輯。LazyRefT—— 類型層面的引用如果你想要編譯期的 populate 狀態(tài)安全但又不想承擔(dān)Reference帶來(lái)的.$/.get()間接訪問(wèn)可以使用LazyRefT。它是純類型標(biāo)記運(yùn)行時(shí)屬性直接持有實(shí)體實(shí)例與不帶ref: true的普通關(guān)系完全一致但 TypeScript 在Loaded收窄之前只允許你訪問(wèn)主鍵。ManyToOne(() Author) author!: LazyRefAuthor;用defineEntity時(shí)對(duì)應(yīng).lazyRef()const BookSchema defineEntity({ name: Book, properties: { author: () p.manyToOne(AuthorSchema).lazyRef(), }, });從源碼看LazyRef是一個(gè)帶唯一符號(hào)品牌brand的交叉類型{ [K in PrimaryPropertyT keyof T]: T[K] } LazyRef.BrandTtypings.ts它把可訪問(wèn)屬性收窄為主鍵其余屬性在編譯期被鎖住。語(yǔ)義對(duì)比LazyRefTvsRefTLazyRefTRefT運(yùn)行時(shí)值實(shí)體實(shí)例stub 或已水合Reference包裝器instanceof T運(yùn)行時(shí)truefalse訪問(wèn)未加載的主鍵ref.id?ref.id?訪問(wèn)未加載的非主鍵編譯錯(cuò)誤 ?編譯錯(cuò)誤 ?訪問(wèn)已加載屬性loaded.author.name無(wú).$loaded.author.$.nameload()/loadOrFail()方法? —— 需在目標(biāo)實(shí)體上用Loadablemixin? 內(nèi)置關(guān)于instanceof的注意點(diǎn)上表中的instanceof T指的是運(yùn)行時(shí) JS 檢查——book.author instanceof Author返回true。但 TypeScript 的instanceof控制流收窄不會(huì)剝離LazyRefT的品牌標(biāo)記所以if (book.author instanceof Author) { /* 這里 book.author.name 依然是編譯錯(cuò)誤 */ }并不能讓你獲得完整實(shí)體訪問(wèn)。請(qǐng)使用unref()或Loaded收窄來(lái)獲得編譯期訪問(wèn)。用法示例const book await em.findOneOrFail(Book, 1); book.author.id; // ok —— 主鍵總是可訪問(wèn) book.author.name; // 編譯錯(cuò)誤 —— 未加載 const loaded await em.findOneOrFail(Book, 1, { populate: [author] }); loaded.author.name; // ok —— LoadedBook, author 把 LazyRefAuthor 收窄為 Author測(cè)試 lazy-ref.test.ts 對(duì)上述語(yǔ)義做了逐一驗(yàn)證運(yùn)行時(shí)值是實(shí)體實(shí)例而非包裝器第 85-90 行、未 populate 時(shí)主鍵可訪問(wèn)而name是編譯錯(cuò)誤第 126-133 行、populate 后Loaded收窄恢復(fù)完整訪問(wèn)第 135-140 行。適用范圍LazyRefT只用于 to-one 關(guān)系ManyToOne、OneToOne。集合關(guān)系本身已有CollectionT的間接層無(wú)需此標(biāo)記。注意安全邊界該安全純粹是編譯期的。JS 代碼、as any強(qiáng)轉(zhuǎn)、或繞過(guò)Loaded的代碼路徑在運(yùn)行時(shí)可以自由讀取任何屬性——對(duì)未 populate 的引用只有主鍵的 stub這些讀取會(huì)得到undefined。如果關(guān)系已被 populate底層實(shí)體已完全水合讀取行為正常該警告只針對(duì) stub 場(chǎng)景與普通非Ref關(guān)系是同一個(gè)坑。類型性能LazyRefT在Loaded/AutoPath收窄路徑上只增加一個(gè)條件分支成本與RefT相當(dāng)已加載收窄時(shí)甚至略便宜因?yàn)椴粫?huì)產(chǎn)生LoadedReference交叉類型。測(cè)量數(shù)據(jù)見(jiàn) tests/bench/types/lazy-ref.tsLoaded LazyRef - single to-one為 954 次實(shí)例化對(duì)應(yīng)Ref基線為 971 次深層鏈5 級(jí)AutoPath LazyRef為 1165 次實(shí)例化。unref()—— 無(wú)法穿透Loaded時(shí)的逃生通道當(dāng)代碼周圍都是裸Book類型而非LoadedBook, author而你確信關(guān)系已被 populate 時(shí)用unref()把LazyRefT或RefT收窄回Timport { unref } from mikro-orm/core; function logAuthor(book: Book) { // book.author 是 LazyRefAuthor —— 直接寫(xiě) .name 是編譯錯(cuò)誤 console.log(unref(book.author).name); }unref()是ref()的逆操作作用于以下幾類值實(shí)現(xiàn)見(jiàn) Reference.tsRefT/ReferenceT實(shí)體—— 調(diào)用.unwrap()返回TLazyRefT—— 運(yùn)行時(shí)身份轉(zhuǎn)換底層值本來(lái)就是T返回T普通T—— 透?jìng)鞣祷豑ScalarReferenceV/ScalarRefV—— 調(diào)用.unwrap()返回V | undefined標(biāo)量可能未綁定null/undefined—— 透?jìng)鳌：推胀╝s強(qiáng)轉(zhuǎn)一樣unref()對(duì)實(shí)體關(guān)系只做編譯期收窄——若實(shí)體是從未 populate 的 stub非主鍵屬性在運(yùn)行時(shí)仍是undefined。在你確信關(guān)系已加載時(shí)使用它能穿透Loaded時(shí)優(yōu)先選擇把它寫(xiě)進(jìn)函數(shù)簽名。測(cè)試 lazy-ref.test.ts 覆蓋了unref()對(duì)LazyRef、Ref、普通實(shí)體、標(biāo)量引用及null/undefined的全部行為。Loadablemixin —— 在實(shí)體上獲得load()/loadOrFail()如果你用的是普通關(guān)系或LazyRefT又想要Reference包裝器提供的load()/loadOrFail()便利可以在實(shí)體類上啟用Loadablemixin。它把這兩個(gè)方法掛到實(shí)體原型上讓你能直接在關(guān)系目標(biāo)上調(diào)用import { BaseEntity, Loadable, LoadableBaseEntity } from mikro-orm/core; // 便捷方式BaseEntity 已預(yù)組合該 mixin class User extends LoadableBaseEntity { // ... } // 獨(dú)立方式不繼承任何基類 class Product extends Loadable() { // ... } // 或與自己的基類組合 class Article extends Loadable(MyBase) { // ... } const user orm.em.getReference(User, 1); const loaded await user.load(); // PromiseUser | null const loadedOrThrows await user.loadOrFail(); // PromiseUser該 mixin 的實(shí)現(xiàn)位于 BaseEntity.tsload()內(nèi)部就是Reference.create(this).load(...)因此同樣遵循已加載則不重復(fù)查詢的 Identity Map 語(yǔ)義LoadableBaseEntity是Loadable(BaseEntity)的預(yù)組合別名BaseEntity.ts。按設(shè)計(jì)選擇啟用BaseEntity本身不會(huì)獲得這兩個(gè)方法因此已擁有l(wèi)oad/loadOrFail屬性的實(shí)體不會(huì)受影響。反過(guò)來(lái)若對(duì)已定義load的基類應(yīng)用 mixin會(huì)觸發(fā)編譯錯(cuò)誤以防止靜默覆蓋EnsureNoLoadConflict檢查BaseEntity.ts。Loaded類型LoadedEntity, Hints在編譯期追蹤哪些關(guān)系已被 populate。所有em.find*方法都返回該類型// 類型LoadedUser, never[] const users await em.find(User, {}); // 類型LoadedUser, identity | friends[] const usersWithRelations await em.find(User, {}, { populate: [identity, friends], });其內(nèi)部構(gòu)造typings.ts會(huì)遍歷實(shí)體屬性把 populate 提示中命中的關(guān)系屬性替換為L(zhǎng)oadedProp對(duì)LazyRef/Ref/Collection分別收窄并附加__loadedType、__loadHint標(biāo)記符號(hào)__loadHint利用逆變contravariance保證LoadedA, b不可賦值給LoadedA, b.c從而讓嵌套提示精確匹配。以下面的User實(shí)體為例含identity引用關(guān)系與friends集合關(guān)系defineEntity classimport { defineEntity, p } from mikro-orm/core; const UserSchema defineEntity({ name: User, properties: { id: p.integer().primary(), identity: p.manyToOne(() Identity).ref(), friends: p.manyToMany(() User), }, }); export class User extends UserSchema.class {} UserSchema.setClass(User);純defineEntityimport { defineEntity, p } from mikro-orm/core; export const User defineEntity({ name: User, properties: { id: p.integer().primary(), identity: () p.manyToOne(Identity).ref(), friends: () p.manyToMany(User), }, });reflect-metadata 裝飾器import { Entity, PrimaryKey, ManyToOne, ManyToMany, Collection, Ref, ref } from mikro-orm/core; Entity() export class User { PrimaryKey() id!: number; ManyToOne(() Identity, { ref: true }) identity: RefIdentity; ManyToMany(() User) friends new CollectionUser(this); constructor(identity: Identity) { this.identity ref(identity); } }ts-morph 裝飾器import { Entity, PrimaryKey, ManyToOne, ManyToMany, Collection, Ref, ref } from mikro-orm/core; Entity() export class User { PrimaryKey() id!: number; ManyToOne() identity: RefIdentity; ManyToMany(() User) friends new CollectionUser(this); constructor(identity: Identity) { this.identity ref(identity); } }用$做類型安全訪問(wèn)當(dāng)關(guān)系出現(xiàn)在Loaded提示中時(shí)即可通過(guò)$同步訪問(wèn)// 類型LoadedUser, identity const user await em.findOneOrFail(User, 1, { populate: [identity] }); // 類型安全的同步訪問(wèn) console.log(user.identity.$.email);沒(méi)有 populate 提示時(shí)訪問(wèn)$是編譯錯(cuò)誤// 類型LoadedUser, never const user await em.findOneOrFail(User, 1); // TS 錯(cuò)誤Property $ does not exist on type RefIdentity console.log(user.identity.$.email);$與get()的運(yùn)行時(shí)等價(jià)性由原型上的取值器保證Reference.ts類型層面則由LoadedReference接口typings.ts聲明$: NonNullableT與get(): NonNullableT。如果你不喜歡$這種魔法符號(hào)風(fēng)格可以直接用get()方法二者完全等價(jià)。在函數(shù)簽名中要求已加載關(guān)系可以把Loaded寫(xiě)進(jìn)函數(shù)參數(shù)讓編譯器替你把關(guān)function sendWelcomeEmail(user: LoadedUser, identity) { // 類型安全 —— identity 保證已加載 const email user.identity.$.email; mailer.send(email, Welcome!); } // 可行 —— identity 已被 populate const user1 await em.findOneOrFail(User, 1, { populate: [identity] }); sendWelcomeEmail(user1); // 編譯錯(cuò)誤 —— identity 未 populate const user2 await em.findOneOrFail(User, 1); sendWelcomeEmail(user2);集合的$訪問(wèn)$同樣適用于Collection// 類型LoadedUser, friends const user await em.findOneOrFail(User, 1, { populate: [friends] }); // 對(duì)已加載集合做類型安全迭代 for (const friend of user.friends.$) { console.log(friend.email); }集合側(cè)的收窄由LoadedCollection接口提供typings.ts額外支持getItems()便捷方法。注意Loaded純粹是編譯期構(gòu)造。你可以用類型斷言繞過(guò)它但那恰恰破壞了類型安全的意義。給RefT屬性賦值向RefT屬性賦值時(shí)需要先把實(shí)體包裝成引用import { ref } from mikro-orm/core; const book await em.findOne(Book, 1); // 方式一ref() 助手 book.author ref(someAuthor); // 方式二getReference 的 wrapped 選項(xiàng) book.author em.getReference(Author, 2, { wrapped: true }); // 方式三toReference() book.author wrap(someAuthor).toReference();ref(e)是wrap(e).toReference()的快捷方式二者等價(jià)于Reference.create(e)。wrap()的toReference()實(shí)現(xiàn)WrappedEntity.ts會(huì)緩存并返回一個(gè)Reference包裝器ref()的多態(tài)重載Reference.ts則兼容實(shí)體實(shí)例 / 實(shí)體類型主鍵 / 標(biāo)量值三種入?yún)⑿螒B(tài)。無(wú)需 EntityManager 地創(chuàng)建引用rel()在實(shí)體構(gòu)造函數(shù)內(nèi)部可以用rel()直接按主鍵創(chuàng)建裸引用defineEntity classimport { defineEntity, p, rel } from mikro-orm/core; const BookSchema defineEntity({ name: Book, properties: { id: p.integer().primary(), author: p.manyToOne(() Author).ref(), }, }); // 用法用作者引用創(chuàng)建 book const book em.create(Book, { author: rel(Author, authorId) }); export class Book extends BookSchema.class {} BookSchema.setClass(Book);純defineEntityimport { defineEntity, p, rel } from mikro-orm/core; export const Book defineEntity({ name: Book, properties: { id: p.integer().primary(), author: () p.manyToOne(Author).ref(), }, }); // 用法用作者引用創(chuàng)建 book const book em.create(Book, { author: rel(Author, authorId) });reflect-metadata 裝飾器import { Entity, ManyToOne, PrimaryKey, Ref, rel } from mikro-orm/core; Entity() export class Book { PrimaryKey() id!: number; ManyToOne(() Author, { ref: true }) author!: RefAuthor; constructor(authorId: number) { this.author rel(Author, authorId); } }ts-morph 裝飾器import { Entity, ManyToOne, PrimaryKey, Ref, rel } from mikro-orm/core; Entity() export class Book { PrimaryKey() id!: number; ManyToOne() author!: RefAuthor; constructor(authorId: number) { this.author rel(Author, authorId); } }另一種方式是用wrap()助手提供的toReference()const author new Author(...); book.author wrap(author).toReference();rel()內(nèi)部是Reference.createNakedFromPK(entityType, pk)Reference.ts——注意它創(chuàng)建的是裸實(shí)體引用不套R(shí)eference包裝因此非常適合在構(gòu)造函數(shù)/em.create這類還沒(méi)有 EntityManager 上下文的地方按主鍵占位。主鍵訪問(wèn)RefT類型天然包含實(shí)體的主鍵允許不加載直接讀取const book await em.findOne(Book, 1); console.log(book.author.id); // OK —— 主鍵總是可用MikroORM 按_id、uuid、id的順序探測(cè)主鍵屬性自定義主鍵名時(shí)使用PrimaryKeyProp符號(hào)聲明類型層實(shí)現(xiàn)見(jiàn) typings.ts 的Primary/PrimaryProperty探測(cè)邏輯defineEntity classimport { defineEntity, p } from mikro-orm/core; const AuthorSchema defineEntity({ name: Author, properties: { myPrimaryKey: p.integer().primary(), }, }); export class Author extends AuthorSchema.class {} AuthorSchema.setClass(Author); // 使用 defineEntity 時(shí) PrimaryKeyProp 會(huì)被自動(dòng)推斷純defineEntityimport { defineEntity, p, PrimaryKeyProp } from mikro-orm/core; export const Author defineEntity({ name: Author, properties: { myPrimaryKey: p.integer().primary(), }, }); // 使用 defineEntity 時(shí) PrimaryKeyProp 會(huì)被自動(dòng)推斷reflect-metadata 裝飾器import { Entity, PrimaryKey, PrimaryKeyProp } from mikro-orm/core; Entity() export class Author { PrimaryKey() myPrimaryKey!: number; [PrimaryKeyProp]?: myPrimaryKey; }ts-morph 裝飾器import { Entity, PrimaryKey, PrimaryKeyProp } from mikro-orm/core; Entity() export class Author { PrimaryKey() myPrimaryKey!: number; [PrimaryKeyProp]?: myPrimaryKey; }聲明之后自定義主鍵名即可直接訪問(wèn)// 現(xiàn)在自定義主鍵名也能用了 const book await em.findOne(Book, 1); console.log(book.author.myPrimaryKey);MongoDB 的雙主鍵形態(tài)對(duì) MongoDBidstring與_idObjectId同時(shí)可用defineEntity classimport { defineEntity, p } from mikro-orm/core; const BookSchema defineEntity({ name: Book, properties: { _id: p.type(ObjectId).primary(), id: p.string().serializedPrimaryKey(), author: p.manyToOne(() Author).ref(), }, }); export class Book extends BookSchema.class {} BookSchema.setClass(Book);純defineEntityimport { defineEntity, p } from mikro-orm/core; export const Book defineEntity({ name: Book, properties: { _id: p.type(ObjectId).primary(), id: p.string().serializedPrimaryKey(), author: () p.manyToOne(Author).ref(), }, });reflect-metadata 裝飾器import { Entity, PrimaryKey, SerializedPrimaryKey, ManyToOne, Ref } from mikro-orm/core; Entity() export class Book { PrimaryKey() _id!: ObjectId; SerializedPrimaryKey() id!: string; ManyToOne(() Author, { ref: true }) author!: RefAuthor; }ts-morph 裝飾器import { Entity, PrimaryKey, SerializedPrimaryKey, ManyToOne, Ref } from mikro-orm/core; Entity() export class Book { PrimaryKey() _id!: ObjectId; SerializedPrimaryKey() id!: string; ManyToOne() author!: RefAuthor; }const book await em.findOne(Book, 1); console.log(book.author.id); // string console.log(book.author._id); // ObjectId之所以兩種主鍵都能直接讀是因?yàn)镽eference構(gòu)造時(shí)會(huì)為實(shí)體元數(shù)據(jù)中的每個(gè)主鍵以及序列化主鍵serializedPrimaryKey注冊(cè)取值器Reference.ts。ScalarReference包裝器惰性加載的標(biāo)量屬性非關(guān)系使用ScalarRefTProperty({ lazy: true, ref: true }) passwordHash!: Refstring; Property({ type: json, lazy: true, ref: true }) metadata!: ScalarRefRecordstring, unknown;const user await em.findOne(User, 1); // 加載惰性標(biāo)量 const hash await user.passwordHash.load(); // 或直接 populate const userWithHash await em.findOne(User, 1, { populate: [passwordHash], }); console.log(userWithHash.passwordHash.$);對(duì)string、number這類原始類型RefT會(huì)自動(dòng)解析為ScalarReference對(duì)對(duì)象類型則需要顯式寫(xiě)ScalarRefT。這一分支邏輯體現(xiàn)在RefT條件類型定義中typings.tsT extends Scalar ? ScalarReferenceT : EntityRefT。ScalarReference的運(yùn)行時(shí)實(shí)現(xiàn)Reference.ts通過(guò)bind(entity, property)與宿主實(shí)體綁定load()內(nèi)部調(diào)用helper(entity).populate([property])走與關(guān)系 populate 相同的加載管線$/get()取值器直接返回標(biāo)量值Reference.ts?？煽諛?biāo)量當(dāng)標(biāo)量引用可空時(shí)包裝器本身恒為真值需要在加載后檢查值Property({ type: json, nullable: true, lazy: true, ref: true }) config!: ScalarRefConfig | null;const entity await em.findOne(Entity, 1, { populate: [config] }); // 包裝器存在但值可能是 null if (entity.config.$) { // 這里可以安全使用 console.log(entity.config.$.setting); }小結(jié)按場(chǎng)景選擇正確的工具需求推薦方案顯式區(qū)分已加載/未加載接受.$間接訪問(wèn)RefTref: trueReference包裝器運(yùn)行時(shí)零包裝、只想要編譯期防護(hù)LazyRefTLoaded收窄在裸實(shí)體類型上直接load()/loadOrFail()Loadablemixin /LoadableBaseEntity無(wú)法穿透Loaded時(shí)的逃生通道unref()惰性標(biāo)量屬性非關(guān)系ScalarRefT對(duì)象類型需顯式聲明在構(gòu)造函數(shù)/em.create中按主鍵占位rel()/Reference.createNakedFromPK核心取舍一句話RefT用運(yùn)行時(shí)多一層包裝換運(yùn)行時(shí)與編譯期雙重安全LazyRefT用運(yùn)行時(shí)零成本換僅編譯期安全。兩者都依賴Loaded在類型層面追蹤 populate 狀態(tài)配合$同步訪問(wèn)器可以把空引用訪問(wèn)undefined這類運(yùn)行時(shí)錯(cuò)誤前移到編譯期。相關(guān)源碼與測(cè)試可繼續(xù)深入 packages/core/src/entity/Reference.ts、packages/core/src/typings.ts、tests/features/lazy-ref.test.ts 與 tests/bench/types/lazy-ref.ts。贊分享后端【免費(fèi)下載鏈接】mikro-ormTypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.項(xiàng)目地址https://gitcode.com/gh_mirrors/mi/mikro-orm點(diǎn)擊查看免費(fèi)下載相關(guān)推薦MikroORM 類型安全關(guān)系Type-Safe Relations實(shí)戰(zhàn)指南Reference、Loaded 與 LazyRef 完全解析MikroORM 類型安全關(guān)系Type Safe Relations實(shí)戰(zhàn)指南Reference、Loaded 與 LazyRef 完全解析 導(dǎo)讀 本文是后端MikroORM 7 類型安全關(guān)系Type-Safe Relations完全指南Reference、Loaded 與 $ 訪問(wèn)器MikroORM 7 類型安全關(guān)系Type Safe Relations完全指南Reference、Loaded 與 $ 訪問(wèn)器 MikroORM 7 的后端mikro-orm 類型安全關(guān)聯(lián)Type-Safe Relations從 Reference 包裝器到 Loaded 類型的實(shí)戰(zhàn)指南mikro orm 類型安全關(guān)聯(lián)Type Safe Relations從 Reference 包裝器到 Loaded 類型的實(shí)戰(zhàn)指南 本文以 mikro后端上一篇baoyu-slide-deck 幻燈片圖像生成提示詞規(guī)范基于 base-prompt 理解 The Architect 角色與 16:9 渲染管線下一篇AionUi Preview 模塊深度解析多 Tab 文件預(yù)覽編輯系統(tǒng)與 Agent 流式更新機(jī)制創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 MikroORM Type-Safe Relations 實(shí)戰(zhàn)：用 `Ref`、`LazyRef` 與 `Loaded` 在編譯期杜絕“幽靈關(guān)聯(lián)“
后端【免費(fèi)下載鏈接】mikro-ormTypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.項(xiàng)目地址https://gitcode.com/gh_mirrors/mi/mikro-orm點(diǎn)擊查看免費(fèi)下載本篇指南圍繞 MikroORM 7.1 版本文檔docs/versioned_docs/version-7.1/type-safe-relations.md展開(kāi)系統(tǒng)講解如何把實(shí)體關(guān)聯(lián)從運(yùn)行時(shí)才知道是否已加載的盲區(qū)提升為編譯期即可感知的類型安全體驗(yàn)。讀完你將掌握四種互相配合的工具——Reference包裝器、LazyRef類型級(jí)引用、Loaded類型與$同步訪問(wèn)器以及unref()/Loadable/ScalarReference等配套 API能夠?qū)懗鑫醇虞d即編譯報(bào)錯(cuò)、已加載即同步訪問(wèn)的實(shí)體層代碼。為什么關(guān)系需要類型安全在 MikroORM 中實(shí)體關(guān)系被映射為實(shí)體引用entity reference——即至少攜帶主鍵的實(shí)體實(shí)例該引用存放在 Identity Map 中因此同一份數(shù)據(jù)反復(fù)查詢得到的是同一個(gè)對(duì)象引用ManyToOne(() Author) author!: Author;問(wèn)題在于TypeScript 無(wú)法靜態(tài)判斷該關(guān)系是否已真正從數(shù)據(jù)庫(kù)加載。author屬性的類型永遠(yuǎn)是Author即使它只是一個(gè)只有主鍵、其余屬性未初始化的引用stubconst book await em.findOne(Book, 1); console.log(book.author instanceof Author); // true —— 是 Author 實(shí)例 console.log(wrap(book.author).isInitialized()); // false —— 但并未加載 console.log(book.author.name); // undefined —— Author 尚未加載這種看起來(lái)是實(shí)體、摸起來(lái)卻是空殼的關(guān)聯(lián)是運(yùn)行時(shí)錯(cuò)誤的溫床。為此 MikroORM 提供了一整套類型安全工具Reference包裝器把關(guān)系包裝成RefT顯式區(qū)分已加載/未加載狀態(tài)Loaded類型在類型層面追蹤哪些關(guān)系已被populate$訪問(wèn)器對(duì)已加載關(guān)系提供類型安全的同步訪問(wèn)。其類型核心定義位于 typings.ts運(yùn)行時(shí)包裝器實(shí)現(xiàn)在 Reference.ts。Reference包裝器Reference包裝一個(gè)實(shí)體引用并提供一組安全的訪問(wèn)方法方法說(shuō)明load()加載實(shí)體返回PromiseTload(prop)加載實(shí)體并返回指定屬性loadOrFail()加載實(shí)體找不到時(shí)拋出錯(cuò)誤行為同em.findOneOrFail()unwrap()返回底層實(shí)體不安全可能未初始化isInitialized()返回實(shí)體是否已加載getEntity()返回實(shí)體未初始化則拋出錯(cuò)誤getProperty(prop)返回屬性未初始化則拋出錯(cuò)誤$/get()同步訪問(wèn)僅在LoadedReference上可用從源碼看Reference類Reference.ts在構(gòu)造時(shí)會(huì)把實(shí)體的主鍵屬性通過(guò)Object.defineProperty復(fù)制到包裝器上這就是ref.id無(wú)需unwrap()即可直接讀取的原因同時(shí)$與get是定義在Reference.prototype上的取值器Reference.ts分別直接返回底層實(shí)體。定義引用屬性使用RefT類型加上ref: true選項(xiàng)來(lái)聲明引用屬性。MikroORM 7 支持defineEntity、reflect-metadata、ts-morph 等多種實(shí)體定義方式本文按官方文檔的四種 Tab 逐一給出方式一defineEntity class 組合import { defineEntity, p } from mikro-orm/core; const BookSchema defineEntity({ name: Book, properties: { id: p.integer().primary(), author: p.manyToOne(() Author).ref(), }, }); export class Book extends BookSchema.class {} BookSchema.setClass(Book);方式二純defineEntity無(wú) classimport { defineEntity, p } from mikro-orm/core; export const Book defineEntity({ name: Book, properties: { id: p.integer().primary(), author: () p.manyToOne(Author).ref(), }, });方式三reflect-metadata 裝飾器import { Entity, Ref, ManyToOne, PrimaryKey, ref } from mikro-orm/core; Entity() export class Book { PrimaryKey() id!: number; ManyToOne(() Author, { ref: true }) author: RefAuthor; constructor(author: Author) { this.author ref(author); } }方式四ts-morph無(wú)參數(shù)推斷的裝飾器寫(xiě)法import { Entity, Ref, ManyToOne, PrimaryKey, ref } from mikro-orm/core; Entity() export class Book { PrimaryKey() id!: number; ManyToOne() author: RefAuthor; constructor(author: Author) { this.author ref(author); } }使用引用未加載時(shí)Ref只暴露主鍵任何對(duì)非主鍵屬性的訪問(wèn)都會(huì)得到編譯錯(cuò)誤const book await em.findOne(Book, 1); // 引用尚未加載 book.author; // RefAuthor book.author.isInitialized(); // false book.author.id; // OK —— 主鍵永遠(yuǎn)可用 book.author.name; // TS 錯(cuò)誤 —— RefAuthor 上沒(méi)有 name // 加載引用 const author await book.author.load(); author.name; // OK —— 現(xiàn)在已加載 // 或者只加載并取出某個(gè)屬性 const name await book.author.load(name);當(dāng)關(guān)系被 populate 后你得到的是LoadedReference可以通過(guò)$同步訪問(wèn)const book await em.findOne(Book, 1, { populate: [author] }); book.author; // LoadedReferenceAuthor book.author.$.name; // OK —— 類型安全的同步訪問(wèn) book.author.get().name; // 同上另一種等價(jià)寫(xiě)法嚴(yán)格校驗(yàn)getEntity/getPropertyunwrap()是裸奔接口而getEntity()/getProperty()會(huì)在未初始化時(shí)拋錯(cuò)適合在需要強(qiáng)校驗(yàn)的場(chǎng)景使用const book await em.findOne(Book, 1); // 未初始化時(shí)拋錯(cuò) book.author.getEntity(); // Error: ReferenceAuthor not initialized book.author.getProperty(name); // Error: ReferenceAuthor not initialized // 先加載再同步訪問(wèn) await book.author.load(); book.author.getEntity().name; // OK book.author.getProperty(name); // OK對(duì)應(yīng)錯(cuò)誤信息由getEntity()在未初始化時(shí)拋出Reference.ts。與wrap(entity).init()總是從數(shù)據(jù)庫(kù)刷新不同Reference.load()只有當(dāng)實(shí)體不在 Identity Map 中時(shí)才會(huì)發(fā)起查詢——已加載則直接復(fù)用內(nèi)存中的對(duì)象見(jiàn) Reference.ts 中isInitialized()與refresh選項(xiàng)的分支邏輯。LazyRefT—— 類型層面的引用如果你想要編譯期的 populate 狀態(tài)安全但又不想承擔(dān)Reference帶來(lái)的.$/.get()間接訪問(wèn)可以使用LazyRefT。它是純類型標(biāo)記運(yùn)行時(shí)屬性直接持有實(shí)體實(shí)例與不帶ref: true的普通關(guān)系完全一致但 TypeScript 在Loaded收窄之前只允許你訪問(wèn)主鍵。ManyToOne(() Author) author!: LazyRefAuthor;用defineEntity時(shí)對(duì)應(yīng).lazyRef()const BookSchema defineEntity({ name: Book, properties: { author: () p.manyToOne(AuthorSchema).lazyRef(), }, });從源碼看LazyRef是一個(gè)帶唯一符號(hào)品牌brand的交叉類型{ [K in PrimaryPropertyT keyof T]: T[K] } LazyRef.BrandTtypings.ts它把可訪問(wèn)屬性收窄為主鍵其余屬性在編譯期被鎖住。語(yǔ)義對(duì)比LazyRefTvsRefTLazyRefTRefT運(yùn)行時(shí)值實(shí)體實(shí)例stub 或已水合Reference包裝器instanceof T運(yùn)行時(shí)truefalse訪問(wèn)未加載的主鍵ref.id?ref.id?訪問(wèn)未加載的非主鍵編譯錯(cuò)誤 ?編譯錯(cuò)誤 ?訪問(wèn)已加載屬性loaded.author.name無(wú).$loaded.author.$.nameload()/loadOrFail()方法? —— 需在目標(biāo)實(shí)體上用Loadablemixin? 內(nèi)置關(guān)于instanceof的注意點(diǎn)上表中的instanceof T指的是運(yùn)行時(shí) JS 檢查——book.author instanceof Author返回true。但 TypeScript 的instanceof控制流收窄不會(huì)剝離LazyRefT的品牌標(biāo)記所以if (book.author instanceof Author) { /* 這里 book.author.name 依然是編譯錯(cuò)誤 */ }并不能讓你獲得完整實(shí)體訪問(wèn)。請(qǐng)使用unref()或Loaded收窄來(lái)獲得編譯期訪問(wèn)。用法示例const book await em.findOneOrFail(Book, 1); book.author.id; // ok —— 主鍵總是可訪問(wèn) book.author.name; // 編譯錯(cuò)誤 —— 未加載 const loaded await em.findOneOrFail(Book, 1, { populate: [author] }); loaded.author.name; // ok —— LoadedBook, author 把 LazyRefAuthor 收窄為 Author測(cè)試 lazy-ref.test.ts 對(duì)上述語(yǔ)義做了逐一驗(yàn)證運(yùn)行時(shí)值是實(shí)體實(shí)例而非包裝器第 85-90 行、未 populate 時(shí)主鍵可訪問(wèn)而name是編譯錯(cuò)誤第 126-133 行、populate 后Loaded收窄恢復(fù)完整訪問(wèn)第 135-140 行。適用范圍LazyRefT只用于 to-one 關(guān)系ManyToOne、OneToOne。集合關(guān)系本身已有CollectionT的間接層無(wú)需此標(biāo)記。注意安全邊界該安全純粹是編譯期的。JS 代碼、as any強(qiáng)轉(zhuǎn)、或繞過(guò)Loaded的代碼路徑在運(yùn)行時(shí)可以自由讀取任何屬性——對(duì)未 populate 的引用只有主鍵的 stub這些讀取會(huì)得到undefined。如果關(guān)系已被 populate底層實(shí)體已完全水合讀取行為正常該警告只針對(duì) stub 場(chǎng)景與普通非Ref關(guān)系是同一個(gè)坑。類型性能LazyRefT在Loaded/AutoPath收窄路徑上只增加一個(gè)條件分支成本與RefT相當(dāng)已加載收窄時(shí)甚至略便宜因?yàn)椴粫?huì)產(chǎn)生LoadedReference交叉類型。測(cè)量數(shù)據(jù)見(jiàn) tests/bench/types/lazy-ref.tsLoaded LazyRef - single to-one為 954 次實(shí)例化對(duì)應(yīng)Ref基線為 971 次深層鏈5 級(jí)AutoPath LazyRef為 1165 次實(shí)例化。unref()—— 無(wú)法穿透Loaded時(shí)的逃生通道當(dāng)代碼周圍都是裸Book類型而非LoadedBook, author而你確信關(guān)系已被 populate 時(shí)用unref()把LazyRefT或RefT收窄回Timport { unref } from mikro-orm/core; function logAuthor(book: Book) { // book.author 是 LazyRefAuthor —— 直接寫(xiě) .name 是編譯錯(cuò)誤 console.log(unref(book.author).name); }unref()是ref()的逆操作作用于以下幾類值實(shí)現(xiàn)見(jiàn) Reference.tsRefT/ReferenceT實(shí)體—— 調(diào)用.unwrap()返回TLazyRefT—— 運(yùn)行時(shí)身份轉(zhuǎn)換底層值本來(lái)就是T返回T普通T—— 透?jìng)鞣祷豑ScalarReferenceV/ScalarRefV—— 調(diào)用.unwrap()返回V | undefined標(biāo)量可能未綁定null/undefined—— 透?jìng)鳌：推胀╝s強(qiáng)轉(zhuǎn)一樣unref()對(duì)實(shí)體關(guān)系只做編譯期收窄——若實(shí)體是從未 populate 的 stub非主鍵屬性在運(yùn)行時(shí)仍是undefined。在你確信關(guān)系已加載時(shí)使用它能穿透Loaded時(shí)優(yōu)先選擇把它寫(xiě)進(jìn)函數(shù)簽名。測(cè)試 lazy-ref.test.ts 覆蓋了unref()對(duì)LazyRef、Ref、普通實(shí)體、標(biāo)量引用及null/undefined的全部行為。Loadablemixin —— 在實(shí)體上獲得load()/loadOrFail()如果你用的是普通關(guān)系或LazyRefT又想要Reference包裝器提供的load()/loadOrFail()便利可以在實(shí)體類上啟用Loadablemixin。它把這兩個(gè)方法掛到實(shí)體原型上讓你能直接在關(guān)系目標(biāo)上調(diào)用import { BaseEntity, Loadable, LoadableBaseEntity } from mikro-orm/core; // 便捷方式BaseEntity 已預(yù)組合該 mixin class User extends LoadableBaseEntity { // ... } // 獨(dú)立方式不繼承任何基類 class Product extends Loadable() { // ... } // 或與自己的基類組合 class Article extends Loadable(MyBase) { // ... } const user orm.em.getReference(User, 1); const loaded await user.load(); // PromiseUser | null const loadedOrThrows await user.loadOrFail(); // PromiseUser該 mixin 的實(shí)現(xiàn)位于 BaseEntity.tsload()內(nèi)部就是Reference.create(this).load(...)因此同樣遵循已加載則不重復(fù)查詢的 Identity Map 語(yǔ)義LoadableBaseEntity是Loadable(BaseEntity)的預(yù)組合別名BaseEntity.ts。按設(shè)計(jì)選擇啟用BaseEntity本身不會(huì)獲得這兩個(gè)方法因此已擁有l(wèi)oad/loadOrFail屬性的實(shí)體不會(huì)受影響。反過(guò)來(lái)若對(duì)已定義load的基類應(yīng)用 mixin會(huì)觸發(fā)編譯錯(cuò)誤以防止靜默覆蓋EnsureNoLoadConflict檢查BaseEntity.ts。Loaded類型LoadedEntity, Hints在編譯期追蹤哪些關(guān)系已被 populate。所有em.find*方法都返回該類型// 類型LoadedUser, never[] const users await em.find(User, {}); // 類型LoadedUser, identity | friends[] const usersWithRelations await em.find(User, {}, { populate: [identity, friends], });其內(nèi)部構(gòu)造typings.ts會(huì)遍歷實(shí)體屬性把 populate 提示中命中的關(guān)系屬性替換為L(zhǎng)oadedProp對(duì)LazyRef/Ref/Collection分別收窄并附加__loadedType、__loadHint標(biāo)記符號(hào)__loadHint利用逆變contravariance保證LoadedA, b不可賦值給LoadedA, b.c從而讓嵌套提示精確匹配。以下面的User實(shí)體為例含identity引用關(guān)系與friends集合關(guān)系defineEntity classimport { defineEntity, p } from mikro-orm/core; const UserSchema defineEntity({ name: User, properties: { id: p.integer().primary(), identity: p.manyToOne(() Identity).ref(), friends: p.manyToMany(() User), }, }); export class User extends UserSchema.class {} UserSchema.setClass(User);純defineEntityimport { defineEntity, p } from mikro-orm/core; export const User defineEntity({ name: User, properties: { id: p.integer().primary(), identity: () p.manyToOne(Identity).ref(), friends: () p.manyToMany(User), }, });reflect-metadata 裝飾器import { Entity, PrimaryKey, ManyToOne, ManyToMany, Collection, Ref, ref } from mikro-orm/core; Entity() export class User { PrimaryKey() id!: number; ManyToOne(() Identity, { ref: true }) identity: RefIdentity; ManyToMany(() User) friends new CollectionUser(this); constructor(identity: Identity) { this.identity ref(identity); } }ts-morph 裝飾器import { Entity, PrimaryKey, ManyToOne, ManyToMany, Collection, Ref, ref } from mikro-orm/core; Entity() export class User { PrimaryKey() id!: number; ManyToOne() identity: RefIdentity; ManyToMany(() User) friends new CollectionUser(this); constructor(identity: Identity) { this.identity ref(identity); } }用$做類型安全訪問(wèn)當(dāng)關(guān)系出現(xiàn)在Loaded提示中時(shí)即可通過(guò)$同步訪問(wèn)// 類型LoadedUser, identity const user await em.findOneOrFail(User, 1, { populate: [identity] }); // 類型安全的同步訪問(wèn) console.log(user.identity.$.email);沒(méi)有 populate 提示時(shí)訪問(wèn)$是編譯錯(cuò)誤// 類型LoadedUser, never const user await em.findOneOrFail(User, 1); // TS 錯(cuò)誤Property $ does not exist on type RefIdentity console.log(user.identity.$.email);$與get()的運(yùn)行時(shí)等價(jià)性由原型上的取值器保證Reference.ts類型層面則由LoadedReference接口typings.ts聲明$: NonNullableT與get(): NonNullableT。如果你不喜歡$這種魔法符號(hào)風(fēng)格可以直接用get()方法二者完全等價(jià)。在函數(shù)簽名中要求已加載關(guān)系可以把Loaded寫(xiě)進(jìn)函數(shù)參數(shù)讓編譯器替你把關(guān)function sendWelcomeEmail(user: LoadedUser, identity) { // 類型安全 —— identity 保證已加載 const email user.identity.$.email; mailer.send(email, Welcome!); } // 可行 —— identity 已被 populate const user1 await em.findOneOrFail(User, 1, { populate: [identity] }); sendWelcomeEmail(user1); // 編譯錯(cuò)誤 —— identity 未 populate const user2 await em.findOneOrFail(User, 1); sendWelcomeEmail(user2);集合的$訪問(wèn)$同樣適用于Collection// 類型LoadedUser, friends const user await em.findOneOrFail(User, 1, { populate: [friends] }); // 對(duì)已加載集合做類型安全迭代 for (const friend of user.friends.$) { console.log(friend.email); }集合側(cè)的收窄由LoadedCollection接口提供typings.ts額外支持getItems()便捷方法。注意Loaded純粹是編譯期構(gòu)造。你可以用類型斷言繞過(guò)它但那恰恰破壞了類型安全的意義。給RefT屬性賦值向RefT屬性賦值時(shí)需要先把實(shí)體包裝成引用import { ref } from mikro-orm/core; const book await em.findOne(Book, 1); // 方式一ref() 助手 book.author ref(someAuthor); // 方式二getReference 的 wrapped 選項(xiàng) book.author em.getReference(Author, 2, { wrapped: true }); // 方式三toReference() book.author wrap(someAuthor).toReference();ref(e)是wrap(e).toReference()的快捷方式二者等價(jià)于Reference.create(e)。wrap()的toReference()實(shí)現(xiàn)WrappedEntity.ts會(huì)緩存并返回一個(gè)Reference包裝器ref()的多態(tài)重載Reference.ts則兼容實(shí)體實(shí)例 / 實(shí)體類型主鍵 / 標(biāo)量值三種入?yún)⑿螒B(tài)。無(wú)需 EntityManager 地創(chuàng)建引用rel()在實(shí)體構(gòu)造函數(shù)內(nèi)部可以用rel()直接按主鍵創(chuàng)建裸引用defineEntity classimport { defineEntity, p, rel } from mikro-orm/core; const BookSchema defineEntity({ name: Book, properties: { id: p.integer().primary(), author: p.manyToOne(() Author).ref(), }, }); // 用法用作者引用創(chuàng)建 book const book em.create(Book, { author: rel(Author, authorId) }); export class Book extends BookSchema.class {} BookSchema.setClass(Book);純defineEntityimport { defineEntity, p, rel } from mikro-orm/core; export const Book defineEntity({ name: Book, properties: { id: p.integer().primary(), author: () p.manyToOne(Author).ref(), }, }); // 用法用作者引用創(chuàng)建 book const book em.create(Book, { author: rel(Author, authorId) });reflect-metadata 裝飾器import { Entity, ManyToOne, PrimaryKey, Ref, rel } from mikro-orm/core; Entity() export class Book { PrimaryKey() id!: number; ManyToOne(() Author, { ref: true }) author!: RefAuthor; constructor(authorId: number) { this.author rel(Author, authorId); } }ts-morph 裝飾器import { Entity, ManyToOne, PrimaryKey, Ref, rel } from mikro-orm/core; Entity() export class Book { PrimaryKey() id!: number; ManyToOne() author!: RefAuthor; constructor(authorId: number) { this.author rel(Author, authorId); } }另一種方式是用wrap()助手提供的toReference()const author new Author(...); book.author wrap(author).toReference();rel()內(nèi)部是Reference.createNakedFromPK(entityType, pk)Reference.ts——注意它創(chuàng)建的是裸實(shí)體引用不套R(shí)eference包裝因此非常適合在構(gòu)造函數(shù)/em.create這類還沒(méi)有 EntityManager 上下文的地方按主鍵占位。主鍵訪問(wèn)RefT類型天然包含實(shí)體的主鍵允許不加載直接讀取const book await em.findOne(Book, 1); console.log(book.author.id); // OK —— 主鍵總是可用MikroORM 按_id、uuid、id的順序探測(cè)主鍵屬性自定義主鍵名時(shí)使用PrimaryKeyProp符號(hào)聲明類型層實(shí)現(xiàn)見(jiàn) typings.ts 的Primary/PrimaryProperty探測(cè)邏輯defineEntity classimport { defineEntity, p } from mikro-orm/core; const AuthorSchema defineEntity({ name: Author, properties: { myPrimaryKey: p.integer().primary(), }, }); export class Author extends AuthorSchema.class {} AuthorSchema.setClass(Author); // 使用 defineEntity 時(shí) PrimaryKeyProp 會(huì)被自動(dòng)推斷純defineEntityimport { defineEntity, p, PrimaryKeyProp } from mikro-orm/core; export const Author defineEntity({ name: Author, properties: { myPrimaryKey: p.integer().primary(), }, }); // 使用 defineEntity 時(shí) PrimaryKeyProp 會(huì)被自動(dòng)推斷reflect-metadata 裝飾器import { Entity, PrimaryKey, PrimaryKeyProp } from mikro-orm/core; Entity() export class Author { PrimaryKey() myPrimaryKey!: number; [PrimaryKeyProp]?: myPrimaryKey; }ts-morph 裝飾器import { Entity, PrimaryKey, PrimaryKeyProp } from mikro-orm/core; Entity() export class Author { PrimaryKey() myPrimaryKey!: number; [PrimaryKeyProp]?: myPrimaryKey; }聲明之后自定義主鍵名即可直接訪問(wèn)// 現(xiàn)在自定義主鍵名也能用了 const book await em.findOne(Book, 1); console.log(book.author.myPrimaryKey);MongoDB 的雙主鍵形態(tài)對(duì) MongoDBidstring與_idObjectId同時(shí)可用defineEntity classimport { defineEntity, p } from mikro-orm/core; const BookSchema defineEntity({ name: Book, properties: { _id: p.type(ObjectId).primary(), id: p.string().serializedPrimaryKey(), author: p.manyToOne(() Author).ref(), }, }); export class Book extends BookSchema.class {} BookSchema.setClass(Book);純defineEntityimport { defineEntity, p } from mikro-orm/core; export const Book defineEntity({ name: Book, properties: { _id: p.type(ObjectId).primary(), id: p.string().serializedPrimaryKey(), author: () p.manyToOne(Author).ref(), }, });reflect-metadata 裝飾器import { Entity, PrimaryKey, SerializedPrimaryKey, ManyToOne, Ref } from mikro-orm/core; Entity() export class Book { PrimaryKey() _id!: ObjectId; SerializedPrimaryKey() id!: string; ManyToOne(() Author, { ref: true }) author!: RefAuthor; }ts-morph 裝飾器import { Entity, PrimaryKey, SerializedPrimaryKey, ManyToOne, Ref } from mikro-orm/core; Entity() export class Book { PrimaryKey() _id!: ObjectId; SerializedPrimaryKey() id!: string; ManyToOne() author!: RefAuthor; }const book await em.findOne(Book, 1); console.log(book.author.id); // string console.log(book.author._id); // ObjectId之所以兩種主鍵都能直接讀是因?yàn)镽eference構(gòu)造時(shí)會(huì)為實(shí)體元數(shù)據(jù)中的每個(gè)主鍵以及序列化主鍵serializedPrimaryKey注冊(cè)取值器Reference.ts。ScalarReference包裝器惰性加載的標(biāo)量屬性非關(guān)系使用ScalarRefTProperty({ lazy: true, ref: true }) passwordHash!: Refstring; Property({ type: json, lazy: true, ref: true }) metadata!: ScalarRefRecordstring, unknown;const user await em.findOne(User, 1); // 加載惰性標(biāo)量 const hash await user.passwordHash.load(); // 或直接 populate const userWithHash await em.findOne(User, 1, { populate: [passwordHash], }); console.log(userWithHash.passwordHash.$);對(duì)string、number這類原始類型RefT會(huì)自動(dòng)解析為ScalarReference對(duì)對(duì)象類型則需要顯式寫(xiě)ScalarRefT。這一分支邏輯體現(xiàn)在RefT條件類型定義中typings.tsT extends Scalar ? ScalarReferenceT : EntityRefT。ScalarReference的運(yùn)行時(shí)實(shí)現(xiàn)Reference.ts通過(guò)bind(entity, property)與宿主實(shí)體綁定load()內(nèi)部調(diào)用helper(entity).populate([property])走與關(guān)系 populate 相同的加載管線$/get()取值器直接返回標(biāo)量值Reference.ts?？煽諛?biāo)量當(dāng)標(biāo)量引用可空時(shí)包裝器本身恒為真值需要在加載后檢查值Property({ type: json, nullable: true, lazy: true, ref: true }) config!: ScalarRefConfig | null;const entity await em.findOne(Entity, 1, { populate: [config] }); // 包裝器存在但值可能是 null if (entity.config.$) { // 這里可以安全使用 console.log(entity.config.$.setting); }小結(jié)按場(chǎng)景選擇正確的工具需求推薦方案顯式區(qū)分已加載/未加載接受.$間接訪問(wèn)RefTref: trueReference包裝器運(yùn)行時(shí)零包裝、只想要編譯期防護(hù)LazyRefTLoaded收窄在裸實(shí)體類型上直接load()/loadOrFail()Loadablemixin /LoadableBaseEntity無(wú)法穿透Loaded時(shí)的逃生通道unref()惰性標(biāo)量屬性非關(guān)系ScalarRefT對(duì)象類型需顯式聲明在構(gòu)造函數(shù)/em.create中按主鍵占位rel()/Reference.createNakedFromPK核心取舍一句話RefT用運(yùn)行時(shí)多一層包裝換運(yùn)行時(shí)與編譯期雙重安全LazyRefT用運(yùn)行時(shí)零成本換僅編譯期安全。兩者都依賴Loaded在類型層面追蹤 populate 狀態(tài)配合$同步訪問(wèn)器可以把空引用訪問(wèn)undefined這類運(yùn)行時(shí)錯(cuò)誤前移到編譯期。相關(guān)源碼與測(cè)試可繼續(xù)深入 packages/core/src/entity/Reference.ts、packages/core/src/typings.ts、tests/features/lazy-ref.test.ts 與 tests/bench/types/lazy-ref.ts。贊分享后端【免費(fèi)下載鏈接】mikro-ormTypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.項(xiàng)目地址https://gitcode.com/gh_mirrors/mi/mikro-orm點(diǎn)擊查看免費(fèi)下載相關(guān)推薦MikroORM 類型安全關(guān)系Type-Safe Relations實(shí)戰(zhàn)指南Reference、Loaded 與 LazyRef 完全解析MikroORM 類型安全關(guān)系Type Safe Relations實(shí)戰(zhàn)指南Reference、Loaded 與 LazyRef 完全解析 導(dǎo)讀 本文是后端MikroORM 7 類型安全關(guān)系Type-Safe Relations完全指南Reference、Loaded 與 $ 訪問(wèn)器MikroORM 7 類型安全關(guān)系Type Safe Relations完全指南Reference、Loaded 與 $ 訪問(wèn)器 MikroORM 7 的后端mikro-orm 類型安全關(guān)聯(lián)Type-Safe Relations從 Reference 包裝器到 Loaded 類型的實(shí)戰(zhàn)指南mikro orm 類型安全關(guān)聯(lián)Type Safe Relations從 Reference 包裝器到 Loaded 類型的實(shí)戰(zhàn)指南 本文以 mikro后端上一篇baoyu-slide-deck 幻燈片圖像生成提示詞規(guī)范基于 base-prompt 理解 The Architect 角色與 16:9 渲染管線下一篇AionUi Preview 模塊深度解析多 Tab 文件預(yù)覽編輯系統(tǒng)與 Agent 流式更新機(jī)制創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考