Tony Bai - Part 53

Go语言开发者的Apache Arrow使用指南：数据类型

六月 25, 2023
2 条评论

本文永久链接 – https://tonybai.com/2023/06/25/a-guide-of-using-apache-arrow-for-gopher-part1

如果你不是做大数据分析的，提到Arrow这个词，你可能会以为我要聊聊那个箭牌卫浴或是箭牌口香糖(注：其实箭牌口香糖使用的单词并非Arrow)。其实我要聊的是Apache的一个顶级项目：Arrow。

为什么要聊这个项目呢？说来话长，主要是因为前段时间接触到的几个时序数据库开源项目，包括国外大名鼎鼎的InfluxDB(尤指其iox这个新存储引擎)以及国内一个新初创公司的开源项目greptimedb。它们其实是竞争对手，但他们有一个共同的特点，那就是时序数据在内存中的组织都是基于Arrow设计与实现的。

InfluxDB iox的主力开发者Andrew Lamb在他的一次技术分享中曾提到这样一个观点：

如果你在编码实现一个分析型数据库系统，那么你最终将实现Arrow的功能集合。

在上述公司技术人员的眼中，Arrow是构建下一代时序数据库引擎的核心技术之一。

Arrow内容很多，不是一篇文章可以聊完的，因此我计划了一个系列的文章，争取能覆盖到Arrow项目的核心部分的内容，这里是第一篇。

注：Arrow是语言无关的，但这里所有代码示例使用的都是Go语言^_^。

1. Arrow项目简介

按照Arrow项目官方的说法：“Apache Arrow是一个用于内存分析的开发平台。它包含一组技术，这些技术可以使大数据系统能够快速处理和移动数据。它为平面和分层数据指定了一种标准化的独立于语言的列式内存格式，其组织形式为现代硬件上的数据的高效分析操作做了充分考虑”。

简单诠释一下上面这段话：

Apache Arrow编写了一套编程语言无关的内存格式规范(当前版本为v1.3)，这是一种列式存储的格式，基于这种格式可以实现高压缩比的数据的压缩存储、高效的性能分析操作以及无需序列化和反序列化的低开销数据传输。

下图是展示了Arrow的列式存储格式。最上面的是一个逻辑表，这个表有三个列：ARCHER、LOCATION和YEAR，左下角是使用行式存储实现逻辑表的内存存储方式，而右下角则是Arrow的方案，即采用列式存储格式实现逻辑表的方式：

注：上图由来自《In-Memory Analytics with Apache Arrow》书中的几幅图拼接而成。

一套规范，大家共尊，这样数据传递和处理时，无需序列化和反序列化

注：上图同样由来自《In-Memory Analytics with Apache Arrow》书中的2幅图拼接而成。

多种主流语言的实现

下面是Arrow项目的各个编程语言的实现和支持矩阵情况：

我们看到，目前C++、Java、Go和Rust等对Arrow的支持较为全面。

通信传输与磁盘存储

Arrow的子项目Arrow Flight RPC为使用Arrow内存格式的系统提供了标准的通信传输方式。

Apache的另外一个顶级项目Parquet则经常被用作Arrow数据的磁盘存储格式，InfluxDB iox项目也是将内存中的Arrow格式数据转换为Parquet后存储在对象存储中的。

了解了Arrow项目的大致情况后，我们接下来再来看看Arrow项目的核心规范：Arrow Columnar Format。

2. Arrow Columnar Format规范

很多人最厌恶读所谓的“规范”了，太抽象，太概念化了，啃起来很烧脑。很不巧，Arrow Columnar Format规范也归属在这一类规范中。

不过，再难啃也得啃。如果不了解规范中的术语和概念，后面我们很可能就走不下去了。好在我们有《In-Memory Analytics with Apache Arrow》的帮助，算是有了抓手，将书与规范结合在一起看，略微降低一些理解上的难度。

Arrow的列式格式有一些关键特性，这里引述一下：

顺序访问(扫描)的数据邻接性
O(1)（恒定时间）随机访问
对SIMD和矢量化友好
可重新定位，没有”指针摆动”，允许在共享内存中实现真正的零拷贝访问

这些关键特性都在告诉我们Arrow具备一个优点：快！这也是为什么influxdb iox引擎使用Arrow作为数据在内存中组织形式的原因，Andrew Lamb在他的分享中给出了Rust使用Arrow和不使用Arrow的性能对比：

我们看到基于Arrow的实现比原生Rust实现还要快很多！

前面说过：Arrow是列式存储格式，它的核心型态就是Array。

Array是已知长度的同构类型值的序列，Array中一个值称为一个slot：

规范同时定义了承载Array的内存表示(physical layout)，通常一个Array的内存表示由多个buffer构成，每个buffer实际上就是一个固定长度的连续内存区域：

Array支持嵌套，像List\<U>就是一个嵌套类型(Nested type)，而List\<U>称为parent array类型，而U则称为child array type。如果一个Array不是嵌套类型，那么称之为Primitive type。

要真正了解Arrow，就要了解每个Array type的physical layout，一个array type也被称为一个logical type。Arrow定义了多种logical type，它们拥有不同的physical layout，当然也可以拥有相同的physical layout。相同physical layout的logical type可以划为一类，按layout type进行分类，我们能得到下面这张表(摘自《In-Memory Analytics with Apache Arrow》一书)：

我们看到不同layout中有一些buffer并非用来存储data，比如多数layout的buffer0存储的是一个bitmap，有的buffer1存储的是offset，这些非data的信息被称为metadata。实际上，一个array是由一些metadata和真正的data组合而成的。

下面我们逐个来看看这些layout不同的Arrow array类型。

3. 数据类型

3.1 metadata

在介绍Arrow的array类型之前，我们简单说说metadata。

Arrow array有如下几个常见的属性是存放在metadata中的：

Array length：array中slot的数量，即array有几个元素，通常用64-bit signed integer表示；
Null count：null value slot的数量，同样也通常用64-bit signed integer表示；
Validity bitmaps：bitmap中的bit用来指示对应的array slot是否为null。并且arrow使用的是“小端bit序”，以一个字节(8bit)为一组，bitmap的最右侧bit指示的是array中第一个slot是否为null(未置位代表是null)，下面是一个示意图：

下面是用arrow的go包实现的上述示意图中的代码示例：

// bitmap_of_array.go
package main

import (
    "encoding/hex"
    "fmt"

    "github.com/apache/arrow/go/v13/arrow/array"
    "github.com/apache/arrow/go/v13/arrow/memory"
)

