React Router 的 useLoaderData / useActionData 類型推斷 ADR從盲目類型斷言到基于泛式的端到端類型安全【免費下載鏈接】react-routerDeclarative routing for React項目地址: https://gitcode.com/GitHub_Trending/re/react-router本文解析 React Router 架構(gòu)決策記錄 0003 的核心內(nèi)容為什么 Remix v1.6.4 時代的useLoaderDataMyData()泛式本質(zhì)上是一次盲目斷言、Date序列化陷阱如何暴露該設(shè)計的缺陷以及顯式提供隱式輸入類型、再推斷返回類型這一決策如何解決 loader/action 與組件之間跨網(wǎng)絡(luò)的類型對齊問題。讀完本文你將理解該 ADR 的完整論證鏈、六條解決標準以及這套設(shè)計在 React Router 7 源碼中SerializeFrom、data()等的最終落地形態(tài)還能看清它后來如何被 ADR 0012 類型推斷 的 typegen 方案取代。一、ADR 背景v1.6.4 的手工對類型時代該 ADR日期 2022-07-11的目標是以優(yōu)秀的開發(fā)者體驗DX實現(xiàn)useLoaderData和useActionData的端到端類型安全。在 Remix v1.6.4 中兩個 hook 的泛式都要求用戶手動指定一個數(shù)據(jù)類型type MyLoaderData { /* ... */ }; type MyActionData { /* ... */ }; export default function Route() { const loaderData useLoaderDataMyLoaderData(); const actionData useActionDataMyActionData(); return div{/* ... */}/div; }為了獲得端到端的類型安全用戶還必須在loader/action中保證json泛式使用同一個類型export const loader: LoaderFunction () { return jsonMyLoaderData({ /* ... */ }); }; export const action: ActionFunction () { return jsonMyActionData({ /* ... */ }); };也就是說一份數(shù)據(jù)形狀要寫兩遍類型甚至三遍且沒有任何機制保證兩邊一致。二、深挖 v1.6.4 源碼泛式只是把any強轉(zhuǎn)成TADR 追溯了 v1.6.4 中remix-run/react的源碼發(fā)現(xiàn)useLoaderData返回的實際上是一個any類型被隱式強轉(zhuǎn)成泛式傳入的任何類型export function useLoaderDataT AppData(): T { return useRemixRouteContext().data; } interface RemixRouteContextType { data: AppData; // AppData any id: string; } export type AppData any;化簡之后就是let data: any; // 某處loader 被調(diào)用并把某個值賦給 data function useLoaderDataT(): T { return data; // -- TypeScript 把這個 any 強轉(zhuǎn)為 T }關(guān)鍵結(jié)論useLoaderData的返回類型既不基于data是怎么被設(shè)置的即loader的返回值也不做任何數(shù)據(jù)校驗而是盲目地把data強轉(zhuǎn)為用戶傳入的泛式T。雙重代價冗余代碼 序列化陷阱ADR 指出了當前方案的兩個問題DX 差、代碼冗余用戶必須手寫數(shù)據(jù)類型的重復(fù)聲明。數(shù)據(jù)形狀一旦變化既要改聲明的type/interface又要改json的實參——而這些類型本可以從json的實參中推斷出來。Date序列化陷阱footgun當前方案鼓勵用戶給json和useLoaderData傳同一個類型但這恰恰是個坑——json可以接受Date這類可 JSON 序列化的類型而useLoaderData拿到的卻是序列化后的類型type MyLoaderData { birthday: Date; }; export const loader: LoaderFunction () { return jsonMyLoaderData({ birthday: new Date(February 15, 1992) }); }; export default function Route() { const { birthday } useLoaderDataMyLoaderData(); // ^ useLoaderData 騙過 TypeScript 認為這是 Date實際上運行時它是一個 string }useActionData同理。數(shù)據(jù)經(jīng)過網(wǎng)絡(luò)傳輸必然是 JSON 序列化后的產(chǎn)物而類型系統(tǒng)對此視而不見——這是一整類編譯通過、運行出錯的隱患。三、解決方案標準Solution CriteriaADR 給出了六條硬約束任何候選方案都必須滿足useLoaderData/useActionData的返回類型應(yīng)當從loader/action推斷出來而不是盲目類型斷言loader/action自身的返回類型應(yīng)當是可推斷的這就要求json的返回類型能從其實參推斷不允許模塊副作用因此像makeLoader這樣的高階函數(shù)方案被直接排除;json應(yīng)當允許JSON.stringify允許的一切;json應(yīng)當只允許JSON.stringify允許的東西useLoaderData不應(yīng)返回JSON.parse無法產(chǎn)生的任何東西。第 4、5、6 條共同刻畫了核心不變量loader 端的可序列化輸入約束 與 組件端的反序列化輸出類型約束必須嚴格對應(yīng)從而消滅Date陷阱這一類錯誤。四、關(guān)鍵洞察loader是useLoaderData的隱式輸入對用 TypeScript 泛式推斷 hook 返回類型曾有過猶豫ADR 引用了社區(qū)討論因為TypeScript 泛式天生適合描述/推斷輸入而不是用來盲目斷言輸出。突破點在于認識到loader和action其實是useLoaderData/useActionData的隱式輸入。換句話說如果保證loader和useLoaderData運行在同一進程中不跨網(wǎng)絡(luò)我們完全可以寫成useLoaderData(loader)把loader變成顯式輸入// 概念上 loader 是 useLoaderData 的輸入 function useLoaderDataLoader extends LoaderFunction(loader: Loader) { /*...*/ }現(xiàn)實中l(wèi)oader在瀏覽器運行時并不存在它跑在服務(wù)端useLoaderData需要在編譯期獲知loader的類型。而loader與useLoaderData由框架統(tǒng)一管理、跨越網(wǎng)絡(luò)協(xié)作拿到的數(shù)據(jù)與自己的loader不對應(yīng)是極其罕見的邊界情況——因此用一個泛式參數(shù)把loader的類型顯式注入給 hook 是安全且合理的。ADR 還類比為 Prisma盡管存在編譯期之后、運行期之前數(shù)據(jù)庫 schema 被修改這類罕見邊界情況Prisma 依然從運行期可用的 schema 推斷類型。五、決策顯式提供隱式輸入的類型再推斷返回值最終決策為useLoaderData顯式提供其隱式輸入loader的類型然后由 hook 推斷自己的返回類型action/useActionData同理export const loader async (args: LoaderArgs) { // ... return json(/*...*/); }; export default function Route() { const data useLoaderDatatypeof loader(); // ... }注意這里不再是手寫MyLoaderData這類獨立類型而是typeof loader——類型直接錨定在loader的真實返回類型上冗余聲明被徹底消除。同時useLoaderData推斷出的返回類型只包含可序列化的JSON類型從類型層面兌現(xiàn)了只返回JSON.parse能產(chǎn)生的東西這條標準。省略泛式時返回unknown如果useLoaderData/useActionData省略泛式就返回any會掩蓋潛在的類型錯誤。ADR 決定改為返回unknowntype MyLoaderData { /*...*/ }; export default function Route() { const data useLoaderData(); // ^? unknown }ADR 同時注明由于這是破壞性變更把缺省返回類型改為unknown被排期到 v2。棄用非推斷的泛式寫法直接傳一個手寫的非推斷類型給useLoaderData本質(zhì)是在隱藏一次不安全的類型斷言。ADR 決定棄用該寫法引導(dǎo)用戶改用顯式類型斷言——斷言清楚地表達了我在此處做了假設(shè)export default function Route() { const dataGeneric useLoaderDataMyLoaderData(); // -- 將被棄用 const dataCast useLoaderData() as MyLoaderData; // - 改用這種寫法 }六、決策的后果與硬性約束ADR 明確列出了該決策帶來的行為變化用戶仍可繼續(xù)提供非推斷類型方式是對useLoaderData/useActionData的返回值做類型斷言用戶通過在泛式中寫typeof loader/typeof action來選擇性加入類型推斷l(xiāng)oader/action的返回類型成為useLoaderData/useActionData推斷類型的唯一事實來源source of truth用戶不再需要為跨網(wǎng)絡(luò)對齊類型而寫冗余代碼;useLoaderData/useActionData的返回類型將與json調(diào)用中數(shù)據(jù)序列化后的類型嚴格對應(yīng)消滅一整類錯誤;選擇類型推斷時不應(yīng)再標注LoaderFunction/ActionFunction——它們會覆蓋推斷出的更窄的返回類型1。 最關(guān)鍵的硬性約束選擇類型推斷的用戶必須從json返回TypedResponse絕不能返回裸對象const loader () { // NO return { hello: world }; // YES return json({ hello: world }); };只有經(jīng)過json后在 React Router 7 中更名/演進為data包裝的數(shù)據(jù)其返回類型才能被正確推斷并施加序列化約束裸返回的對象類型無法參與這一推斷鏈條。七、當前倉庫中的落地印證SerializeFrom與data()ADR 描述的是歷史設(shè)計但 React Router 7 的源碼完整保留并工程化了這套思想?？梢詫φ找韵聦崿F(xiàn)逐條驗證1. hook 的當前簽名——泛式輸入 序列化后輸出。在 packages/react-router/lib/hooks.tsx 中export function useLoaderDataT any(): SerializeFromT { let state useDataRouterState(DataRouterStateHook.UseLoaderData); let routeId useCurrentRouteId(DataRouterStateHook.UseLoaderData); return state.loaderData[routeId] as SerializeFromT; } export function useActionDataT any(): SerializeFromT | undefined { let state useDataRouterState(DataRouterStateHook.UseActionData); let routeId useCurrentRouteId(DataRouterStateHook.UseLoaderData); return (state.actionData ? state.actionData[routeId] : undefined) as | SerializeFromT | undefined; }返回值不再是裸的T而是SerializeFromT——這正是 ADR 推斷出的返回類型只包含可序列化 JSON 類型 的類型學(xué)實現(xiàn)。官方文檔 useLoaderData 與 useActionData 中的示例仍然使用useLoaderDatatypeof loader()這一 ADR 確立的用法。2.SerializeFrom的完整定義。在 packages/react-router/lib/types/route-data.ts 中該類型先判斷函數(shù)參數(shù)的形態(tài)再決定走服務(wù)端數(shù)據(jù)還是客戶端數(shù)據(jù)路徑export type SerializeFromT T extends (...args: infer Args) unknown ? Args extends [ | ClientLoaderFunctionArgs | ClientActionFunctionArgs | ClientDataFunctionArgsunknown, ] ? ClientDataFromT // 客戶端函數(shù)數(shù)據(jù)不過網(wǎng)絡(luò)原樣保留 : ServerDataFromT // 服務(wù)端函數(shù)施加序列化轉(zhuǎn)換 : T;ServerDataFrom會對其返回值套用SerializeT遞歸映射同文件的 L16-L46先識別unstable_SerializesTo品牌類型已可序列化的類型原樣保留函數(shù)一律映射為undefined并遞歸處理Promise、Map/Set、數(shù)組、元組與對象——這比 ADR 原始設(shè)想的純 JSON 字符串化更進一步與 turbo-stream 傳輸層支持的容器類型精確對應(yīng);ClientDataFrom則跳過序列化映射因為clientLoader/clientAction的數(shù)據(jù)不跨網(wǎng)絡(luò)同文件還定義了GetLoaderData/GetActionDataL174-L208處理loaderclientLoaderclientLoader.hydrateHydrateFallback組合下的數(shù)據(jù)形態(tài)——這恰是后續(xù) ADR 0012 中那張組合表格的類型學(xué)基礎(chǔ)。3. 文件內(nèi)的類型級測試。route-data.ts 末尾內(nèi)置了一組ExpectEqual...類型測試直接驗證了 ADR 關(guān)心的行為例如Expect Equal ServerDataFrom() { a: string; b: Date; c: () boolean; d: unstable_SerializesTonumber }, { a: string; b: Date; c: undefined; d: number } c函數(shù)被映射為undefined、d帶序列化品牌被映射為number——正是loader 端只允許可序列化輸入、組件端只得到可反序列化輸出這一不變量的可執(zhí)行證明。4.json約束的運行時對應(yīng)物。ADR 中必須走json的約束在當前倉庫對應(yīng)data()輔助函數(shù)及其Serializable入?yún)⒓s束定義于 packages/react-router/lib/server-runtime/single-fetch.tsSerializable是一個遞歸類型string | number | boolean | bigint | Date | URL | RegExp | Error | Map | Set | Promise | 數(shù)組 | 對象的遞歸聯(lián)合data(value: Serializable, init?)的簽名把它變成了編譯期檢查。這同時滿足了 ADR 解決標準中json允許且只允許JSON.stringify允許的東西兩條——函數(shù)、Symbol等不可序列化值在類型層面即被拒絕。八、結(jié)局被 ADR 0012 取代——從typeof loader到 typegenADR 頭部明確標注了狀態(tài)Superseded by #0012即 decisions/0012-type-inference.md日期 2024-09-20。0012 指出typeof loader方案雖有實質(zhì)改進區(qū)別于useParamsid那種純斷言泛式但仍是樣板代碼且隨應(yīng)用規(guī)模放大容易出錯尤其clientLoaderhydrateHydrateFallback的組合下泛式的正確寫法極其繁瑣。最終方案是放棄用戶手寫泛式改為代碼生成typegen對routes.ts返回的每一條路由把 route 模塊的類型生成到 gitignored 的.react-router/types目錄下路徑鏡像如app/routes/product.tsx對應(yīng)types.product.ts借助tsconfig.json的rootDirs選項讓用戶像從兄弟文件一樣import { LoaderArgs, DefaultProps } from ./types.product并把params、loaderData、actionData作為 props 直接注入default組件——useLoaderData等 hook 因向后兼容保留但目標是逐步棄用。0012 還系統(tǒng)否決了defineRoute、defineLoader系列、Svelte Kit 式零成本類型安全語言服務(wù)插件注入和 TypeScript 插件等替代路線理由包括 tree-shaking/HMR 兼容性與工具鏈typescript-eslint、tsc的互操作。從 0003 到 0012 的演進脈絡(luò)值得注意0003 確立了以 loader/action 返回類型為類型事實來源 序列化感知這兩個核心原則0012 只是把由用戶手寫typeof loader泛式替換為由 typegen 自動注入而 0003 中SerializeFrom所依賴的序列化映射邏輯則原樣保留在今天的 route-data.ts 中。九、實踐要點小結(jié)在本倉庫對應(yīng)的 React Router 7 代碼中推薦寫法仍是useLoaderDatatypeof loader()見 hooks.tsx 的官方示例注釋若框架模式已啟用 typegen則優(yōu)先使用生成的Route.LoaderArgs/ props 方案;loader/action 必須返回data(...)v7 中json的繼任者包裝的TypedResponse裸對象返回會繞過序列化感知類型需要給特殊自定義序列化類型聲明序列化后形態(tài)時使用 unstable_SerializesTo 品牌類型而不是手寫斷言;理解 ADR 的論證結(jié)構(gòu)現(xiàn)狀剖析 → 解決標準 → 關(guān)鍵洞察 → 決策 → 后果與約束是閱讀本倉庫decisions/目錄下其他 ADR 的通用模板ADR 模板 可作參考。原 ADR 腳注引用了當時 TypeScript 提案中的satisfies運算符它能約束函數(shù)類型的同時保留更窄的推斷返回類型從而讓LoaderFunction/ActionFunction與類型推斷共存。?【免費下載鏈接】react-routerDeclarative routing for React項目地址: https://gitcode.com/GitHub_Trending/re/react-router創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 React Router 的 useLoaderData / useActionData 類型推斷 ADR：從盲目類型斷言到基于泛式的端到端類型安全
React Router 的 useLoaderData / useActionData 類型推斷 ADR從盲目類型斷言到基于泛式的端到端類型安全【免費下載鏈接】react-routerDeclarative routing for React項目地址: https://gitcode.com/GitHub_Trending/re/react-router本文解析 React Router 架構(gòu)決策記錄 0003 的核心內(nèi)容為什么 Remix v1.6.4 時代的useLoaderDataMyData()泛式本質(zhì)上是一次盲目斷言、Date序列化陷阱如何暴露該設(shè)計的缺陷以及顯式提供隱式輸入類型、再推斷返回類型這一決策如何解決 loader/action 與組件之間跨網(wǎng)絡(luò)的類型對齊問題。讀完本文你將理解該 ADR 的完整論證鏈、六條解決標準以及這套設(shè)計在 React Router 7 源碼中SerializeFrom、data()等的最終落地形態(tài)還能看清它后來如何被 ADR 0012 類型推斷 的 typegen 方案取代。一、ADR 背景v1.6.4 的手工對類型時代該 ADR日期 2022-07-11的目標是以優(yōu)秀的開發(fā)者體驗DX實現(xiàn)useLoaderData和useActionData的端到端類型安全。在 Remix v1.6.4 中兩個 hook 的泛式都要求用戶手動指定一個數(shù)據(jù)類型type MyLoaderData { /* ... */ }; type MyActionData { /* ... */ }; export default function Route() { const loaderData useLoaderDataMyLoaderData(); const actionData useActionDataMyActionData(); return div{/* ... */}/div; }為了獲得端到端的類型安全用戶還必須在loader/action中保證json泛式使用同一個類型export const loader: LoaderFunction () { return jsonMyLoaderData({ /* ... */ }); }; export const action: ActionFunction () { return jsonMyActionData({ /* ... */ }); };也就是說一份數(shù)據(jù)形狀要寫兩遍類型甚至三遍且沒有任何機制保證兩邊一致。二、深挖 v1.6.4 源碼泛式只是把any強轉(zhuǎn)成TADR 追溯了 v1.6.4 中remix-run/react的源碼發(fā)現(xiàn)useLoaderData返回的實際上是一個any類型被隱式強轉(zhuǎn)成泛式傳入的任何類型export function useLoaderDataT AppData(): T { return useRemixRouteContext().data; } interface RemixRouteContextType { data: AppData; // AppData any id: string; } export type AppData any;化簡之后就是let data: any; // 某處loader 被調(diào)用并把某個值賦給 data function useLoaderDataT(): T { return data; // -- TypeScript 把這個 any 強轉(zhuǎn)為 T }關(guān)鍵結(jié)論useLoaderData的返回類型既不基于data是怎么被設(shè)置的即loader的返回值也不做任何數(shù)據(jù)校驗而是盲目地把data強轉(zhuǎn)為用戶傳入的泛式T。雙重代價冗余代碼 序列化陷阱ADR 指出了當前方案的兩個問題DX 差、代碼冗余用戶必須手寫數(shù)據(jù)類型的重復(fù)聲明。數(shù)據(jù)形狀一旦變化既要改聲明的type/interface又要改json的實參——而這些類型本可以從json的實參中推斷出來。Date序列化陷阱footgun當前方案鼓勵用戶給json和useLoaderData傳同一個類型但這恰恰是個坑——json可以接受Date這類可 JSON 序列化的類型而useLoaderData拿到的卻是序列化后的類型type MyLoaderData { birthday: Date; }; export const loader: LoaderFunction () { return jsonMyLoaderData({ birthday: new Date(February 15, 1992) }); }; export default function Route() { const { birthday } useLoaderDataMyLoaderData(); // ^ useLoaderData 騙過 TypeScript 認為這是 Date實際上運行時它是一個 string }useActionData同理。數(shù)據(jù)經(jīng)過網(wǎng)絡(luò)傳輸必然是 JSON 序列化后的產(chǎn)物而類型系統(tǒng)對此視而不見——這是一整類編譯通過、運行出錯的隱患。三、解決方案標準Solution CriteriaADR 給出了六條硬約束任何候選方案都必須滿足useLoaderData/useActionData的返回類型應(yīng)當從loader/action推斷出來而不是盲目類型斷言loader/action自身的返回類型應(yīng)當是可推斷的這就要求json的返回類型能從其實參推斷不允許模塊副作用因此像makeLoader這樣的高階函數(shù)方案被直接排除;json應(yīng)當允許JSON.stringify允許的一切;json應(yīng)當只允許JSON.stringify允許的東西useLoaderData不應(yīng)返回JSON.parse無法產(chǎn)生的任何東西。第 4、5、6 條共同刻畫了核心不變量loader 端的可序列化輸入約束 與 組件端的反序列化輸出類型約束必須嚴格對應(yīng)從而消滅Date陷阱這一類錯誤。四、關(guān)鍵洞察loader是useLoaderData的隱式輸入對用 TypeScript 泛式推斷 hook 返回類型曾有過猶豫ADR 引用了社區(qū)討論因為TypeScript 泛式天生適合描述/推斷輸入而不是用來盲目斷言輸出。突破點在于認識到loader和action其實是useLoaderData/useActionData的隱式輸入。換句話說如果保證loader和useLoaderData運行在同一進程中不跨網(wǎng)絡(luò)我們完全可以寫成useLoaderData(loader)把loader變成顯式輸入// 概念上 loader 是 useLoaderData 的輸入 function useLoaderDataLoader extends LoaderFunction(loader: Loader) { /*...*/ }現(xiàn)實中l(wèi)oader在瀏覽器運行時并不存在它跑在服務(wù)端useLoaderData需要在編譯期獲知loader的類型。而loader與useLoaderData由框架統(tǒng)一管理、跨越網(wǎng)絡(luò)協(xié)作拿到的數(shù)據(jù)與自己的loader不對應(yīng)是極其罕見的邊界情況——因此用一個泛式參數(shù)把loader的類型顯式注入給 hook 是安全且合理的。ADR 還類比為 Prisma盡管存在編譯期之后、運行期之前數(shù)據(jù)庫 schema 被修改這類罕見邊界情況Prisma 依然從運行期可用的 schema 推斷類型。五、決策顯式提供隱式輸入的類型再推斷返回值最終決策為useLoaderData顯式提供其隱式輸入loader的類型然后由 hook 推斷自己的返回類型action/useActionData同理export const loader async (args: LoaderArgs) { // ... return json(/*...*/); }; export default function Route() { const data useLoaderDatatypeof loader(); // ... }注意這里不再是手寫MyLoaderData這類獨立類型而是typeof loader——類型直接錨定在loader的真實返回類型上冗余聲明被徹底消除。同時useLoaderData推斷出的返回類型只包含可序列化的JSON類型從類型層面兌現(xiàn)了只返回JSON.parse能產(chǎn)生的東西這條標準。省略泛式時返回unknown如果useLoaderData/useActionData省略泛式就返回any會掩蓋潛在的類型錯誤。ADR 決定改為返回unknowntype MyLoaderData { /*...*/ }; export default function Route() { const data useLoaderData(); // ^? unknown }ADR 同時注明由于這是破壞性變更把缺省返回類型改為unknown被排期到 v2。棄用非推斷的泛式寫法直接傳一個手寫的非推斷類型給useLoaderData本質(zhì)是在隱藏一次不安全的類型斷言。ADR 決定棄用該寫法引導(dǎo)用戶改用顯式類型斷言——斷言清楚地表達了我在此處做了假設(shè)export default function Route() { const dataGeneric useLoaderDataMyLoaderData(); // -- 將被棄用 const dataCast useLoaderData() as MyLoaderData; // - 改用這種寫法 }六、決策的后果與硬性約束ADR 明確列出了該決策帶來的行為變化用戶仍可繼續(xù)提供非推斷類型方式是對useLoaderData/useActionData的返回值做類型斷言用戶通過在泛式中寫typeof loader/typeof action來選擇性加入類型推斷l(xiāng)oader/action的返回類型成為useLoaderData/useActionData推斷類型的唯一事實來源source of truth用戶不再需要為跨網(wǎng)絡(luò)對齊類型而寫冗余代碼;useLoaderData/useActionData的返回類型將與json調(diào)用中數(shù)據(jù)序列化后的類型嚴格對應(yīng)消滅一整類錯誤;選擇類型推斷時不應(yīng)再標注LoaderFunction/ActionFunction——它們會覆蓋推斷出的更窄的返回類型1。 最關(guān)鍵的硬性約束選擇類型推斷的用戶必須從json返回TypedResponse絕不能返回裸對象const loader () { // NO return { hello: world }; // YES return json({ hello: world }); };只有經(jīng)過json后在 React Router 7 中更名/演進為data包裝的數(shù)據(jù)其返回類型才能被正確推斷并施加序列化約束裸返回的對象類型無法參與這一推斷鏈條。七、當前倉庫中的落地印證SerializeFrom與data()ADR 描述的是歷史設(shè)計但 React Router 7 的源碼完整保留并工程化了這套思想?？梢詫φ找韵聦崿F(xiàn)逐條驗證1. hook 的當前簽名——泛式輸入 序列化后輸出。在 packages/react-router/lib/hooks.tsx 中export function useLoaderDataT any(): SerializeFromT { let state useDataRouterState(DataRouterStateHook.UseLoaderData); let routeId useCurrentRouteId(DataRouterStateHook.UseLoaderData); return state.loaderData[routeId] as SerializeFromT; } export function useActionDataT any(): SerializeFromT | undefined { let state useDataRouterState(DataRouterStateHook.UseActionData); let routeId useCurrentRouteId(DataRouterStateHook.UseLoaderData); return (state.actionData ? state.actionData[routeId] : undefined) as | SerializeFromT | undefined; }返回值不再是裸的T而是SerializeFromT——這正是 ADR 推斷出的返回類型只包含可序列化 JSON 類型 的類型學(xué)實現(xiàn)。官方文檔 useLoaderData 與 useActionData 中的示例仍然使用useLoaderDatatypeof loader()這一 ADR 確立的用法。2.SerializeFrom的完整定義。在 packages/react-router/lib/types/route-data.ts 中該類型先判斷函數(shù)參數(shù)的形態(tài)再決定走服務(wù)端數(shù)據(jù)還是客戶端數(shù)據(jù)路徑export type SerializeFromT T extends (...args: infer Args) unknown ? Args extends [ | ClientLoaderFunctionArgs | ClientActionFunctionArgs | ClientDataFunctionArgsunknown, ] ? ClientDataFromT // 客戶端函數(shù)數(shù)據(jù)不過網(wǎng)絡(luò)原樣保留 : ServerDataFromT // 服務(wù)端函數(shù)施加序列化轉(zhuǎn)換 : T;ServerDataFrom會對其返回值套用SerializeT遞歸映射同文件的 L16-L46先識別unstable_SerializesTo品牌類型已可序列化的類型原樣保留函數(shù)一律映射為undefined并遞歸處理Promise、Map/Set、數(shù)組、元組與對象——這比 ADR 原始設(shè)想的純 JSON 字符串化更進一步與 turbo-stream 傳輸層支持的容器類型精確對應(yīng);ClientDataFrom則跳過序列化映射因為clientLoader/clientAction的數(shù)據(jù)不跨網(wǎng)絡(luò)同文件還定義了GetLoaderData/GetActionDataL174-L208處理loaderclientLoaderclientLoader.hydrateHydrateFallback組合下的數(shù)據(jù)形態(tài)——這恰是后續(xù) ADR 0012 中那張組合表格的類型學(xué)基礎(chǔ)。3. 文件內(nèi)的類型級測試。route-data.ts 末尾內(nèi)置了一組ExpectEqual...類型測試直接驗證了 ADR 關(guān)心的行為例如Expect Equal ServerDataFrom() { a: string; b: Date; c: () boolean; d: unstable_SerializesTonumber }, { a: string; b: Date; c: undefined; d: number } c函數(shù)被映射為undefined、d帶序列化品牌被映射為number——正是loader 端只允許可序列化輸入、組件端只得到可反序列化輸出這一不變量的可執(zhí)行證明。4.json約束的運行時對應(yīng)物。ADR 中必須走json的約束在當前倉庫對應(yīng)data()輔助函數(shù)及其Serializable入?yún)⒓s束定義于 packages/react-router/lib/server-runtime/single-fetch.tsSerializable是一個遞歸類型string | number | boolean | bigint | Date | URL | RegExp | Error | Map | Set | Promise | 數(shù)組 | 對象的遞歸聯(lián)合data(value: Serializable, init?)的簽名把它變成了編譯期檢查。這同時滿足了 ADR 解決標準中json允許且只允許JSON.stringify允許的東西兩條——函數(shù)、Symbol等不可序列化值在類型層面即被拒絕。八、結(jié)局被 ADR 0012 取代——從typeof loader到 typegenADR 頭部明確標注了狀態(tài)Superseded by #0012即 decisions/0012-type-inference.md日期 2024-09-20。0012 指出typeof loader方案雖有實質(zhì)改進區(qū)別于useParamsid那種純斷言泛式但仍是樣板代碼且隨應(yīng)用規(guī)模放大容易出錯尤其clientLoaderhydrateHydrateFallback的組合下泛式的正確寫法極其繁瑣。最終方案是放棄用戶手寫泛式改為代碼生成typegen對routes.ts返回的每一條路由把 route 模塊的類型生成到 gitignored 的.react-router/types目錄下路徑鏡像如app/routes/product.tsx對應(yīng)types.product.ts借助tsconfig.json的rootDirs選項讓用戶像從兄弟文件一樣import { LoaderArgs, DefaultProps } from ./types.product并把params、loaderData、actionData作為 props 直接注入default組件——useLoaderData等 hook 因向后兼容保留但目標是逐步棄用。0012 還系統(tǒng)否決了defineRoute、defineLoader系列、Svelte Kit 式零成本類型安全語言服務(wù)插件注入和 TypeScript 插件等替代路線理由包括 tree-shaking/HMR 兼容性與工具鏈typescript-eslint、tsc的互操作。從 0003 到 0012 的演進脈絡(luò)值得注意0003 確立了以 loader/action 返回類型為類型事實來源 序列化感知這兩個核心原則0012 只是把由用戶手寫typeof loader泛式替換為由 typegen 自動注入而 0003 中SerializeFrom所依賴的序列化映射邏輯則原樣保留在今天的 route-data.ts 中。九、實踐要點小結(jié)在本倉庫對應(yīng)的 React Router 7 代碼中推薦寫法仍是useLoaderDatatypeof loader()見 hooks.tsx 的官方示例注釋若框架模式已啟用 typegen則優(yōu)先使用生成的Route.LoaderArgs/ props 方案;loader/action 必須返回data(...)v7 中json的繼任者包裝的TypedResponse裸對象返回會繞過序列化感知類型需要給特殊自定義序列化類型聲明序列化后形態(tài)時使用 unstable_SerializesTo 品牌類型而不是手寫斷言;理解 ADR 的論證結(jié)構(gòu)現(xiàn)狀剖析 → 解決標準 → 關(guān)鍵洞察 → 決策 → 后果與約束是閱讀本倉庫decisions/目錄下其他 ADR 的通用模板ADR 模板 可作參考。原 ADR 腳注引用了當時 TypeScript 提案中的satisfies運算符它能約束函數(shù)類型的同時保留更窄的推斷返回類型從而讓LoaderFunction/ActionFunction與類型推斷共存。?【免費下載鏈接】react-routerDeclarative routing for React項目地址: https://gitcode.com/GitHub_Trending/re/react-router創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考