OSS C++ SDK V2

环境准备

• C++17 及以上版本的编译器（GCC 7+、Clang 5+、MSVC 2017+）。

• CMake 3.15 及以上版本。

通过 cmake --version 命令查看 CMake 版本。如果当前环境没有 CMake 或版本低于 3.15，请下载并安装 CMake。

安装 SDK

建议使用 vcpkg 方式安装 OSS C++ SDK V2。

vcpkg install alibabacloud-oss-cpp-sdk-v2[curl]

# Windows 环境可改用 WinHTTP 作为 HTTP 传输层
vcpkg install alibabacloud-oss-cpp-sdk-v2[winhttp]

git clone https://github.com/aliyun/alibabacloud-oss-cpp-sdk-v2.git
vcpkg install alibabacloud-oss-cpp-sdk-v2[curl] --overlay-ports=alibabacloud-oss-cpp-sdk-v2/vcpkg --head

git clone https://github.com/aliyun/alibabacloud-oss-cpp-sdk-v2.git
cd alibabacloud-oss-cpp-sdk-v2
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build . --target install

在项目的 CMakeLists.txt 中添加依赖：

cmake_minimum_required(VERSION 3.15)
project(my-app)

find_package(alibabacloud_oss_v2 REQUIRED)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE alibabacloud_oss_v2::oss)

配置访问凭证

将 RAM 用户的 AccessKey 写入环境变量作为凭证。

在RAM 控制台，创建使用永久 AccessKey 访问的 RAM 用户，保存 AccessKey，然后为该用户授予AliyunOSSFullAccess权限。

初始化客户端

SDK 提供三种请求模式：OSSClient（同步）、OSSClient（异步）（基于线程池的异步请求）和 OSSAsyncClient（异步）（原生异步请求），按业务场景选择。以下示例均使用 ListBuckets 接口列出当前账号下的 Bucket。

#include <iostream>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();

    oss::OSSClient client(conf);

    auto outcome = client.listBuckets(
        oss::models::ListBucketsRequest());

    if (!outcome.has_value()) {
        auto& err = outcome.error();
        std::cerr << "Error Code: " << err.getCode() << std::endl;
        std::cerr << "Error Message: " << err.getMessage() << std::endl;
        std::cerr << "Request ID: " << err.getRequestId() << std::endl;
        return 1;
    }

    auto& result = outcome.value();
    for (auto& bucket : result.getBuckets()) {
        std::cout << "bucket: name:" << bucket.name
                  << ", region:" << bucket.region
                  << ", storageClass:" << bucket.storageClass
                  << std::endl;
    }

    return 0;
}

#include <future>
#include <iostream>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"
#include "alibabacloud/oss2/utils/DefaultExecutor.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
    // 关键：配置线程池，开启 OSSClient 的 asyncCall() 支持
    conf.executor = std::make_shared<oss::DefaultExecutor>();

    oss::OSSClient client(conf);

    // 异步调用，返回 std::future
    auto future = client.asyncCall(oss::models::ListBucketsRequest());

    // 通过 get() 等待结果（future 模式）
    auto outcome = future.get();
    if (!outcome.has_value()) {
        auto& err = outcome.error();
        std::cerr << "Error Code: " << err.getCode() << std::endl;
        std::cerr << "Error Message: " << err.getMessage() << std::endl;
        return 1;
    }

    auto& result = outcome.value();
    for (auto& bucket : result.getBuckets()) {
        std::cout << "bucket: name:" << bucket.name
                  << ", region:" << bucket.region << std::endl;
    }
    return 0;
}

#include <iostream>
#include <thread>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSAsyncClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();

    auto client = std::make_shared<oss::OSSAsyncClient>(conf);

    client->listBucketsAsync(
        oss::models::ListBucketsRequest(),
        oss::ListBucketsAsyncCallback([](oss::ListBucketsOutcome outcome) {
            if (!outcome.has_value()) {
                auto& err = outcome.error();
                std::cerr << "Error Code: " << err.getCode() << std::endl;
                std::cerr << "Error Message: " << err.getMessage() << std::endl;
                return;
            }

            auto& result = outcome.value();
            for (auto& bucket : result.getBuckets()) {
                std::cout << "bucket: name:" << bucket.name
                          << ", region:" << bucket.region
                          << ", storageClass:" << bucket.storageClass
                          << std::endl;
            }
        }));

    // 等待异步操作完成
    std::this_thread::sleep_for(std::chrono::seconds(5));

    return 0;
}