func main() {
    bldr := array.NewInt64Builder(memory.DefaultAllocator)
    defer bldr.Release()
    bldr.AppendValues([]int64{1, 2}, nil)
    bldr.AppendNull()
    bldr.AppendValues([]int64{4, 5, 6, 7, 8, 9, 10}, nil)
    arr := bldr.NewArray()
    defer arr.Release()
    bitmaps := arr.NullBitmapBytes()
    fmt.Println(hex.Dump(bitmaps)) // fb 03 00 00
    fmt.Println(arr)               // [1 2 (null) 4 5 6 7 8 9 10]
}

如果一个array没有null元素，那也可以省略bitmap。

看完metadata，我们接下来就来看一些arrow定义的array逻辑类型。

3.2 Null type

Null type并非null，它是一种无需真正分配内存的logical type，下面是arrow go实现中NullType的定义：

// NullType describes a degenerate array, with zero physical storage.
type NullType struct{}

我们知道struct{}不占用任何真实内存空间，NullType则“继承”了这点。

3.3 Primitive Type

Primitive type指的是slot元素类型相同且定长的arrow array type，从Go的源码中我们能找到如下这些Primitive Types:

var (
    PrimitiveTypes = struct {
        Int8    DataType
        Int16   DataType
        Int32   DataType
        Int64   DataType
        Uint8   DataType
        Uint16  DataType
        Uint32  DataType
        Uint64  DataType
        Float32 DataType
        Float64 DataType
        Date32  DataType
        Date64  DataType
    }{
        ... ...
    }
)

下面挑重点说说。

3.3.1 Boolean Type

Boolean Type不在上面的Primitive Types行列，但实质上，Boolean Type也属于PrimitiveType这一类。在Arrow中，Boolean array Type是使用bit对每一个slot进行存储的。我们来看一个例子：

// boolean_array_type.go
package main

import (
    "encoding/hex"
    "fmt"

    "github.com/apache/arrow/go/v13/arrow/array"
    "github.com/apache/arrow/go/v13/arrow/memory"
)

func main() {
    bldr := array.NewBooleanBuilder(memory.DefaultAllocator)
    defer bldr.Release()
    bldr.AppendValues([]bool{true, false}, nil)
    bldr.AppendNull()
    bldr.AppendValues([]bool{true, true, true, false, false, false, true}, nil)
    arr := bldr.NewArray()
    defer arr.Release()
    bitmaps := arr.NullBitmapBytes()
    fmt.Println(hex.Dump(bitmaps))
    bufs := arr.Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }
    fmt.Println(arr)
}

这个例子输出的结果如下：

$go run boolean_array_type.go
00000000  fb 03 00 00                                       |....|

00000000  fb 03 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  39 02 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |9...............|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

[true false (null) true true true false false false true]

输出结果的第一行是bitmap的部分。

后面两段则是构成boolean array的两个buffer的layout，我们看到第一个buffer存储的是bitmap，第二个buffer则是存储的是boolean data。

大家看到这个输出结果的第一感觉是：为什么用了这么多字节？我们数了一数，每个buffer用了64字节，这与arrow对buffer的对齐要求是分不开的，默认情况下，要求buffer按64字节对齐。

3.3.2 Integer types

arrow支持各种integer type作为primitive types，这里以int32为例：

// int32_array_type.go
func main() {
    bldr := array.NewInt32Builder(memory.DefaultAllocator)
    defer bldr.Release()
    bldr.AppendValues([]int32{1, 2}, nil)
    bldr.AppendNull()
    bldr.AppendValues([]int32{4, 5, 6, 7, 8, 9, 10}, nil)
    arr := bldr.NewArray()
    defer arr.Release()
    bitmaps := arr.NullBitmapBytes()
    fmt.Println(hex.Dump(bitmaps))
    bufs := arr.Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }
    fmt.Println(arr)
}

输出上述程序的执行结果：

$go run int32_array_type.go
00000000  fb 03 00 00                                       |....|

00000000  fb 03 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  01 00 00 00 02 00 00 00  00 00 00 00 04 00 00 00  |................|
00000010  05 00 00 00 06 00 00 00  07 00 00 00 08 00 00 00  |................|
00000020  09 00 00 00 0a 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

[1 2 (null) 4 5 6 7 8 9 10]

值得注意的是：data buffer中是以小端字节序存储的int32。

3.3.3 Float types

Go对arrow的实现支持float16、float32和float64三个精度的浮点数类型，下面以float32为例，看看其layout：

// float32_array_type.go
func main() {
    bldr := array.NewFloat32Builder(memory.DefaultAllocator)
    defer bldr.Release()
    bldr.AppendValues([]float32{1.0, 2.0}, nil)
    bldr.AppendNull()
    bldr.AppendValues([]float32{4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.1}, nil)
    arr := bldr.NewArray()
    defer arr.Release()
    bitmaps := arr.NullBitmapBytes()
    fmt.Println(hex.Dump(bitmaps))
    bufs := arr.Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }
    fmt.Println(arr)
}

输出上述程序的执行结果：

$go run float32_array_type.go
00000000  fb 03 00 00                                       |....|

00000000  fb 03 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  00 00 80 3f 00 00 00 40  00 00 00 00 00 00 80 40  |...?...@.......@|
00000010  00 00 a0 40 00 00 c0 40  00 00 e0 40 00 00 00 41  |...@...@...@...A|
00000020  00 00 10 41 9a 99 21 41  00 00 00 00 00 00 00 00  |...A..!A........|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

[1 2 (null) 4 5 6 7 8 9 10.1]

3.4 Variable-size Binary Type

Primitive Types的slot是定长类型的，针对变长类型slot，Arrow定义了Variable-size Binary Type。在前面的那张不同类型的layout表中我们看到Variable-size Binary Type除了有bitmap buffer、data buffer外，还有一个offset buffer。

下面我们就以最为典型的字符串(string) array为例，看看Variable-size Binary Type的layout是什么样子的：

// string_array_type.go

func main() {
    bldr := array.NewStringBuilder(memory.DefaultAllocator)
    defer bldr.Release()
    bldr.AppendValues([]string{"hello", "apache arrow"}, nil)
    arr := bldr.NewArray()
    defer arr.Release()
    bitmaps := arr.NullBitmapBytes()
    fmt.Println(hex.Dump(bitmaps))
    bufs := arr.Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }
    fmt.Println(arr)
}

运行该示例：

$go run string_array_type.go
00000000  03                                                |.|

