值 ID、字符串 entity_id 與類型安全的儀表板標(biāo)識(shí))
Metabase Embedding SDK 的 SdkDashboardId 類型數(shù)值 ID、字符串 entity_id 與類型安全的儀表板標(biāo)識(shí)【免費(fèi)下載鏈接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:項(xiàng)目地址: https://gitcode.com/GitHub_Trending/me/metabaseSdkDashboardId是 Metabase Embedding SDK模塊化嵌入中用于標(biāo)識(shí)儀表板的統(tǒng)一類型它以聯(lián)合類型的形式同時(shí)接納「URL 中的數(shù)值 ID」與「API 返回的字符串 entity_id」兩種形態(tài)。本文將以該類型定義為骨架結(jié)合SdkDashboard組件、SdkDashboardEntityPublicProps等公開類型及frontend/src/embedding-sdk-bundle下的真實(shí)實(shí)現(xiàn)講解它的定義、獲取方式、使用位置與底層解析邏輯幫助你寫出類型安全、不會(huì)因 ID 形態(tài)混淆而出錯(cuò)的嵌入式儀表板代碼。類型定義一個(gè)聯(lián)合類型三種形態(tài)在 docs/embedding/sdk/api/snippets/SdkDashboardId.md 中該類型的定義只有一行type SdkDashboardId number | string | SdkEntityId;它不是一個(gè)普通的新類型而是三個(gè)可接受形態(tài)的聯(lián)合union形態(tài)類型含義典型來(lái)源數(shù)值 IDnumber儀表板在 Metabase 數(shù)據(jù)庫(kù)中的自增主鍵儀表板訪問鏈接中的數(shù)字段普通字符串string以字符串形式承載的任意標(biāo)識(shí)通過 API 或 Collection Browser 拿到的entity_id實(shí)體 IDSdkEntityId一種帶品牌標(biāo)記的字符串類型專門表示 Metabase 的實(shí)體標(biāo)識(shí)符API 響應(yīng)中 dashboard 對(duì)象的entity_id字段從類型系統(tǒng)的角度看number | string已經(jīng)足夠?qū)捤傻谌?xiàng)SdkEntityId的加入并不是功能上的硬性要求而是為類型層面的可讀性與約束服務(wù)的——它讓這是 entity_id 字符串這一語(yǔ)義在編譯期就可見。SdkEntityId一種被標(biāo)記的字符串類型SdkEntityId同樣定義在 SDK 的類型目錄中見 docs/embedding/sdk/api/snippets/SdkEntityId.mdtype SdkEntityId string {};這是 TypeScript 中經(jīng)典的品牌類型branded type寫法string {}在運(yùn)行時(shí)沒有任何額外結(jié)構(gòu){}的作用純粹是為了讓SdkEntityId與普通string在類型層面區(qū)分開。這樣設(shè)計(jì)的好處是運(yùn)行時(shí)零開銷它就是一個(gè)字符串可以直接傳給 API、URL 或存儲(chǔ)語(yǔ)義可區(qū)分當(dāng)一個(gè)函數(shù)聲明參數(shù)為SdkEntityId調(diào)用方就清楚這里應(yīng)當(dāng)傳入 entity_id 而非其他任意字符串賦值仍然兼容SdkEntityId可以賦給string類型的變量反之則需要顯式斷言從而在編譯期攔截把普通字符串誤當(dāng) entity_id的用法。對(duì)應(yīng)的源碼聲明位于 frontend/src/embedding-sdk-bundle/types/entity.tsexport type SdkEntityId string {}; export type SdkEntityToken string;如何獲取儀表板的 ID兩條來(lái)源路徑SdkDashboardEntityPublicProps的文檔見 docs/embedding/sdk/api/snippets/SdkDashboardEntityPublicProps.md明確說明了dashboardId的兩種合法來(lái)源數(shù)值 ID當(dāng)你訪問儀表板鏈接時(shí)URL 形如http://localhost:3000/dashboard/1-my-dashboard其中的數(shù)字1就是數(shù)值 ID。字符串 entity_id當(dāng)你直接使用 Metabase API或使用 SDK 的 Collection Browser 選擇儀表板時(shí)數(shù)據(jù)對(duì)象中的entity_id字段就是字符串形式的 ID。在 API 返回的MetabaseDashboard實(shí)體類型中兩種 ID 會(huì)同時(shí)存在定義見 frontend/src/embedding-sdk-bundle/types/dashboard.tsexport type MetabaseDashboard { id: SdkDashboardId; // 數(shù)值 ID或字符串 entity_id entity_id: SdkEntityId; // 字符串實(shí)體 ID created_at: string; updated_at: string; collection?: MetabaseCollection | null; name: string; description: string | null; last-edit-info: { id: number; email: string; first_name: string; last_name: string; timestamp: string; }; };其中id字段直接聲明為SdkDashboardIdentity_id字段聲明為SdkEntityId與類型定義一一對(duì)應(yīng)。SdkDashboardId 在 SDK 中的核心使用位置1. SdkDashboard 組件的dashboardId屬性SdkDashboard以及基于它的InteractiveDashboard、EditableDashboard是模塊化嵌入中最常用的儀表板組件。它的dashboardIdprop 類型就是SdkDashboardId見 frontend/src/embedding-sdk-bundle/components/public/dashboard/SdkDashboard.tsxexport type SdkDashboardProps PropsWithChildren { // ... /** * The ID of the dashboard. * This is either: * - the numerical ID when accessing a dashboard link, * i.e. http://localhost:3000/dashboard/1-my-dashboard where the ID is 1 * - the string ID found in the entity_id key of the dashboard object * when using the API directly or using the SDK Collection Browser */ dashboardId: SdkDashboardId; // ... } // ... ;實(shí)際使用時(shí)兩種寫法都合法// 方式一數(shù)值 ID從儀表板 URL 中提取 SdkDashboard dashboardId{1} / // 方式二字符串 entity_id從 API 或 Collection Browser 獲取 SdkDashboard dashboardIdG3gHfP_4hOG8k6JwQmXvzA /2. SdkDashboardEntityPublicPropsdashboardId 與 guest token 的二選一在SdkDashboardEntityPublicProps中SdkDashboardId與SdkEntityTokenguest 嵌入的 JWT token構(gòu)成互斥關(guān)系——要么通過dashboardId指定儀表板要么通過token走 guest 嵌入二者不可同時(shí)出現(xiàn)見 frontend/src/embedding-sdk-bundle/types/dashboard.tsexport type SdkDashboardEntityPublicProps | { dashboardId: SdkDashboardId | null; token?: never; } | { dashboardId?: never; token: SdkEntityToken | null; };這一設(shè)計(jì)用 TypeScript 的 discriminated union 在編譯期就杜絕了同時(shí)傳入兩個(gè)標(biāo)識(shí)的歧義當(dāng)選擇dashboardId分支時(shí)token被約束為never選擇token分支時(shí)dashboardId被約束為never。3. 內(nèi)部統(tǒng)一處理useSdkDashboardParams 與 JWT 解析在 SDK 內(nèi)部dashboardId并不總是直接作為請(qǐng)求參數(shù)使用。SdkDashboard組件的內(nèi)部實(shí)現(xiàn)中首先通過useExtractResourceIdFromJwtToken判斷當(dāng)前是否為 guest 嵌入若是則從 JWT token 中提取資源 ID否則直接使用傳入的dashboardId見 SdkDashboard.tsxconst { resourceId: dashboardId, token, tokenError, } useExtractResourceIdFromJwtToken({ isGuestEmbed, resourceId: rawDashboardId, token: (!isFirstRender ? tokenFromStore : null) ?? rawToken ?? undefined, });也就是說SdkDashboardId在內(nèi)部會(huì)被解析為真正用于加載數(shù)據(jù)的resourceId這一層對(duì)使用者完全透明。4. 無(wú)效 ID 的錯(cuò)誤處理對(duì)于無(wú)效的 IDSDK 有明確的兜底邏輯。在 SdkDashboard.tsx 中404儀表板不存在與 400entity_id 格式非法都會(huì)被識(shí)別為儀表板未找到渲染DashboardNotFoundError// Passing an invalid entity ID format results in a 400 Bad Request. // We can show this as a generic not found error on the frontend. const isDashboardNotFound errorPage?.status 404 || errorPage?.status 400; if (!dashboardId || isDashboardNotFound) { return ( DashboardNotFoundError id{dashboardId ?? } / ); }這一實(shí)現(xiàn)提醒我們傳入格式非法的 entity_id 會(huì)得到 400 而不是 404二者在 SDK 中被統(tǒng)一處理為未找到。與 SdkQuestionId 的對(duì)比儀表板沒有新建特殊值同為實(shí)體標(biāo)識(shí)類型SdkQuestionId 比SdkDashboardId多出兩個(gè)特殊字符串值type SdkQuestionId number | new | new-native | SdkEntityId;SdkQuestionId中的new與new-native分別代表新建 notebook 式問題與新建原生 SQL 問題用于讓InteractiveQuestion組件進(jìn)入創(chuàng)建模式。而SdkDashboardId沒有對(duì)應(yīng)的特殊值——儀表板組件總是渲染一個(gè)已存在的儀表板新建儀表板需要通過useCreateDashboardApi鉤子創(chuàng)建完成后會(huì)返回新儀表板的 ID隨后即可將其作為SdkDashboardId傳入組件。從源碼可以印證在SdkDashboard的 query builder 流程中新建問題使用的是questionIdnew見 SdkDashboard.tsx而儀表板 ID 始終來(lái)自dashboard.id不存在new這類占位值。實(shí)踐建議何時(shí)用數(shù)值 ID何時(shí)用 entity_id結(jié)合類型定義與使用場(chǎng)景可以給出以下實(shí)踐指引鏈接跳轉(zhuǎn) / 深鏈接場(chǎng)景如果嵌入應(yīng)用需要根據(jù) URL 路由還原儀表板從/dashboard/{id}-{slug}中解析出的數(shù)值 ID 直接就是合法的SdkDashboardId無(wú)需轉(zhuǎn)換。API / Collection Browser 場(chǎng)景當(dāng)儀表板數(shù)據(jù)來(lái)自 API 響應(yīng)或用戶在 Collection Browser 中選中時(shí)優(yōu)先使用entity_id。entity_id 是跨環(huán)境穩(wěn)定的業(yè)務(wù)標(biāo)識(shí)不隨數(shù)據(jù)庫(kù)重建或遷移而改變更適合持久化存儲(chǔ)。類型安全定義自己的組件 props 時(shí)盡量顯式聲明為SdkDashboardId這樣調(diào)用方傳入任何合法形態(tài)都能通過編譯檢查如果需要明確語(yǔ)義比如只接受 entity_id則可以進(jìn)一步使用SdkEntityId。錯(cuò)誤兜底由于非法 entity_id 會(huì)觸發(fā) 400 錯(cuò)誤SDK 會(huì)將其當(dāng)作儀表板未找到處理建議在持久化 entity_id 時(shí)先校驗(yàn)其格式或在組件外層監(jiān)聽加載錯(cuò)誤回調(diào)onLoad/onLoadWithoutCards定義見 dashboard.ts做統(tǒng)一的降級(jí) UI?？偨Y(jié)SdkDashboardId雖然只是一個(gè)三行聯(lián)合類型卻是整個(gè) Embedding SDK 儀表板能力的入口類型它統(tǒng)一了數(shù)值 ID 與字符串 entity_id 兩種形態(tài)通過SdkEntityId的品牌類型為字符串標(biāo)識(shí)提供類型級(jí)語(yǔ)義約束并貫穿于SdkDashboardProps、SdkDashboardEntityPublicProps、MetabaseDashboard實(shí)體與 guest 嵌入的 JWT 解析鏈路中。理解它的定義與解析路徑就能在嵌入開發(fā)中正確選擇 ID 來(lái)源、規(guī)避 400/404 錯(cuò)誤并寫出更健壯的類型安全代碼。【免費(fèi)下載鏈接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:項(xiàng)目地址: https://gitcode.com/GitHub_Trending/me/metabase創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Metabase Embedding SDK 的 SdkDashboardId 類型：數(shù)值 ID、字符串 entity_id 與類型安全的儀表板標(biāo)識(shí)
Metabase Embedding SDK 的 SdkDashboardId 類型數(shù)值 ID、字符串 entity_id 與類型安全的儀表板標(biāo)識(shí)【免費(fèi)下載鏈接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:項(xiàng)目地址: https://gitcode.com/GitHub_Trending/me/metabaseSdkDashboardId是 Metabase Embedding SDK模塊化嵌入中用于標(biāo)識(shí)儀表板的統(tǒng)一類型它以聯(lián)合類型的形式同時(shí)接納「URL 中的數(shù)值 ID」與「API 返回的字符串 entity_id」兩種形態(tài)。本文將以該類型定義為骨架結(jié)合SdkDashboard組件、SdkDashboardEntityPublicProps等公開類型及frontend/src/embedding-sdk-bundle下的真實(shí)實(shí)現(xiàn)講解它的定義、獲取方式、使用位置與底層解析邏輯幫助你寫出類型安全、不會(huì)因 ID 形態(tài)混淆而出錯(cuò)的嵌入式儀表板代碼。類型定義一個(gè)聯(lián)合類型三種形態(tài)在 docs/embedding/sdk/api/snippets/SdkDashboardId.md 中該類型的定義只有一行type SdkDashboardId number | string | SdkEntityId;它不是一個(gè)普通的新類型而是三個(gè)可接受形態(tài)的聯(lián)合union形態(tài)類型含義典型來(lái)源數(shù)值 IDnumber儀表板在 Metabase 數(shù)據(jù)庫(kù)中的自增主鍵儀表板訪問鏈接中的數(shù)字段普通字符串string以字符串形式承載的任意標(biāo)識(shí)通過 API 或 Collection Browser 拿到的entity_id實(shí)體 IDSdkEntityId一種帶品牌標(biāo)記的字符串類型專門表示 Metabase 的實(shí)體標(biāo)識(shí)符API 響應(yīng)中 dashboard 對(duì)象的entity_id字段從類型系統(tǒng)的角度看number | string已經(jīng)足夠?qū)捤傻谌?xiàng)SdkEntityId的加入并不是功能上的硬性要求而是為類型層面的可讀性與約束服務(wù)的——它讓這是 entity_id 字符串這一語(yǔ)義在編譯期就可見。SdkEntityId一種被標(biāo)記的字符串類型SdkEntityId同樣定義在 SDK 的類型目錄中見 docs/embedding/sdk/api/snippets/SdkEntityId.mdtype SdkEntityId string {};這是 TypeScript 中經(jīng)典的品牌類型branded type寫法string {}在運(yùn)行時(shí)沒有任何額外結(jié)構(gòu){}的作用純粹是為了讓SdkEntityId與普通string在類型層面區(qū)分開。這樣設(shè)計(jì)的好處是運(yùn)行時(shí)零開銷它就是一個(gè)字符串可以直接傳給 API、URL 或存儲(chǔ)語(yǔ)義可區(qū)分當(dāng)一個(gè)函數(shù)聲明參數(shù)為SdkEntityId調(diào)用方就清楚這里應(yīng)當(dāng)傳入 entity_id 而非其他任意字符串賦值仍然兼容SdkEntityId可以賦給string類型的變量反之則需要顯式斷言從而在編譯期攔截把普通字符串誤當(dāng) entity_id的用法。對(duì)應(yīng)的源碼聲明位于 frontend/src/embedding-sdk-bundle/types/entity.tsexport type SdkEntityId string {}; export type SdkEntityToken string;如何獲取儀表板的 ID兩條來(lái)源路徑SdkDashboardEntityPublicProps的文檔見 docs/embedding/sdk/api/snippets/SdkDashboardEntityPublicProps.md明確說明了dashboardId的兩種合法來(lái)源數(shù)值 ID當(dāng)你訪問儀表板鏈接時(shí)URL 形如http://localhost:3000/dashboard/1-my-dashboard其中的數(shù)字1就是數(shù)值 ID。字符串 entity_id當(dāng)你直接使用 Metabase API或使用 SDK 的 Collection Browser 選擇儀表板時(shí)數(shù)據(jù)對(duì)象中的entity_id字段就是字符串形式的 ID。在 API 返回的MetabaseDashboard實(shí)體類型中兩種 ID 會(huì)同時(shí)存在定義見 frontend/src/embedding-sdk-bundle/types/dashboard.tsexport type MetabaseDashboard { id: SdkDashboardId; // 數(shù)值 ID或字符串 entity_id entity_id: SdkEntityId; // 字符串實(shí)體 ID created_at: string; updated_at: string; collection?: MetabaseCollection | null; name: string; description: string | null; last-edit-info: { id: number; email: string; first_name: string; last_name: string; timestamp: string; }; };其中id字段直接聲明為SdkDashboardIdentity_id字段聲明為SdkEntityId與類型定義一一對(duì)應(yīng)。SdkDashboardId 在 SDK 中的核心使用位置1. SdkDashboard 組件的dashboardId屬性SdkDashboard以及基于它的InteractiveDashboard、EditableDashboard是模塊化嵌入中最常用的儀表板組件。它的dashboardIdprop 類型就是SdkDashboardId見 frontend/src/embedding-sdk-bundle/components/public/dashboard/SdkDashboard.tsxexport type SdkDashboardProps PropsWithChildren { // ... /** * The ID of the dashboard. * This is either: * - the numerical ID when accessing a dashboard link, * i.e. http://localhost:3000/dashboard/1-my-dashboard where the ID is 1 * - the string ID found in the entity_id key of the dashboard object * when using the API directly or using the SDK Collection Browser */ dashboardId: SdkDashboardId; // ... } // ... ;實(shí)際使用時(shí)兩種寫法都合法// 方式一數(shù)值 ID從儀表板 URL 中提取 SdkDashboard dashboardId{1} / // 方式二字符串 entity_id從 API 或 Collection Browser 獲取 SdkDashboard dashboardIdG3gHfP_4hOG8k6JwQmXvzA /2. SdkDashboardEntityPublicPropsdashboardId 與 guest token 的二選一在SdkDashboardEntityPublicProps中SdkDashboardId與SdkEntityTokenguest 嵌入的 JWT token構(gòu)成互斥關(guān)系——要么通過dashboardId指定儀表板要么通過token走 guest 嵌入二者不可同時(shí)出現(xiàn)見 frontend/src/embedding-sdk-bundle/types/dashboard.tsexport type SdkDashboardEntityPublicProps | { dashboardId: SdkDashboardId | null; token?: never; } | { dashboardId?: never; token: SdkEntityToken | null; };這一設(shè)計(jì)用 TypeScript 的 discriminated union 在編譯期就杜絕了同時(shí)傳入兩個(gè)標(biāo)識(shí)的歧義當(dāng)選擇dashboardId分支時(shí)token被約束為never選擇token分支時(shí)dashboardId被約束為never。3. 內(nèi)部統(tǒng)一處理useSdkDashboardParams 與 JWT 解析在 SDK 內(nèi)部dashboardId并不總是直接作為請(qǐng)求參數(shù)使用。SdkDashboard組件的內(nèi)部實(shí)現(xiàn)中首先通過useExtractResourceIdFromJwtToken判斷當(dāng)前是否為 guest 嵌入若是則從 JWT token 中提取資源 ID否則直接使用傳入的dashboardId見 SdkDashboard.tsxconst { resourceId: dashboardId, token, tokenError, } useExtractResourceIdFromJwtToken({ isGuestEmbed, resourceId: rawDashboardId, token: (!isFirstRender ? tokenFromStore : null) ?? rawToken ?? undefined, });也就是說SdkDashboardId在內(nèi)部會(huì)被解析為真正用于加載數(shù)據(jù)的resourceId這一層對(duì)使用者完全透明。4. 無(wú)效 ID 的錯(cuò)誤處理對(duì)于無(wú)效的 IDSDK 有明確的兜底邏輯。在 SdkDashboard.tsx 中404儀表板不存在與 400entity_id 格式非法都會(huì)被識(shí)別為儀表板未找到渲染DashboardNotFoundError// Passing an invalid entity ID format results in a 400 Bad Request. // We can show this as a generic not found error on the frontend. const isDashboardNotFound errorPage?.status 404 || errorPage?.status 400; if (!dashboardId || isDashboardNotFound) { return ( DashboardNotFoundError id{dashboardId ?? } / ); }這一實(shí)現(xiàn)提醒我們傳入格式非法的 entity_id 會(huì)得到 400 而不是 404二者在 SDK 中被統(tǒng)一處理為未找到。與 SdkQuestionId 的對(duì)比儀表板沒有新建特殊值同為實(shí)體標(biāo)識(shí)類型SdkQuestionId 比SdkDashboardId多出兩個(gè)特殊字符串值type SdkQuestionId number | new | new-native | SdkEntityId;SdkQuestionId中的new與new-native分別代表新建 notebook 式問題與新建原生 SQL 問題用于讓InteractiveQuestion組件進(jìn)入創(chuàng)建模式。而SdkDashboardId沒有對(duì)應(yīng)的特殊值——儀表板組件總是渲染一個(gè)已存在的儀表板新建儀表板需要通過useCreateDashboardApi鉤子創(chuàng)建完成后會(huì)返回新儀表板的 ID隨后即可將其作為SdkDashboardId傳入組件。從源碼可以印證在SdkDashboard的 query builder 流程中新建問題使用的是questionIdnew見 SdkDashboard.tsx而儀表板 ID 始終來(lái)自dashboard.id不存在new這類占位值。實(shí)踐建議何時(shí)用數(shù)值 ID何時(shí)用 entity_id結(jié)合類型定義與使用場(chǎng)景可以給出以下實(shí)踐指引鏈接跳轉(zhuǎn) / 深鏈接場(chǎng)景如果嵌入應(yīng)用需要根據(jù) URL 路由還原儀表板從/dashboard/{id}-{slug}中解析出的數(shù)值 ID 直接就是合法的SdkDashboardId無(wú)需轉(zhuǎn)換。API / Collection Browser 場(chǎng)景當(dāng)儀表板數(shù)據(jù)來(lái)自 API 響應(yīng)或用戶在 Collection Browser 中選中時(shí)優(yōu)先使用entity_id。entity_id 是跨環(huán)境穩(wěn)定的業(yè)務(wù)標(biāo)識(shí)不隨數(shù)據(jù)庫(kù)重建或遷移而改變更適合持久化存儲(chǔ)。類型安全定義自己的組件 props 時(shí)盡量顯式聲明為SdkDashboardId這樣調(diào)用方傳入任何合法形態(tài)都能通過編譯檢查如果需要明確語(yǔ)義比如只接受 entity_id則可以進(jìn)一步使用SdkEntityId。錯(cuò)誤兜底由于非法 entity_id 會(huì)觸發(fā) 400 錯(cuò)誤SDK 會(huì)將其當(dāng)作儀表板未找到處理建議在持久化 entity_id 時(shí)先校驗(yàn)其格式或在組件外層監(jiān)聽加載錯(cuò)誤回調(diào)onLoad/onLoadWithoutCards定義見 dashboard.ts做統(tǒng)一的降級(jí) UI?？偨Y(jié)SdkDashboardId雖然只是一個(gè)三行聯(lián)合類型卻是整個(gè) Embedding SDK 儀表板能力的入口類型它統(tǒng)一了數(shù)值 ID 與字符串 entity_id 兩種形態(tài)通過SdkEntityId的品牌類型為字符串標(biāo)識(shí)提供類型級(jí)語(yǔ)義約束并貫穿于SdkDashboardProps、SdkDashboardEntityPublicProps、MetabaseDashboard實(shí)體與 guest 嵌入的 JWT 解析鏈路中。理解它的定義與解析路徑就能在嵌入開發(fā)中正確選擇 ID 來(lái)源、規(guī)避 400/404 錯(cuò)誤并寫出更健壯的類型安全代碼。【免費(fèi)下載鏈接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:項(xiàng)目地址: https://gitcode.com/GitHub_Trending/me/metabase創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考