Apache OpenDAL 0.47.10 常用工具与 API 详解

Apache OpenDAL 0.47.10 常用工具与 API 详解：OpenDAL 无命令行工具，按 API 速查 Operator 统一算子的 create_dir/write/read/stat/list 核心方法，给出代码示例与实测回显、AsyncOperator 与模块表面、storage schemes 支持矩阵与 FAQ。

Apache OpenDALApache OpenDAL2026/10/11

Apache OpenDAL 0.47.10 常用工具与 API 详解

目标：详解 Apache OpenDAL 0.47.10 Python 绑定的常用 API。OpenDAL 以「库 + 统一算子」形态提供，没有独立命令行工具，数据访问通过 Operator（同步）/ AsyncOperator（异步）完成。本文按 API 速查 create_dir、write、read、stat、list 等核心方法，给出代码示例与实测回显，并附 storage schemes 支持矩阵与 FAQ。已在 Ubuntu 22.04.5 LTS（Python 3.10.12）实测。

一、环境信息

项目值
操作系统Ubuntu 22.04.5 LTS
Pythonpython3 3.10.12
OpenDAL Python 绑定0.47.10（PyPI wheel，约 19.2 MB）
实测 schemefs（本地文件系统），数据目录 /tmp/opendal-demo
运行用户root

二、工具概览

OpenDAL 以「库 + 统一算子」形态提供，没有 opendal 命令行可执行程序；对数据的全部操作都通过代码调用绑定 API 完成。Python 绑定模块表面（实测归纳）：

模块/对象作用
Operator同步统一算子，本文实测主体
AsyncOperator异步统一算子
capability能力查询模块
config / operator / services / types / layers / file / exceptions配置、算子、服务、类型、层、文件与异常等支撑模块

💡 说明：OpenDAL 的核心抽象是「一套 API 访问任意存储」：统一算子 Operator（同步）/ AsyncOperator（异步）通过 scheme + 配置构建，换后端只改构建参数，API 调用方式不变。

三、前置条件

# 安装 opendal Python 绑定
pip3 install opendal

# 确认版本
python3 -c "import opendal; print(opendal.__version__)"

# 创建演示数据目录
mkdir -p /tmp/opendal-demo

实测输出：0.47.10。

四、核心 API 详解

4.1 Operator：构建统一算子

Operator 通过 scheme + 配置构建，是所有数据操作的入口：

import opendal

op = opendal.Operator('fs', root='/tmp/opendal-demo')
  • 第 1 个位置参数为 scheme（存储后端），关键字参数为该后端配置（fs 只需 root）。
  • 异步形态为 AsyncOperator，同样通过 scheme + 配置构建（本次实测以同步 Operator 为准）。

4.2 create_dir：创建目录

# fs 下真实创建目录；路径以 / 结尾表示目录
op.create_dir('subdir/')

实测确认：磁盘侧生成 /tmp/opendal-demo/subdir/ 目录（ls 核对存在）。

4.3 write / read：写入与读取

# 写入字节内容
op.write('hello.txt', b'Hello OpenDAL')

# 读回原始字节
data = op.read('hello.txt')

实测回显（打印 repr）：

read('hello.txt') -> b'Hello OpenDAL'

write 接收字节串、read 返回字节对象；文本内容读取后用 data.decode('utf-8') 转换。

4.4 stat：查询元数据

st = op.stat('hello.txt')
print("stat('hello.txt') -> mode={}, size={}, last_modified={}".format(
    st.mode, st.content_length, st.last_modified))

实测回显：

stat('hello.txt') -> mode=EntryMode.File, size=13, last_modified=2026-10-11 11:21:45.391546+00:00
元数据含义（实测）
st.mode条目类型，文件为 EntryMode.File
st.content_length文件大小（字节），实测 13 与磁盘字节数一致
st.last_modified最后修改时间（UTC 时区 +00:00）

4.5 list：列出条目

# 列出根目录第一层条目
entries = op.list('')
print("list('') ->", [e.name for e in entries])

