请求模型约定

必填字段

每个方法在发送请求前都会校验必要参数，校验失败直接返回 error，请求不会发出。错误信息形如 request clusterId should not be null or empty。请求指针为 nil 时返回 request should not be nil。

常见必填字段：

指针类型与值类型

结构体字段的 json tag 大量使用 omitempty：零值字段不会出现在请求体中。因此同一个语义值，用指针类型还是值类型承载，发送结果并不相同：

• 指针类型（*bool、*int、*int64、*string）为 nil 时不发送该字段；取地址赋值后发送，包括 0、false 等零值。用于区分"未设置"与"显式设为零值"。
• 值类型带 omitempty 时，零值会被省略，无法表达"显式传 0/false"。
• 值类型不带 omitempty 时始终按当前值发送，未赋值即发送 0 或 false。

需要显式发送 false 或 0 时，必须使用指针字段：

1disabled := false
2
3request := &kafka.SwitchClusterAdvertisedIpRequest{
4	ClusterID:           "{{集群 ID}}",
5	AdvertisedIPEnabled: &disabled,   // 明确发送 false
6}

Provisioned 中的 PublicIPEnabled、PublicIPBandwidth、IntranetIPEnabled、ACLEnabled、NumberOfBrokerNodes、DeploySetEnabled 是不带 omitempty 的值类型，始终随请求发送，构造 CreateCluster 请求时应显式赋值，不要依赖"未设置"语义。

请求结构体中的常见指针字段按语义归类如下：

响应结构体同样大量使用指针，读取前必须判空，否则会 panic：

所有 Get*Response 中承载主体数据的字段都是结构体指针，例如 GetClusterDetailResponse.Cluster、GetTopicDetailResponse.Topic、GetJobDetailResponse.Job。

集合字段

请求中的切片与 map 为 nil 时不发送；显式设置为空集合时会发送空数组或空对象。只有服务端支持清空的字段才应传递显式空集合。

1// nil：字段不发送
2request := &kafka.CreateClusterRequest{Name: "demo"}
3
4// 非 nil 空切片：发送 "tags": []
5request := &kafka.CreateClusterRequest{
6	Name: "demo",
7	Tags: []kafka.Tag{},
8}

omitempty 本身会把非 nil 的空集合一并省略，因此 21 个结构体实现了自定义 MarshalJSON，用 marshalWithPresentCollections 保证空集合语义不丢失：

Provisioned 同样实现了 MarshalJSON，覆盖 subnets、logicalZones、securityGroups、securityGroup、subnetIds、securityGroupIds、authentications、maintenancePeriods 八个集合字段。

CreateTopicRequest.OtherConfigs 与 UpdateTopicRequest.OtherConfigs 使用 map[string]string，键为 Kafka 主题级参数名，值统一为字符串。

另有两个结构体的 MarshalJSON 用于补齐默认值而非保留空集合：

• ConfigMeta：Context 为 nil 时序列化成空对象 {}，且 context 字段总会出现。
• StorageMeta：NumberOfDisk 为 0 时序列化成 1。

模型默认值

Go 结构体字面量的字段默认为零值。三个结构体提供 New* 构造函数以获得非零默认值：

直接用字面量构造这三个结构体不会得到上述默认值，所有字段都是零值，需要按需手动传入。

两处默认值在序列化阶段仍会兜底：StorageMeta.NumberOfDisk 为 0 时按 1 发送；ConfigMeta.Context 为 nil 时按 {} 发送。Billing 的 MarshalJSON 会强制发送 timeUnit、autoRenewTimeUnit、isAutoPay 三个字段，即使为零值。

分页默认值不在结构体上，而在方法内部：ListTopicPartitions 的 PageNo 为 nil 时按 1 处理，PageSize 为 nil 时按 10 处理。