00000000  03 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  00 00 00 00 05 00 00 00  11 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  68 65 6c 6c 6f 61 70 61  63 68 65 20 61 72 72 6f  |helloapache arro|
00000010  77 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |w...............|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

["hello" "apache arrow"]

我们看到Variable-size Binary Type使用了三个buffer，除了第一个bitmap buffer和最后的data buffer外，中间的那个是offset buffer。在offset buffer中，arrow使用一个整型数来指示每个slot的起始offset，这里将上面例子整理成一张示意图，大家可以看的更清晰一些：

3.5 Fixed-Size List type

在上面Primitive Types的基础上，arrow提供了“嵌套类型”，比如List type。list type分为两类，一类是Fixed-Size List type，另一类则是Variable-Size List type。我们先来看Fixed-Size List type。

顾名思义，Fixed-Size List type就是list的每个slot存储的都是类型相同且定长的值，可记作：FixedSizeList\<T>[N]。T可以是Primitive type或其他嵌套类型，N是T的长度。

下面是一个fixed-size list type的示例，这里的Fixed-Size List type可以表示为FixedSizeList\<Int32>[3]，即list中每个slot存储的都是一个[3]int32数组：

// fixed_list_array_type.go
func main() {
    const N = 3
    var (
        vs = [][N]int32{{0, 1, 2}, {3, 4, 5}, {6, 7, 8}, {9, -9, -8}}
    )

    lb := array.NewFixedSizeListBuilder(memory.DefaultAllocator, N, arrow.PrimitiveTypes.Int32)
    defer lb.Release()

    vb := lb.ValueBuilder().(*array.Int32Builder)
    vb.Reserve(len(vs))

    for _, v := range vs {
        lb.Append(true)
        vb.AppendValues(v[:], nil)
    }

    arr := lb.NewArray().(*array.FixedSizeList)
    defer arr.Release()
    bitmaps := arr.NullBitmapBytes()
    fmt.Println(hex.Dump(bitmaps))

    varr := arr.ListValues().(*array.Int32)
    bufs := varr.Data().Buffers()

    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }
    fmt.Println(arr)
}

我们不再像前面那样直接打印FixedSizeList的Buffer layout，我们仅输出FixedSizeList的bitmap buffer，其value的buffer需要获取到其values，然后通过values type的buffer输出。上述示例输出结果如下：

$go run fixed_list_array_type.go
00000000  0f 00 00 00                                       |....|

00000000  ff 0f 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  00 00 00 00 01 00 00 00  02 00 00 00 03 00 00 00  |................|
00000010  04 00 00 00 05 00 00 00  06 00 00 00 07 00 00 00  |................|
00000020  08 00 00 00 09 00 00 00  f7 ff ff ff f8 ff ff ff  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

[[0 1 2] [3 4 5] [6 7 8] [9 -9 -8]]

这里有两个bitmap，一个是FixedSizeList的，一个是其values类型的，其value类型就是一个定长的int32 primitive array type。大家也可以借助《In-Memory Analytics with Apache Arrow》书中的一幅示意图再深刻理解一下FixedSizeList的layout：

3.6 Variable-Size List type

有了FixedSizeList做铺垫，那么Variable-Size List type理解起来就容易了。和variable-size binary type一样，相较于FixedSizeList，Variable-Size List type在bitmap buffer基础上又多了一个offset buffer，我们看下面例子：

// variable_list_array_type.go

func main() {
    var (
        vs = [][]int32{{0, 1}, {2, 3, 4, 5}, {6}, {7, 8, 9}}
    )

    lb := array.NewListBuilder(memory.DefaultAllocator, arrow.PrimitiveTypes.Int32)
    defer lb.Release()

    vb := lb.ValueBuilder().(*array.Int32Builder)
    vb.Reserve(len(vs))

    for _, v := range vs {
        lb.Append(true)
        vb.AppendValues(v[:], nil)
    }

    arr := lb.NewArray().(*array.List)
    defer arr.Release()
    bitmaps := arr.NullBitmapBytes()
    fmt.Println(hex.Dump(bitmaps))
    bufs := arr.Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }

    varr := arr.ListValues().(*array.Int32)
    bufs = varr.Data().Buffers()

    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }
    fmt.Println(arr)
}

输出上述示例的运行结果：

$go run variable_list_array_type.go
00000000  0f 00 00 00                                       |....|

00000000  0f 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  00 00 00 00 02 00 00 00  06 00 00 00 07 00 00 00  |................|
00000010  0a 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  ff 03 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  00 00 00 00 01 00 00 00  02 00 00 00 03 00 00 00  |................|
00000010  04 00 00 00 05 00 00 00  06 00 00 00 07 00 00 00  |................|
00000020  08 00 00 00 09 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

[[0 1] [2 3 4 5] [6] [7 8 9]]

前两大块数据是Variable-Size List type的bitmap buffer和offset buffer。后两大段数据则是int32 array type的bitmap buffer和data buffer。Variable-Size List type的offset buffer有四个偏移量：0, 2, 6, 7，分别指向int32 array type的data buffer中的相应位置。

《In-Memory Analytics with Apache Arrow》书中的一幅示意图可以帮助我们理解Variable-size List的layout：

3.7 Struct type

struct也是一个嵌套类型，它可以包含多个field，而每个field又是一个arrow array type。struct的layout中包含bitmap buffer，之后就是各个field value buffer。每个field也都有自己的layout，具体layout是什么样子的需根据field的type而定。下面是一个示例，这个示例中的struct有两个field：name和age，name是一个String类型的array，而age则是int32类型的array：

// struct_array_type.go
func main() {
    fields := []arrow.Field{
        arrow.Field{Name: "name", Type: arrow.BinaryTypes.String},
        arrow.Field{Name: "age", Type: arrow.PrimitiveTypes.Int32},
    }
    structType := arrow.StructOf(fields...)
    sb := array.NewStructBuilder(memory.DefaultAllocator, structType)
    defer sb.Release()

    names := []string{"Alice", "Bob", "Charlie"}
    ages := []int32{25, 30, 35}
    valid := []bool{true, true, true}

    nameBuilder := sb.FieldBuilder(0).(*array.StringBuilder)
    ageBuilder := sb.FieldBuilder(1).(*array.Int32Builder)

    sb.Reserve(len(names))
    nameBuilder.Resize(len(names))
    ageBuilder.Resize(len(names))

    sb.AppendValues(valid)
    nameBuilder.AppendValues(names, valid)
    ageBuilder.AppendValues(ages, valid)

    arr := sb.NewArray().(*array.Struct)
    defer arr.Release()

    bitmaps := arr.NullBitmapBytes()
    fmt.Println(hex.Dump(bitmaps))
    bufs := arr.Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }

    nameArr := arr.Field(0).(*array.String)
    bufs = nameArr.Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }

    ageArr := arr.Field(1).(*array.Int32)
    bufs = ageArr.Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }

    fmt.Println(arr)
}

