binrw 是一个针对二进制文件格式的（反）序列化库。不同于 serde 等其他的序列化库 —— serde 关注的是如何更轻松准确地把 Rust structs 映射为 serde 的内部数据模型，而序列化和反序列化这一步（即从 serde 的数据模型到文件格式的映射）需要自行编写后端，当然通用格式的后端基本都是有的，比如 JSON 和 XML。而 binrw 的针对的恰好是序列化/反序列化这一步：它能够让你更轻松地表达 Rust struct 与二进制文件格式里每个字节之间的映射关系，而无需手工编写 Serializer/Deserializer。

我一开始试图找过类似的库，也许是关键词不对、或者是看的不仔细而错过了，导致没有 binrw 可用的时候，我只能手写反序列化代码，比如：

pub fn read_pol(reader: &mut dyn Read) -> Result<PolFile, Box<dyn Error>> {
    let mut magic = [0u8; 4];

    // 读取四字节 magic number
    reader.read_exact(&mut magic)?;

    match magic {
        [0x50, 0x4f, 0x4c, 0x59] => (), // "POLY"
        _ => panic!("Not a valid pol file"),
    }

    // 序列化、反序列化时需要注意字节序
    let some_flag = reader.read_u32::<LittleEndian>()?;
    let mesh_count = reader.read_u32::<LittleEndian>()?;
    let mut geom_node_descs = vec![];

    // 读进一个数组
    for _i in 0..mesh_count {
        let unknown = reader.read_w_vec(26)?;
        geom_node_descs.push(GeomNodeDesc { unknown });
    }

    let mut unknown_count = 0;
    let mut unknown_data = vec![];
    if some_flag > 100 {
        // 只有版本大于某个值时才会有这部分数据
    }

    let mut meshes = vec![];
    for _i in 0..mesh_count {
        meshes.push(read_pol_mesh(reader)?);
    }

    Ok(...)
}

一开始对于我来说倒是问题不大，一是文件格式有限，几种格式写个遍也还好；再就是这些格式的含义都是逆向分析得出的，本身搞清楚他们的意思就很慢，写反序列化代码这部分暂时算不上瓶颈。

到了后来，问题的重要性才开始提高：

1. 项目预计的领域扩大了。现在不光需要解析读取仙剑三的各类文件，还需要读仙剑四、五、轩辕剑、古剑等诸多游戏的各类文件，每个文件类型都手写一下，会很难受。
2. 现在只写了反序列化的代码，序列化代码需要再写一份。
3. 代码不够简洁。现在的代码其实还算清晰、复杂度也不高，但是 boilerplate 很多，维护起来虽不费劲但也有一些成本。文件格式增多会加重这一点。

直到解析古剑奇谭的 GameBryo NIF 格式的模型时，又去网上冲浪了一圈，果然被我找到了 binrw。有了 binrw，我就可以这样说话了：

#[binrw]
#[brw(little)]
#[derive(Debug)]
pub struct NiObjectNET {
    name: u32,
    num_extra_data: u32,

    #[br(count = num_extra_data)]
    extra_data: Vec<u32>,

    controller: u32,
}

首先是指定字节序这件事，用 [brw(little)] 就可以了。数组也不在话下，可以直接指定结构体里的成员作为数组长度。再比如：

#[binrw]
#[brw(little)]
#[derive(Debug, Serialize)]
pub struct HAnimPlugin {
    pub header: HAnimHeader,

    #[br(if(header.bone_count > 0))]
    pub unknown: Option<HAnimUnknown>,

    #[br(count = header.bone_count)]
    pub bones: Vec<HAnimBone>,
}

可选字段也可以轻松应对—— 只有在 bone_count > 0 的时候，二进制文件中才会有一段区域描述这个 unknown 结构，否则会直接进入 bones 字段的内容。再如：

#[binrw]
#[brw(little)]
#[brw(import{half_float: bool = false})]
#[derive(Debug, Serialize)]
pub struct Vec3f {
    #[br(parse_with = float_parser)]
    #[br(args(half_float))]
    pub x: f32,

    #[br(parse_with = float_parser)]
    #[br(args(half_float))]
    pub y: f32,

    #[br(parse_with = float_parser)]
    #[br(args(half_float))]
    pub z: f32,
}

一个坐标点，里面维度的数值可能是 f32，也可能是 f16。解析每个 field 时可以指定一个自定义的解析函数，同时支持传入一些参数。在这个例子中，传给 float_parser 的参数 half_float 本身是这个结构体的序列化参数，由 #[brw(import{half_float: bool = false})] 指定。使用这个 Vec3f 时，可以在外部传入这个参数：

#[binread]
#[brw(little)]
#[br(import(kf_type: u32))]
#[derive(Debug, Serialize)]
pub struct AnmKeyFrame {
    pub ts: f32,

    #[br(args{half_float: kf_type == 2})]
    pub rot: Vec4f,

    #[br(args{half_float: kf_type == 2})]
    pub pos: Vec3f,

    pub pref_frame_off: u32,

    #[br(if(kf_type == 2))]
    pub kf_offset: Option<Vec3f>,

    #[br(if(kf_type == 2))]
    pub kf_offset_scalar: Option<Vec3f>,
}

每个 binrw 了的结构体会自动生成 read、write 函数，可以直接调用进行反序列化/序列化：

NifModel::read(&mut Cursor::new(...))

现在除了一些 corner case，几乎不需要再手写任何序列化代码了。描述序列化的各种参数都跟字段本身放在一起，一眼望过去就大概知道文件格式是什么样的，序列化/反序列化时做了什么事情，查错维护很方便。

总之世界简洁了不少，绝对算得上相见恨晚。现在已经离不开了。