# 子目录写入并列出
op.write('subdir/nested.txt', b'nested content')
print("list('subdir/') ->", [e.name for e in op.list('subdir/')])

实测回显：

list('') -> ['/', 'hello.txt', 'subdir/']
list('subdir/') -> ['subdir/', 'nested.txt']
  • '/' 为根标记；目录名带尾部斜杠（如 subdir/），用于区分文件与目录。
  • e.name 取条目名；list 只列出第一层条目。

五、storage schemes 支持矩阵

Scheme后端说明
fs本地文件系统本文实测使用
s3AWS S3 / 兼容对象存储常用
oss阿里云对象存储 OSS
gcsGoogle Cloud Storage
azblobAzure Blob StorageAzure 别名 azure
cos腾讯云 COS
hdfsHadoop HDFS
webdav / http / ftp / sftp网络文件协议
memory进程内内存测试用
sqlite / rocksdb / sled 等各类嵌入式存储

⚠️ 注意：本文所有实测基于 fs scheme；其余 scheme 为官方支持矩阵口径，未在实测环境覆盖，接入前需准备对应服务的连接参数。

六、完整最小示例与实测回显

把上述 API 串成完整演示脚本 /tmp/opendal_demo.py：

import opendal

op = opendal.Operator('fs', root='/tmp/opendal-demo')

# 建目录（fs 下 create_dir 真实创建目录）
op.create_dir('subdir/')
print("create_dir('subdir/') OK")

# 写文件
op.write('hello.txt', b'Hello OpenDAL')
print("write('hello.txt', b'Hello OpenDAL') OK")

# 读文件
data = op.read('hello.txt')
print("read('hello.txt') ->", repr(data))

# stat
st = op.stat('hello.txt')
print("stat('hello.txt') -> mode={}, size={}, last_modified={}".format(
    st.mode, st.content_length, st.last_modified))

# list 根目录
entries = op.list('')
print("list('') ->", [e.name for e in entries])

# 子目录写入并列出
op.write('subdir/nested.txt', b'nested content')
print("list('subdir/') ->", [e.name for e in op.list('subdir/')])

# 运行演示脚本
python3 /tmp/opendal_demo.py

实测回显（Python 3.10.12 + opendal 0.47.10）：

create_dir('subdir/') OK
write('hello.txt', b'Hello OpenDAL') OK
read('hello.txt') -> b'Hello OpenDAL'
stat('hello.txt') -> mode=EntryMode.File, size=13, last_modified=2026-10-11 11:21:45.391546+00:00
list('') -> ['/', 'hello.txt', 'subdir/']
list('subdir/') -> ['subdir/', 'nested.txt']

磁盘侧核对（ls -laR /tmp/opendal-demo）：hello.txt 13 字节、subdir/nested.txt 14 字节，与 API 读写的字节数完全一致。

七、注意事项

⚠️ 注意：

  1. OpenDAL 没有命令行工具，所有操作通过代码调用绑定 API 完成。
  2. read 返回字节对象、write 接收字节串；文本需自行 decode('utf-8')。
  3. list 只列出第一层条目，根标记 '/' 与目录尾部斜杠属正常形态。
  4. 三生态版本不同步（Rust 0.59.4 / Python 0.47.10 / Java 0.46.4），按所用生态选版本。

八、常见问题

Q1：OpenDAL 有 CLI 吗？ 没有独立命令行工具，统一通过 Operator / AsyncOperator API 访问数据。

Q2：import opendal 报 ModuleNotFoundError？ 未安装或 Python 版本低于 3.10。执行 pip3 install opendal 安装；若报 No matching distribution found，先把 Python 升级到 3.10 及以上。

Q3：stat 的 size 与磁盘大小对不上？ size 单位是字节；核对时用 ls -l 的字节数列（而非 ls -lh 的人类可读值）对比。本次实测 size=13 与磁盘 13 字节一致。

Q4：想换后端存储需要改很多代码吗？ 只需更换构建 Operator 时的 scheme 与对应连接参数，write / read / stat / list 等 API 调用保持不变。

九、参考链接