| <!doctype html><html lang=zh-CN dir=ltr class="docs-wrapper plugin-docs plugin-id-default docs-version-0.13 docs-doc-page docs-doc-id-guide/python_serialization" data-has-hydrated=false><head><meta charset=UTF-8><meta name=generator content="Docusaurus v3.10.1"><title data-rh=true>Python 序列化 | Apache Fory™</title><meta data-rh=true name=viewport content="width=device-width, initial-scale=1.0"/><meta data-rh=true property=og:url content=https://fory.apache.org/zh-CN/docs/0.13/guide/python_serialization /><meta data-rh=true property=og:locale content=zh_CN /><meta data-rh=true property=og:locale:alternate content=en_US /><meta data-rh=true name=docusaurus_locale content=zh-CN /><meta data-rh=true name=docsearch:language content=zh-CN /><meta data-rh=true http-equiv=Content-Security-Policy content="frame-src 'self' https://ghbtns.com/;"/><meta data-rh=true property=og:image content=https://fory.apache.org/img/logo.png /><meta data-rh=true property=og:image:width content=1500 /><meta data-rh=true property=og:image:height content=1500 /><meta data-rh=true name=twitter:card content=summary_large_image /><meta data-rh=true name=twitter:image content=https://fory.apache.org/img/logo.png /><meta data-rh=true name=docusaurus_version content=0.13 /><meta data-rh=true name=docusaurus_tag content=docs-default-0.13 /><meta data-rh=true name=docsearch:version content=0.13 /><meta data-rh=true name=docsearch:docusaurus_tag content=docs-default-0.13 /><meta data-rh=true property=og:title content="Python 序列化 | Apache Fory™"/><meta data-rh=true name=description content="Apache Fory™ Python"/><meta data-rh=true property=og:description content="Apache Fory™ Python"/><link data-rh=true rel=icon href=/zh-CN/img/favicon.ico /><link data-rh=true rel=canonical href=https://fory.apache.org/zh-CN/docs/0.13/guide/python_serialization /><link data-rh=true rel=alternate href=https://fory.apache.org/docs/0.13/guide/python_serialization hreflang=en-US /><link data-rh=true rel=alternate href=https://fory.apache.org/zh-CN/docs/0.13/guide/python_serialization hreflang=zh-CN /><link data-rh=true rel=alternate href=https://fory.apache.org/docs/0.13/guide/python_serialization hreflang=x-default /><script data-rh=true type=application/ld+json>{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://fory.apache.org/zh-CN/docs/0.13/guide/python_serialization","name":"Python 序列化","position":1}]}</script><link rel=alternate type=application/rss+xml href=/zh-CN/blog/rss.xml title="Apache Fory™ RSS Feed"><link rel=alternate type=application/atom+xml href=/zh-CN/blog/atom.xml title="Apache Fory™ Atom Feed"><script type=text/javascript>"fury.apache.org"===window.location.host&&(window.location.href="https://fory.apache.org"),function(){for(var o=window.location.pathname,a=["guide","introduction","start"],n=0;n<a.length;n++){var t=a[n],i=RegExp("^((?:/[a-z]{2}-[A-Z]{2})?/docs(?:/(?:next|[0-9]+.[0-9]+))?)/docs/"+t+"(/.*)?$"),c=o.match(i);if(c){var r=c[1]+"/"+t+(c[2]||"");window.location.replace(r+window.location.search+window.location.hash);return}}}()</script><link rel=stylesheet href=/zh-CN/assets/css/styles.3a1edaa1.css /><script src=/zh-CN/assets/js/runtime~main.49719703.js defer></script><script src=/zh-CN/assets/js/main.bc407ed5.js defer></script></head><body><svg style="display: none;"><defs> |
| <symbol id=theme-svg-external-link viewBox="0 0 24 24"><path fill=currentColor d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol> |
| </defs></svg> |
| <script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||"light"),document.documentElement.setAttribute("data-theme-choice",t||"light")}(),function(){try{for(var[t,e]of new URLSearchParams(window.location.search).entries())if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id=__docusaurus><div role=region aria-label=跳到主要内容><a class=skipToContent_fXgn href=#__docusaurus_skipToContent_fallback>跳到主要内容</a></div><nav aria-label=主导航 class="theme-layout-navbar navbar navbar--fixed-top"><div class=navbar__inner><div class="theme-layout-navbar-left navbar__items"><button aria-label=切换导航栏 aria-expanded=false class="navbar__toggle clean-btn" type=button><svg width=30 height=30 viewBox="0 0 30 30" aria-hidden=true><path stroke=currentColor stroke-linecap=round stroke-miterlimit=10 stroke-width=2 d="M4 7h22M4 15h22M4 23h22"/></svg></button><a class=navbar__brand href=/zh-CN/><div class=navbar__logo><img src=/zh-CN/img/fory-logo-light.png alt="Fory Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"/><img src=/zh-CN/img/fory-logo-dark.png alt="Fory Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"/></div><b class="navbar__title text--truncate"></b></a><a aria-current=page class="navbar__item navbar__link navbar__link--active" href=/zh-CN/docs/0.13/introduction/overview>文档</a><a class="navbar__item navbar__link" href=/zh-CN/docs/0.13/specification/xlang_serialization_spec>规范</a><a class="navbar__item navbar__link" href=/zh-CN/docs/0.13/community/>社区</a><a class="navbar__item navbar__link" href=/zh-CN/user>用户</a><a class="navbar__item navbar__link" href=/zh-CN/download>下载</a><a class="navbar__item navbar__link" href=/zh-CN/blog>博客</a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href=# aria-haspopup=true aria-expanded=false role=button class=navbar__link>ASF</a><ul class=dropdown__menu><li><a href=https://www.apache.org/ target=_blank rel="noopener noreferrer" class=dropdown__link>基金会</a><li><a href=https://www.apache.org/licenses/ target=_blank rel="noopener noreferrer" class=dropdown__link>许可证</a><li><a href=https://www.apache.org/events/current-event.html target=_blank rel="noopener noreferrer" class=dropdown__link>事件</a><li><a href=https://privacy.apache.org/policies/privacy-policy-public.html target=_blank rel="noopener noreferrer" class=dropdown__link>隐私</a><li><a href=https://www.apache.org/security/ target=_blank rel="noopener noreferrer" class=dropdown__link>安全</a><li><a href=https://www.apache.org/foundation/sponsorship.html target=_blank rel="noopener noreferrer" class=dropdown__link>赞助</a><li><a href=https://www.apache.org/foundation/thanks.html target=_blank rel="noopener noreferrer" class=dropdown__link>感谢</a><li><a href=https://www.apache.org/foundation/policies/conduct.html target=_blank rel="noopener noreferrer" class=dropdown__link>行为准则</a></ul></div><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a class=navbar__link aria-haspopup=true aria-expanded=false role=button href=/zh-CN/docs/0.13/guide/python_serialization>0.13</a><ul class=dropdown__menu><li><a class=dropdown__link href=/zh-CN/docs/next/introduction/overview>dev</a><li><a class=dropdown__link href=/zh-CN/docs/introduction/overview>1.3.0</a><li><a class=dropdown__link href=/zh-CN/docs/1.2.0/introduction/overview>1.2.0</a><li><a class=dropdown__link href=/zh-CN/docs/1.1.0/introduction/overview>1.1.0</a><li><a class=dropdown__link href=/zh-CN/docs/1.0.0/introduction/overview>1.0.0</a><li><a class=dropdown__link href=/zh-CN/docs/0.17/introduction/overview>0.17</a><li><a class=dropdown__link href=/zh-CN/docs/0.16/introduction/overview>0.16</a><li><a class=dropdown__link href=/zh-CN/docs/0.15/introduction/overview>0.15</a><li><a class=dropdown__link href=/zh-CN/docs/0.14/introduction/overview>0.14</a><li><a aria-current=page class="dropdown__link dropdown__link--active" href=/zh-CN/docs/0.13/guide/python_serialization>0.13</a><li><a class=dropdown__link href=/zh-CN/docs/0.12/introduction/overview>0.12</a><li><a class=dropdown__link href=/zh-CN/docs/0.11/introduction/overview>0.11</a><li><a class=dropdown__link href=/zh-CN/docs/0.10/introduction/overview>0.10</a></ul></div><a href=https://github.com/apache/fory target=_blank rel="noopener noreferrer" class="navbar__item navbar__link header-github-link" aria-label="GitHub repository"></a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href=# aria-haspopup=true aria-expanded=false role=button class=navbar__link><svg viewBox="0 0 24 24" width=20 height=20 aria-hidden=true class=iconLanguage_nlXk><path fill=currentColor d="M12.87 15.07l-2.54-2.51.03-.03c1.74-1.94 2.98-4.17 3.71-6.53H17V4h-7V2H8v2H1v1.99h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12zm-2.62 7l1.62-4.33L19.12 17h-3.24z"/></svg>简体中文</a><ul class=dropdown__menu><li><a href=/docs/0.13/guide/python_serialization target=_self rel="noopener noreferrer" class=dropdown__link lang=en-US>English</a><li><a href=/zh-CN/docs/0.13/guide/python_serialization target=_self rel="noopener noreferrer" class="dropdown__link dropdown__link--active" lang=zh-CN>简体中文</a></ul></div><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type=button disabled title="system mode" aria-label="切换浅色/暗黑模式（当前为system mode）"><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill=currentColor d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill=currentColor d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill=currentColor d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"/></svg></button></div><div class=navbarSearchContainer_Bca1><div class=navbar__search><span aria-label="expand searchbar" role=button class=search-icon tabindex=0></span><input id=search_input_react type=search placeholder=Loading... aria-label=Search class="navbar__search-input search-bar" disabled/></div></div></div></div><div role=presentation class=navbar-sidebar__backdrop></div></nav><div id=__docusaurus_skipToContent_fallback class="theme-layout-main main-wrapper mainWrapper_z2l0"><div class=docsWrapper_hBAB><button aria-label=回到顶部 class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type=button></button><div class=docRoot_UBD9><aside class="theme-doc-sidebar-container docSidebarContainer_YfHR"><div class=sidebarViewport_aRkj><div class=sidebar_njMd><nav aria-label=文档侧边栏 class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" href=/zh-CN/docs/0.13/introduction/overview><span title="Apache Fory 介绍" class=categoryLinkLabel_W154>Apache Fory 介绍</span></a><button aria-label="展开侧边栏分类 'Apache Fory 介绍'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role=button aria-expanded=false href=/zh-CN/docs/0.13/start/install><span title=快速开始 class=categoryLinkLabel_W154>快速开始</span></a></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" role=button aria-expanded=true href=/zh-CN/docs/0.13/guide/serialization><span title=用户指南 class=categoryLinkLabel_W154>用户指南</span></a></div><ul class=menu__list><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/zh-CN/docs/0.13/guide/serialization><span title="Java 序列化" class=linkLabel_WmDU>Java 序列化</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current=page tabindex=0 href=/zh-CN/docs/0.13/guide/python_serialization><span title="Python 序列化" class=linkLabel_WmDU>Python 序列化</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/zh-CN/docs/0.13/guide/rust_serialization><span title="Rust 序列化" class=linkLabel_WmDU>Rust 序列化</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/zh-CN/docs/0.13/guide/scala_serialization><span title="Scala 序列化" class=linkLabel_WmDU>Scala 序列化</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/zh-CN/docs/0.13/guide/xlang_serialization><span title=多语言序列化 class=linkLabel_WmDU>多语言序列化</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/zh-CN/docs/0.13/guide/row_format><span title=行存格式 class=linkLabel_WmDU>行存格式</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/zh-CN/docs/0.13/guide/graalvm_serialization><span title="GraalVM 序列化" class=linkLabel_WmDU>GraalVM 序列化</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/zh-CN/docs/0.13/guide/development><span title=开发指南 class=linkLabel_WmDU>开发指南</span></a></ul></ul></nav></div></div></aside><main class=docMainContainer_TBSr><div class="container padding-top--md padding-bottom--lg"><div class=row><div class="col docItemCol_VOVn"><div class="theme-doc-version-banner alert alert--warning margin-bottom--md" role=alert><div>此为 <!-- -->Apache Fory™<!-- --> <b>0.13</b> 版的文档，现已不再积极维护。</div><div class=margin-top--md>最新的文档请参阅 <b><a href=/zh-CN/docs/introduction/overview>最新版本</a></b> (<!-- -->1.3.0<!-- -->)。</div></div><div class=docItemContainer_Djhp><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label=页面路径><ul class=breadcrumbs><li class=breadcrumbs__item><a aria-label=主页面 class=breadcrumbs__link href=/zh-CN/><svg viewBox="0 0 24 24" class=breadcrumbHomeIcon_YNFT><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill=currentColor /></svg></a><li class=breadcrumbs__item><span class=breadcrumbs__link>用户指南</span><li class="breadcrumbs__item breadcrumbs__item--active"><span class=breadcrumbs__link>Python 序列化</span></ul></nav><span class="theme-doc-version-badge badge badge--secondary">版本：0.13</span><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type=button class="clean-btn tocCollapsibleButton_TO0P">本页总览</button></div><div class="theme-doc-markdown markdown"><header><h1>Python 序列化</h1></header><h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=apache-fory-python>Apache Fory™ Python<a href=#apache-fory-python class=hash-link aria-label="Apache Fory™ Python的直接链接" title="Apache Fory™ Python的直接链接" translate=no></a></h2> |
| <p><strong>Apache Fory™</strong> 是一个极速的多语言序列化框架，基于 <strong>JIT 编译</strong>和<strong>零拷贝</strong>技术，在保持易用性和安全性的同时提供<strong>超高性能</strong>。</p> |
| <p><code>pyfory</code> 提供了 Apache Fory™ 的 Python 实现，同时支持高性能对象序列化和用于数据处理任务的高级行格式能力。</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-核心特性>🚀 核心特性<a href=#-核心特性 class=hash-link aria-label="🚀 核心特性的直接链接" title="🚀 核心特性的直接链接" translate=no></a></h2> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=-灵活的序列化模式>🔧 <strong>灵活的序列化模式</strong><a href=#-灵活的序列化模式 class=hash-link aria-label=-灵活的序列化模式的直接链接 title=-灵活的序列化模式的直接链接 translate=no></a></h3> |
| <ul> |
| <li class=""><strong>Python 原生模式</strong>：完全兼容 Python，可作为 pickle/cloudpickle 的直接替代品</li> |
| <li class=""><strong>跨语言模式</strong>：针对多语言数据交换优化</li> |
| <li class=""><strong>行格式</strong>：用于分析工作负载的零拷贝行格式</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=-多样的序列化功能>🎯 多样的序列化功能<a href=#-多样的序列化功能 class=hash-link aria-label="🎯 多样的序列化功能的直接链接" title="🎯 多样的序列化功能的直接链接" translate=no></a></h3> |
| <ul> |
| <li class=""><strong>共享/循环引用支持</strong>：在 Python 原生模式和跨语言模式中支持复杂对象图</li> |
| <li class=""><strong>多态支持</strong>：支持自定义类型的自动类型分发</li> |
| <li class=""><strong>Schema 演化</strong>：在跨语言模式下使用 dataclass 时支持向后/向前兼容</li> |
| <li class=""><strong>带外缓冲区支持</strong>：支持大型数据结构（如 NumPy 数组和 Pandas DataFrame）的零拷贝序列化，兼容 pickle protocol 5</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=-极速性能>⚡ <strong>极速性能</strong><a href=#-极速性能 class=hash-link aria-label=-极速性能的直接链接 title=-极速性能的直接链接 translate=no></a></h3> |
| <ul> |
| <li class="">相比其他序列化框架具有<strong>极快的性能</strong></li> |
| <li class=""><strong>运行时代码生成</strong>和 <strong>Cython 加速</strong>的核心实现，获得最佳性能</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=-紧凑的数据大小>📦 紧凑的数据大小<a href=#-紧凑的数据大小 class=hash-link aria-label="📦 紧凑的数据大小的直接链接" title="📦 紧凑的数据大小的直接链接" translate=no></a></h3> |
| <ul> |
| <li class=""><strong>紧凑的对象图协议</strong>，空间开销极小——相比 pickle/cloudpickle 最多减少 3 倍大小</li> |
| <li class=""><strong>元数据打包和共享</strong>，最小化类型向前/向后兼容的空间开销</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=️-安全性>🛡️ <strong>安全性</strong><a href=#️-安全性 class=hash-link aria-label=️-安全性的直接链接 title=️-安全性的直接链接 translate=no></a></h3> |
| <ul> |
| <li class=""><strong>严格模式</strong>通过类型注册和检查防止反序列化不受信任的类型</li> |
| <li class=""><strong>引用跟踪</strong>安全处理循环引用</li> |
| </ul> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-安装>📦 安装<a href=#-安装 class=hash-link aria-label="📦 安装的直接链接" title="📦 安装的直接链接" translate=no></a></h2> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=基础安装>基础安装<a href=#基础安装 class=hash-link aria-label=基础安装的直接链接 title=基础安装的直接链接 translate=no></a></h3> |
| <p>使用 pip 安装 pyfory：</p> |
| <div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">pip </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"> pyfory</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=可选依赖>可选依赖<a href=#可选依赖 class=hash-link aria-label=可选依赖的直接链接 title=可选依赖的直接链接 translate=no></a></h3> |
| <div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># 安装行格式支持（需要 Apache Arrow）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">pip </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">format</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 从源码安装用于开发</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token function" style=color:#d73a49>git</span><span class="token plain"> clone https://github.com/apache/fory.git</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">cd</span><span class="token plain"> fory/python</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">pip </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>-e</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>".[dev,format]"</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=环境要求>环境要求<a href=#环境要求 class=hash-link aria-label=环境要求的直接链接 title=环境要求的直接链接 translate=no></a></h3> |
| <ul> |
| <li class=""><strong>Python</strong>：3.8 或更高版本</li> |
| <li class=""><strong>操作系统</strong>：Linux、macOS、Windows</li> |
| </ul> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-python-原生序列化>🐍 Python 原生序列化<a href=#-python-原生序列化 class=hash-link aria-label="🐍 Python 原生序列化的直接链接" title="🐍 Python 原生序列化的直接链接" translate=no></a></h2> |
| <p><code>pyfory</code> 提供了 Python 原生序列化模式，提供与 pickle/cloudpickle 相同的功能，但具有<strong>显著更好的性能、更小的数据大小和增强的安全特性</strong>。</p> |
| <p>二进制协议和 API 与 Fory 的 xlang 模式类似，但 Python 原生模式可以序列化任何 Python 对象——包括全局函数、局部函数、lambda 表达式、局部类以及使用 <code>__getstate__/__reduce__/__reduce_ex__</code> 自定义序列化的类型，这些在 xlang 模式中是不允许的。</p> |
| <p>要使用 Python 原生模式，请创建 <code>xlang=False</code> 的 <code>Fory</code>。此模式针对纯 Python 应用程序优化：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=基础对象序列化>基础对象序列化<a href=#基础对象序列化 class=hash-link aria-label=基础对象序列化的直接链接 title=基础对象序列化的直接链接 translate=no></a></h3> |
| <p>使用简单的 API 序列化和反序列化 Python 对象。此示例展示了序列化包含混合类型的字典：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 创建 Fory 实例</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化任何 Python 对象</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>"name"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"Alice"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"age"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>30</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"scores"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token number" style=color:#36acaa>95</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>87</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>92</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 反序列化回 Python 对象</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">obj </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># {'name': 'Alice', 'age': 30, 'scores': [95, 87, 92]}</span><br/></div></code></pre></div></div> |
| <p><strong>注意</strong>：<code>dumps()</code>/<code>loads()</code> 是 <code>serialize()</code>/<code>deserialize()</code> 的别名。两组 API 完全相同，使用您觉得更直观的即可。</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=自定义类序列化>自定义类序列化<a href=#自定义类序列化 class=hash-link aria-label=自定义类序列化的直接链接 title=自定义类序列化的直接链接 translate=no></a></h3> |
| <p>Fory 自动处理 dataclass 和自定义类型。注册您的类一次，然后无缝序列化实例：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> dataclasses </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> dataclass</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> typing </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> List</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> Dict</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token decorator annotation punctuation" style=color:#393A34>@dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Person</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> age</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> scores</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> List</span><span class="token punctuation" style=color:#393A34>[</span><span class="token builtin">int</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> metadata</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> Dict</span><span class="token punctuation" style=color:#393A34>[</span><span class="token builtin">str</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># Python 模式 - 支持所有 Python 类型，包括 dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Person</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">person </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> Person</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"Bob"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>25</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token number" style=color:#36acaa>88</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>92</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>85</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>"team"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"engineering"</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">person</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">result</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># Person(name='Bob', age=25, ...)</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=picklecloudpickle-的直接替代品>Pickle/Cloudpickle 的直接替代品<a href=#picklecloudpickle-的直接替代品 class=hash-link aria-label="Pickle/Cloudpickle 的直接替代品的直接链接" title="Pickle/Cloudpickle 的直接替代品的直接链接" translate=no></a></h3> |
| <p><code>pyfory</code> 可以使用以下配置序列化任何 Python 对象：</p> |
| <ul> |
| <li class=""><strong>循环引用</strong>：设置 <code>ref=True</code> 启用引用跟踪</li> |
| <li class=""><strong>函数/类</strong>：设置 <code>strict=False</code> 允许反序列化动态类型</li> |
| </ul> |
| <p><strong>⚠️ 安全警告</strong>：当 <code>strict=False</code> 时，Fory 将反序列化任意类型，如果数据来自不可信来源，这可能带来安全风险。仅在您完全信任数据源的受控环境中使用 <code>strict=False</code>。如果确实需要使用 <code>strict=False</code>，请在创建 fory 时使用 <code>policy=your_policy</code> 配置 <code>DeserializationPolicy</code> 来控制反序列化行为。</p> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=常见用法>常见用法<a href=#常见用法 class=hash-link aria-label=常见用法的直接链接 title=常见用法的直接链接 translate=no></a></h4> |
| <p>序列化常见的 Python 对象，包括字典、列表和自定义类，无需任何注册：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 创建 Fory 实例</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化常见的 Python 对象</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>"name"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"Alice"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"age"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>30</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"scores"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token number" style=color:#36acaa>95</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>87</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>92</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化自定义对象</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> dataclasses </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> dataclass</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token decorator annotation punctuation" style=color:#393A34>@dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Person</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> age</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">person </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> Person</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"Bob"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>25</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">person</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># Person(name='Bob', age=25)</span><br/></div></code></pre></div></div> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=序列化全局函数>序列化全局函数<a href=#序列化全局函数 class=hash-link aria-label=序列化全局函数的直接链接 title=序列化全局函数的直接链接 translate=no></a></h4> |
| <p>捕获和获取在模块级别定义的函数。Fory 反序列化并返回相同的函数对象：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 创建 Fory 实例</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化全局函数</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>my_global_function</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">x</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> x</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">my_global_function</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 100</span><br/></div></code></pre></div></div> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=序列化局部函数lambda-表达式>序列化局部函数/Lambda 表达式<a href=#序列化局部函数lambda-表达式 class=hash-link aria-label="序列化局部函数/Lambda 表达式的直接链接" title="序列化局部函数/Lambda 表达式的直接链接" translate=no></a></h4> |
| <p>序列化带闭包的函数和 lambda 表达式。Fory 自动捕获闭包变量：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 创建 Fory 实例</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化带闭包的局部函数</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>my_function</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> local_var </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>local_func</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">x</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> x </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> local_var</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> local_func</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">my_function</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 100</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化 lambda 表达式</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>lambda</span><span class="token plain"> x</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> x</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 100</span><br/></div></code></pre></div></div> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=序列化全局类方法>序列化全局类/方法<a href=#序列化全局类方法 class=hash-link aria-label=序列化全局类/方法的直接链接 title=序列化全局类/方法的直接链接 translate=no></a></h4> |
| <p>序列化类对象、实例方法、类方法和静态方法。支持所有方法类型：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> dataclasses </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> dataclass</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化全局类</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token decorator annotation punctuation" style=color:#393A34>@dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Person</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> age</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>f</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> x</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> self</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">age </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> x</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token decorator annotation punctuation" style=color:#393A34>@classmethod</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>g</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">cls</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> x</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> x</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token decorator annotation punctuation" style=color:#393A34>@staticmethod</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>h</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">x</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> x</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Person</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"Bob"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>25</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># Person(name='Bob', age=25)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化全局类实例方法</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Person</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"Bob"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>20</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 200</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化全局类的类方法</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Person</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">g</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 100</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化全局类的静态方法</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Person</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">h</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 100</span><br/></div></code></pre></div></div> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=序列化局部类方法>序列化局部类/方法<a href=#序列化局部类方法 class=hash-link aria-label=序列化局部类/方法的直接链接 title=序列化局部类/方法的直接链接 translate=no></a></h4> |
| <p>序列化函数内定义的类及其方法。适用于动态类创建：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> dataclasses </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> dataclass</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>create_local_class</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">LocalClass</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>f</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> x</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> x</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token decorator annotation punctuation" style=color:#393A34>@classmethod</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>g</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">cls</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> x</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> x</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token decorator annotation punctuation" style=color:#393A34>@staticmethod</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>h</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">x</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> x</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> LocalClass</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化局部类</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">create_local_class</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 100</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化局部类实例方法</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">create_local_class</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 100</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化局部类的类方法</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">create_local_class</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">g</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 100</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化局部类的静态方法</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">create_local_class</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">h</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 100</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=带外缓冲区序列化>带外缓冲区序列化<a href=#带外缓冲区序列化 class=hash-link aria-label=带外缓冲区序列化的直接链接 title=带外缓冲区序列化的直接链接 translate=no></a></h3> |
| <p>Fory 支持兼容 pickle5 的带外缓冲区序列化，用于高效零拷贝处理大型数据结构。这对于 NumPy 数组、Pandas DataFrame 和其他具有大内存占用的对象特别有用。</p> |
| <p>带外序列化将元数据与实际数据缓冲区分离，从而实现：</p> |
| <ul> |
| <li class="">使用 <code>memoryview</code> 通过网络或 IPC 发送数据时<strong>零拷贝传输</strong></li> |
| <li class="">大型数据集的<strong>性能提升</strong></li> |
| <li class=""><strong>Pickle5 兼容性</strong>，使用 <code>pickle.PickleBuffer</code></li> |
| <li class=""><strong>灵活的流支持</strong> - 写入任何可写对象（文件、BytesIO、套接字等）</li> |
| </ul> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=基础带外序列化>基础带外序列化<a href=#基础带外序列化 class=hash-link aria-label=基础带外序列化的直接链接 title=基础带外序列化的��直接链接 translate=no></a></h4> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> numpy </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> np</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 大型 numpy 数组</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">array </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">arange</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10000</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> dtype</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">float64</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 使用带外缓冲区序列化</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">buffer_objects </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">serialized_data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">array</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> buffer_callback</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">buffer_objects</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">append</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 将缓冲区对象转换为 memoryview 以实现零拷贝传输</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 对于连续缓冲区（bytes、numpy 数组），这是零拷贝的</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 对于非连续数据，可能会创建副本以确保连续性</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">buffers </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">getbuffer</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> obj </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> buffer_objects</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 使用带外缓冲区反序列化（接受 memoryview、bytes 或 Buffer）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">deserialized_array </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">serialized_data</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> buffers</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">buffers</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>assert</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">array_equal</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">array</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> deserialized_array</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=带外序列化-pandas-dataframe>带外序列化 Pandas DataFrame<a href=#带外序列化-pandas-dataframe class=hash-link aria-label="带外序列化 Pandas DataFrame的直接链接" title="带外序列化 Pandas DataFrame的直接链接" translate=no></a></h4> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pandas </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> pd</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> numpy </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> np</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 创建包含数值列的 DataFrame</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">df </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pd</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">DataFrame</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token string" style=color:#e3116c>'a'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">arange</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1000</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> dtype</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">float64</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token string" style=color:#e3116c>'b'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">arange</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1000</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> dtype</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">int64</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token string" style=color:#e3116c>'c'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token string" style=color:#e3116c>'text'</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1000</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 使用带外缓冲区序列化</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">buffer_objects </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">serialized_data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">df</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> buffer_callback</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">buffer_objects</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">append</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">buffers </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">getbuffer</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> obj </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> buffer_objects</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 反序列化</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">deserialized_df </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">serialized_data</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> buffers</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">buffers</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>assert</span><span class="token plain"> df</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">equals</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">deserialized_df</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=选择性带外序列化>选择性带外序列化<a href=#选择性带外序列化 class=hash-link aria-label=选择性带外序列化的直接链接 title=选择性带外序列化的直接链接 translate=no></a></h4> |
| <p>您可以通过提供回调函数来控制哪些缓冲区进行带外处理，该函数返回 <code>True</code> 将数据保持在带内，返回 <code>False</code>（并追加到列表）将其发送到带外：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> numpy </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> np</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">arr1 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">arange</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1000</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> dtype</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">float64</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">arr2 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">arange</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>2000</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> dtype</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">float64</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">arr1</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> arr2</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">buffer_objects </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">counter </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>selective_callback</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">buffer_object</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>global</span><span class="token plain"> counter</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> counter </span><span class="token operator" style=color:#393A34>+=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 仅将偶数编号的缓冲区发送到带外</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>if</span><span class="token plain"> counter </span><span class="token operator" style=color:#393A34>%</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>==</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> buffer_objects</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">append</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">buffer_object</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>False</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 带外</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>True</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 带内</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">serialized </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> buffer_callback</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">selective_callback</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">buffers </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">getbuffer</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> obj </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> buffer_objects</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">deserialized </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">serialized</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> buffers</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">buffers</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=pickle5-兼容性>Pickle5 兼容性<a href=#pickle5-兼容性 class=hash-link aria-label="Pickle5 兼容性的直接链接" title="Pickle5 兼容性的直接链接" translate=no></a></h4> |
| <p>Fory 的带外序列化与 pickle protocol 5 完全兼容。当对象实现 <code>__reduce_ex__(protocol)</code> 时，Fory 自动使用 protocol 5 来启用 <code>pickle.PickleBuffer</code> 支持：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pickle</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 自动支持 PickleBuffer 对象</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>b"Large binary data"</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">pickle_buffer </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pickle</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">PickleBuffer</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 使用缓冲区回调进行带外处理序列化</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">buffer_objects </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">serialized </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">pickle_buffer</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> buffer_callback</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">buffer_objects</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">append</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">buffers </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">getbuffer</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> obj </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> buffer_objects</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 使用缓冲区反序列化</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">deserialized </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">serialized</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> buffers</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">buffers</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>assert</span><span class="token plain"> </span><span class="token builtin">bytes</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">deserialized</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">raw</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>==</span><span class="token plain"> data</span><br/></div></code></pre></div></div> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=将缓冲区写入不同的流>将缓冲区写入不同的流<a href=#将缓冲区写入不同的流 class=hash-link aria-label=将缓冲区写入不同的流的直接链接 title=将缓冲区写入不同的流的直接链接 translate=no></a></h4> |
| <p><code>BufferObject.write_to()</code> 方法接受任何可写流对象，使其适用于各种用例：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> numpy </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> np</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> io</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">array </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">arange</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1000</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> dtype</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">float64</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 收集带外缓冲区</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">buffer_objects </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">serialized </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">array</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> buffer_callback</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">buffer_objects</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">append</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 写入不同的流类型</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> buffer_obj </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> buffer_objects</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 写入 BytesIO（内存流）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> bytes_stream </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> io</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">BytesIO</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> buffer_obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">write_to</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">bytes_stream</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 写入文件</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>with</span><span class="token plain"> </span><span class="token builtin">open</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>'/tmp/buffer_data.bin'</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'wb'</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> buffer_obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">write_to</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 获取零拷贝 memoryview（对于连续缓冲区）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> mv </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> buffer_obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">getbuffer</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>assert</span><span class="token plain"> </span><span class="token builtin">isinstance</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">mv</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token builtin">memoryview</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <p><strong>注意</strong>：对于连续内存缓冲区（如 bytes、numpy 数组），<code>getbuffer()</code> 返回零拷贝 <code>memoryview</code>。对于非连续数据，可能会创建副本以确保连续性。</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=️-跨语言对象图序列化>🏃♂️ 跨语言对象图序列化<a href=#️-跨语言对象图序列化 class=hash-link aria-label="🏃♂️ 跨语言对象图序列化的直接链接" title="🏃♂️ 跨语言对象图序列化的直接链接" translate=no></a></h2> |
| <p><code>pyfory</code> 支持跨语言对象图序列化，允许您在 Python 中序列化数据，然后在 Java、Go、Rust 或其他支持的语言中反序列化。</p> |
| <p>二进制协议和 API 与 <code>pyfory</code> 的 python-native 模式类似，但 Python 原生模式可以序列化任何 Python 对象——包括全局函数、局部函数、lambda 表达式、局部类以及使用 <code>__getstate__/__reduce__/__reduce_ex__</code> 自定义序列化的类型，这些在 xlang 模式中是不允许的。</p> |
| <p>要使用 xlang 模式，请创建 <code>xlang=True</code> 的 <code>Fory</code>。此模式用于 xlang 序列化应用：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=跨语言序列化>跨语言序列化<a href=#跨语言序列化 class=hash-link aria-label=跨语言序列化的直接链接 title=跨语言序列化的直接链接 translate=no></a></h3> |
| <p>在 Python 中序列化数据，然后在 Java、Go、Rust 或其他支持的语言中反序列化。双方必须注册相同的类型并使用匹配的名称：</p> |
| <p><strong>Python (序列化端)</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 用于互操作性的跨语言模式</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 注册类型以实现跨语言兼容</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token decorator annotation punctuation" style=color:#393A34>@dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Person</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> age</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">int32</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Person</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> typename</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"example.Person"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">person </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> Person</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"Charlie"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>35</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">binary_data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">person</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># binary_data 现在可以发送到 Java、Go 等</span><br/></div></code></pre></div></div> |
| <p><strong>Java (反序列化端)</strong></p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token import namespace" style=opacity:0.7>org</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>apache</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import namespace" style=opacity:0.7>fory</span><span class="token import namespace punctuation" style=opacity:0.7;color:#393A34>.</span><span class="token import operator" style=color:#393A34>*</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Person</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>int</span><span class="token plain"> age</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">Fory</span><span class="token plain"> fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">Fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withLanguage</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Language</span><span class="token punctuation" style=color:#393A34>.</span><span class="token constant" style=color:#36acaa>XLANG</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withRefTracking</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Person</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"example.Person"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">Person</span><span class="token plain"> person </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Person</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">binaryData</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-行格式---零拷贝处理>📊 行格式 - 零拷贝处理<a href=#-行格式---零拷贝处理 class=hash-link aria-label="📊 行格式 - 零拷贝处理的直接链接" title="📊 行格式 - 零拷贝处理的直接链接" translate=no></a></h2> |
| <p>Apache Fury™ 提供了一种随机访问行格式，无需完全反序列化即可从二进制数据中读取嵌套字段。这在处理大型对象时，当只需要访问部分数据时，大大减少了开销。该格式还支持内存映射文件，实现超低内存占用。</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=行格式基础用法>行格式基础用法<a href=#行格式基础用法 class=hash-link aria-label=行格式基础用法的直接链接 title=行格式基础用法的直接链接 translate=no></a></h3> |
| <p>将对象编码为行格式以实现随机访问，无需完全反序列化。适用于大型数据集：</p> |
| <p><strong>Python</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyarrow </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> pa</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> dataclasses </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> dataclass</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> typing </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> List</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> Dict</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token decorator annotation punctuation" style=color:#393A34>@dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Bar</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f1</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f2</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> List</span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">pa</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">int64</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token decorator annotation punctuation" style=color:#393A34>@dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Foo</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f1</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> pa</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">int32</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f2</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> List</span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">pa</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">int32</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f3</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> Dict</span><span class="token punctuation" style=color:#393A34>[</span><span class="token builtin">str</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> pa</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">int32</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f4</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> List</span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">Bar</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 创建行格式编码器</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">encoder </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">encoder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Foo</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 创建大型数据集</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">foo </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> Foo</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f1</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f2</span><span class="token operator" style=color:#393A34>=</span><span class="token builtin">list</span><span class="token punctuation" style=color:#393A34>(</span><span class="token builtin">range</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1_000_000</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f3</span><span class="token operator" style=color:#393A34>=</span><span class="token punctuation" style=color:#393A34>{</span><span class="token string-interpolation string" style=color:#e3116c>f"k</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">i</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> i </span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> i </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> </span><span class="token builtin">range</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1_000_000</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f4</span><span class="token operator" style=color:#393A34>=</span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">Bar</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">f1</span><span class="token operator" style=color:#393A34>=</span><span class="token string-interpolation string" style=color:#e3116c>f"s</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">i</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> f2</span><span class="token operator" style=color:#393A34>=</span><span class="token builtin">list</span><span class="token punctuation" style=color:#393A34>(</span><span class="token builtin">range</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> i </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> </span><span class="token builtin">range</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1_000_000</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 编码为行格式</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">binary</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bytes</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> encoder</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">to_row</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">foo</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">to_bytes</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 零拷贝访问 - 无需完全反序列化！</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">foo_row </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">RowData</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">encoder</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">schema</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> binary</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">foo_row</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f2</span><span class="token punctuation" style=color:#393A34>[</span><span class="token number" style=color:#36acaa>100000</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 直接访问第 100,000 个元素</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">foo_row</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f4</span><span class="token punctuation" style=color:#393A34>[</span><span class="token number" style=color:#36acaa>100000</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f1</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 直接访问嵌套字段</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">foo_row</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f4</span><span class="token punctuation" style=color:#393A34>[</span><span class="token number" style=color:#36acaa>200000</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f2</span><span class="token punctuation" style=color:#393A34>[</span><span class="token number" style=color:#36acaa>5</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 直接访问深度嵌套字段</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=跨语言兼容性>跨语言兼容性<a href=#跨语言兼容性 class=hash-link aria-label=跨语言兼容性的直接链接 title=跨语言兼容性的直接链接 translate=no></a></h3> |
| <p>行格式可以跨语言工作。以下是在 Java 中访问相同数据结构的示例：</p> |
| <p><strong>Java</strong></p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Bar</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> f1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">List</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Long</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> f2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Foo</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>int</span><span class="token plain"> f1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">List</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Integer</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> f2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">Map</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">String</span><span class="token generics punctuation" style=color:#393A34>,</span><span class="token generics"> </span><span class="token generics class-name">Integer</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> f3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">List</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Bar</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> f4</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">RowEncoder</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Foo</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> encoder </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">Encoders</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>bean</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Foo</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// 创建大型数据集</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">Foo</span><span class="token plain"> foo </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">Foo</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">foo</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f1 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">foo</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f2 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">IntStream</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>range</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1_000_000</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>boxed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>collect</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Collectors</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toList</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">foo</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f3 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">IntStream</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>range</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1_000_000</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>boxed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>collect</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Collectors</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toMap</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">i </span><span class="token operator" style=color:#393A34>-></span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"k"</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>+</span><span class="token plain"> i</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> i </span><span class="token operator" style=color:#393A34>-></span><span class="token plain"> i</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">List</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Bar</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> bars </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">ArrayList</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1_000_000</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>int</span><span class="token plain"> i </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> i </span><span class="token operator" style=color:#393A34><</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1_000_000</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> i</span><span class="token operator" style=color:#393A34>++</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token class-name">Bar</span><span class="token plain"> bar </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token class-name">Bar</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> bar</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f1 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"s"</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>+</span><span class="token plain"> i</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> bar</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f2 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">LongStream</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>range</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>boxed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>collect</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Collectors</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toList</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> bars</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>add</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">bar</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">foo</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f4 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> bars</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// 编码为行格式（与 Python 跨语言兼容）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">BinaryRow</span><span class="token plain"> binaryRow </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> encoder</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toRow</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">foo</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// 零拷贝随机访问，无需完全反序列化</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">BinaryArray</span><span class="token plain"> f2Array </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> binaryRow</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>getArray</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 访问 f2 列表</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">BinaryArray</span><span class="token plain"> f4Array </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> binaryRow</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>getArray</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 访问 f4 列表</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">BinaryRow</span><span class="token plain"> bar10 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f4Array</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>getStruct</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 访问第 11 个 Bar</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>long</span><span class="token plain"> value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> bar10</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>getArray</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>getInt64</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>5</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 访问 bar.f2 的第 6 个元素</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// 部分反序列化 - 只反序列化需要的内容</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">RowEncoder</span><span class="token generics punctuation" style=color:#393A34><</span><span class="token generics class-name">Bar</span><span class="token generics punctuation" style=color:#393A34>></span><span class="token plain"> barEncoder </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">Encoders</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>bean</span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Bar</span><span class="token punctuation" style=color:#393A34>.</span><span class="token keyword" style=color:#00009f>class</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">Bar</span><span class="token plain"> bar1 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> barEncoder</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>fromRow</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">f4Array</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>getStruct</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 仅反序列化第 11 个 Bar</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">Bar</span><span class="token plain"> bar2 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> barEncoder</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>fromRow</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">f4Array</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>getStruct</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>20</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 仅反序列化第 21 个 Bar</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// 需要时进行完全反序列化</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">Foo</span><span class="token plain"> newFoo </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> encoder</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>fromRow</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">binaryRow</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p><strong>C++</strong></p> |
| <p>在 C++ 中使用编译时类型信息：</p> |
| <div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token macro property directive-hash" style=color:#36acaa>#</span><span class="token macro property directive keyword" style=color:#00009f>include</span><span class="token macro property" style=color:#36acaa> </span><span class="token macro property string" style=color:#e3116c>"fory/encoder/row_encoder.h"</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token macro property directive-hash" style=color:#36acaa>#</span><span class="token macro property directive keyword" style=color:#00009f>include</span><span class="token macro property" style=color:#36acaa> </span><span class="token macro property string" style=color:#e3116c>"fory/row/writer.h"</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>struct</span><span class="token plain"> </span><span class="token class-name">Bar</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> std</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token plain">string f1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> std</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token plain">vector</span><span class="token operator" style=color:#393A34><</span><span class="token keyword" style=color:#00009f>int64_t</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> f2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token function" style=color:#d73a49>FORY_FIELD_INFO</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Bar</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> f1</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> f2</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>struct</span><span class="token plain"> </span><span class="token class-name">Foo</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>int32_t</span><span class="token plain"> f1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> std</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token plain">vector</span><span class="token operator" style=color:#393A34><</span><span class="token keyword" style=color:#00009f>int32_t</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> f2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> std</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token plain">map</span><span class="token operator" style=color:#393A34><</span><span class="token plain">std</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token plain">string</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>int32_t</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> f3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> std</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token plain">vector</span><span class="token operator" style=color:#393A34><</span><span class="token plain">Bar</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> f4</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token function" style=color:#d73a49>FORY_FIELD_INFO</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Foo</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> f1</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> f2</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> f3</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> f4</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// 创建大型数据集</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">Foo foo</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">foo</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f1 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>int</span><span class="token plain"> i </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> i </span><span class="token operator" style=color:#393A34><</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1000000</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> i</span><span class="token operator" style=color:#393A34>++</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> foo</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f2</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>push_back</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">i</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> foo</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f3</span><span class="token punctuation" style=color:#393A34>[</span><span class="token string" style=color:#e3116c>"k"</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>+</span><span class="token plain"> std</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token function" style=color:#d73a49>to_string</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">i</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> i</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>int</span><span class="token plain"> i </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> i </span><span class="token operator" style=color:#393A34><</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1000000</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> i</span><span class="token operator" style=color:#393A34>++</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> Bar bar</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> bar</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f1 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"s"</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>+</span><span class="token plain"> std</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token function" style=color:#d73a49>to_string</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">i</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>int</span><span class="token plain"> j </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> j </span><span class="token operator" style=color:#393A34><</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> j</span><span class="token operator" style=color:#393A34>++</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> bar</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f2</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>push_back</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">j</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> foo</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f4</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>push_back</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">bar</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// 编码为行格式（与 Python/Java 跨语言兼容）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token plain">encoder</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token plain">RowEncoder</span><span class="token operator" style=color:#393A34><</span><span class="token plain">Foo</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> encoder</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">encoder</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>Encode</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">foo</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>auto</span><span class="token plain"> row </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> encoder</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>GetWriter</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>ToRow</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// 零拷贝随机访问，无需完全反序列化</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>auto</span><span class="token plain"> f2_array </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> row</span><span class="token operator" style=color:#393A34>-></span><span class="token function" style=color:#d73a49>GetArray</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 访问 f2 列表</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>auto</span><span class="token plain"> f4_array </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> row</span><span class="token operator" style=color:#393A34>-></span><span class="token function" style=color:#d73a49>GetArray</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 访问 f4 列表</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>auto</span><span class="token plain"> bar10 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f4_array</span><span class="token operator" style=color:#393A34>-></span><span class="token function" style=color:#d73a49>GetStruct</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 访问第 11 个 Bar</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>int64_t</span><span class="token plain"> value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> bar10</span><span class="token operator" style=color:#393A34>-></span><span class="token function" style=color:#d73a49>GetArray</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>)</span><span class="token operator" style=color:#393A34>-></span><span class="token function" style=color:#d73a49>GetInt64</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>5</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 访问 bar.f2 的第 6 个元素</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">std</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token plain">string str </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> bar10</span><span class="token operator" style=color:#393A34>-></span><span class="token function" style=color:#d73a49>GetString</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// 访问 bar.f1</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=主要优势>主要优势<a href=#主要优势 class=hash-link aria-label=主要优势的直接链接 title=主要优势的直接链接 translate=no></a></h3> |
| <ul> |
| <li class=""><strong>零拷贝访问</strong>：无需反序列化整个对象即可读取嵌套字段</li> |
| <li class=""><strong>内存效率</strong>：直接从磁盘内存映射大型数据集</li> |
| <li class=""><strong>跨语言</strong>：二进制格式在 Python、Java 和其他 Fury 实现之间兼容</li> |
| <li class=""><strong>部分反序列化</strong>：仅反序列化您需要的特定元素</li> |
| <li class=""><strong>高性能</strong>：跳过不必要的数据解析，适用于分析和大数据工作负载</li> |
| </ul> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=️-核心-api-参考>🏗️ 核心 API 参考<a href=#️-核心-api-参考 class=hash-link aria-label="🏗️ 核心 API 参考的直接链接" title="🏗️ 核心 API 参考的直接链接" translate=no></a></h2> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=fory-类>Fory 类<a href=#fory-类 class=hash-link aria-label="Fory 类的直接链接" title="Fory 类的直接链接" translate=no></a></h3> |
| <p>主要的序列化接口：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Fory</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>__init__</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> xlang</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bool</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ref</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bool</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> strict</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bool</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> compatible</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bool</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> max_depth</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>50</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=threadsafefory-类>ThreadSafeFory 类<a href=#threadsafefory-类 class=hash-link aria-label="ThreadSafeFory 类的直接链接" title="ThreadSafeFory 类的直接链接" translate=no></a></h3> |
| <p>使用线程本地存储的线程安全序列化接口：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">ThreadSafeFory</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>__init__</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> xlang</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bool</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ref</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bool</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> strict</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bool</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> compatible</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bool</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> max_depth</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>50</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <p><code>ThreadSafeFory</code> 通过维护一个受锁保护的 <code>Fory</code> 实例池来提供线程安全的序列化。当线程需要序列化/反序列化时，它从池中获取一个实例，使用它，然后归还。所有类型注册必须在任何序列化之前完成，以确保所有实例之间的一致性。</p> |
| <p><strong>线程安全示例：</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> threading</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> dataclasses </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> dataclass</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token decorator annotation punctuation" style=color:#393A34>@dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Person</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> age</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 创建线程安全的 Fory 实例</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">ThreadSafeFory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Person</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 在多个线程中安全使用</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>serialize_in_thread</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">thread_id</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> person </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> Person</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">name</span><span class="token operator" style=color:#393A34>=</span><span class="token string-interpolation string" style=color:#e3116c>f"User</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">thread_id</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> age</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>25</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>+</span><span class="token plain"> thread_id</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">person</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string-interpolation string" style=color:#e3116c>f"Thread </span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">thread_id</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>: </span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">result</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">threads </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">threading</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Thread</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">target</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">serialize_in_thread</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> args</span><span class="token operator" style=color:#393A34>=</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">i</span><span class="token punctuation" style=color:#393A34>,</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> i </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> </span><span class="token builtin">range</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> t </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> threads</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> t</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">start</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> t </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> threads</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> t</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">join</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <p><strong>主要特性：</strong></p> |
| <ul> |
| <li class=""><strong>实例池</strong>：维护一个受锁保护的 <code>Fory</code> 实例池以实现线程安全</li> |
| <li class=""><strong>共享配置</strong>：所有注册必须预先完成并应用于所有实例</li> |
| <li class=""><strong>相同 API</strong>：与 <code>Fory</code> 类具有相同方法的直接替代品</li> |
| <li class=""><strong>注册安全</strong>：防止首次使用后注册以确保一致性</li> |
| </ul> |
| <p><strong>何时使用：</strong></p> |
| <ul> |
| <li class=""><strong>多线程应用</strong>：Web 服务器、并发工作线程、并行处理</li> |
| <li class=""><strong>共享 Fory 实例</strong>：当多个线程需要序列化/反序列化数据时</li> |
| <li class=""><strong>线程池</strong>：使用线程池或 concurrent.futures 的应用程序</li> |
| </ul> |
| <p><strong>参数：</strong></p> |
| <ul> |
| <li class=""><strong><code>xlang</code></strong> (<code>bool</code>, 默认=<code>False</code>)：启用跨语言序列化。当为 <code>False</code> 时，启用支持所有 Python 对象的 Python 原生模式。当为 <code>True</code> 时，启用与 Java、Go、Rust 等兼容的跨语言模式。</li> |
| <li class=""><strong><code>ref</code></strong> (<code>bool</code>, 默认=<code>False</code>)：启用共享/循环引用的引用跟踪。如果您的数据没有共享引用，禁用以获得更好的性能。</li> |
| <li class=""><strong><code>strict</code></strong> (<code>bool</code>, 默认=<code>True</code>)：要求类型注册以确保安全。<strong>强烈建议</strong>用于生产环境。仅在受信任的环境中禁用。</li> |
| <li class=""><strong><code>compatible</code></strong> (<code>bool</code>, 默认=<code>False</code>)：在跨语言模式下启用 schema 演化，允许在保持兼容性的同时添加/删除字段。</li> |
| <li class=""><strong><code>max_depth</code></strong> (<code>int</code>, 默认=<code>50</code>)：反序列化的最大深度，用于安全防护，防止栈溢出攻击。</li> |
| </ul> |
| <p><strong>主要方法：</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># 序列化（serialize/deserialize 与 dumps/loads 完全相同）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bytes</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">obj </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 替代 API（别名）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">bytes</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">obj </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 通过 id 注册类型（用于 Python 模式）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>123</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>123</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> serializer</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">custom_serializer</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 通过名称注册类型（用于跨语言模式）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> typename</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"my.package.MyClass"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> typename</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"my.package.MyClass"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> serializer</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">custom_serializer</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=语言模式对比>语言模式对比<a href=#语言模式对比 class=hash-link aria-label=语言模式对比的直接链接 title=语言模式对比的直接链接 translate=no></a></h3> |
| <table><thead><tr><th>特性<th>Python 模式 (<code>xlang=False</code>)<th>跨语言模式 (<code>xlang=True</code>)<tbody><tr><td><strong>用例</strong><td>纯 Python 应用<td>多语言系统<tr><td><strong>兼容性</strong><td>仅 Python<td>Java、Go、Rust、C++、JavaScript 等<tr><td><strong>支持的类型</strong><td>所有 Python 类型<td>仅跨语言兼容的类型<tr><td><strong>函数/Lambda</strong><td>✓ 支持<td>✗ 不允许<tr><td><strong>局部类</strong><td>✓ 支持<td>✗ 不允许<tr><td><strong>动态类</strong><td>✓ 支持<td>✗ 不允许<tr><td><strong>Schema 演化</strong><td>✓ 支持（启用 <code>compatible=True</code>）<td>✓ 支持（启用 <code>compatible=True</code>）<tr><td><strong>性能</strong><td>极快<td>非常快<tr><td><strong>数据大小</strong><td>紧凑<td>紧凑且包含类型元数据</table> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=python-模式-xlangfalse>Python 模式 (<code>xlang=False</code>)<a href=#python-模式-xlangfalse class=hash-link aria-label=python-模式-xlangfalse的直接链接 title=python-模式-xlangfalse的直接链接 translate=no></a></h4> |
| <p>Python 模式支持所有 Python 类型，包括函数、类和闭包。非常适合纯 Python 应用：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 完全 Python 兼容模式</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 支持所有 Python 对象：</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token string" style=color:#e3116c>'function'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>lambda</span><span class="token plain"> x</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> x </span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 函数和 lambda 表达式</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token string" style=color:#e3116c>'class'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">type</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>'Dynamic'</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 动态类</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token string" style=color:#e3116c>'method'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">upper</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 方法</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token string" style=color:#e3116c>'nested'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>'circular_ref'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>None</span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 循环引用（当 ref=True 时）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># pickle/cloudpickle 的直接替代品</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pickle</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">obj </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>"nested"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>4</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>assert</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>==</span><span class="token plain"> pickle</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">pickle</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 比 pickle 显著更快更紧凑</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> timeit</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">obj </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token string-interpolation string" style=color:#e3116c>f"key</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">i</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string-interpolation string" style=color:#e3116c>f"value</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">i</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> i </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> </span><span class="token builtin">range</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10000</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string-interpolation string" style=color:#e3116c>f"Fory: </span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">timeit</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>.</span><span class="token string-interpolation interpolation">timeit</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>(</span><span class="token string-interpolation interpolation keyword" style=color:#00009f>lambda</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>:</span><span class="token string-interpolation interpolation"> fory</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>.</span><span class="token string-interpolation interpolation">dumps</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>(</span><span class="token string-interpolation interpolation">obj</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>)</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>,</span><span class="token string-interpolation interpolation"> number</span><span class="token string-interpolation interpolation operator" style=color:#393A34>=</span><span class="token string-interpolation interpolation number" style=color:#36acaa>1000</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>)</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>:</span><span class="token string-interpolation interpolation format-spec">.3f</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>s"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string-interpolation string" style=color:#e3116c>f"Pickle: </span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">timeit</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>.</span><span class="token string-interpolation interpolation">timeit</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>(</span><span class="token string-interpolation interpolation keyword" style=color:#00009f>lambda</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>:</span><span class="token string-interpolation interpolation"> pickle</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>.</span><span class="token string-interpolation interpolation">dumps</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>(</span><span class="token string-interpolation interpolation">obj</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>)</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>,</span><span class="token string-interpolation interpolation"> number</span><span class="token string-interpolation interpolation operator" style=color:#393A34>=</span><span class="token string-interpolation interpolation number" style=color:#36acaa>1000</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>)</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>:</span><span class="token string-interpolation interpolation format-spec">.3f</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>s"</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=跨语言模式-xlangtrue>跨语言模式 (<code>xlang=True</code>)<a href=#跨语言模式-xlangtrue class=hash-link aria-label=跨语言模式-xlangtrue的直接链接 title=跨语言模式-xlangtrue的直接链接 translate=no></a></h4> |
| <p>跨语言模式将类型限制为所有 Fory 实现通用的类型。用于多语言系统：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 跨语言兼容模式</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 仅支持跨语言兼容的类型</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyDataClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> typename</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"com.example.MyDataClass"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 数据可以被 Java、Go、Rust 等读取</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyDataClass</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">field1</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"value"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> field2</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>42</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-高级特性>🔧 高级特性<a href=#-高级特性 class=hash-link aria-label="🔧 高级特性的直接链接" title="🔧 高级特性的直接链接" translate=no></a></h2> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=引用跟踪和循环引用>引用跟踪和循环引用<a href=#引用跟踪和循环引用 class=hash-link aria-label=引用跟踪和循环引用的直接链接 title=引用跟踪和循环引用的直接链接 translate=no></a></h3> |
| <p>安全处理共享引用和循环依赖。设置 <code>ref=True</code> 来去重对象：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 启用引用跟踪</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 安全处理循环引用</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Node</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>__init__</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> value</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> self</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> value</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> self</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">children </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> self</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">parent </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>None</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">root </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> Node</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"root"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">child </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> Node</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"child"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">child</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">parent </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> root </span><span class="token comment" style=color:#999988;font-style:italic># 循环引用</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">root</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">children</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">append</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">child</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 序列化不会无限递归</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">root</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>assert</span><span class="token plain"> result</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">children</span><span class="token punctuation" style=color:#393A34>[</span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">parent </span><span class="token keyword" style=color:#00009f>is</span><span class="token plain"> result </span><span class="token comment" style=color:#999988;font-style:italic># 引用被保留</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=类型注册和安全>类型注册和安全<a href=#类型注册和安全 class=hash-link aria-label=类型注册和安全的直接链接 title=类型注册和安全的直接链接 translate=no></a></h3> |
| <p>在严格模式下，只有注册的类型才能被反序列化。这可以防止任意代码执行：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 严格模式（推荐用于生产环境）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">SafeClass</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>__init__</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> self</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> data</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 在严格模式下必须注册类型</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">SafeClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> typename</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"com.example.SafeClass"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 现在序列化可以工作</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">obj </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> SafeClass</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"safe data"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 未注册的类型将引发异常</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">UnsafeClass</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>pass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 在严格模式下这将失败</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>try</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">UnsafeClass</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>except</span><span class="token plain"> Exception </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> e</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"安全保护已启动！"</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=自定义序列化器>自定义序列化器<a href=#自定义序列化器 class=hash-link aria-label=自定义序列化器的直接链接 title=自定义序列化器的直接链接 translate=no></a></h3> |
| <p>为特殊类型实现自定义序列化逻辑。覆盖 <code>write/read</code> 用于 Python 模式，<code>xwrite/xread</code> 用于跨语言：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serializer </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> Serializer</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> dataclasses </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> dataclass</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token decorator annotation punctuation" style=color:#393A34>@dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Foo</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f1</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f2</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">FooSerializer</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Serializer</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>__init__</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> cls</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">super</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">__init__</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> cls</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>write</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> obj</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> Foo</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 自定义序列化逻辑</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">write_varint32</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f1</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">write_string</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f2</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>read</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 自定义反序列化逻辑</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f1 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">read_varint32</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> f2 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">read_string</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> Foo</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">f1</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> f2</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 用于跨语言模式</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>xwrite</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> obj</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> Foo</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">write_int32</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f1</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">write_string</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">f2</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>xread</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> Foo</span><span class="token punctuation" style=color:#393A34>(</span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">read_int32</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token builtin">buffer</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">read_string</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Foo</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> serializer</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">FooSerializer</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> Foo</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 现在 Foo 使用您的自定义序列化器</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">Foo</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>42</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"hello"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">result</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># Foo(f1=42, f2='hello')</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=numpy-和科学计算>Numpy 和科学计算<a href=#numpy-和科学计算 class=hash-link aria-label="Numpy 和科学计算的直接链接" title="Numpy 和科学计算的直接链接" translate=no></a></h3> |
| <p>Fory 原生支持 numpy 数组，使用优化的序列化。大型数组在可能的情况下使用零拷贝：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> numpy </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> np</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 原生支持 Numpy 数组</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">arrays </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token string" style=color:#e3116c>'matrix'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">random</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">rand</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1000</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1000</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token string" style=color:#e3116c>'vector'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">arange</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>10000</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token string" style=color:#e3116c>'bool_mask'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">random</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">choice</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>[</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> size</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>5000</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">arrays</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 对于兼容的数组类型使用零拷贝</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>assert</span><span class="token plain"> np</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">array_equal</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">arrays</span><span class="token punctuation" style=color:#393A34>[</span><span class="token string" style=color:#e3116c>'matrix'</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> result</span><span class="token punctuation" style=color:#393A34>[</span><span class="token string" style=color:#e3116c>'matrix'</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-最佳实践>💡 最佳实践<a href=#-最佳实践 class=hash-link aria-label="💡 最佳实践的直接链接" title="💡 最佳实践的直接链接" translate=no></a></h2> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=生产环境配置>生产环境配置<a href=#生产环境配置 class=hash-link aria-label=生产环境配置的直接链接 title=生产环境配置的直接链接 translate=no></a></h3> |
| <p>使用这些推荐设置在生产环境中平衡安全性、性能和功能：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 生产环境推荐设置</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 如果需要跨语言支持则使用 True</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 如果有共享/循环引用则启用</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 关键：生产环境中始终为 True</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> compatible</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 仅在需要 schema 演化时启用</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> max_depth</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>20</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 根据数据结构深度调整</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 预先注册所有类型</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">UserModel</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">OrderModel</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">ProductModel</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>102</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=性能优化技巧>性能优化技巧<a href=#性能优化技巧 class=hash-link aria-label=性能优化技巧的直接链接 title=性能优化技巧的直接链接 translate=no></a></h3> |
| <p>使用这些指南优化序列化速度和内存使用：</p> |
| <ol> |
| <li class=""><strong>如果不需要则禁用 <code>ref=True</code></strong>：引用跟踪有开销</li> |
| <li class=""><strong>使用 type_id 而不是 typename</strong>：整数 ID 比字符串名称更快</li> |
| <li class=""><strong>复用 Fory 实例</strong>：创建一次，多次使用</li> |
| <li class=""><strong>启用 Cython</strong>：确保 <code>ENABLE_FORY_CYTHON_SERIALIZATION=1</code>，应默认启用</li> |
| <li class=""><strong>对大型数组使用行格式</strong>：用于分析的零拷贝访问</li> |
| </ol> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># 好的做法：复用实例</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> obj </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> objects</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 不好的做法：每次创建新实例</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> obj </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> objects</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 浪费！</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=类型注册模式>类型注册模式<a href=#类型注册模式 class=hash-link aria-label=类型注册模式的直接链接 title=类型注册模式的直接链接 translate=no></a></h3> |
| <p>为您的用例选择正确的注册方法：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># 模式 1：简单注册</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 模式 2：使用 typename 的跨语言</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> typename</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"com.example.MyClass"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 模式 3：使用自定义序列化器</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> serializer</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">MySerializer</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> MyClass</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 模式 4：批量注册</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">type_id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>100</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> model_class </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">User</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> Order</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> Product</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> Invoice</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">model_class</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">type_id</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> type_id </span><span class="token operator" style=color:#393A34>+=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=错误处理>错误处理<a href=#错误处理 class=hash-link aria-label=错误处理的直接链接 title=错误处理的直接链接 translate=no></a></h3> |
| <p>优雅地处理常见的序列化错误。捕获特定异常以实现更好的错误恢复：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">error </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> TypeUnregisteredError</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> TypeNotCompatibleError</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>try</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">my_object</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>except</span><span class="token plain"> TypeUnregisteredError </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> e</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string-interpolation string" style=color:#e3116c>f"类型未注册：</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">e</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 注册类型并重试</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token builtin">type</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">my_object</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">my_object</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>except</span><span class="token plain"> Exception </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> e</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string-interpolation string" style=color:#e3116c>f"序列化失败：</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">e</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>try</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> obj </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>except</span><span class="token plain"> TypeNotCompatibleError </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> e</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string-interpolation string" style=color:#e3116c>f"Schema 不匹配：</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">e</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 处理版本不匹配</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>except</span><span class="token plain"> Exception </span><span class="token keyword" style=color:#00009f>as</span><span class="token plain"> e</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string-interpolation string" style=color:#e3116c>f"反序列化失败：</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">e</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=️-迁移指南>🛠️ 迁移指南<a href=#️-迁移指南 class=hash-link aria-label="🛠️ 迁移指南的直接链接" title="🛠️ 迁移指南的直接链接" translate=no></a></h2> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=从-pickle-迁移>从 Pickle 迁移<a href=#从-pickle-迁移 class=hash-link aria-label="从 Pickle 迁移的直接链接" title="从 Pickle 迁移的直接链接" translate=no></a></h3> |
| <p>用 Fory 替换 pickle 以获得更好的性能，同时保持相同的 API：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># 之前（pickle）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pickle</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pickle</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pickle</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 之后（Fory - 具有更好性能的直接替代品）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">obj</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 更快更紧凑</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 更快的反序列化</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 优势：</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># - 序列化速度快 2-10 倍</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># - 反序列化速度快 2-5 倍</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># - 数据大小最多减少 3 倍</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># - 相同的 API，更好的性能</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=从-json-迁移>从 JSON 迁移<a href=#从-json-迁移 class=hash-link aria-label="从 JSON 迁移的直接链接" title="从 JSON 迁移的直接链接" translate=no></a></h3> |
| <p>与 JSON 不同，Fory 支持任意 Python 类型，包括函数：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># 之前（JSON - 类型有限）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> json</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> json</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>"name"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"Alice"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"age"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>30</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> json</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 之后（Fory - 所有 Python 类型）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>"name"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"Alice"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"age"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>30</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"func"</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>lambda</span><span class="token plain"> x</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> x</span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-安全最佳实践>🚨 安全最佳实践<a href=#-安全最佳实践 class=hash-link aria-label="🚨 安全最佳实践的直接链接" title="🚨 安全最佳实践的直接链接" translate=no></a></h2> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=生产环境配置-1>生产环境配置<a href=#生产环境配置-1 class=hash-link aria-label=生产环境配置的直接链接 title=生产环境配置的直接链接 translate=no></a></h3> |
| <p>除非您的环境完全可信，否则不要在生产环境中禁用 <code>strict=True</code>：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 推荐的生产环境设置</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 或 True 用于跨语言</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 处理循环引用</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 重要：防止恶意数据</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> max_depth</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 防止深度递归攻击</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 显式注册允许的类型</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">UserModel</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">OrderModel</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 绝不要在处理不可信数据的生产环境中设置 strict=False！</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=开发与生产环境>开发与生产环境<a href=#开发与生产环境 class=hash-link aria-label=开发与生产环境的直接链接 title=开发与生产环境的直接链接 translate=no></a></h3> |
| <p>使用环境变量在开发和生产配置之间切换：</p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> os</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 开发配置</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>if</span><span class="token plain"> os</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">getenv</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>'ENV'</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>==</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'development'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 开发时允许任何类型</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> max_depth</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>1000</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 开发时更高的限制</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>else</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 生产配置（安全加固）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 关键：需要注册</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> max_depth</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 合理的限制</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 仅注册已知的安全类型</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>for</span><span class="token plain"> idx</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> model_class </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> </span><span class="token builtin">enumerate</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain">UserModel</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ProductModel</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> OrderModel</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">model_class</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>+</span><span class="token plain"> idx</span><span class="token punctuation" style=color:#393A34>)</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=deserializationpolicy>DeserializationPolicy<a href=#deserializationpolicy class=hash-link aria-label=DeserializationPolicy的直接链接 title=DeserializationPolicy的直接链接 translate=no></a></h3> |
| <p>当必须使用 <code>strict=False</code> 时（例如，反序列化函数/lambda 表达式），使用 <code>DeserializationPolicy</code> 在反序列化期间实现细粒度的安全控制。这提供了类似于 <code>pickle.Unpickler.find_class()</code> 的保护，但具有更全面的钩子。</p> |
| <p><strong>为什么使用 DeserializationPolicy？</strong></p> |
| <ul> |
| <li class="">阻止危险的类/模块（例如，<code>subprocess.Popen</code>）</li> |
| <li class="">在调用之前拦截和验证 <code>__reduce__</code> 可调用对象</li> |
| <li class="">在 <code>__setstate__</code> 期间清理敏感数据</li> |
| <li class="">根据自定义规则替换或拒绝反序列化的对象</li> |
| </ul> |
| <p><strong>示例：阻止危险的类</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>from</span><span class="token plain"> pyfory </span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> DeserializationPolicy</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">dangerous_modules </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token string" style=color:#e3116c>'subprocess'</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'os'</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'__builtin__'</span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">SafeDeserializationPolicy</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">DeserializationPolicy</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token triple-quoted-string string" style=color:#e3116c>"""在反序列化期间阻止潜在危险的类。"""</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>validate_class</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> cls</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> is_local</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>**</span><span class="token plain">kwargs</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 阻止危险模块</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>if</span><span class="token plain"> cls</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">__module__ </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> dangerous_modules</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>raise</span><span class="token plain"> ValueError</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string-interpolation string" style=color:#e3116c>f"阻止危险类：</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">cls</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>.</span><span class="token string-interpolation interpolation">__module__</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>.</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>{</span><span class="token string-interpolation interpolation">cls</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>.</span><span class="token string-interpolation interpolation">__name__</span><span class="token string-interpolation interpolation punctuation" style=color:#393A34>}</span><span class="token string-interpolation string" style=color:#e3116c>"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>None</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>intercept_reduce_call</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> callable_obj</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> args</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>**</span><span class="token plain">kwargs</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 在 __reduce__ 期间阻止特定的可调用对象调用</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>if</span><span class="token plain"> </span><span class="token builtin">getattr</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">callable_obj</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'__name__'</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>""</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>==</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'Popen'</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>raise</span><span class="token plain"> ValueError</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"阻止尝试调用 subprocess.Popen"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>None</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>intercept_setstate</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> obj</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> state</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>**</span><span class="token plain">kwargs</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 清理敏感数据</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>if</span><span class="token plain"> </span><span class="token builtin">isinstance</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">state</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token builtin">dict</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>and</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'password'</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>in</span><span class="token plain"> state</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> state</span><span class="token punctuation" style=color:#393A34>[</span><span class="token string" style=color:#e3116c>'password'</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'***REDACTED***'</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>None</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 使用自定义安全策略创建 Fory</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">policy </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> SafeDeserializationPolicy</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> policy</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">policy</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 现在反序列化受到您自定义策略的保护</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">serialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">my_object</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">deserialize</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 将调用策略钩子</span><br/></div></code></pre></div></div> |
| <p><strong>可用的策略钩子：</strong></p> |
| <ul> |
| <li class=""><code>validate_class(cls, is_local)</code> - 在反序列化期间验证/阻止类类型</li> |
| <li class=""><code>validate_module(module, is_local)</code> - 验证/阻止模块导入</li> |
| <li class=""><code>validate_function(func, is_local)</code> - 验证/阻止函数引用</li> |
| <li class=""><code>intercept_reduce_call(callable_obj, args)</code> - 拦截 <code>__reduce__</code> 调用</li> |
| <li class=""><code>inspect_reduced_object(obj)</code> - 检查/替换通过 <code>__reduce__</code> 创建的对象</li> |
| <li class=""><code>intercept_setstate(obj, state)</code> - 在 <code>__setstate__</code> 之前检查状态</li> |
| <li class=""><code>authorize_instantiation(cls, args, kwargs)</code> - 控制类实例化</li> |
| </ul> |
| <p><strong>另见：</strong> <code>pyfory/policy.py</code> 包含每个hook的详细文档和示例。</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-故障排查>🐛 故障排查<a href=#-故障排查 class=hash-link aria-label="🐛 故障排查的直接链接" title="🐛 故障排查的直接链接" translate=no></a></h2> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=常见问题>常见问题<a href=#常见问题 class=hash-link aria-label=常见问题的直接链接 title=常见问题的直接链接 translate=no></a></h3> |
| <p><strong>Q: 格式功能的 ImportError</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># A: 安装行格式支持</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">pip install pyfory</span><span class="token punctuation" style=color:#393A34>[</span><span class="token builtin">format</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 或从源码安装并支持格式功能</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">pip install </span><span class="token operator" style=color:#393A34>-</span><span class="token plain">e </span><span class="token string" style=color:#e3116c>".[format]"</span><br/></div></code></pre></div></div> |
| <p><strong>Q: 序列化性能慢</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># A: 检查是否启用了 Cython 加速</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">ENABLE_FORY_CYTHON_SERIALIZATION</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 应该为 True</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 如果为 False，Cython 扩展可能未正确编译</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 使用以下命令重新安装：pip install --force-reinstall --no-cache-dir pyfory</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 对于调试，您可以在导入前禁用 Cython 模式</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> os</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">os</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">environ</span><span class="token punctuation" style=color:#393A34>[</span><span class="token string" style=color:#e3116c>'ENABLE_FORY_CYTHON_SERIALIZATION'</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'0'</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory </span><span class="token comment" style=color:#999988;font-style:italic># 现在使用纯 Python 模式</span><br/></div></code></pre></div></div> |
| <p><strong>Q: 跨语言兼容性问题</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># A: 使用显式类型注册和一致的命名</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> typename</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"com.package.MyClass"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 在所有语言中使用相同的名称</span><br/></div></code></pre></div></div> |
| <p><strong>Q: 循环引用错误或重复数据</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># A: 启用引用跟踪</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">ref</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 循环引用必需</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 循环引用示例</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Node</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>def</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>__init__</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">self</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> value</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> self</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> value</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> self</span><span class="token punctuation" style=color:#393A34>.</span><span class="token builtin">next</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>None</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">node1 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> Node</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">node2 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> Node</span><span class="token punctuation" style=color:#393A34>(</span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">node1</span><span class="token punctuation" style=color:#393A34>.</span><span class="token builtin">next</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> node2</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">node2</span><span class="token punctuation" style=color:#393A34>.</span><span class="token builtin">next</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> node1 </span><span class="token comment" style=color:#999988;font-style:italic># 循环引用</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">node1</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>assert</span><span class="token plain"> result</span><span class="token punctuation" style=color:#393A34>.</span><span class="token builtin">next</span><span class="token punctuation" style=color:#393A34>.</span><span class="token builtin">next</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>is</span><span class="token plain"> result </span><span class="token comment" style=color:#999988;font-style:italic># 循环引用被保留</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=调试模式>调试模式<a href=#调试模式 class=hash-link aria-label=调试模式的直接链接 title=调试模式的直接链接 translate=no></a></h3> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># 在导入 pyfory 之前设置环境变量以禁用 Cython 进行调试</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> os</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">os</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">environ</span><span class="token punctuation" style=color:#393A34>[</span><span class="token string" style=color:#e3116c>'ENABLE_FORY_CYTHON_SERIALIZATION'</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'0'</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> pyfory </span><span class="token comment" style=color:#999988;font-style:italic># 现在使用纯 Python 实现</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 这对以下情况很有用：</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 1. 调试协议问题</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 2. 理解序列化行为</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 3. 无需重新编译 Cython 进行开发</span><br/></div></code></pre></div></div> |
| <p><strong>Q: Schema 演化不起作用</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># A: 为 schema 演化启用兼容模式</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">xlang</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> compatible</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 版本 1：原始类</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token decorator annotation punctuation" style=color:#393A34>@dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> age</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">User</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> typename</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"User"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">data </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">dumps</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">User</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"Alice"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>30</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 版本 2：添加新字段（向后兼容）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token decorator annotation punctuation" style=color:#393A34>@dataclass</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> name</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> age</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> email</span><span class="token punctuation" style=color:#393A34>:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"unknown@example.com"</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 带默认值的新字段</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 仍然可以反序列化旧数据</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">user </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">loads</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">data</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>print</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">user</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">email</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># "unknown@example.com"</span><br/></div></code></pre></div></div> |
| <p><strong>Q: 严格模式下的类型注册错误</strong></p> |
| <div class="language-python codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-python codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic># A: 在序列化之前注册所有自定义类型</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>True</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 使用前必须注册</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">MyClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">register</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">AnotherClass</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> type_id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 或禁用严格模式（不推荐用于生产环境）</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">f </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> pyfory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Fory</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">strict</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>False</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic># 仅在受信任的环境中使用</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-贡献>🤝 贡献<a href=#-贡献 class=hash-link aria-label="🤝 贡献的直接链接" title="🤝 贡献的直接链接" translate=no></a></h2> |
| <p>Apache Fory™ 是 Apache 软件基金会下的开源项目。我们欢迎所有形式的贡献：</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=如何贡献>如何贡献<a href=#如何贡献 class=hash-link aria-label=如何贡献的直接链接 title=如何贡献的直接链接 translate=no></a></h3> |
| <ol> |
| <li class=""><strong>报告问题</strong>：发现 bug？<a href=https://github.com/apache/fory/issues target=_blank rel="noopener noreferrer" class="">提交 issue</a></li> |
| <li class=""><strong>建议功能</strong>：有想法？开始讨论</li> |
| <li class=""><strong>改进文档</strong>：文档改进总是受欢迎的</li> |
| <li class=""><strong>提交代码</strong>：请查看我们的<a href=https://github.com/apache/fory/blob/main/CONTRIBUTING.md target=_blank rel="noopener noreferrer" class="">贡献指南</a></li> |
| </ol> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=开发环境设置>开发环境设置<a href=#开发环境设置 class=hash-link aria-label=开发环境设置的直接链接 title=开发环境设置的直接链接 translate=no></a></h3> |
| <div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token function" style=color:#d73a49>git</span><span class="token plain"> clone https://github.com/apache/fory.git</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">cd</span><span class="token plain"> fory/python</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 安装依赖</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">pip </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>-e</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>".[dev,format]"</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 运行测试</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">pytest </span><span class="token parameter variable" style=color:#36acaa>-v</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>-s</span><span class="token plain"> </span><span class="token builtin class-name">.</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 运行特定测试</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">pytest </span><span class="token parameter variable" style=color:#36acaa>-v</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>-s</span><span class="token plain"> pyfory/tests/test_serializer.py</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic># 格式化代码</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">ruff </span><span class="token function" style=color:#d73a49>format</span><span class="token plain"> </span><span class="token builtin class-name">.</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">ruff check </span><span class="token parameter variable" style=color:#36acaa>--fix</span><span class="token plain"> </span><span class="token builtin class-name">.</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-许可证>📄 许可证<a href=#-许可证 class=hash-link aria-label="📄 许可证的直接链接" title="📄 许可证的直接链接" translate=no></a></h2> |
| <p>Apache License 2.0。详见 <a href=https://github.com/apache/fory/blob/main/LICENSE target=_blank rel="noopener noreferrer" class="">LICENSE</a>。</p> |
| <hr/> |
| <p><strong>Apache Fory™</strong> - 适用于现代应用的极速、安全且多功能的序列化框架。</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-链接>🔗 链接<a href=#-链接 class=hash-link aria-label="🔗 链接的直接链接" title="🔗 链接的直接链接" translate=no></a></h2> |
| <ul> |
| <li class=""><strong>文档</strong>：<a href=https://fory.apache.org/docs/latest/python_guide/ target=_blank rel="noopener noreferrer" class="">https://fory.apache.org/docs/latest/python_guide/</a></li> |
| <li class=""><strong>GitHub</strong>：<a href=https://github.com/apache/fory target=_blank rel="noopener noreferrer" class="">https://github.com/apache/fory</a></li> |
| <li class=""><strong>PyPI</strong>：<a href=https://pypi.org/project/pyfory/ target=_blank rel="noopener noreferrer" class="">https://pypi.org/project/pyfory/</a></li> |
| <li class=""><strong>Issues</strong>：<a href=https://github.com/apache/fory/issues target=_blank rel="noopener noreferrer" class="">https://github.com/apache/fory/issues</a></li> |
| <li class=""><strong>Slack</strong>：<a href=https://join.slack.com/t/fory-project/shared_invite/zt-36g0qouzm-kcQSvV_dtfbtBKHRwT5gsw target=_blank rel="noopener noreferrer" class="">https://join.slack.com/t/fory-project/shared_invite/zt-36g0qouzm-kcQSvV_dtfbtBKHRwT5gsw</a></li> |
| <li class=""><strong>基准测试</strong>：<a href=https://fory.apache.org/docs/latest/benchmarks/ target=_blank rel="noopener noreferrer" class="">https://fory.apache.org/docs/latest/benchmarks/</a></li> |
| </ul> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=-社区>🌟 社区<a href=#-社区 class=hash-link aria-label="🌟 社区的直接链接" title="🌟 社区的直接链接" translate=no></a></h2> |
| <p>我们欢迎贡献！无论是 bug 报告、功能请求、文档改进还是代码贡献，我们都感激您的帮助。</p> |
| <ul> |
| <li class="">在 <a href=https://github.com/apache/fory target=_blank rel="noopener noreferrer" class="">GitHub</a> 上给项目加星 ⭐</li> |
| <li class="">加入我们的 <a href=https://join.slack.com/t/fory-project/shared_invite/zt-36g0qouzm-kcQSvV_dtfbtBKHRwT5gsw target=_blank rel="noopener noreferrer" class="">Slack 社区</a> 💬</li> |
| <li class="">在 <a href=https://x.com/ApacheFory target=_blank rel="noopener noreferrer" class="">X/Twitter</a> 上关注我们 🐦</li> |
| </ul></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col noPrint_WFHX"><a href=https://github.com/apache/fory-site/tree/main/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.13/guide/python_guide.md target=_blank rel="noopener noreferrer" class=theme-edit-this-page><svg fill=currentColor height=20 width=20 viewBox="0 0 40 40" class=iconEdit_Z9Sw aria-hidden=true><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"/></g></svg>编辑此页</a></div><div class="col lastUpdated_JAkA"></div></div></footer></article><nav class="docusaurus-mt-lg pagination-nav" aria-label=文件选项卡><a class="pagination-nav__link pagination-nav__link--prev" href=/zh-CN/docs/0.13/guide/serialization><div class=pagination-nav__sublabel>上一页</div><div class=pagination-nav__label>Java 序列化</div></a><a class="pagination-nav__link pagination-nav__link--next" href=/zh-CN/docs/0.13/guide/rust_serialization><div class=pagination-nav__sublabel>下一页</div><div class=pagination-nav__label>Rust 序列化</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href=#apache-fory-python class="table-of-contents__link toc-highlight">Apache Fory™ Python</a><li><a href=#-核心特性 class="table-of-contents__link toc-highlight">🚀 核心特性</a><ul><li><a href=#-灵活的序列化模式 class="table-of-contents__link toc-highlight">🔧 <strong>灵活的序列化模式</strong></a><li><a href=#-多样的序列化功能 class="table-of-contents__link toc-highlight">🎯 多样的序列化功能</a><li><a href=#-极速性能 class="table-of-contents__link toc-highlight">⚡ <strong>极速性能</strong></a><li><a href=#-紧凑的数据大小 class="table-of-contents__link toc-highlight">📦 紧凑的数据大小</a><li><a href=#️-安全性 class="table-of-contents__link toc-highlight">🛡️ <strong>安全性</strong></a></ul><li><a href=#-安装 class="table-of-contents__link toc-highlight">📦 安装</a><ul><li><a href=#基础安装 class="table-of-contents__link toc-highlight">基础安装</a><li><a href=#可选依赖 class="table-of-contents__link toc-highlight">可选依赖</a><li><a href=#环境要求 class="table-of-contents__link toc-highlight">环境要求</a></ul><li><a href=#-python-原生序列化 class="table-of-contents__link toc-highlight">🐍 Python 原生序列化</a><ul><li><a href=#基础对象序列化 class="table-of-contents__link toc-highlight">基础对象序列化</a><li><a href=#自定义类序列化 class="table-of-contents__link toc-highlight">自定义类序列化</a><li><a href=#picklecloudpickle-的直接替代品 class="table-of-contents__link toc-highlight">Pickle/Cloudpickle 的直接替代品</a><li><a href=#带外缓冲区序列化 class="table-of-contents__link toc-highlight">带外缓冲区序列化</a></ul><li><a href=#️-跨语言�对象图序列化 class="table-of-contents__link toc-highlight">🏃♂️ 跨语言对象图序列化</a><ul><li><a href=#跨语言序列化 class="table-of-contents__link toc-highlight">跨语言序列化</a></ul><li><a href=#-行格式---零拷贝处理 class="table-of-contents__link toc-highlight">📊 行格式 - 零拷贝处理</a><ul><li><a href=#行格式基础用法 class="table-of-contents__link toc-highlight">行格式基础用法</a><li><a href=#跨语言兼容性 class="table-of-contents__link toc-highlight">跨语言兼容性</a><li><a href=#主要优势 class="table-of-contents__link toc-highlight">主要优势</a></ul><li><a href=#️-核心-api-参考 class="table-of-contents__link toc-highlight">🏗️ 核心 API 参考</a><ul><li><a href=#fory-类 class="table-of-contents__link toc-highlight">Fory 类</a><li><a href=#threadsafefory-类 class="table-of-contents__link toc-highlight">ThreadSafeFory 类</a><li><a href=#语言模式对比 class="table-of-contents__link toc-highlight">语言模式对比</a></ul><li><a href=#-高级特性 class="table-of-contents__link toc-highlight">🔧 高级特性</a><ul><li><a href=#引用跟踪和循环引用 class="table-of-contents__link toc-highlight">引用跟踪和循环引用</a><li><a href=#类型注册和安全 class="table-of-contents__link toc-highlight">类型注册和安全</a><li><a href=#自定义序列化器 class="table-of-contents__link toc-highlight">自定义序列化器</a><li><a href=#numpy-和科学计算 class="table-of-contents__link toc-highlight">Numpy 和科学计算</a></ul><li><a href=#-最佳实践 class="table-of-contents__link toc-highlight">💡 最佳实践</a><ul><li><a href=#生产环境配置 class="table-of-contents__link toc-highlight">生产环境配置</a><li><a href=#性能优化技巧 class="table-of-contents__link toc-highlight">性能优化技巧</a><li><a href=#类型注册模式 class="table-of-contents__link toc-highlight">类型注册模式</a><li><a href=#错误处理 class="table-of-contents__link toc-highlight">错误处理</a></ul><li><a href=#️-迁移指南 class="table-of-contents__link toc-highlight">🛠️ 迁移指南</a><ul><li><a href=#从-pickle-迁移 class="table-of-contents__link toc-highlight">从 Pickle 迁移</a><li><a href=#从-json-迁移 class="table-of-contents__link toc-highlight">从 JSON 迁移</a></ul><li><a href=#-安全最佳实践 class="table-of-contents__link toc-highlight">🚨 安全最佳实践</a><ul><li><a href=#生产环境配置-1 class="table-of-contents__link toc-highlight">生产环境配置</a><li><a href=#开发与生产环境 class="table-of-contents__link toc-highlight">开发与生产环境</a><li><a href=#deserializationpolicy class="table-of-contents__link toc-highlight">DeserializationPolicy</a></ul><li><a href=#-故障排查 class="table-of-contents__link toc-highlight">🐛 故障排查</a><ul><li><a href=#常见问题 class="table-of-contents__link toc-highlight">常见问题</a><li><a href=#调试模式 class="table-of-contents__link toc-highlight">调试模式</a></ul><li><a href=#-贡献 class="table-of-contents__link toc-highlight">🤝 贡献</a><ul><li><a href=#如何贡献 class="table-of-contents__link toc-highlight">如何贡献</a><li><a href=#开发环境设置 class="table-of-contents__link toc-highlight">开发环境设置</a></ul><li><a href=#-许可证 class="table-of-contents__link toc-highlight">📄 许可证</a><li><a href=#-链接 class="table-of-contents__link toc-highlight">🔗 链接</a><li><a href=#-社区 class="table-of-contents__link toc-highlight">🌟 社区</a></ul></div></div></div></div></main></div></div></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class=footer__title>社区</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://lists.apache.org/list.html?dev@fory.apache.org target=_blank rel="noopener noreferrer" class=footer__link-item>邮件列表<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://join.slack.com/t/fory-project/shared_invite/zt-1u8soj4qc-ieYEu7ciHOqA2mo47llS8A target=_blank rel="noopener noreferrer" class=footer__link-item>Slack<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://twitter.com/ApacheFory target=_blank rel="noopener noreferrer" class=footer__link-item>Twitter<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>文档</div><ul class="footer__items clean-list"><li class=footer__item><a class=footer__link-item href=/zh-CN/docs/start/install>安装</a><li class=footer__item><a class=footer__link-item href=/zh-CN/docs/start/usage>使用</a><li class=footer__item><a class=footer__link-item href=/zh-CN/docs/introduction/benchmark>基准测试</a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>代码库</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://github.com/apache/fory target=_blank rel="noopener noreferrer" class=footer__link-item>Apache Fory™<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://github.com/apache/fory-site target=_blank rel="noopener noreferrer" class=footer__link-item>网站<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div></div><div class="footer__bottom text--center"><div class=margin-bottom--sm><a href=https://apache.org/ rel="noopener noreferrer" class=footerLogoLink_BH7S><img src=/zh-CN/img/asf_logo.svg alt="Apache Incubator 标志" class="footer__logo themedComponent_mlkZ themedComponent--light_NVdE" width=200 /><img src=/zh-CN/img/asf_logo.svg alt="Apache Incubator 标志" class="footer__logo themedComponent_mlkZ themedComponent--dark_xIcU" width=200 /></a></div><div class=footer__copyright><div> |
| <p> 版权所有 © 2025 The Apache Software Foundation，许可证：Apache License, Version 2.0。 <br/> |
| Apache Fory、Fory、Apache、Apache Logo、Apache Fory Logo 是 Apache 软件基金会在美国和/或其他国家的注册商标或商标。 |
| </p> |
| </div></div></div></div></footer></div></body> |
