crd的go结构体需json/yaml标签、validation注释、scheme注册三者严格对齐：字段须用指针+omitempty标签；嵌套结构需显式json标签；切片需json:"items,omitempty"；validation注释类型名须匹配openapi v3（如integer非int）；spec.versions必须为数组且仅一个storage: true；addtoscheme顺序不可错。
CRD 的 Go 结构体定义不是“写完 struct 就能用”，关键在 JSON/YAML 标签、validation 注释、scheme 注册三者必须对齐，缺一不可。
字段必须带 json 和 yaml 标签，且指针 + omitempty 是默认安全写法
不加标签或漏掉 omitempty 会导致 kubectl apply 失败，错误是 OpenAPI schema 生成失败，不是运行时报错。K8s API Server 在加载 CRD 时就拒绝注册。
-
string字段别直接写Field string，要写成Field *string `json:"field,omitempty" yaml:"field,omitempty"` -
int32同理：用Replicas *int32 `json:"replicas,omitempty" yaml:"replicas,omitempty"` - 嵌套结构体字段必须显式加
json:"nested,omitempty"+struct{}，不能用map[string]interface{}—— controller-gen 不会生成合法 schema - 切片字段（如
[]string）必须带json:"items,omitempty"，否则kubectl describe会报错
// +kubebuilder:validation 注释必须显式声明，且类型名严格匹配 OpenAPI v3
make manifests 生成的 CRD YAML 默认没有 validation，一旦字段有约束但没注释，kubectl apply -f crd.yaml 会报 spec.validation.openAPIV3Schema.type is required。
- 必填字段加
// +kubebuilder:validation:Required（注意双斜杠+空格） - 字符串长度限制用
// +kubebuilder:validation:MinLength=1，数组长度用MinItems=1（不是MinLength） - 数字范围写
// +kubebuilder:validation:Minimum=0，布尔值无需额外注释 - 字段类型必须写
integer、boolean、string，不能写int或bool—— 否则 validation 静默失效
CRD YAML 的 spec.versions 必须是数组，且仅一个 storage: true
用 spec.version（单字段）会直接被 K8s 1.16+ 拒绝，报错信息明确指出 unknown field "version"。
-
spec.versions是数组，每个元素含name、served、storage - 仅一个版本可设
storage: true（推荐最新版，如v1） - 旧版（如
v1alpha1）可设served: true但storage: false，方便后续迁移 - 生成后务必检查 YAML 中
openAPIV3Schema.properties.spec.type是否存在，这是 validation 生效的前提
AddToScheme 调用顺序错乱会导致 panic：「no kind is registered for the type」
controller-runtime 启动时找不到你的 CR 类型，90% 是因为 scheme 注册顺序错了 —— 不是没注册，是注册得太晚。
- 必须先调
clientgoscheme.AddToScheme(scheme)，再调你自己的myappv1alpha1.AddToScheme(scheme) - 如果用了多版本（
v1alpha1和v1），两个都要注册，漏一个，watch 对应版本对象就会失败 -
Builder.For(&myappv1alpha1.MyApp{})中的类型必须和 CRD 的spec.group/spec.names.kind完全一致（大小写、复数、包路径都不能错） - 不要在
SetupWithManager里重复调AddToScheme—— Scheme 是全局单例，重复注册会 panic
最容易被忽略的是：validation 注释生成的 schema 字段类型必须和 OpenAPI v3 规范字面量完全一致，哪怕只是大小写差异（比如 Integer ≠ integer），K8s 就会静默跳过整段 validation。这问题没法靠编译发现，只能靠检查生成的 YAML。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