使用自定义域名

使用 OSS 默认域名访问时，可能会出现文件禁止访问、文件无法预览等问题；通过通过自定义域名访问OSS，不仅支持浏览器直接预览文件，还可结合 CDN 加速分发。

运行示例代码前，请将代码中的 <region-id> 替换为实际的地域和Endpoint，如 cn-hangzhou。

#include <iostream>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.endpoint = "https://your-custom-domain.com";
    conf.useCName = true;
    conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();

    oss::OSSClient client(conf);

    // 使用自定义域名进行操作
    auto outcome = client.putObject(
        oss::models::PutObjectRequest()
            .setBucket("your-bucket")
            .setKey("your-key")
            .setBody(oss::RequestBody::fromString("Hello, OSS!")));

    if (!outcome.has_value()) {
        auto& err = outcome.error();
        std::cerr << "Error: " << err.getMessage() << std::endl;
        return 1;
    }

    std::cout << "Upload successful" << std::endl;
    return 0;
}

超时控制

通过 connectTimeout 和 readWriteTimeout 配置连接超时和读写超时时间（单位：毫秒）。

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// 设置连接超时时间为 10 秒
conf.connectTimeout = 10000;
// 设置读写超时时间为 30 秒
conf.readWriteTimeout = 30000;

oss::OSSClient client(conf);

重试策略

C++ SDK V2 内置 StandardRetryer，默认使用 FullJitterBackoff 退避策略，最大尝试次数为 3。你可以通过 retryMaxAttempts 设置最大尝试次数。

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// 设置最大重试次数为 5
conf.retryMaxAttempts = 5;

oss::OSSClient client(conf);

更多自定义重试策略示例，请参见 CustomRetryStrategy.cpp。

HTTP/HTTPS 协议

默认使用 HTTPS 协议。如需使用 HTTP 协议，设置 disableSsl 为 true。

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// 使用 HTTP 协议
conf.disableSsl = true;

oss::OSSClient client(conf);

代理服务器

通过 proxyHost 配置代理服务器地址。

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// 设置代理服务器
conf.proxyHost = "http://your-proxy:8080";

oss::OSSClient client(conf);

使用内网域名

当应用部署在阿里云 ECS 上时，可以使用内网域名访问 OSS，减少公网流量费用。

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// 使用内网域名
conf.useInternalEndpoint = true;

oss::OSSClient client(conf);

使用传输加速域名

通过传输加速域名访问 OSS，提升远距离传输速度。

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// 使用传输加速域名
conf.useAccelerateEndpoint = true;

oss::OSSClient client(conf);

使用专有域名

使用自定义域名（CNAME）访问 OSS。

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
conf.endpoint = "https://your-custom-domain.com";
conf.useCName = true;

oss::OSSClient client(conf);

使用金融云域名

金融云地域的 OSS 使用特殊的 Endpoint。请在初始化时指定对应的 Endpoint。

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "cn-hangzhou";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
conf.endpoint = "https://oss-cn-hzjbp-a-internal.aliyuncs.com";

oss::OSSClient client(conf);

使用政务云域名

政务云地域的 OSS 使用特殊的 Endpoint。请在初始化时指定对应的 Endpoint。

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "cn-north-2-gov-1";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
conf.endpoint = "https://oss-cn-north-2-gov-1.aliyuncs.com";

oss::OSSClient client(conf);

自定义 HTTP 传输

C++ SDK V2 默认使用 Curl 作为 HTTP 传输层。你可以通过 httpTransport 替换为其他实现。Windows 平台还支持 WinHTTP。

自定义传输层示例，请参见 CurlCustomConfig.cpp 和 WinHttpCustomConfig.cpp。

使用 RAM 用户的 AK

如果您的应用程序部署在安全、稳定且不易被外部访问的环境中，可以使用 RAM 用户的 AccessKey。

#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::StaticCredentialsProvider>(
        "YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET");

    oss::OSSClient client(conf);
    // 使用 client 进行操作
    return 0;
}

使用 STS 临时凭证

