Kubernetes API設計怎么實現可選字段

本篇內容介紹了“Kubernetes  API設計怎么實現可選字段”的有關知識，在實際案例的操作過程中，不少人都會遇到這樣的困境，接下來就讓小編帶領大家學習一下如何處理這些情況吧！希望大家仔細閱讀，能夠學有所成！

導讀

在閱讀 Kubernetes API 或 其他項目的 API時，細心的讀者會發現這些 API 中有些字段包含了 // +optional 標記（下面簡稱optional標記），比如 Deployment API中的 Replicas 字段就包含這個標記：

// 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標記，你知道他們的區別嗎？

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

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

• 在設計API時，字段是否應該包含omitempty 標簽？

• 在設計API時，字段是否應該定義為指針類型？

筆者最初沒有深入地了解optional標記，直到自己設計API時走了一些彎路才意識到這里面大有學問，更準確地說是前人經驗的總結。本文站在API設計者角度來介紹應該如何處理字段的可選性。

本節內容由Kubernetes社區相關討論、案例中總結而來，需要說明的是，在Kubernetes項目早期，關于API字段的可選性設計并沒有統一的原則，這也導致了目前仍有部分API并不是十分規范。

optional標記的作用

optional標記本身是一個特殊格式的注釋，其特殊性體現在兩方面：

• 該標記占用單行注釋

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

該標記除了提高代碼可讀性以外，主要用于生成OpenAPI文檔以及相應的校驗規則。比如controller-gen 工具就會根據這個標記生成CRD的校驗規則。

optional標記僅用于標記字段的可選性，除此之外，API設計者還需要了解一些字段設計的約定，或者說是經驗之談。

字段可選性約定

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

• 注釋中包含optional標記；

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

• 字段的Tag中通常包含omitempty標記；

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

• 注釋中沒有optional標記；

• 字段類型不是指針；

• 字段的Tag中沒有omitempty標記；

關于omitempty標記

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

如何區別空值和零值

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

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

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

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

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

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

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

{"dummy":{}}

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

“Kubernetes  API設計怎么實現可選字段”的內容就介紹到這里了，感謝大家的閱讀。如果想了解更多行業相關的知識可以關注億速云網站，小編將為大家輸出更多高質量的實用文章！