执行上述代码，我们将得到如下输出：

$go run struct_array_type.go
00000000  07 00 00 00                                       |....|

00000000  07 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  07 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  00 00 00 00 05 00 00 00  08 00 00 00 0f 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  41 6c 69 63 65 42 6f 62  43 68 61 72 6c 69 65 00  |AliceBobCharlie.|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  07 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  19 00 00 00 1e 00 00 00  23 00 00 00 00 00 00 00  |........#.......|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

{["Alice" "Bob" "Charlie"] [25 30 35]}

第一大块数据是struct的bitmap buffer，之后的三大块数据是name field的bitmap、offset和data buffer，最后两大块数据则是age field的bitmap和data buffer。

下面是那本书中的一个struct类型layout的示意图，可以帮助大家理解这个结构：

3.8 Union type

学过C语言的都知道union，名为联合体，说白了就是一堆类型共享一块内存，好比现代医学中的“多重人格”，能表现出哪种人格全由你来定。

Arrow的union array type就是每个slot中放置一个union类型的序列。Arrow的union array type还分为两种，一种为dense union type，一种是sparse union type。至于他们有什么区别，我们可以通过下面的两个示例直观的看到。union array type相对于上面的primitive type和list、struct这样的嵌套类型来说都相对难于理解一些。

我们先来看看dense union array type。

3.8.1 dense union array type

我们先看一个这样的union array: [{i32=5} {f32=1.2} {f32=\<nil>} {f32=3.4} {i32=6}]。我们看到这个union array实例有两种union type: float32和int32。其中float32有三个值：1.2、null和3.4；int32有两个值：5和6。我们编写go代码来构建一下这个union array：

// dense_union_array_type.go 

var (
    F32 arrow.UnionTypeCode = 7
    I32 arrow.UnionTypeCode = 13
)

func main() {

    childFloat32Bldr := array.NewFloat32Builder(memory.DefaultAllocator)
    childInt32Bldr := array.NewInt32Builder(memory.DefaultAllocator)

    defer func() {
        childFloat32Bldr.Release()
        childInt32Bldr.Release()
    }()

    ub := array.NewDenseUnionBuilderWithBuilders(memory.DefaultAllocator,
        arrow.DenseUnionOf([]arrow.Field{
            {Name: "f32", Type: arrow.PrimitiveTypes.Float32, Nullable: true},
            {Name: "i32", Type: arrow.PrimitiveTypes.Int32, Nullable: true},
        }, []arrow.UnionTypeCode{F32, I32}),
        []array.Builder{childFloat32Bldr, childInt32Bldr})
    defer ub.Release()

    ub.Append(I32)
    childInt32Bldr.Append(5)
    ub.Append(F32)
    childFloat32Bldr.Append(1.2)
    ub.AppendNull()
    ub.Append(F32)
    childFloat32Bldr.Append(3.4)
    ub.Append(I32)
    childInt32Bldr.Append(6)

    arr := ub.NewDenseUnionArray()
    defer arr.Release()

    // print type buffer
    buf := arr.TypeCodes().Buf()
    fmt.Println(hex.Dump(buf))

    // print offsets
    offsets := arr.RawValueOffsets()
    fmt.Println(offsets)
    fmt.Println()

    // print buffer of child array
    bufs := arr.Field(0).Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }

    bufs = arr.Field(1).Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }

    fmt.Println(arr)
}

我们看到union array的构建也是非常复杂的。按照前面的表格，dense union array type的layout中metadata占用两个buffer，第一个buffer是typeIds，第二个buffer则是offset。没有data buffer，真正的数据存储在child array的layout中。我们运行一下上面的示例直观看一下：

$go run dense_union_array_type.go
00000000  0d 07 07 07 0d 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

[0 0 1 2 1]

00000000  05 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  9a 99 99 3f 00 00 00 00  9a 99 59 40 00 00 00 00  |...?......Y@....|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  03 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  05 00 00 00 06 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

[{i32=5} {f32=1.2} {f32=<nil>} {f32=3.4} {i32=6}]

第一块数据是union typeid buffer，这里我们的union array type一共有两类子类型，我分为赋予他们的typeid为float32(0×07)和int32(0x0d)。union array type一共有5个slot(3个float32，2个int32)，typeids buffer这里用一个字节表示一个slot的类型，因此有3个07和2个0d。

下面输出的[0 0 1 2 1]则是一个offset buffer。表示同类type的value buffer的offset(一个offset值是一个4字节的int32)。以int32 slot为例，我们有两个int32 slot，分为位于总union array type 的第一个和第五个。但int32 slot是放在一起存储为int32 primitive array type的，因此union array type的第一个slot是int32 primitive array type的第一个slot，即其offset在int32 type中的偏移为0。而union array type的第5个slot是int32 primitive array type的第2个slot，即其offset在int32 type中的偏移为1。这就是[0 0 1 2 1]中第一个值为0和最后一个值为1的原因。依次类推，你可以算一下为何中间的三个值为0 1 2。

后面的四块数据则分别是float32 array type的buffer和int32 array type的buffer layout。我们用下图可以更直观地看到union array type的laytout：

3.8.2 sparse union array type

接下来，趁热打铁，我们再来看看sparse union array type。我们还以union array: [{i32=5} {f32=1.2} {f32=\<nil>} {f32=3.4} {i32=6}]为例，看看用sparse union array type来表示其layout是什么样子的。我们先用go构建出这个union array type：

// sparse_union_array_type.go

var (
    F32 arrow.UnionTypeCode = 7
    I32 arrow.UnionTypeCode = 13
)