如果您的应用程序需要临时访问 OSS，您可以通过 STS 服务获取临时身份凭证（AccessKey ID、AccessKey Secret 和 SecurityToken）初始化凭证提供者。需要注意的是，该方式需要您手动维护一个 STS Token，存在安全性风险和维护复杂度增加的风险。此外，如果您需要多次临时访问 OSS，您需要手动刷新 STS Token。

#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::StaticCredentialsProvider>(
        "STS_ACCESS_KEY_ID", "STS_ACCESS_KEY_SECRET", "STS_SECURITY_TOKEN");

    oss::OSSClient client(conf);
    // 使用 client 进行操作
    return 0;
}

使用 RAMRoleARN / ECSRAMRole / OIDCRoleARN

对于 RAMRoleARN、ECSRAMRole、OIDCRoleARN 等凭证方式，建议通过 alibabacloud-credentials-cpp 库配合 CredentialsProviderFunc 使用。

1. 安装依赖。

   vcpkg install alibabacloud-credentials-cpp

2. 在 CMakeLists.txt 中添加依赖。

   find_package(alibabacloud_credentials REQUIRED)

3. 通过 CredentialsProviderFunc 集成。

   RAMRoleARN

   #include "alibabacloud/oss2/ClientConfiguration.h"
   #include "alibabacloud/oss2/OSSClient.h"
   #include "alibabacloud/oss2/credentials/CredentialsProvider.h"
   #include <darabonba/core/Client.hpp>
   #include <alibabacloud/credential.hpp>
   
   namespace oss = alibabacloud::oss2;
   
   int main() {
       auto credConfig = std::make_shared<Alibabacloud_Credential::Config>();
       // 凭证类型固定为 ram_role_arn
       credConfig->type = std::make_shared<std::string>("ram_role_arn");
       // RAM 用户的 AccessKey ID。建议通过环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID 注入，避免硬编码
       credConfig->accessKeyId = std::make_shared<std::string>("YOUR_ACCESS_KEY_ID");
       // RAM 用户的 AccessKey Secret。建议通过环境变量 ALIBABA_CLOUD_ACCESS_KEY_SECRET 注入
       credConfig->accessKeySecret = std::make_shared<std::string>("YOUR_ACCESS_KEY_SECRET");
       // 要扮演的 RAM 角色 ARN，示例：acs:ram::123456789012****:role/adminrole
       // 也可通过环境变量 ALIBABA_CLOUD_ROLE_ARN 设置
       credConfig->roleArn = std::make_shared<std::string>("YOUR_ROLE_ARN");
       // 角色会话名称，用于审计区分。也可通过环境变量 ALIBABA_CLOUD_ROLE_SESSION_NAME 设置
       credConfig->roleSessionName = std::make_shared<std::string>("your-session-name");
       // （可选）通过 policy 进一步收窄权限至最小集合，非必填
       // 示例：{"Statement":[{"Action":["oss:GetObject"],"Effect":"Allow","Resource":["*"]}],"Version":"1"}
       // credConfig->policy = std::make_shared<std::string>("<Policy>");
       // （可选）角色会话有效期，单位为秒，默认 3600 秒（1 小时），非必填
       // credConfig->roleSessionExpiration = std::make_shared<long>(3600);
   
       auto credClient = std::make_shared<Alibabacloud_Credential::Client>(credConfig);
   
       auto conf = oss::ClientConfiguration::loadDefault();
       conf.region = "<region-id>";
       conf.credentialsProvider = std::make_shared<oss::CredentialsProviderFunc>(
           [credClient]() -> oss::Credentials {
               auto cred = credClient->getCredential();
               auto ak = cred.getAccessKeyId();
               auto sk = cred.getAccessKeySecret();
               if (ak.empty() || sk.empty()) {
                   return oss::Credentials::withRetryableError(
                       "failed to get credentials from alibabacloud-credentials-cpp");
               }
               auto token = cred.getSecurityToken();
               return oss::Credentials(std::move(ak), std::move(sk), std::move(token));
           });
   
       oss::OSSClient client(conf);
       // 使用 client 进行操作
       return 0;
   }

   ECSRAMRole

   #include "alibabacloud/oss2/ClientConfiguration.h"
   #include "alibabacloud/oss2/OSSClient.h"
   #include "alibabacloud/oss2/credentials/CredentialsProvider.h"
   #include <darabonba/core/Client.hpp>
   #include <alibabacloud/credential.hpp>
   
   namespace oss = alibabacloud::oss2;
   
   int main() {
       auto credConfig = std::make_shared<Alibabacloud_Credential::Config>();
       // 凭证类型固定为 ecs_ram_role
       credConfig->type = std::make_shared<std::string>("ecs_ram_role");
       // 为 ECS 授予的 RAM 角色名称。可选参数；不设置时 SDK 会自动从元数据服务检索，
       // 强烈建议显式设置以减少对元数据服务的请求
       credConfig->roleName = std::make_shared<std::string>("YOUR_ECS_ROLE_NAME");
   
       auto credClient = std::make_shared<Alibabacloud_Credential::Client>(credConfig);
   
       auto conf = oss::ClientConfiguration::loadDefault();
       conf.region = "<region-id>";
       conf.credentialsProvider = std::make_shared<oss::CredentialsProviderFunc>(
           [credClient]() -> oss::Credentials {
               auto cred = credClient->getCredential();
               auto ak = cred.getAccessKeyId();
               auto sk = cred.getAccessKeySecret();
               if (ak.empty() || sk.empty()) {
                   return oss::Credentials::withRetryableError(
                       "failed to get credentials from alibabacloud-credentials-cpp");
               }
               auto token = cred.getSecurityToken();
               return oss::Credentials(std::move(ak), std::move(sk), std::move(token));
           });
   
       oss::OSSClient client(conf);
       // 使用 client 进行操作
       return 0;
   }

   OIDCRoleARN

   #include "alibabacloud/oss2/ClientConfiguration.h"
   #include "alibabacloud/oss2/OSSClient.h"
   #include "alibabacloud/oss2/credentials/CredentialsProvider.h"
   #include <darabonba/core/Client.hpp>
   #include <alibabacloud/credential.hpp>
   
   namespace oss = alibabacloud::oss2;
   
   int main() {
       auto credConfig = std::make_shared<Alibabacloud_Credential::Config>();
       // 凭证类型固定为 oidc_role_arn
       credConfig->type = std::make_shared<std::string>("oidc_role_arn");
       // 要扮演的 RAM 角色 ARN。也可通过环境变量 ALIBABA_CLOUD_ROLE_ARN 设置
       credConfig->roleArn = std::make_shared<std::string>("YOUR_ROLE_ARN");
       // OIDC 身份提供商 ARN。也可通过环境变量 ALIBABA_CLOUD_OIDC_PROVIDER_ARN 设置
       credConfig->oidcProviderArn = std::make_shared<std::string>("YOUR_OIDC_PROVIDER_ARN");
       // OIDC Token 文件路径，由 RRSA 自动挂载到 Pod 内。也可通过环境变量 ALIBABA_CLOUD_OIDC_TOKEN_FILE 设置
       credConfig->oidcTokenFilePath = std::make_shared<std::string>("/var/run/secrets/tokens/oidc-token");
       // 角色会话名称，用于审计区分。也可通过环境变量 ALIBABA_CLOUD_ROLE_SESSION_NAME 设置
       credConfig->roleSessionName = std::make_shared<std::string>("your-session-name");
       // （可选）通过 policy 进一步收窄权限，非必填
       // credConfig->policy = std::make_shared<std::string>("<Policy>");
   
       auto credClient = std::make_shared<Alibabacloud_Credential::Client>(credConfig);
   
       auto conf = oss::ClientConfiguration::loadDefault();
       conf.region = "<region-id>";
       conf.credentialsProvider = std::make_shared<oss::CredentialsProviderFunc>(
           [credClient]() -> oss::Credentials {
               auto cred = credClient->getCredential();
               auto ak = cred.getAccessKeyId();
               auto sk = cred.getAccessKeySecret();
               if (ak.empty() || sk.empty()) {
                   return oss::Credentials::withRetryableError(
                       "failed to get credentials from alibabacloud-credentials-cpp");
               }
               auto token = cred.getSecurityToken();
               return oss::Credentials(std::move(ak), std::move(sk), std::move(token));
           });
   
       oss::OSSClient client(conf);
       // 使用 client 进行操作
       return 0;
   }

   更多凭证示例，请参见 credentials 示例。

