Lib.rs

OpenFeature Rust SDK

OpenFeature 是一个开放标准，提供了一种供应商无关、社区驱动的 API，用于功能标志，可以与您喜欢的功能标志管理工具配合使用。

🚀 快速入门

需求

此包是用 Rust 版本 1.70.0 构建的。早期版本可能也可以工作，但不保证。

安装

将以下内容添加到 Cargo.toml 文件中

open-feature = "0.2.4"

用法

async fn example() -> Result<(), Error> {
    // Acquire an OpenFeature API instance.
    // Note the `await` call here because asynchronous lock is used to
    // guarantee thread safety.
    let mut api = OpenFeature::singleton_mut().await;

    // Configure a provider.
    // By default [`NoOpProvider`] is used.
    api.set_provider(NoOpProvider::default()).await;

    // create a client
    let client = api.get_client();

    // get a bool flag value
    let is_feature_enabled = client
        .get_bool_value("v2_enabled", None, None)
        .unwrap_or(false)
        .await;

    Ok(())
}

请注意，默认的 NoOpProvider 总是为任何给定的输入返回 Err。

扩展示例

#[tokio::test]
async fn extended_example() {
    // Acquire an OpenFeature API instance.
    let mut api = OpenFeature::singleton_mut().await;

    // Set the default (unnamed) provider.
    api.set_provider(NoOpProvider::default()).await;

    // Create an unnamed client.
    let client = api.create_client();

    // Create an evaluation context.
    // It supports types mentioned in the specification.
    let evaluation_context = EvaluationContext::default()
        .with_targeting_key("Targeting")
        .with_custom_field("bool_key", true)
        .with_custom_field("int_key", 100)
        .with_custom_field("float_key", 3.14)
        .with_custom_field("string_key", "Hello".to_string())
        .with_custom_field("datetime_key", time::OffsetDateTime::now_utc())
        .with_custom_field(
            "struct_key",
            EvaluationContextFieldValue::Struct(Arc::new(MyStruct::default())),
        )
        .with_custom_field("another_struct_key", Arc::new(MyStruct::default()))
        .with_custom_field(
            "yet_another_struct_key",
            EvaluationContextFieldValue::new_struct(MyStruct::default()),
        );

    // This function returns a `Result`.
    // You can process it with functions provided by std.
    let is_feature_enabled = client
        .get_bool_value("SomeFlagEnabled", Some(&evaluation_context), None)
        .await
        .unwrap_or(false);

    if is_feature_enabled {
        // Let's get evaluation details.
        let _result = client
            .get_int_details("key", Some(&evaluation_context), None)
            .await;
    }
}

从提供者获取结构

可以从提供者中提取结构。内部，此 SDK 定义了一个类型 StructValue 来存储任何结构值。函数 client.get_struct_value() 接受一个类型参数 T。它将尝试将提供者解析的 StructValue 转换为 T，只要 T 实现了特例 TryFrom<StructValue>。

您可以将满足此特例约束的类型传递进来。当转换失败时，它返回一个带有 EvaluationReason::TypeMismatch 的 Err。

API 参考

请参阅 此处 的 API 文档。

🌟 功能

_{已实现：✅ | 进行中：⚠️ | 尚未实现：❌}

提供者

提供者是标志管理系统和OpenFeature SDK之间的抽象。请在此查看所有可用的提供者列表。如果您正在寻找的提供者尚未创建，请参阅开发提供者部分以了解如何自己构建。

一旦将提供者作为依赖项添加，就可以像这样将其注册到OpenFeature

// Set the default feature provider. Please replace the `NoOpProvider` with the one you want.
// If you do not do that, [`NoOpProvider`] will be used by default.
//
// [`NoOpProvider`] always returns `Err` despite any input. You can use functions like 
// `unwrap_or()` to specify default values.
//
// If you set a new provider after creating some clients, the existing clients will pick up
// the new provider you just set.
//
// You must `await` it to let the provider's initialization to finish.
let mut api = OpenFeature::singleton_mut().await;
api.set_provider(NoOpProvider::default()).await;

在某些情况下，在同一个应用程序中注册多个提供者可能有益。这可以通过使用命名客户端来实现，下面将详细介绍。

目标

有时，标志的值必须考虑关于应用程序或用户的某些动态标准，例如用户的地理位置、IP、电子邮件地址或服务器的位置。在OpenFeature中，我们将其称为目标。如果您使用的标志管理系统支持目标，则可以使用评估上下文提供输入数据。

// Create a global evaluation context and set it into the API.
// Note that this is optional. By default it uses an empty one.
let mut api = OpenFeature::singleton_mut().await;
api.set_evaluation_context(global_evaluation_context).await;

// Set client level evaluation context.
// It will overwrite the global one for the existing keys.
let mut client = api.create_client();
client.set_evaluation_context(client_evaluation_context);

// Pass evaluation context in evaluation functions.
// This one will overwrite the globla evaluation context and 
// the client level one.
client.get_int_value("flag", Some(&evaluation_context), None);

钩子

钩子尚未在Rust SDK中提供。

日志记录

日志自定义尚未在Rust SDK中提供。

命名客户端

可以为客户端指定一个名称。名称是一个逻辑标识符，可以用于将客户端与特定提供者相关联。如果没有与名称关联的提供者，则使用全局提供者。

// Create a named provider and bind it.
api.set_named_provider("named", NoOpProvider::default()).await;

// This named client will use the feature provider bound to this name.
let client = api.create_named_client("named");

assert_eq!(client.get_int_value("key", None, None).await.unwrap(), 42);

事件

事件尚未在Rust SDK中提供。

关闭

OpenFeature API提供了一个关闭函数来清理所有注册的提供者。仅在您的应用程序正在关闭过程中时才应调用此函数。

// This will clean all the registered providers and invoke their `shutdown()` function.
let api = OpenFeature::singleton_mut().await;
api.shutdown();

扩展

开发提供者

要开发提供者，您需要创建一个新项目并将OpenFeature SDK作为依赖项。这可以是一个新的存储库，也可以包含在OpenFeature组织下的现有 contrib 存储库中。然后您需要通过实现OpenFeature SDK导出的FeatureProvider接口来编写提供者。

请检查NoOpProvider的源代码以获取示例。

已构建新的提供者？告诉我们，以便我们可以将其添加到文档中！

开发钩子

钩子尚未在Rust SDK中提供。

⭐️ 支持项目

• 为这个仓库点一个⭐️！
• 在社交媒体上关注我们
  • Twitter: @openfeature
  • LinkedIn: OpenFeature
• 加入我们的Slack
• 更多信息，请查看我们的社区页面

🤝 贡献

有兴趣贡献？太好了，我们非常乐意得到您的帮助！要开始，请查看CONTRIBUTING指南。

感谢所有已经做出贡献的人

由 contrib.rocks 制作。