func main() {
    childFloat32Bldr := array.NewFloat32Builder(memory.DefaultAllocator)
    childInt32Bldr := array.NewInt32Builder(memory.DefaultAllocator)

    defer func() {
        childFloat32Bldr.Release()
        childInt32Bldr.Release()
    }()

    ub := array.NewSparseUnionBuilderWithBuilders(memory.DefaultAllocator,
        arrow.SparseUnionOf([]arrow.Field{
            {Name: "f32", Type: arrow.PrimitiveTypes.Float32, Nullable: true},
            {Name: "i32", Type: arrow.PrimitiveTypes.Int32, Nullable: true},
        }, []arrow.UnionTypeCode{F32, I32}),
        []array.Builder{childFloat32Bldr, childInt32Bldr})
    defer ub.Release()

    ub.Append(I32)
    childInt32Bldr.Append(5)
    childFloat32Bldr.AppendEmptyValue()

    ub.Append(F32)
    childFloat32Bldr.Append(1.2)
    childInt32Bldr.AppendEmptyValue()

    ub.AppendNull()

    ub.Append(F32)
    childFloat32Bldr.Append(3.4)
    childInt32Bldr.AppendEmptyValue()

    ub.Append(I32)
    childInt32Bldr.Append(6)
    childFloat32Bldr.AppendEmptyValue()

    arr := ub.NewSparseUnionArray()
    defer arr.Release()

    // print type buffer
    buf := arr.TypeCodes().Buf()
    fmt.Println(hex.Dump(buf))

    // print child
    bufs := arr.Field(0).Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }

    bufs = arr.Field(1).Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }

    fmt.Println(arr)
}

和dense union type相比，sparse union type要求所有child type的length都要与union type相同。这就是上述代码为什么在append一个float32后，还要append一个emtpy的int32的原因。下面是上述程序的执行结果：

$go run sparse_union_array_type.go

00000000  0d 07 07 07 0d 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  1b 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  00 00 00 00 9a 99 99 3f  00 00 00 00 9a 99 59 40  |.......?......Y@|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  1f 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  05 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  06 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

[{i32=5} {f32=1.2} {f32=<nil>} {f32=3.4} {i32=6}]

同样，我们用一幅示意图可以直观的展现上述结果：

到这里，我们可以简单对比一下dense和sparse union了。显然sparse由于特殊的要求，它实际占用的内存空间会更大。

那么sparse union type用在何种场景呢？按《In Memory Analytics With Apache Arrow》书中的说法，sparse union更容易与矢量表达式求值(vectorized expression evaluation)一起使用。

3.9 Dictionary-encoded type

最后说说字典编码类型。如果现在我们要存储一组字符串，这组字符串中存在重复的值，比如：["foo", "bar", "foo", "bar", null, "baz"]，若使用之前提到variable-size binary type来表示，相同的字符串不会只存储一份，而是分别存储。

针对这样的问题，Arrow提供了采用dictionary-encode的array type，在这种type下重复的字符串只会存储一份。我们看一个示例：

// dictionary_encoded_array_type.go

func main() {
    dictType := &arrow.DictionaryType{IndexType: &arrow.Int8Type{}, ValueType: &arrow.StringType{}}
    bldr := array.NewDictionaryBuilder(memory.DefaultAllocator, dictType)
    defer bldr.Release()

    bldr.AppendValueFromString("foo")
    bldr.AppendValueFromString("bar")
    bldr.AppendValueFromString("foo")
    bldr.AppendValueFromString("bar")
    bldr.AppendNull()
    bldr.AppendValueFromString("baz")

    arr := bldr.NewDictionaryArray()
    defer arr.Release()
    bufs := arr.Data().Buffers()
    for _, buf := range bufs {
        fmt.Println(hex.Dump(buf.Buf()))
    }

    dict := arr.Dictionary()
    // print value string in dict
    bufs = dict.Data().Buffers()
    for _, buf := range bufs {
        if buf == nil {
            continue
        }
        fmt.Println(hex.Dump(buf.Buf()))
    }

    fmt.Println(arr)
}

输出上述程序的执行结果：

$go run dictionary_encoded_array_type.go
00000000  2f 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |/...............|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  00 01 00 01 00 02 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  00 00 00 00 03 00 00 00  06 00 00 00 09 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

00000000  66 6f 6f 62 61 72 62 61  7a 00 00 00 00 00 00 00  |foobarbaz.......|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

{ dictionary: ["foo" "bar" "baz"]
  indices: [0 1 0 1 (null) 2] }

对照的下面的示意图，我们可以更好的理解这大段输出：

我们看到dictionary array type实际上是通过一个indices建立了到底层存储字符串的array的offset的映射来实现字典编码的，这可以大大节省内存空间。

还有一些类型，比如Time32/Time64、Date32/Date64等，其存储结构与上面的一些类型大同小异，大家可以自行研读规范以及做编码实践来理解体会。

4. Arrow格式规范的版本管理与稳定性

Arrow格式规范自1.0开始便承诺遵循semver规范，即采用major.minor.fix的版本格式。只有当major版本发生变更时，才会引入不兼容的变化。当前format的版本是1.3，所以我们可以将其视作是向后兼容的。

5. 小结

本文介绍了Apache顶级项目Arrow，这是一个旨在在内存中建立各个类型的统一格式规范的项目，基于Arrow，各个大数据系统便可以省去序列化/反序列化的动作直接操作Arrow数据；同时Arrow采用列式模型，天生适合数据处理与分析。

文中对arrow的常见array type的layout进行了分析。虽然都叫type，但arrow定义的array type是描述一个“列”的，比如primitive types中的int32 type，它表示的是一个什么样的列呢？列中元素定长：sizeof(int32)、列的长度(array length)也是fixed的。只有理解到这一层次，才能更好的理解arrow。

本文的代码和layout适用于： Arrow Columnar Format Version: 1.3版本。

注：本文涉及的源代码在这里可以下载。

6. 参考资料

Arrow FAQ – https://arrow.apache.org/faq/
Arrow implementation matrix – https://arrow.apache.org/docs/status.html
influxdb团队将arrow的Go实现捐献给apache arrow项目 – https://arrow.apache.org/blog/2018/03/22/go-code-donation/
Go and Apache Arrow: building blocks for data science – https://arrow.apache.org/blog/2018/03/22/go-code-donation/
Use Apache Arrow and Go for Your Data Workflows – https://voltrondata.com/resources/use-apache-arrow-and-go-for-your-data-workflows
Make Data Files Easier to Work With Using Golang and Apache Arrow – https://voltrondata.com/resources/make-data-files-easier-to-work-with-golang-arrow
《In-Memory Analytics with Apache Arrow》- https://book.douban.com/subject/35954154/
Apache Arrow的起源及其在当今数据领域的适用性 – https://www.dremio.com/blog/the-origins-of-apache-arrow-its-fit-in-todays-data-landscape/