使用匿名访问

如果请求的 Bucket 和 Object 已设置公共读权限，可以使用匿名访问。

#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::AnonymousCredentialsProvider>();

    oss::OSSClient client(conf);
    // 使用 client 进行操作
    return 0;
}

自定义凭证提供者

如果以上凭证方式不能满足需求，您可以通过 CredentialsProviderFunc 自定义凭证获取逻辑。

#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

#include <cstdlib>

namespace oss = alibabacloud::oss2;

// 示例：从自定义环境变量或配置文件加载凭证
static oss::Credentials loadCredentialsFromCustomSource() {
    // 在实际应用中，您可以从以下来源读取凭证：
    //   - 配置文件（如 ~/.ossrc）
    //   - 密钥管理服务（如 HashiCorp Vault、KMS）
    //   - 元数据服务
    //   - 数据库
    const char* ak = std::getenv("MY_APP_ACCESS_KEY_ID");
    const char* sk = std::getenv("MY_APP_ACCESS_KEY_SECRET");
    const char* token = std::getenv("MY_APP_SESSION_TOKEN");

    if (!ak || !sk) {
        // 错误信息会传播到 OperationError::getMessage()
        return oss::Credentials::withError(
            "MY_APP_ACCESS_KEY_ID and MY_APP_ACCESS_KEY_SECRET must be set");
        // 对于临时性故障（如网络超时），使用 withRetryableError，
        // SDK 将自动重试获取凭证。
        // return oss::Credentials::withRetryableError("...");
    }

    return oss::Credentials(ak, sk, token ? token : "");
}

