Cloud SDK不同FluentHelper返回对象不一致及统一响应属性诉求

问题背景 #

使用Cloud SDK时存在FluentHelper行为不一致的问题：

• 成功请求时，FluentHelperByKey不返回响应头；但错误场景下FluentHelperCreate会携带响应头
• FluentHelperByKey、FluentHelperRead仅返回业务实体EntityT或实体列表List<EntityT>，而FluentHelperCreate可直接获取响应头、状态码等元数据

可行解决方案 #

1. 自定义提取响应头（适用于快速获取特定头信息）

针对查询类FluentHelper（ByKey/Read），可以通过withHttpHeaderExtractor钩子函数手动捕获响应头，不影响原有实体返回逻辑：

// FluentHelperByKey示例
YourEntity targetEntity = new YourEntityByKeyFluentHelper("target-key")
    .withHttpHeaderExtractor(headers -> {
        // 按需提取并保存响应头，比如获取自定义追踪ID
        String traceId = headers.getFirst("X-Request-Trace-Id");
        // 返回null不干扰实体结果的正常返回
        return null;
    })
    .execute(yourCloudService);

2. 获取完整响应对象（彻底统一所有FluentHelper的返回形式）

所有FluentHelper都支持executeRequest方法，该方法会返回包含完整响应元数据的HttpResponse对象，不管是查询还是写操作都能拿到一致的返回结构：

// 获取FluentHelperByKey的完整响应
HttpResponse<YourEntity> fullResponse = new YourEntityByKeyFluentHelper("target-key")
    .executeRequest(yourCloudService);

// 从响应中获取业务实体
YourEntity entity = fullResponse.getBody();
// 获取响应头集合
HttpHeaders responseHeaders = fullResponse.getHeaders();
// 获取HTTP状态码
int statusCode = fullResponse.getStatusCode();

这种方式完全规避了不同FluentHelper的返回差异，所有请求都能拿到统一格式的响应封装。

3. 建议官方统一行为

如果希望从根源上解决这种不一致性，可以向Cloud SDK官方提交Feature Request，建议：

• 为所有FluentHelper提供统一的响应元数据访问API
• 或者将所有FluentHelper的默认返回改为包含实体+响应元数据的封装对象

内容的提问来源于stack exchange，提问作者Stephan