Kubernetes API設(shè)計(jì)怎么實(shí)現(xiàn)可選字段

本篇內(nèi)容介紹了“Kubernetes  API設(shè)計(jì)怎么實(shí)現(xiàn)可選字段”的有關(guān)知識，在實(shí)際案例的操作過程中，不少人都會遇到這樣的困境，接下來就讓小編帶領(lǐng)大家學(xué)習(xí)一下如何處理這些情況吧！希望大家仔細(xì)閱讀，能夠?qū)W有所成！

導(dǎo)讀

在閱讀 Kubernetes API 或 其他項(xiàng)目的 API時，細(xì)心的讀者會發(fā)現(xiàn)這些 API 中有些字段包含了 // +optional 標(biāo)記（下面簡稱optional標(biāo)記），比如 Deployment API中的 Replicas 字段就包含這個標(biāo)記：

// DeploymentSpec is the specification of the desired behavior of the Deployment.
type DeploymentSpec struct {
	// Number of desired pods. This is a pointer to distinguish between explicit
	// zero and not specified. Defaults to 1.
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`
	...
	// Template describes the pods that will be created.
	Template v1.PodTemplateSpec `json:"template"`
	...
}

作為對比，Deployment API中的 Template 字段就沒有optional標(biāo)記，你知道他們的區(qū)別嗎？

讀者可能會說，這還不簡單，包含optional標(biāo)記的字段是可選的，反之就是必選的。事實(shí)確實(shí)如此，不過，對于API設(shè)計(jì)者還需要思考下面的問題：

• optional標(biāo)記除了提高可讀性以外，還有什么作用？

• 在設(shè)計(jì)API時，字段是否應(yīng)該包含omitempty 標(biāo)簽？

• 在設(shè)計(jì)API時，字段是否應(yīng)該定義為指針類型？

筆者最初沒有深入地了解optional標(biāo)記，直到自己設(shè)計(jì)API時走了一些彎路才意識到這里面大有學(xué)問，更準(zhǔn)確地說是前人經(jīng)驗(yàn)的總結(jié)。本文站在API設(shè)計(jì)者角度來介紹應(yīng)該如何處理字段的可選性。

本節(jié)內(nèi)容由Kubernetes社區(qū)相關(guān)討論、案例中總結(jié)而來，需要說明的是，在Kubernetes項(xiàng)目早期，關(guān)于API字段的可選性設(shè)計(jì)并沒有統(tǒng)一的原則，這也導(dǎo)致了目前仍有部分API并不是十分規(guī)范。

optional標(biāo)記的作用

optional標(biāo)記本身是一個特殊格式的注釋，其特殊性體現(xiàn)在兩方面：

• 該標(biāo)記占用單行注釋

• 注釋以空格開始，然后附加以“+”為前綴的標(biāo)記（類似Golang語言中的build 標(biāo)簽）。

該標(biāo)記除了提高代碼可讀性以外，主要用于生成OpenAPI文檔以及相應(yīng)的校驗(yàn)規(guī)則。比如controller-gen 工具就會根據(jù)這個標(biāo)記生成CRD的校驗(yàn)規(guī)則。

optional標(biāo)記僅用于標(biāo)記字段的可選性，除此之外，API設(shè)計(jì)者還需要了解一些字段設(shè)計(jì)的約定，或者說是經(jīng)驗(yàn)之談。

字段可選性約定

可選字段通常具備以下特征：

• 注釋中包含optional標(biāo)記；

• 字段類型通常為指針、map、slice；

• 字段的Tag中通常包含omitempty標(biāo)記；

必選字段通常具備以下特征：

• 注釋中沒有optional標(biāo)記；

• 字段類型不是指針；

• 字段的Tag中沒有omitempty標(biāo)記；

關(guān)于omitempty標(biāo)記

在optional標(biāo)記出現(xiàn)以前，Kubernetes的API中廣泛依賴字段的omitempty標(biāo)記來判斷字段的可選性，擁有omitempty標(biāo)記的被自動識別的可選字段，反之則為必選字段?，F(xiàn)在慢慢過渡到使用optional標(biāo)記來識別可選性。

如何區(qū)別空值和零值

對于下面的可選字段而言，如果用戶設(shè)置字段為0（空值），由于該值等同于類型的零值，開發(fā)者無法區(qū)別出用戶到底有沒有設(shè)置。

	// +optional
	Foo int32 `json:"foo,omitempty"`

所以，建議對于可選字段，建議使用指針，如果指針為nil表示用戶沒有設(shè)置，反之則代表用戶顯式地設(shè)置了字段值。

除此之外，如果可選字段類型為自定義結(jié)構(gòu)體類型，使用指針還可以簡化JSON編碼。參考下面的例子：

type DummyStruct struct {
	// +optional
	Foo *int `json:"foo,omitempty"`
}

type MyStruct struct {
	// +optional
	Dummy DummyStruct `json:"dummy,omitempty"`
}

盡管Dummy字段標(biāo)簽中包含omitempty標(biāo)記，在將其JSON編碼（json.Marshal）時，仍然為出現(xiàn)一個空的JSON鍵，如下所示

{"dummy":{}}

如果API中包含大量這樣的字段，則在JSON編碼時會比較丑陋，而將其定義為指針類型可消除這個問題。

“Kubernetes  API設(shè)計(jì)怎么實(shí)現(xiàn)可選字段”的內(nèi)容就介紹到這里了，感謝大家的閱讀。如果想了解更多行業(yè)相關(guān)的知識可以關(guān)注億速云網(wǎng)站，小編將為大家輸出更多高質(zhì)量的實(shí)用文章！