“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群！高品质首发Go技术文章，“三天”首发阅读权，每年两期Go语言发展现状分析，每天提前1小时阅读到新鲜的Gopher日报，网课、技术专栏、图书内容前瞻，六小时内必答保证等满足你关于Go语言生态的所有需求！2023年，Gopher部落将进一步聚焦于如何编写雅、地道、可读、可测试的Go代码，关注代码质量并深入理解Go核心技术，并继续加强与星友的互动。欢迎大家加入！

img{512x368}

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式：

微博(暂不可用)：https://weibo.com/bigwhite20xx
微博2：https://weibo.com/u/6484441286
博客：tonybai.com
github: https://github.com/bigwhite

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

Go语言包设计指南

六月 18, 2023
0 条评论

本文永久链接 – https://tonybai.com/2023/06/18/go-package-design-guide

1. Go包的认知

1.1 Go包是基本功能单元

我们知道Go包是Go编程语言中的一个重要概念，它是一组相关的Go源代码文件。并且，在Go中，每个Go源文件都必须属于一个包。

Go包是一个逻辑上独立的单元，是Go的基本功能单元，用来做功能边界的划分。这些基本功能单元的累加就构成了Go应用，因此Go应用的本质就是一组Go包的集合。

Go包这种功能独立的单元为Go开发者提供了“封装”和复用的便利。在Go中，Go包也是代码复用的基本单元，被用来管理和组织代码，Go项目的结构布局本质上就是安排Go包的位置，使得代码更易于维护和重用。

1.2 Go包是基本编译单元

Go包还是编译时的最小单位。也就是说，Go编译器编译代码时会以包为单位进行编译，而不是以文件为单位。这意味着一个包中的所有源文件都将被编译成一个单独的目标文件，而不是多个目标文件。

使用包而不是文件作为编译单元，有助于提高编译效率和管理依赖关系。

注：编译速度快是包这种设计“先进性”的一个表现，即便每次编译都是从零开始。Go编译速度快的几个原因与以包作为编译单元是密不可分的，具体体现在Go源文件在开头处显式地列出所有依赖包，编译器不必读取整个文件就可确定依赖包列表；Go包之间不能存在循环依赖，由于无环，包可以被单独编译，也可以并行编译；已编译的Go包的目标文件中记录了其所依赖包的导出符号信息。Go编译器在读取该目标文件时不需进一步读取其依赖包的目标文件。

1.3 Go包是基本设计单元

这个世界越来越复杂，软件系统同样变得日益复杂。无论你是什么编程语言的开发者，我们要面对的都是如何驯服这种复杂性。到目前为止，我们驯服这种复杂性的思路还很初级，无非是对复杂性进行分解、分解、分解，并按照我们更容易理解的方式重新组合。

Go包是基本功能单元，对于Go开发者，我们要将复杂性分解为一个个包，然后以一种合理的方式将包组合在一起以实现我们要的系统，因此Go包也是我们面对一个系统时的基本设计单元。我们不仅要设计每个包肩负的职责，还要设计包与包之间的关系。

因此，Go系统设计就是面向包进行设计。

接下来，我们就来看看Go包的设计思路。

2. Go包设计思路

即便你没写过Go程序，作为程序员你也应该知道“高内聚，低耦合”这个原则在软件系统设计中的分量。这里我们就以这个原则作为“抓手”来展开看看Go包的设计思路。

高内聚, 低耦合这个顶层原则，适用于所有编程语言的系统设计。但落到Go包设计上面，具体如何体现高内聚与低耦合呢？我们继续往下看。

2.1 功能选桶：自然内聚

面对一个复杂系统，我们通常会做一些系统分析，比如用领域驱动设计的方式从需求中挖掘出一堆术语、事件、命令等(即便你不懂领域设计的纯正方法，你的实际操作过程也或多或少与领域设计的内容重叠)。之后，通常会分层、划分服务，每个服务又要划分模块或包。

在服务这一层次上哪些功能放到哪个包里呢？这个过程我称之为“功能选桶”。

这让我想到了和孩子一起学习动物分类时的书中题目：

有这样一组动物：老虎、狮子、海马、大雁、熊猫、黄鹂、鲸鱼，这些动物能分为哪几个类别呢?

一个稍稍被启蒙了的孩子都会给出这样的分类：

陆地动物：老虎、狮子、熊猫
海洋动物：海马、鲸鱼
天空动物：大雁、黄鹂

而另外一个稍有一些生物学入门知识的大点的孩子可能也会给出下面的分类：

哺乳动物：老虎、狮子、熊猫、鲸鱼
卵生动物：海马、大雁、黄鹂

无论哪种，这些分类都是基于动物行为特征的自然结合。第一种似乎更直观自然，第二种则需要有更“专业”的知识（领域知识）。Go包的“功能选桶”其实是一个道理，相关功能自然结合到一个包中，保证这个包的内聚性。

比如下面有几个功能函数：Add、Subtract、Multiply、Divide、Sum、Average、Histogram，我们如何为这几个函数选桶呢？

一种不那么内聚的作法是将上述所有函数都放入math包；而更自然内聚一些的作法则是将Add、Subtract、Multiply、Divide放入math包，而将Sum、Average、Histogram等放入stats包(statistics，统计学)。

在功能选桶过程中，越符合常人思维，就越自然，可读性和可理解性大概率就越好。

2.2 包间关系：最小耦合

功能选桶之后，我们再来看包与包之间的关系，通常我们这种关系称为耦合。

用白话来理解耦合就是：当a变化时，b受到影响并随之变化，则说b与a之间存在耦合，即b依赖a。a是引发b变化的一个原因。

程序员都知道：一种理想的耦合情况是正交，即你变你自变，我岿然不动。但现实中这很难达到，我们应该追求的是尽可能地降低包与包间的耦合。

在包依赖层面，Go强制要求不能存在循环依赖，即Go包之间的耦合一定是有向无环的，这一定层度上也能帮助Go包之间降低耦合。

要降低包与包之间的耦合，我们首先要了解Go包间的最低耦合关系是什么呢？

在代码层面最低的耦合是接口耦合，在Go中，接口的实现是隐式的，即a包实现b包中定义的接口时是不需要显式导入b包的，我们可以在c包中完成对a包与b包的组装，这样c包依赖a包和b包，但a包与b包之间没有任何耦合。

那么负责组装a包与b包的c包能否在代码层面消除掉对a和b的依赖呢？这个就很难了。不过我们可以使用依赖注入技术来消除在代码层面手动基于依赖进行初始化或创建时的复杂性，不过依赖注入技术也是有“门槛”的，它会让你的代码不那么straightforward，代码的可读性和可理解性会下降。

