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

59次阅读

共计 2065 个字符，预计需要花费 6 分钟才能阅读完成。

本篇内容介绍了“Kubernetes API 设计怎么实现可选字段”的有关知识，在实际案例的操作过程中，不少人都会遇到这样的困境，接下来就让丸趣 TV 小编带领大家学习一下如何处理这些情况吧！希望大家仔细阅读，能够学有所成！

导读

在阅读 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 键，如下所示