Project Anni 之旅（2）ValueAfterTable——toml-rs的实现与限制

Published: at 15:25

ToC

前言

大家好，好久不见，我是某昨。

最近将 Anni 的元数据仓库标准更新到 1.1 时出现了问题。在 1.1 的标准中，date 字段可以通过指定 year、month 和 day 表示相对模糊的专辑发售日期：

1
[album]
2
date = { year = 2021, month = 10 }

对反序列化而言，一切都没有问题，但在序列化的时候，问题出现了：

1
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: ValueAfterTable', anni-repo/src/album.rs:52:32
2
stack backtrace:
3
   0: rust_begin_unwind
4
             at /rustc/a178d0322ce20e33eac124758e837cbd80a6f633/library/std/src/panicking.rs:515:5
5
   1: core::panicking::panic_fmt
6
             at /rustc/a178d0322ce20e33eac124758e837cbd80a6f633/library/core/src/panicking.rs:92:14
7
   2: core::result::unwrap_failed
8
             at /rustc/a178d0322ce20e33eac124758e837cbd80a6f633/library/core/src/result.rs:1355:5
9
   3: anni_repo::manager::RepositoryManager::add_album
10
   4: <anni::subcommands::repo::RepoAction as anni_clap_handler::traits::Handler>::execute
11
   5: anni_clap_handler::traits::Handler::execute
12
   6: anni_clap_handler::traits::Handler::run
13
   7: <core::future::from_generator::GenFuture<T> as core::future::future::Future>::poll
14
   8: tokio::runtime::enter::Enter::block_on
15
   9: tokio::runtime::Runtime::block_on
16
  10: anni::main
17
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

可以看到，抛出的 Error 是 ValueAfterTable。以 ValueAfterTable 为关键词搜索，在 GitHub 上有一大堆：

那这个问题是怎么出现，又是为什么会出现呢？本期走近科学将会……

了解 TOML

想要知道 toml-rs 的问题所在，就必须了解 TOML 本身。TOML 是一门非常适合作为配置文件的语言，相比 JSON 等序列化方案的可读性要高上不少。TOML 中最复杂的结构就是 Table 了，类似 JSON 中的 Object，用于描述嵌套的层级关系。TOML 的 Table 有好几种写法：

1
# 最基本的写法
2
# { "table1": { "key": "value" } }
3
[table1]
4
key = "value"
5


6
# 简单的嵌套
7
# { "table1": { "table2": { "key": "value" } } }
8
[table1.table2]
9
key = "value"
10


11
# 在字段名上嵌套
12
table1.key = "value"
13


14
# 内联
15
table1 = { key = "value" }

问题所在

上述的这四种表示方法都可以用来表示 Table，这赋予了 TOML 更高的可读性，但同时也限制了 toml-rs 的发挥。试想以下场景：

1
[table]
2
one = 1
3
inner = { key = 2 }
4
another = 3

反序列化之后，我们得到了对应的 struct，但隐含在 inner 中的信息却丢失了——inner 应该是一个内联 Table。在序列化时，我们不知道 inner 是内联 Table 这一关键信息，尝试将所有的 Table 都序列化成：

1
[table]
2
one = 1
3
[table.inner]
4
key = 2
5
another = 3 #???

不难发现，another = 3 现在被分在了 [table.inner] 下，而非 [table] 下，实际的结构完全错了。这也是 toml 选择限制 table 字段必须在最后序列化的原因所在了。

如何解决？

解决这个问题有三种方案：

  1. 调整字段的顺序，让嵌套的 Table 在最后序列化
  2. 实现支持内联 Table
  3. 抛弃 serde

第一种方案是最简单的，但在这意味着字段的顺序需要改变；第二种解决方案最彻底，但需要 toml-rs 对现有架构做一定变动；第三种方案最激进，但抛弃 serde 意味着对原文件结构有着更深的了解，并且能够支持一些类似运行时的特性。

而对于 Anni——我选择把 struct 换成 string（逃