注：个人觉得：依赖注入在Go中并非是一种惯用法。Google开源了像wire这样的依赖注入框架(通过代码生成而实现的编译期依赖注入)，更多是为了解决掉内部大型Go项目初始化时各种创建动作的复杂性。

我们可以参考软件界用于降低代码耦合的原则，比如由Robert C. Martin（通常被称为“Uncle Bob”）在《敏捷软件开发》一书中提出的旨在帮助开发人员设计更加灵活、可扩展和可维护的软件系统的SOLID敏捷设计原则，这些原则如何应用在Go上呢，或者在Go中如何体现呢，我们接下来就来看一下。

注：“敏捷设计是一个过程，而不是一次事件。它是一个持续应用原则、模式以及实践来改进软件结构和可读性的过程。它致力于保持系统的设计在任何时间都尽可能的简单、整洁和富有表现力。” – 《敏捷软件开发》

2.3 应用SOLID设计原则

2.3.1 单一职责原则（SRP）

对于一个类而言，应该仅有一个原因会引起它的变化。在SRP的语境中，我们把职责定义为“变化的原因”(a reason for change)。如果你有超过一个的动机去改变一个类，那么这个类就具有多种职责。- 《敏捷软件开发》

就像Uncle Bob在书中说的那样：“如果你有超过一个的动机去改变一个类，那么这个类就具有多种职责。有时，我们很难注意到这一点。我们习惯于以组(group)的形式去考虑职责”。

在Go包这一层次上，SRP更多体现在功能内聚上，就像前面举的math包和stats包的例子。

再比如我们有一个图形库，它可以绘制不同类型的图形，如矩形、圆形、三角形等。我们可能会定义一个graph包，里面定义了Graphics类型，它具有Draw方法，用于绘制图形。在不遵循SRP的情况下，graph包Graphics类型可能会包含绘制各种类型图形的代码，这会导致类不仅包含多个职责，而且功能不够内聚。

在遵循SRP的情况下，我们可以在graph包中定义Graphics接口，该接口具有Draw方法，然后在rectangle、circle、triangle包中分别定义Graphics接口的实现：Rectangle类型、Circle类型与Triangle类型：

graph/
    - graph.go // 定义Graphics接口
    - rectangle/
        - rectangle.go // 定义Rectangle类型和其Draw方法
    - circle/
        - circle.go // 定义Circle类型和其Draw方法
    - triangle/
        - triangle.go // 定义Triangle类型和其Draw方法

这样，每个包都只负责一个图形类型，职责更加单一，也更容易维护和扩展。

2.3.2 开放-关闭原则(OCP)

软件实体（类、模块、方法等）应该对扩展开放，但是对修改关闭。- 《敏捷软件开发》

还以上面的graph等包为例，OCP原则可以体现在两方面：

扩展Graphics接口的实现

我们无法修改graph.go中的Graphics接口，但如果你要添加一个square包，定义Square类型并实现Draw方法，那么我们可以在graph包下面添加一个square包，这个包和circle等包位于同等位置，都实现了graph包的Draw方法。

基于Graphics接口的组合

我们无法修改graph.go中的Graphics接口，但是我们可以基于graph.Graphics接口去组合出其他具有更多职责的接口或非接口类型，就像io包中的Reader、Writer接口被组合到ReaderCloser、ReadWriteCloser中一样。

OCP原则的关键是抽象，在Go中建立包与包之间关系抽象的最佳方法就是建立接口类型。前面说过，通过接口的耦合是最低的包间耦合，因此采用OCP原则对于降低包间耦合具有重要意义。

不过，Bob大叔在书中也说了：“遵循OCP的代价也是昂贵的。创建恰当的抽象是要花费时间和精力的。那些抽象也增加了软件设计的复杂性，开发人员有能力处理的抽象数量是有限的”。OCP原则的应用应该被限定在最可能发生的变化上。

2.3.3 里氏替换原则(LSP)

对于里氏替换原则(LSP)，可以如此解释：子类型(subtype)必须能够替换掉它们的基类(base type)。- 《敏捷软件开发》

Bob大叔在讲解LSP原则时使用的语言是C++和Java，对于这两种静态类型的OO语言来说，支持抽象和多态的关键机制之一是继承(inheritance)。也只有在继承的概念之上，采用基类和子类之分。

不过Go并非传统意义上的OO语言，它没有继承，没有类型层次体系。即便没有这些，Go也不乏抽象表达能力，最直接的就是接口这个行为的集合。

这样里氏替换原则(LSP)在Go中就可以如此解释：接口I的所有实现都是可以相互替代的，因为它们履行了同样的契约。

2.3.4 接口隔离原则(ISP)

客户端程序不应该被迫依赖于它们不需要的方法。- 《敏捷软件开发》

这个在体现Go包与包关系层面不是那么明显，方法已经告诉你这种耦合是接口耦合，但究竟用的是什么样的接口呢？“胖接口”，不是！我们需要刚刚好，不多不少的接口。

来看一个例子：我们有如下一些接口定义：

type Printer interface {
    Print()
}

type Scanner interface {
    Scan()
}

type PrintSleeper interface {
    Printer
    Sleep()
}

type PrintScanSleeper interface {
    Printer
    Scanner
    Sleep()
}

现在我们要实现一个打印机打印的API，我们最初的设计是：

func Print(p PrintScanSleeper, data []byte) error {
}

在这个设计中，Print函数依赖的是PrintScanSleeper，这意味着传入的合法参数的类型必须要实现Print、Scan和Sleep三个方法，但我们的函数只是为了实现打印，它不需要调用Scanner的Scan方法，根据ISP原则，我们不应该强迫Print函数依赖它们本不需要的方法，于是第二版设计如下：

func Print(p Printer, data []byte) error {
}

这似乎无懈可击。但常识告诉我们，每次打印结束后，都需要让打印机休眠，那么显然仅依赖Printer接口又缺少了点东西，那么最终版的设计如下：

func Print(p PrintSleeper, data []byte) error {
}

对ISP原则的白话阐述就是：“不多不少，刚刚好”！

2.3.5 依赖倒置原则(DIP)

高层次的模块不应该依赖低层次的模块。两者都应该依赖抽象。抽象不应该依赖于细节，细节应该依赖于抽象。- 《敏捷软件开发》

如果你的代码符合上面的几条原则的话，那么到这里，你的代码很大可能也是符合DIP原则的。

一提到“依赖抽象”，大家肯定想到的还是接口。在Go中，接口是抽象的主要代名词。

