Apache OpenDAL 将 Append 并入 Write 的设计与实现：RFC-2758 全解析

数据存储后端【免费下载链接】opendalApache OpenDAL: One Layer, All Storage.项目地址https://gitcode.com/gh_mirrors/op/opendal点击查看免费下载Apache OpenDAL 曾经用writer和appender两套独立 API 分别处理“覆盖写”与“追加写”。本文基于仓库中的设计文档 RFC-2758: merge_append_into_write讲解这项 API 合并提案的动机、目标形态与参考实现并结合当前仓库源码OpWrite、WriteOptions、CorrectnessCheckLayer、AppendWrite等还原该提案落地后的实际调用链与行为契约帮助你理解 OpenDAL 追加写append从 API 到服务端的完整实现路径。一、背景为什么需要合并 appender 与 writerOpenDAL 的写能力最初由writer提供基于 multipart分片上传语义数据在close()返回Ok之前对外不可读且文件关闭后无法再追加。为解决这两个限制仓库中保留了前序提案 RFC-2133: append_api引入独立的appenderAPIasync fn append_test(op: Operation) - Result() { // create writer let append op.append(path_to_file).await?; let bs read_from_file(); append.append(bs).await?; let bs read_from_another_file(); append.append(bs).await?; // close the file append.close().await?; }RFC-2133 对两种操作的语义区分是write总是创建新文件在close之前不可读append可以向已存在的 appendable 文件追加每次append返回后即可读。但双 API 并存带来维护成本。RFC-2758 的 Motivation 部分指出两套 API 迫使使用者为“写数据”学习两份接口。合并后可以更小的 API 面——使用者只需要学习一套写 API减少 append 与 write 两套实现之间的代码重复原子追加语义由writer内部处理sinkAPI 可复用于overwrite与append两种模式参见 RFC-2083: writer sink API。提案名称为merge_append_into_write起始日期 2023-08-02。其核心一句话摘要为通过引入writer_with.append(true)方法将appenderAPI 合并进writer。二、Guide 级合并后的追加写用法RFC-2758 给出的目标形态是不再存在独立的appenderAPI直接在 writer 上开启追加模式let mut writer op.writer_with(file.txt).append(true).await?; writer.write(bs).await?; // appends to file writer.write(bs).await?; // appends again调用writer_with.append(true)后 writer 进入 append 模式后续write()全部变为追加而非覆盖。该形态在当前仓库中已经落地。Writer 的文档注释 明确给出了启用追加的用法与语义契约/// ### Write with append enabled /// /// Writer also supports to write with append enabled. This is useful when users want to append /// some data to the end of the file. /// /// - If file doesnt exist, it will be created and just like calling write. /// - If file exists, data will be appended to the end of the file. /// /// Possible Errors: /// /// - Some services store normal file and appendable file in different way. Trying to append /// on non-appendable file could return [ErrorKind::Conflict] error. /// - Services that doesnt support append will return [ErrorKind::Unsupported] error when /// creating writer with append enabled.对应 FutureWriter::append 的实现 及其文档示例/// [Operator::writer_with] returns this future. pub type FutureWriterF OperatorFutureoptions::WriteOptions, Writer, F; implF: FutureOutput ResultWriter FutureWriterF { /// Sets append mode for this write request. /// /// /// # async fn test(op: Operator) - Result() { /// let mut w op.writer_with(path/to/file).append(true).await?; /// w.write(vec![0; 4096]).await?; /// w.write(vec![1; 4096]).await?; /// w.close().await?; /// # Ok(()) /// # } /// pub fn append(mut self, v: bool) - Self { self.args.append v; self } // ... }同样的append(bool)方法也定义在一把梭式写入的FutureWrite上operator_futures.rs使op.write_with(path, data).append(true).await?与op.writer_with(path).append(true)两种写法行为一致——这正是 RFC 中“write 与 writer 遵循同一规则”的体现。语义上有三个要点均来自Writer文档与WriteOptions注释options.rs文件不存在时追加写等价于普通write文件会被创建文件存在时数据追加到文件末尾部分服务对普通文件与 appendable 文件采用不同的存储方式向“不可追加”的文件追加可能返回ErrorKind::Conflict服务本身不支持 append 时在创建 writer 阶段就返回ErrorKind::Unsupported。三、Reference 级OpWrite中的append标志RFC-2758 的参考级设计是向OpWrite增加一个append标志所有服务需检查该标志并相应处理 append 模式不支持 append 的服务应当返回Unsupported错误。提案原文impl OpWrite { pub fn with_append(mut self, append: bool) - Self { self.append append; self } }当前仓库的实现在细节上更紧凑append没有单独占一个字段而是以位标志bit flag形式编码进OpWrite。在 raw/ops.rs 中const OP_WRITE_APPEND: u8 1; // ... let mut flags 0; if options.append { flags | OP_WRITE_APPEND; } // ... /// Get the append from op. /// /// The append is the flag to indicate that this write operation is an append operation. #[inline] pub fn append(self) - bool { self.flags OP_WRITE_APPEND ! 0 }也就是说用户层的WriteOptions.append: bool定义在 types/options.rs在构建OpWrite时被折叠进flags位域服务端通过args.append()读取该标志。这种位标志设计让OpWrite能同时承载append、if_not_exists等多个布尔条件而不增加结构体体积。WriteOptions::append的注释把 RFC 中“检查 capability、不支持则报错”的约定固化成了文档契约/// Sets append mode for this operation. /// /// ### Capability /// /// Check [crate::Capability::write_can_append] before using this option. /// /// ### Behavior /// /// - By default, write operations overwrite existing files /// - When append is set to true: /// - New data will be appended to the end of existing file /// - If file doesnt exist, it will be created /// - If not supported, will return an error pub append: bool,其中write_can_append是 Capability 结构体 中的公开字段每个服务在注册时声明自己是否支持追加写。四、Capability 兜底CorrectnessCheckLayer 如何保证“不支持即报错”RFC 要求“服务不支持 append 时应返回Unsupported错误”但把这条契约交给每个服务各自实现并不可靠。OpenDAL 的做法是由一个默认套用的层来统一执行CorrectnessCheckLayer。该层的文档注释直接点明了 append 场景for example, when callingwrite_with_append, butappendis not supported by the underlying service, anUnsupportederror is returned. without this check, undesired data may be written.具体校验逻辑在check_write_args中correctness_check.rsfn check_write_args(self, args: OpWrite) - Result() { let capability self.capability(); let scheme self.info().scheme(); if args.append() !capability.write_can_append { return Err(new_unsupported_error(scheme, Operation::Write, append)); } // ... if_not_exists / if_match / if_none_match 等条件同样在此统一校验 Ok(()) }Service::write与Service::presign其中PresignOperation::Write分支都会先经过该校验。这意味着即使某个服务实现忘记处理append标志CorrectnessCheckLayer也会拦截避免数据被错误地覆盖写入——这正是 RFC 所强调的“原子追加语义由内部正确处理”的防御性兜底该检查对每个服务默认生效使用者无需手动挂载capability 也可通过 capability_override 层 以write_can_appendtrue这类配置串进行覆盖该文件中的测试用此配置验证了覆盖行为。层内自带的单测test_write_withcorrectness_check.rs完整验证了这条契约在write_can_append: false的 mock 服务上执行op.write_with(path, ).append(true).await得到ErrorKind::Unsupported而在write_can_append: true的服务上执行op.writer_with(path).append(true).await则成功创建 writer。五、服务端实现AppendWrite把原生追加适配成oio::Write对原生支持追加对象如对象存储的 appendable object的服务仓库提供了 AppendWrite 适配层服务只需实现AppendWritetrait即可获得符合oio::Write接口的AppendWriter。/// AppendWrite is used to implement [oio::Write] based on append /// object. By implementing AppendWrite, services dont need to /// care about the details of buffering and uploading parts. /// /// The layout after adopting [AppendWrite]: /// /// - Services impl AppendWrite /// - AppendWriter impl Write /// - Expose AppendWriter as Service::Writer pub trait AppendWrite: Send Sync Unpin static { /// Get the current offset of the append object. /// /// Returns 0 if the object is not exist. fn offset(self) - impl FutureOutput Resultu64 MaybeSend; /// Append the data to the end of this object. fn append( self, offset: u64, size: u64, body: Buffer, ) - impl FutureOutput ResultMetadata MaybeSend; }AppendWriter内部维护一个offset状态机首次write时调用inner.offset()获取当前追加偏移对象不存在时返回 0成功追加后把offset推进size字节close()时返回的文件大小为最终偏移。从源码结构看这正是把“追加对象必须带正确 offset 提交”这一服务端细节收敛到适配层使上层Writer的write/close/abort语义与覆盖写完全同构——对应 RFC 中“Reuse thesinkapi for bothoverwriteandappendmode”的目标。AppendWriter::abort直接返回Ok(())从源码结构看追加写没有 multipart 那样的分片资源需要清理这一简化也是合并 API 后“减少重复实现”收益的体现。六、升级迁移从appender到writer.append(true)该 RFC 在 v0.40 版本正式落地upgrade 指南 对迁移路径给出明确说明条目标题写作 “RFC-2578 Merge Append Into Write”链接指向rfc_2758_merge_append_into_write模块RFC-2578 mergesappendintowriteand removesappendAPI.For writing a file at once, please useop.write()for convenience.For appending a file, please useop.write_with().append(true)instead ofop.append().The same rule applies towriter()andwriter_with().迁移前后对照如下场景迁移前appender API迁移后writer append流式追加op.append(path).await?appender.append(bs)op.writer_with(path).append(true).await?writer.write(bs)一次性追加先建 appender 再 appendop.write_with(path, data).append(true).await?该 RFC 在 rustdoc 中通过 docs/rfcs/mod.rs 以rfc_2758_merge_append_into_write模块对外暴露可与rfc_2133_append_api、rfc_2083_writer_sink_api等相邻提案一起阅读理解 append 能力从“引入2133”到“并入 write2758”的完整演进。七、行为测试对 append 语义的验证仓库的行为测试框架把 append 相关用例纳入 tests/behavior/async_write.rs且只在服务声明相应能力时才执行if cap.read cap.write cap.write_can_append cap.stat { // test_write_with_append, // test_write_with_append_returns_metadata, // test_writer_with_append }其中test_write_with_append验证“首次 append 创建文件必须成功、向已存在文件再次 append 必须成功”两条核心断言test_writer_with_append则验证writer_with(...).append(true)路径。从源码结构看这种“按 capability 门控”的策略与第四节的CorrectnessCheckLayer形成呼应能力声明、运行期校验、测试门控三者使用同一个write_can_append事实来源。八、代价与取舍DrawbacksRFC 对合并带来的代价也有坦诚陈述writerAPI 因 append 模式标志而变得更复杂——writer 现在需要同时承载覆盖与追加两条逻辑分支内部实现必须同时处理 overwrite 与 append 两种语义。这些代价换来了 API 面的收敛使用者面对的是统一的write/writer接口族追加只是其中一个布尔选项而正确性风险向不支持 append 的服务误发 append 请求则由CorrectnessCheckLayer的强制校验和write_can_append能力声明共同兜底返回明确的ErrorKind::Unsupported而非静默错写。小结2758_merge_append_into_write 是 OpenDAL 写 API 演进中的关键一步它把 RFC-2133 引入的独立appender收编为write的一个标志位使“追加”成为统一写接口的一个模式而不是第二套 API。在当前仓库中可以完整追踪这条设计线索——用户层的FutureWriter::append与FutureWrite::append写入WriteOptions::append经OpWrite的 flags 位 下传至服务CorrectnessCheckLayer依据Capability::write_can_append强制拦截不支持的场景支持原生追加的服务则通过AppendWrite/AppendWriter把追加对象适配为标准oio::Write。如果你要在自己的服务上实现或消费追加写能力建议按“能力声明 → 正确性校验 → 服务端 offset 管理”这条链路阅读上述源码。赞分享数据存储后端【免费下载链接】opendalApache OpenDAL: One Layer, All Storage.项目地址https://gitcode.com/gh_mirrors/op/opendal点击查看免费下载相关推荐Apache OpenDAL 中 RFC-5556write 操作返回 Metadata 的设计与实现解析Apache OpenDAL 中 RFC 5556write 操作返回 Metadata 的设计与实现解析 在 Apache OpenDAL 中一次写入操作数据存储后端Apache OpenDAL Append API 设计剖析从 RFC 2133 提案到可追加剧写实现Apache OpenDAL Append API 设计剖析从 RFC 2133 提案到可追加剧写实现 本篇技术指南以 Apache OpenDAL 的 ap数据存储后端Apache OpenDAL 的 Multipart 上传设计与实现从 RFC 0438 到并发写入架构Apache OpenDAL 的 Multipart 上传设计与实现从 RFC 0438 到并发写入架构 导读 本文以 OpenDAL 设计文档 core/数据存储后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考