Shulou(Shulou.com)05/31 Report--

This article introduces the knowledge of "how to implement optional fields in Kubernetes API design". Many people will encounter this dilemma in the operation of actual cases, so let the editor lead you to learn how to deal with these situations. I hope you can read it carefully and be able to achieve something!

Guide reading

When reading the API of Kubernetes API or other projects, careful readers will find that some of these API fields contain the / / + optional tag (hereinafter referred to as the optional tag). For example, the Replicas field in Deployment API contains this tag:

/ / 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" `.}

For comparison, there is no optional tag in the Template field in Deployment API. Do you know the difference between them?

Readers might say that this is not easy. Fields that contain optional tags are optional, and vice versa. This is true, but there are some questions that API designers need to think about:

What is the use of optional tags other than improving readability?

When designing an API, should fields contain omitempty tags?

When designing an API, should fields be defined as pointer types?

At first, the author did not have an in-depth understanding of optional tags, and it was not until I took some detours in designing API that I realized that there was a lot of knowledge, or more accurately, a summary of previous experience. This article describes how to handle the selectability of fields from the point of view of the API designer.

The content of this section is summarized from the relevant discussions and cases of the Kubernetes community. It should be noted that in the early days of the Kubernetes project, there was no unified principle for the optional design of API fields, which led to the fact that there are still some API that are not very standardized.

The role of optional markers

The optional tag itself is a specially formatted comment, and its particularity is reflected in two aspects:

The tag takes up single-line comments

Comments start with spaces, followed by tags prefixed with "+" (similar to build tags in the Golang language).

In addition to improving the readability of the code, this tag is mainly used to generate OpenAPI documents and corresponding verification rules. For example, the controller-gen tool will generate validation rules for CRD based on this tag.

Optional tags are only used to mark the selectability of fields, and in addition, API designers need to understand some of the conventions of field design, or experience.

Field optional convention

Optional fields typically have the following characteristics:

Comments contain optional tags

Field types are usually pointer, map, slice

The Tag of a field usually contains an omitempty tag

Required fields typically have the following characteristics:

There are no optional tags in the comment

Field type is not a pointer

There is no omitempty tag in the Tag of the field

About omitempty markup

Before the emergence of the optional tag, the API of Kubernetes widely relied on the omitempty tag of the field to judge the selectability of the field, and had the optional field that was automatically recognized by the omitempty tag, otherwise it was a required field. Now make a slow transition to using optional tags to identify options.

How to distinguish null values from zero values

For the optional fields below, if the user sets the field to 0 (null value), because the value is equivalent to the zero value of the type, the developer cannot tell whether the user has set it or not.

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

Therefore, it is recommended that you use a pointer for optional fields. If the pointer is nil, it means that the user has not set it, otherwise, it explicitly sets the field value on behalf of the user.

In addition, using pointers can simplify JSON coding if the optional field type is a custom structure type. Refer to the following example:

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

Although the Dummy field tag contains the omitempty tag, an empty JSON key appears when its JSON is json.Marshal, as shown below

{"dummy": {}}

If the API contains a large number of such fields, it can be ugly when JSON is encoded, and defining it as a pointer type eliminates this problem.

This is the end of the content of "how to implement optional fields in Kubernetes API design". Thank you for reading. If you want to know more about the industry, you can follow the website, the editor will output more high-quality practical articles for you!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.