在包与包的关系层面上，DIP原则表现为：高层次包依赖接口，低层次的包实现接口，如下图：

因此，在同等条件下，采用DIP原则设计良好的Go程序的包导入图应该是宽而平的，而不是高而窄的：

3. 单包设计

说完了包的内聚与包间关系的耦合后，我们最后将精力聚焦在单包的设计上面，看看一个Go包在设计方面有哪些值得借鉴的tips。

3.1 包名

我们在引用某个包的导出标识符时使用的是：

pkgname.XXX

由此可见包名的重要性，它可以理解为一个包的API的重要组成部分，因此包设计的第一步就是要为包起个好名字。

给Go包起名字首先要注意简单达意，比如标准库的fmt、io、os等，并且包名按惯例应该与其目录名一致；

其次，同一工程内部包名最好是唯一的，避免工程内部出现名字碰撞；

最后，如果为了简洁而失去了包名的内聚性的内涵(功能和作用)，比如utils、common这些名字基本无法表达包究竟担负的职责，那么莫不如将包名加长一些，点缀上能达意的单词，比如printutil而不仅仅是util。

3.2 最小暴露表面积

在单包设计时，要考虑最小暴露表面积，指定是应该尽可能减少包暴露给外部的接口和实现，只暴露必要的最小接口，以提高代码的安全性和可维护性。同时，从用户角度来看，只暴露必要信息的包看起来更易用。

具体来说，可以分为如下几点：

使用接口建立抽象

在设计包时，应该使用接口来建立抽象，而不是直接暴露实现。这样可以将实现细节隐藏起来，只暴露接口，从而提高代码的安全性和稳定性。

最小化暴露的接口

即便是暴露接口，在设计包时，也应该尽量减少暴露给外部的接口数量。只有必要的接口应该暴露出来，从而提高代码的安全性和稳定性。

使用非导出方法和变量封装实现细节

在设计包时，应该使用非导出方法和变量来封装包内部的实现细节，只暴露公共接口。这样可以将实现细节隐藏起来，避免外部代码直接依赖包内部的实现，从而提高代码的可维护性和灵活性。

最小化暴露的实现

在设计包时，应该尽量减少暴露给外部的实现数量。只有必要的实现应该暴露出来，而不是将所有实现都暴露出去。这样可以避免外部代码直接依赖包内部的实现，从而提高代码的可维护性和灵活性。

3.3 避免包级变量带来的包级状态

Go没有显式的全局变量，但包的导出变量本质上就是全局变量。在《聊聊Go语言的全局变量》一文中我们详细说明了全局变量的不足，因此应避免这类充当全局变量的包级变量的暴露。

3.4 main包应尽可能简洁

在Go中，main包是特殊的包，用于定义程序的入口函数main。在Go中，main函数应该尽可能简洁，它应该只负责装配其他包，调用其他函数或模块，不应该包含过多的代码逻辑。这样可以提高代码的可读性和可维护性。如果要对main函数进行单测的话，那么可以将main函数的逻辑放置到另外一个函数中，比如run，然后对run函数进行详尽的测试。

3.5 接口类型定义应放在与使用者更近的地方

Go接口是隐式实现的，意味着其实现者不需要显式告知实现了该接口，实现者所在包也无需导入接口定义所在的包。

这样一来，将接口类型定义放在与使用者更近的地方，可以使代码更加清晰和易于理解。使用者可以直接看到接口类型定义，了解接口类型的作用和使用方法。但注意：这并非是绝对的规则。

有些接口的实现者喜欢在自己的包中放置var i some_interface = (*T)(nil) ，以利用编译器的静态检查断言自己定义的类型*T实现了接口some_interface，这样一来实际上是显式宣告了在实现者和接口包之间关系，属于“增加耦合”的步骤。

如果接口类型在同一个包里提供了默认实现，那么这么做无可厚非，比如io包。

4. 小结

下面对本文内容做个小结：

Go包是Go程序设计的基本单元，分解复杂性的基本单位。
Go包应被设计为高内聚，关注同一职责，并尽量与其他包低耦合。
在设计Go包时，可以按照功能选桶，根据自然内聚思维来划分包，并遵循最小耦合原则减少包间依赖。
可以运用SOLID设计原则优化Go包间的关系:
- SRP：每个包都有单一的职责，具有高内聚。
- OCP：包对扩展开放，对修改关闭。
- LSP：接口的实现是互相替换的。
- ISP：接口将只暴露必要方法。
- DIP：高层包和低层包都依赖抽象，细节应依赖抽象。
在单包设计时应考虑最小暴露表面积，只暴露必要的接口和实现。
避免用包级变量带来的全局状态。main包应简洁。
接口类型定义最好放在使用者更近的地方。

希望能为大家提供参考！如果有不正确或遗漏的地方，欢迎指出，共同进步。

img{512x368}

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式：

微博(暂不可用)：https://weibo.com/bigwhite20xx
微博2：https://weibo.com/u/6484441286
博客：tonybai.com
github: https://github.com/bigwhite

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

Go语言开发者的Apache Arrow使用指南：数据类型

1. Arrow项目简介

2. Arrow Columnar Format规范

3. 数据类型

3.1 metadata

3.2 Null type

3.3 Primitive Type

3.3.1 Boolean Type

3.3.2 Integer types

3.3.3 Float types

3.4 Variable-size Binary Type

3.5 Fixed-Size List type

3.6 Variable-Size List type

3.7 Struct type

3.8 Union type

3.8.1 dense union array type

3.8.2 sparse union array type

3.9 Dictionary-encoded type

4. Arrow格式规范的版本管理与稳定性

5. 小结

6. 参考资料

Go语言包设计指南

1. Go包的认知

1.1 Go包是基本功能单元

1.2 Go包是基本编译单元

1.3 Go包是基本设计单元

2. Go包设计思路

2.1 功能选桶：自然内聚

2.2 包间关系：最小耦合

2.3 应用SOLID设计原则

2.3.1 单一职责原则（SRP）

2.3.2 开放-关闭原则(OCP)

2.3.3 里氏替换原则(LSP)

2.3.4 接口隔离原则(ISP)

2.3.5 依赖倒置原则(DIP)

3. 单包设计

3.1 包名

3.2 最小暴露表面积

3.3 避免包级变量带来的包级状态

3.4 main包应尽可能简洁

3.5 接口类型定义应放在与使用者更近的地方

4. 小结

欢迎使用邮件订阅我的博客

文章

评论

分类

标签

归档

链接

开源项目

翻译项目