js-IPFS 的 IPLD Codecs 完全指南：区块编解码器、Multihash 与 Multibase 的配置与扩展

存储网络通信【免费下载链接】js-ipfsIPFS implementation in JavaScript项目地址https://gitcode.com/gh_mirrors/js/js-ipfs点击查看免费下载js-IPFS 使用 IPLDInterPlanetary Linked Data作为其内容寻址数据模型仓库中的每个数据块都对应一个 CID 和一段字节数据而解码这些字节数据必须依赖对应的 BlockCodec。本文以仓库文档 docs/IPLD.md 为核心骨架系统讲解 js-IPFS 内置的 BlockCodecs、Multihashes、Multibases并给出在进程内节点与 HTTP API Client 两端扩展自定义编解码器的完整配置方案。读完本文你将掌握 CID 编解码机制、内置格式清单以及通过ipld配置项接入自定义 codec / hasher / base 的实战方法。OverviewCID、字节块与 BlockCodec 的关系IPFS 仓库repo内部持有一个 blockstore用来存放构成 IPFS 网络上文件的所有数据块block。每个块在概念上可以看作一个CID 与一段字节数组byte array的配对CID 负责标识内容字节数组负责承载内容本身。CID 中携带一个code属性它告诉我们如何解读与该 CID 关联的字节数组——例如某段字节应当被解析为 protobuf 格式的文件目录还是被解析为 JSON 对象。要完成这种解读就必须加载一个与该code值对应的 BlockCodec区块编解码器。同理Multihash哈希函数与 Multibase基编码的实现也必须可用才能正确计算内容标识、并对外展示或解析 CID 字符串。也就是说编解码器、哈希器、基编码这三类实现共同构成了 js-IPFS 读写 IPLD 数据的基础设施。在 js-IPFS 的源码中这套基础设施在节点启动时被统一组装。以 packages/ipfs-core/src/components/index.js 为例节点会把内置 codecs、用户通过options.ipld.codecs传入的 codec以及loadCodec动态加载函数一起交给Multicodecs实例管理bases、hashers也以同样方式组装见同文件第 90-104 行。HTTP Client 的组装逻辑与之完全对应见 packages/ipfs-http-client/src/index.js这是下文双端配置的关键所在。内置 BlockCodecsjs-IPFS 随包内置了若干编解码器其中四个是创建和解读 UnixFS 结构所必需的ipld/dag-pb用于文件和目录结构。UnixFS 的 protobuf 格式块都由它编解码是add、ls、cat等文件操作的基础。raw用于文件数据当以--raw-leavestrue原始叶子节点导入文件时叶子数据块直接使用 raw codec不再包裹 UnixFS protobuf 头。ipld/dag-cbor用于存储带 CID 链接的 JavaScript 对象支持在对象中内嵌指向其他块的 CID从而构造任意 DAG 图。json用于存储纯 JavaScript 对象不含 CID 链接的普通 JSON 数据。从源码看实际内置的集合比这四者更宽。在 packages/ipfs-core/src/components/index.js 中节点启动时会把multiformats/basics导出的全部 codecs、dag-pb、dag-cbor、dag-json、dag-jose以及 identity codec 一并注册再拼接用户自定义 codec。换言之上表四个是官方文档强调的UnixFS 必需项而真实环境还额外具备dag-json、dag-jose等能力。内置 Multihashesjs-IPFS 内置了 js-multiformats 导出的全部多哈希multihash实现其中就包括最常用的sha2-256以及sha2-512、sha3-*、blake2b-*、identity等。sha2-256也是 js-IPFS 的默认哈希绝大多数 CIDv1 内容标识都基于它生成。从 packages/ipfs-core/src/components/index.js 可以看出节点内置 hashers 来自multiformats/basics的hashes导出用户额外指定的 hashers 会追加到同一列表中最终统一交给Multihashes实例见 packages/ipfs-core-utils/src/multihashes.js。如果应用需要使用内置之外的哈希函数可以通过hashers配置属性追加自定义实现详见下文添加额外的编解码器、哈希器与基编码一节。内置 Multibases与 Multihash 类似js-IPFS 也内置了 js-multiformats 导出的全部多基编码multibase实现包括base58btc默认的 CID 字符串展示形式如Qm...开头的 CIDv0 即 base58btc 编码base32CIDv1 默认使用的基编码小写、无填充形如bafy...即base32前缀为b以及base16hex、base64、base36、base58flickr、base32hex、base32z、base64url等。用户可通过bases配置属性追加额外的基编码。在 packages/ipfs-core/src/components/index.js 中内置 bases 与自定义 bases 会被合并后交给Multibases实例其实现类见 packages/ipfs-core-utils/src/multibases.js它同时维护了按名称与按前缀字符两套查找索引。添加额外的 BlockCodecs、Multihashes 与 Multibases如果应用需要支持额外格式例如读取 git 仓库对象、bitcoin 交易等特殊数据就需要在两个位置分别配置二者缺一不可IPFS 节点侧让节点知道如何把收到的数据交给 IPLD 进行序列化/反序列化HTTP API Client 侧让客户端能通过 HTTP 把数据正确地发送给节点。下面的配置代码就是官方文档给出的推荐写法两类创建入口结构完全一致。1. 配置 IPFS 节点的 IPLD 层以进程内节点为例配置options.ipld即可import { create } from ipfs import customBlockCodec from custom-blockcodec import customMultibase from custom-multibase import customMultihasher from custom-multihasher const node await create({ ipld: { // 方式一把 BlockCodec 直接加入 codecs 列表 codecs: [ customBlockCodec ], // 方式二提供函数按名称/代码动态加载 codec loadCodec: async (codecNameOrCode) { return import(codecNameOrCode) }, // 方式一把 Multibase 加入 bases 列表 bases: [ customMultibase ], // 方式二动态加载 base loadBase: async (baseNameOrCode) { return import(baseNameOrCode) }, // 方式一把 Multihash hasher 加入 hashers 列表 hashers: [ customMultihasher ], // 方式二动态加载 hasher loadHasher: async (hashNameOrCode) { return import(hashNameOrCode) } } })列表 动态加载函数双通道设计codecs/bases/hashers列表用于静态注册明确已知的实现loadCodec/loadBase/loadHasher用于按需动态解析——当遇到列表中未注册、但按名称或代码标识可以加载的实现时节点会调用这些函数。若未提供加载函数底层会使用默认的拒绝逻辑Multicodecs/Multibases/Multihashes类的默认 loader 会直接抛出No codec found for .../No base found for .../No hasher found for ...错误见 packages/ipfs-core-utils/src/multicodecs.js、packages/ipfs-core-utils/src/multibases.js、packages/ipfs-core-utils/src/multihashes.js。需要指出的是该ipld配置对象会与默认配置合并而非整体替换具体约定见 docs/MODULE.md 的options.ipld小节。浏览器端的默认 IPLD 格式集合更精简默认只含dag-pb、dag-cbor、raw等因此浏览器场景下自定义配置的需求更常见。2. 配置 IPFS HTTP API Client客户端侧采用同样的ipld配置结构只是入口函数来自ipfs-http-clientimport { create } from ipfs-http-client import customBlockCodec from custom-blockcodec import customMultibase from custom-multibase import customMultihasher from custom-multihasher const client create({ url: http://127.0.0.1:5002, ipld: { // 方式一直接注册 BlockCodec codecs: [ customBlockCodec ], // 方式二动态加载 loadCodec: async (codecNameOrCode) { return import(codecNameOrCode) }, // 方式一直接注册 Multibase bases: [ customMultibase ], // 方式二动态加载 loadBase: async (baseNameOrCode) { return import(baseNameOrCode) }, // 方式一直接注册 Multihash hasher hashers: [ customMultihasher ], // 方式二动态加载 loadHasher: async (hashNameOrCode) { return import(hashNameOrCode) } } })示例中的http://127.0.0.1:5002正是 js-IPFS 默认的 API 监听地址默认配置中Addresses.API即为/ip4/127.0.0.1/tcp/5002见 packages/ipfs-core-config/src/config.js与文档示例完全一致。从源码看HTTP 客户端在 packages/ipfs-http-client/src/index.js 中以与节点侧几乎相同的逻辑组装Multibases、Multicodecs、Multihashes并把这些能力注入dag、object、refs等 API 实现。为什么节点与客户端都要配置这两处配置承担的是不同职责节点侧配置负责解码与解释节点需要能解析收到的数据、把原始字节按其 code 还原为结构化对象如 UnixFS 目录、DAG-CBOR 对象这依赖于注册在节点上的 codec。客户端侧配置负责编码与发送客户端需要把应用层的数据如dag.put传入的对象编码成正确的字节格式并通过 HTTP 传输给节点若客户端缺少对应 codec就无法完成序列化。两者各司其职因此新增自定义格式时必须两端同时配置否则会出现节点能读但客户端不能写或反之的割裂问题。兼容旧版 IPLD format 的迁移路径对于尚未迁移到新 BlockCodec 接口的旧式 IPLD format例如ipld-git、ipld-bitcoin等社区提供了ipld-format-to-blockcodec模块做桥接转换把旧的 format 包装成新的 BlockCodec 再注册。这一用法在 docs/MODULE.md 的options.ipld章节中有完整示例通过convert(ipldGit)将旧 format 转换为 BlockCodec 后放入codecs列表即可。此外动态加载loadCodec还支持浏览器环境的import()动态导入与 Webpack 魔法注释分包让自定义格式在浏览器端也能按需加载。Next steps可运行的示例与进一步探索如果你想看到上述配置的完整可运行代码官方维护的示例仓库提供了两个高价值参考custom-ipld-formats 示例分别演示了进程内 IPFS 节点、以 daemon 方式运行的 IPFS以及HTTP 客户端三种场景下接入自定义 IPLD 格式的完整代码traverse-ipld-graphs 示例演示如何遍历 IPLD 图并结合ipld-format-to-blockcodec使用尚未移植到新 BlockCodec 接口的旧 IPLD format同时展示如何挂载额外的 Multihash Hasher。在仓库内你也可以直接阅读以下源码与文档深化理解packages/ipfs-core/src/components/index.js节点侧 codec / hasher / base 的组装逻辑packages/ipfs-http-client/src/index.jsHTTP 客户端侧的同构组装逻辑packages/ipfs-core-utils/src/multicodecs.js、packages/ipfs-core-utils/src/multibases.js、packages/ipfs-core-utils/src/multihashes.js三类注册表实现含默认 loader 的报错行为docs/MODULE.mdoptions.ipld的完整配置说明与旧 format 迁移示例docs/core-api/DAG.mdDAG API 的日常使用方式配合自定义 codec 可读写任意 IPLD 数据。赞分享存储网络通信【免费下载链接】js-ipfsIPFS implementation in JavaScript项目地址https://gitcode.com/gh_mirrors/js/js-ipfs点击查看免费下载相关推荐Bluetooth-jammer-esp32项目演进从基础版到Noisy-boy升级路线Bluetooth jammer esp32项目演进从基础版到Noisy boy升级路线 Bluetooth jammer esp32是一个基于ESP32和NNamecoin深度解析blockchain-identity项目记录区块链域名身份的开山鼻祖Namecoin深度解析blockchain identity项目记录区块链域名身份的开山鼻祖 在区块链的世界里Namecoin 是绕不开的名字。作为比特币跨平台图形学前端终极指南如何完美配合IPFS Desktop与IPFS Companion浏览器扩展终极指南如何完美配合IPFS Desktop与IPFS Companion浏览器扩展 IPFS Desktop是一款适用于Windows、Mac和Linux的桌面应用网络存储上一篇音乐解锁终极指南让你的付费音乐真正属于你下一篇ResNet-50图像分类实战从零开始的完整部署指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考