CBOR 格式
簡明二進位物件表示法(Concise Binary Object Representation,簡稱 CBOR)是一種緊湊的二進制格式,擴充了 JSON 資料模型。
為 CBOR 新增相依性
要在專案中使用 CBOR,請將 CBOR 序列化程式庫相依性新增至您的建置檔案中:
// build.gradle(.kts)
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-serialization-cbor:1.11.0")
}<!-- pom.xml -->
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-serialization-cbor</artifactId>
<version>1.11.0</version>
</dependency>
</dependencies>使用 CBOR 進行二進制序列化
Cbor 類別提供兩個函式:
encodeToByteArray()將物件序列化為位元組陣列。decodeFromByteArray()從位元組陣列反序列化為物件。
以下範例將 Project 物件序列化為位元組陣列,然後再反序列化回其原始形式:
import kotlinx.serialization.*
import kotlinx.serialization.cbor.*
fun ByteArray.toAsciiHexString() = joinToString("") {
// Converts bytes in the printable ASCII range to characters
// and other bytes to hex values
if (it in 32..126) it.toInt().toChar().toString() else
"{${it.toUByte().toString(16).padStart(2, '0').uppercase()}}"
}
@Serializable
data class Project(val name: String, val language: String)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val data = Project("kotlinx.serialization", "Kotlin")
// 將物件序列化為 CBOR 位元組陣列
val bytes = Cbor.encodeToByteArray(data)
// 將位元組陣列轉換為易於閱讀的十六進位字串
println(bytes.toAsciiHexString())
// {BF}dnameukotlinx.serializationhlanguagefKotlin{FF}
// 將位元組陣列反序列化回物件
val obj = Cbor.decodeFromByteArray<Project>(bytes)
println(obj)
// Project(name=kotlinx.serialization, language=Kotlin)
}此範例以可讀的混合形式輸出編碼後的位元組。它將可列印的 ASCII 位元組表示為字元,並將不可列印的位元組表示為十六進位數值。
以下是相同輸出的完整 CBOR 十六進位標記法:
Hex code | CBOR type | Description
-----------------------------------------------------|--------------|------------------------------------
BF | map(*) | Start of a CBOR map
├── 64 | text(4) | Length of the string
│ └── 6E616D65 | string | The string "name"
├── 75 | text(21) | Length of the string
│ └── 6B6F746C696E782E73657269616C697A6174696F6E | string | The string "kotlinx.serialization"
├── 68 | text(8) | Length of the string
│ └── 6C616E6775616765 | string | The string "language"
├── 66 | text(6) | Length of the string
│ └── 4B6F746C696E | string | The string "Kotlin"
└── FF | primitive(*) | End of the CBOR map在 CBOR 中忽略未知索引鍵
CBOR 常用於與物聯網 (IoT) 裝置的通訊,這些裝置可能會在 API 演進過程中新增屬性。 預設情況下,反序列化過程中遇到未知索引鍵會導致錯誤。
就像在 JSON 中一樣,您可以將 ignoreUnknownKeys 屬性設定為 true,以在反序列化期間忽略它們:
import kotlinx.serialization.*
import kotlinx.serialization.cbor.*
@Serializable
data class Project(val name: String)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
// 建立一個在反序列化期間忽略未知索引鍵的 Cbor 執行個體
val format = Cbor { ignoreUnknownKeys = true }
// 解碼帶有額外未知 "language" 索引鍵的 CBOR 輸入
val data = format.decodeFromHexString<Project>(
"bf646e616d65756b6f746c696e782e73657269616c697a6174696f6e686c616e6775616765664b6f746c696eff"
)
println(data)
// Project(name=kotlinx.serialization)
}在此 CBOR 輸入中,以下位元組代表未知的 "language" 索引鍵及其值:
- 未知索引鍵
"language":68:索引鍵的長度6c616e6775616765:索引鍵
- 值
"Kotlin":66:值的長度4b6f746c696e:值
完整的 CBOR 十六進位標記法 {...}
Hex code | CBOR type | Description
-----------------------------------------------------|--------------|------------------------------------
BF | map(*) | Start of a CBOR map
├── 64 | text(4) | Length of the string
│ └── 6E616D65 | string | The string "name"
├── 75 | text(21) | Length of the string
│ └── 6B6F746C696E782E73657269616C697A6174696F6E | string | The string "kotlinx.serialization"
├── 68 | text(8) | Length of the string
│ └── 6C616E6775616765 | string | The string "language"
├── 66 | text(6) | Length of the string
│ └── 4B6F746C696E | string | The string "Kotlin"
└── FF | primitive(*) | End of the CBOR map自訂 CBOR 資料編碼
根據 RFC 8949 主要類型 (Major Types) 規範,CBOR 支援以下資料型別:
- 主要類型 0:無號整數
- 主要類型 1:負整數
- 主要類型 2:位元組字串
- 主要類型 3:文字字串
- 主要類型 4:資料項目陣列
- 主要類型 5:成對資料項目的映射 (map)
- 主要類型 6:其他主要類型的可選語意標籤
- 主要類型 7:浮點數、無內容的簡單資料型別,以及「中斷 (break)」停止碼
與 JSON 不同,CBOR 支援具有結構化映射鍵 (structured map keys) 的 map,例如使用者定義類別的執行個體。 然而,某些剖析器(例如 jackson-dataformat-cbor)並不支援它們。
關於 JSON 的暫代解決方案,請參閱允許結構化映射鍵。
將 ByteArray 屬性編碼為位元組字串
您可以自訂資料的 CBOR 表示法,而不是使用預設編碼,例如為了符合外部架構所定義的序列化形式。 在某些情況下,這些自訂設定還可以縮減二進制檔案大小。
預設情況下,Kotlin ByteArray 值會編碼為主要類型 4,表示資料項目陣列。 若要將 ByteArray 屬性編碼為主要類型 2(位元組字串),請使用 @ByteString 註解:
import kotlinx.serialization.*
import kotlinx.serialization.cbor.*
@Serializable
data class Data(
// 將位元組陣列編碼為 CBOR 位元組字串(主要類型 2)
@ByteString
val type2: ByteArray,
// 將位元組陣列編碼為 CBOR 主要類型 4:
// 個別資料項目的陣列
val type4: ByteArray
)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
// 建立具有兩個 ByteArray 欄位的 Data 物件
val data = Data(byteArrayOf(1, 2, 3, 4), byteArrayOf(5, 6, 7, 8))
// 將 Data 物件序列化為 CBOR 位元組陣列
val bytes = Cbor.encodeToByteArray(data)
println(bytes.toAsciiHexString())
// {BF}etype2D{01}{02}{03}{04}etype4{9F}{05}{06}{07}{08}{FF}{FF}
val obj = Cbor.decodeFromByteArray<Data>(bytes)
println(obj)
// Data(type2=[1, 2, 3, 4], type4=[5, 6, 7, 8])
}在此範例中,每個 ByteArray 值之前的位元組不同,因為這些屬性使用了不同的 CBOR 主要類型。
以下是完整 CBOR 十六進位標記法下的已編碼位元組陣列:
完整的 CBOR 十六進位標記法 {...}
Hex code | CBOR type | Description
-----------------------|--------------|-----------------------------------------
BF | map(*) | Start of a CBOR map
├── 65 | text(5) | Length of the string
│ └── 7479706532 | string | The property name "type2"
├── 44 | bytes(4) | Length of the byte string
│ └── 01020304 | byte string | The byte string "\x01\x02\x03\x04"
├── 65 | text(5) | Length of the string
│ └── 7479706534 | string | The property name "type4"
├── 9F | array(*) | Start of a CBOR array
│ ├── 05 | unsigned(5) | The unsigned integer 5
│ ├── 06 | unsigned(6) | The unsigned integer 6
│ ├── 07 | unsigned(7) | The unsigned integer 7
│ ├── 08 | unsigned(8) | The unsigned integer 8
│ └── FF | primitive(*) | End of the CBOR array
└── FF | primitive(*) | End of the CBOR map若要將所有 ByteArray 值編碼為主要類型 2,而無需在每個屬性上加上 @ByteString 註解,請將 alwaysUseByteString 屬性設定為 true:
val format = Cbor {
alwaysUseByteString = true
}將類別編碼為 CBOR 陣列
預設情況下,類別會序列化為 CBOR map,對應於主要類型 5。 這意味著類別的每個屬性都儲存為鍵值對。
您可以使用 @CborArray 註解將類別序列化為 CBOR 陣列(主要類型 4)。 這對於編碼 COSE 訊息結構非常有用,因為 RFC 9052 將其定義為 CBOR 陣列。
以下是一個範例:
@Serializable
@CborArray
data class DataClass(
val alg: Int,
val kid: String?
)
Cbor.encodeToByteArray(DataClass(alg = -7, kid = null))使用 @CborArray 註解時,此範例會編碼為 CBOR 陣列:0x8226f6。 若沒有該註解,相同的類別將編碼為 CBOR map:0xa263616c6726636b6964f6。
CBOR 中的定長與不定長編碼
CBOR 對於 map 和陣列支援兩種編碼方式:定長編碼 (definite-length encoding) 與 不定長編碼 (indefinite-length encoding)。
預設情況下,Kotlin serialization 使用不定長編碼。 在此編碼中,map 或陣列中的元素數量不會明確編碼。相反地,會使用「中斷」停止碼 (0xFF) 來標記集合的結束。
定長編碼則會省略終止位元組,並在 map 或陣列的開頭編碼元素數量。
若要在這兩種模式之間切換,請使用 useDefiniteLengthEncoding 屬性。
CBOR 中的標籤 (Tags) 與標號 (Labels)
CBOR 允許您定義標籤 (tags),用來為屬性和值編碼額外資訊。 您可以使用 @KeyTags 與 @ValueTags 註解來指定這些標籤。 encodeKeyTags、encodeValueTags、verifyKeyTags 與 verifyValueTags 屬性控制著 這些標籤的編碼與驗證。
有關 CBOR 標籤的更多資訊,請參閱 RFC 8949 項目的標籤化 (Tagging of Items)。
您還可以使用 @ObjectTags 註解為類別的所有執行個體指派標籤。
序列化時,@ObjectTags 會直接編碼在已標記物件的資料之前。 如果屬性具有值標籤且其型別具有物件標籤,則值標籤會在物件標籤之前編碼。 encodeObjectTags 與 verifyObjectTags 屬性控制是否對物件標籤進行編碼和驗證。 如果您僅驗證值標籤而不驗證物件標籤,解碼器仍可反序列化帶有額外物件標籤的資料。
如需已知標籤的清單,請參閱 CborTag。
CBOR 支援任何型別的 map 鍵。 在 COSE(CBOR 物件簽署與加密)中,這些鍵僅限於字串與數字,並被稱為標號 (labels)。
您可以使用 @SerialName 註解指派字串標號,並使用 @CborLabel 註解指派數值標號。 當兩者同時存在時,preferCborLabelsOverNames 屬性允許優先使用數值標號而非序列名稱。 您可以使用它來為 CBOR 保留緊湊的標號,同時在序列化為 JSON 時仍保留易讀的名稱。
Kotlin serialization 還提供了一個預定義的 Cbor.CoseCompliant 執行個體,該執行個體遵循 COSE 編碼需求。 它使用定長編碼、編碼並驗證所有標籤,且優先使用數值標號而非序列名稱。
自訂 CBOR 專用序列化器
CBOR 編碼器和解碼器實作了 CborEncoder 與 CborDecoder 介面。
這些介面擴充了一般的 Encoder 與 Decoder 介面,透過 cbor 屬性提供對 CBOR 專用配置的存取。 自訂序列化器可以使用此屬性存取目前的 Cbor 執行個體、產生內嵌的位元組陣列,並讀取目前設定,例如 preferCborLabelsOverNames 與 useDefiniteLengthEncoding。
有關建立自訂序列化器的更多資訊,請參閱建立自訂序列化器。
