必填字段

每个方法在发送请求前都会校验必要参数，校验失败抛出 IllegalArgumentException，异常信息形如 request clusterId should not be null or empty string.。请求对象本身不能为 null。

常见必填字段：

包装类型与基本类型

请求体序列化使用 Jackson，且配置为 Include.NON_NULL：值为 null 的字段不会出现在请求体中。因此包装类型与基本类型的语义不同：

• 包装类型（Integer、Long、Boolean）为 null 时不发送该字段，显式赋值时发送，包括 0、false 等零值。
• 基本类型（int、long、boolean）没有"未设置"状态，始终按当前值发送，未赋值时发送 0 或 false。

Provisioned 中的 publicIpEnabled、intranetIpEnabled、aclEnabled、deploySetEnabled、numberOfBrokerNodes、publicIpBandwidth 都是基本类型，构造 createCluster 请求时应显式赋值，不要依赖"未设置"语义。

集合字段

请求中的 List、Set、Map 为 null 时不发送；显式设置为空集合时会发送空数组或空对象。只有服务端支持清空的字段才应传递显式空集合。

CreateTopicRequest.otherConfigs 与 UpdateTopicRequest.otherConfigs 使用 Map<String, String>，键为 Kafka 主题级参数名，值统一为字符串。

Lombok 与 Builder

模型类使用 Lombok @Data 生成 getter/setter。部分模型额外提供 @Builder，可以链式构造：

1Tag tag = Tag.builder().tagKey("KAFKA-Cluster").tagValue("prod").build();
2
3StorageMeta storageMeta = StorageMeta.builder()
4        .storageType(StorageType.ENHANCED_SSD_PL1)
5        .storageSize(100)
6        .numberOfDisk(1)
7        .build();

提供 Builder 的模型包括 CreateClusterRequest、Provisioned、Billing、StorageMeta、StoragePolicy、ConfigMeta、Authentication、Tag、Vpc、Subnet、SecurityGroup、ListUsersRequest、ListAclRequest 等。

模型默认值

少数模型带有字段初始值，直接 new 即可获得：

使用 @Builder 构造时，未显式设置的字段不会保留上述初始值，需要按需手动传入。

枚举取值

Cluster.mode、Cluster.type、Cluster.state、Authentication.mode、Acl.patternType 等响应字段是 String 而非枚举，比较时以服务端返回的字符串为准。