温馨提示×

温馨提示×

您好,登录后才能下订单哦!

密码登录×
登录注册×
其他方式登录
点击 登录注册 即表示同意《亿速云用户服务条款》

Kubernetes API设计怎么实现可选字段

发布时间:2022-01-07 15:27:15 来源:亿速云 阅读:100 作者:iii 栏目:云计算

本篇内容介绍了“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标记的被自动识别的可选字段,反之则为必选字段。现在慢慢过渡到使用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设计怎么实现可选字段”的内容就介绍到这里了,感谢大家的阅读。如果想了解更多行业相关的知识可以关注亿速云网站,小编将为大家输出更多高质量的实用文章!

向AI问一下细节

免责声明:本站发布的内容(图片、视频和文字)以原创、转载和分享为主,文章观点不代表本网站立场,如果涉及侵权请联系站长邮箱:is@yisu.com进行举报,并提供相关证据,一经查实,将立刻删除涉嫌侵权内容。

AI