Apache OpenDAL 0.47.10 构建并运行示例应用指南

目标：从零构建并运行一个基于 Apache OpenDAL 0.47.10 Python 绑定的最小数据访问应用（SDK 使用示例）。给出完整示例源码、运行命令及真实回显，覆盖 create_dir、write、read、stat、list 五类操作：stat 报告 size=13 与磁盘 13 字节吻合。所有命令与输出均在 Ubuntu 22.04.5 LTS（Python 3.10.12）环境实测通过。

一、环境信息

💡 说明：OpenDAL 核心用 Rust 实现，对外提供 Python / Java / Rust 等多语言绑定；本文示例采用 Python 绑定 0.47.10，通过 fs scheme 操作本地文件系统（/tmp/opendal-demo）。

二、前置条件

1. 已按《Ubuntu 22.04 安装 Apache OpenDAL 指南》安装 Python 3（≥ 3.10）与 opendal Python 绑定：

# 安装 opendal Python 绑定（自动拉取 0.47.10 预编译 wheel）
pip3 install opendal

# 验证版本号
python3 -c "import opendal; print(opendal.__version__)"

实测输出：0.47.10。

2. 创建演示数据目录：

mkdir -p /tmp/opendal-demo

三、示例脚本设计

示例脚本基于同一个 Operator 实例完成五类最常用的数据访问操作：

四、示例源码

使用任意编辑器创建 /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']

六、运行结果解读与磁盘核对

6.1 磁盘侧核对

fs scheme 底层即本地文件系统，直接查看磁盘与 API 结果完全一致：

# 递归列出演示目录
ls -laR /tmp/opendal-demo

实测回显：

/tmp/opendal-demo:
-rw-r--r-- 1 root root  13 Oct 11 11:21 hello.txt      # 13 字节 = b'Hello OpenDAL'
drwxr-xr-x 2 root root 4096 Oct 11 11:21 subdir
/tmp/opendal-demo/subdir:
-rw-r--r-- 1 root root  14 Oct 11 11:21 nested.txt      # 14 字节 = b'nested content'

6.2 结果解读

• stat 元数据：mode=EntryMode.File 表示普通文件；size=13 与磁盘 hello.txt 的 13 字节吻合；last_modified 为带 UTC 时区（+00:00）的最后修改时间。
• list 语义：list('') 返回根标记 '/'、文件项 hello.txt 与目录项 subdir/（目录名统一带尾部斜杠）；list('subdir/') 返回 subdir/ 自身与 nested.txt。
• read 返回 bytes：read('hello.txt') 返回原始字节对象 b'Hello OpenDAL'，需要文本时自行 decode('utf-8')。

七、注意事项

⚠️ 注意：

1. Python 绑定要求 requires_python >= 3.10，Python 3.9 及以下无法安装。
2. opendal.Operator('fs', root='/tmp/opendal-demo') 的 root 决定后续所有相对路径的基准，建议使用绝对路径（本示例即绝对路径 /tmp/opendal-demo）。
3. write 接收字节串（如 b'Hello OpenDAL'），read 返回字节对象，文件大小以字节计。
4. list('') 结果包含根标记 '/' 与带尾部斜杠的目录项，属正常行为。

八、常见问题

Q1：运行报 ModuleNotFoundError: No module named 'opendal'？ 绑定未安装或装在了其他 Python 环境。执行 pip3 install opendal 安装后，用 python3 -c "import opendal; print(opendal.__version__)" 确认版本为 0.47.10。

Q2：pip 安装报 No matching distribution found？ Python 版本低于 3.10。Python 绑定要求 requires_python >= 3.10，升级 Python 后重试。

Q3：list('') 结果里的 '/' 和带尾部斜杠的目录项是什么？ '/' 为根标记，目录名统一带尾部斜杠用于区分文件与目录，属正常行为；取目录名用 e.name，拼接子路径时先去掉尾部斜杠。

Q4：read 返回的是 b'Hello OpenDAL' 而不是字符串？ read 返回原始字节对象，文本内容需 data.decode('utf-8') 转换；写入时同样使用字节串。

九、参考链接

• OpenDAL 官网：https://opendal.apache.org/
• Python 绑定 PyPI 页：https://pypi.org/project/opendal/
• OpenDAL 文档：https://opendal.apache.org/docs/