int main() {
    // 自定义凭证提供函数在每次需要凭证时被调用，
    // 因此可以实现轮换、刷新或缓存逻辑。
    auto provider = std::make_shared<oss::CredentialsProviderFunc>(
        loadCredentialsFromCustomSource);

    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = provider;

    oss::OSSClient client(conf);
    // 使用 client 进行操作
    return 0;
}

接口命名规则

所有方法名采用 camelCase 风格，每个操作接受一个 <OperationName>Request 参数并返回 <OperationName>Outcome（即 Outcome<Result, Error>）。

OSSClient（同步）：

OutcomeType operationName(const models::OperationNameRequest& request, const OperationOptions* options = nullptr)

OSSAsyncClient（原生异步）：

void operationNameAsync(const models::OperationNameRequest& request, const OperationNameAsyncCallback& callback, const OperationOptions* options = nullptr)

调用方式

取消请求

长时间运行的操作可以通过 CancellationToken 取消。在 OperationOptions 中传入 cancellationToken，OSS C++ SDK V2 提供以下两种取消模式：

// 从其他线程主动取消请求
auto cts = oss::CancellationTokenSource::create();

oss::OperationOptions opts;
opts.cancellationToken = cts->getToken();

// 在另一线程发起请求
auto future = std::async([&]() {
    return client.getObject(request, &opts);
});

// 从当前线程取消
cts->cancel();

// 设置 30 秒超时自动取消
auto cts = oss::CancellationTokenSource::create();
cts->cancelAfter(std::chrono::seconds(30));

oss::OperationOptions opts;
opts.cancellationToken = cts->getToken();

auto outcome = client.getObject(request, &opts);

错误处理

OSS C++ SDK V2 使用 Outcome<Result, Error>，接口兼容 std::expected。判断成功使用 has_value()，成功通过 value()（或 *outcome）取结果，失败通过 error() 取错误对象。

auto outcome = client.putObject(request);

if (!outcome.has_value()) {
    auto& err = outcome.error();
    std::cerr << "错误码: " << err.getCode() << std::endl;
    std::cerr << "错误信息: " << err.getMessage() << std::endl;
    std::cerr << "EC: " << err.getEC() << std::endl;
    std::cerr << "请求 ID: " << err.getRequestId() << std::endl;
    std::cerr << "请求地址: " << err.getRequestTarget() << std::endl;
}

使用 -DUSE_STD_EXPECTED=ON（C++23）构建时，Outcome 将成为 std::expected 的类型别名，支持 .and_then()、.transform()、.or_else() 等一元操作。