Sdílet prostřednictvím

Správa funkcí Go

Knihovna pro správu funkcí Go poskytuje způsob, jak vyvíjet a zveřejňovat funkce aplikace na základě příznaků funkcí. Po vytvoření nové funkce má mnoho aplikací zvláštní požadavky, například kdy by měla být tato funkce povolená a za jakých podmínek. Tato knihovna poskytuje způsob, jak tyto relace definovat, a také se integruje do běžných vzorů kódu Go, aby bylo možné tyto funkce odhalit.

Příznaky funkcí poskytují způsob, jak aplikace Go dynamicky zapnout nebo vypnout funkce. Vývojáři můžou používat příznaky funkcí v jednoduchých případech použití, jako jsou podmíněné příkazy.

Tady jsou některé výhody používání knihovny pro správu funkcí Go:

  • Běžná konvence správy funkcí
  • Nízká bariéra pro vstup
    • Zdroj konfiguračního přepínače funkcí Azure App Configuration
  • Správa životnosti funkčních příznaků
    • Hodnoty konfigurace se můžou v reálném čase měnit.
  • Probírané scénáře jednoduché až složité
    • Zapnutí a vypnutí funkcí
    • Dynamické vyhodnocení stavu funkce na základě volání serveru

Knihovna pro správu funkcí Go je opensourcová. Další informace najdete v úložišti GitHub.

Hlavní příznaky

Příznaky funkcí můžou být povolené nebo zakázané. Stav příznaku lze podmíněně provést pomocí filtrů funkcí.

Filtry funkcí

Filtry funkcí definují scénář, kdy má být funkce povolená. Když se funkce vyhodnotí, jestli je zapnutá nebo vypnutá, její seznam filtrů funkcí se projde, dokud se některý z filtrů nerozhodne, že by měla být funkce povolená. V tomto okamžiku se funkce považuje za povolenou a procházení přes filtry funkcí se zastaví. Pokud žádný filtr funkcí indikuje, že by měla být tato funkce povolená, považuje se za zakázanou.

Jako příklad je možné navrhnout filtr funkcí prohlížeče Microsoft Edge. Tento filtr funkcí by aktivoval všechny funkce, které jsou k němu připojené, pokud požadavek HTTP pochází z Microsoft Edge.

Konfigurace přepínače funkcí

Správa funkcí Go podporuje využívání příznaků funkcí definovaných ve službě Azure App Configuration integrovaným poskytovatelem azappconfigpříznaků funkcí a také bodem rozšiřitelnosti prostřednictvím FeatureFlagProvider rozhraní pro využívání příznaků funkcí definovaných jinými poskytovateli.

import (
    "context"
    "log"

    "github.com/Azure/AppConfiguration-GoProvider/azureappconfiguration"
    "github.com/microsoft/Featuremanagement-Go/featuremanagement"
    "github.com/microsoft/Featuremanagement-Go/featuremanagement/providers/azappconfig"
)


// ... ...
// Load Azure App Configuration
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
if err != nil {
    log.Fatalf("Failed to load configuration: %v", err)
}


// Create feature flag provider
featureFlagProvider, err := azappconfig.NewFeatureFlagProvider(appConfig)
if err != nil {
    log.Fatalf("Error creating feature flag provider: %v", err)
}

// Create feature manager
featureManager, err := featuremanagement.NewFeatureManager(featureFlagProvider, nil)
if err != nil {
    log.Fatalf("Error creating feature manager: %v", err)
}

Deklarace příznaku funkce

Následující příklad ukazuje formát použitý k nastavení příznaků funkcí v souboru JSON.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": true
            },
            {
                "id": "FeatureU",
                "enabled": false
            },
            {
                "id": "FeatureV",
                "enabled": true,
                "conditions": {
                    "client_filters": [
                        {
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Část feature_management dokumentu JSON se používá podle konvence k načtení nastavení funkčních příznaků. Objekty příznaku funkce musí být uvedeny v feature_flags poli v oddílu feature_management .

V předchozí části vidíme tři různé funkce. Příznak funkce má id a enabled vlastnosti. Jedná se id o název použitý k identifikaci příznaku funkce a odkaz na tento příznak. Vlastnost enabled určuje povolený stav příznaku funkce. Funkce je vypnutá, pokud není povolená. Pokud enabled je pravda, stav funkce závisí na podmínkách. Pokud neexistují žádné podmínky, je tato funkce zapnutá. Pokud jsou splněné podmínky, funkce je zapnutá. Pokud existují podmínky a nejsou splněné, je tato funkce vypnutá. Vlastnost conditions deklaruje podmínky použité k dynamickému povolení funkce. Vlastnosti definují své filtry funkcí v poli client_filters. FeatureV určuje filtr funkcí s názvem Microsoft.TimeWindow. Tento filtr je příkladem konfigurovatelného filtru funkcí. V příkladu vidíme, že filtr má Parameters vlastnost. Tato vlastnost slouží ke konfiguraci filtru. V tomto případě se konfigurují počáteční a koncové časy aktivní funkce.

Podrobné schéma oddílu feature_management najdete tady.

Pokročilé: Použití dvojtečky ':' je zakázáno v názvech příznaků funkcí.

Deklarace zapnutí/vypnutí

Následující fragment kódu ukazuje alternativní způsob, jak definovat funkci pro jednoduché funkce zapnuto/vypnuto.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": "true"
            },
            {
                "id": "FeatureX",
                "enabled": "false"
            }
        ]
    }
}

Typ požadavku

Vlastnost requirement_type příznaku funkce se používá k určení, jestli filtry mají použít Any nebo All logiku při vyhodnocování stavu funkce. Pokud requirement_type není zadána, výchozí hodnota je Any.

  • Any znamená, že pouze jeden filtr musí být vyhodnocen jako true, aby byla funkce povolená.
  • All znamená, že každý filtr musí být vyhodnocen jako true, aby byla funkce povolená.

requirement_type All mění procházení. Za prvé, pokud nejsou k dispozici žádné filtry, je tato funkce zakázaná. Potom se filtry funkcí procházejí, dokud se některý z filtrů nerozhodne, že by měla být tato funkce zakázaná. Pokud žádný filtr neukazuje, že by funkce měla být zakázaná, považuje se za povolenou.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureW",
                "enabled": "true",
                "conditions": {
                    "requirement_type": "All",
                    "client_filters": [
                        {
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                            }
                        },
                        {
                            "name": "Percentage",
                            "parameters": {
                                "Value": "50"
                            }
                        }
                    ]
                }
            },
        ]
    }
}

V předchozím příkladu FeatureW určuje requirement_type z All, což znamená, že všechny jeho filtry musí být vyhodnoceny jako true, aby byla funkce povolena. V tomto případě je tato funkce povolená pro 50 % uživatelů během zadaného časového intervalu.

Spotřeba

Základní forma správy funkcí kontroluje, jestli je povolený příznak funkce, a pak provádí akce na základě výsledku. Prostřednictvím metody FeatureManagerIsEnabled se provádí kontrola stavu příznaku funkce.

// Create feature flag provider
featureFlagProvider, err := azappconfig.NewFeatureFlagProvider(appConfig)
if err != nil {
    log.Fatalf("Error creating feature flag provider: %v", err)
}

// Create feature manager
featureManager, err := featuremanagement.NewFeatureManager(featureFlagProvider, nil)
if err != nil {
    log.Fatalf("Error creating feature manager: %v", err)
}

// Check if feature is enabled
enabled, err := featureManager.IsEnabled("FeatureX")
if err != nil {
    log.Printf("Error checking feature: %v", err)
    return
}

if enabled {
    // Do something
}

Implementace filtru funkcí

Vytvoření filtru funkcí poskytuje způsob, jak povolit funkce na základě kritérií, která definujete. Aby bylo možné implementovat filtr funkcí, musí být implementováno FeatureFilter rozhraní. FeatureFilter má metodu s názvem Evaluate. Pokud je funkce přidružena k filtru, Evaluate metoda je vyvolána během vyhodnocení. Pokud se Evaluate vrátí jako true, funkce se považuje za povolenou.

type FeatureFilter interface {
	// Name returns the identifier for this filter
	Name() string

	// Evaluate determines whether a feature should be enabled based on the provided contexts
	Evaluate(evalCtx FeatureFilterEvaluationContext, appCtx any) (bool, error)
}

type FeatureFilterEvaluationContext struct {
	// FeatureName is the name of the feature being evaluated
	FeatureName string

	// Parameters contains the filter-specific configuration parameters
	Parameters map[string]any
}

Následující fragment kódu ukazuje, jak implementovat přizpůsobený filtr funkcí.

type MyCustomFilter struct{}

func (f *MyCustomFilter) Evaluate(ctx context.Context, context *FeatureFilterEvaluationContext) bool {
    // Custom logic to determine if feature should be enabled
    if satisfyCriteria() {
        return true
    }
    return false
}

func (f *MyCustomFilter) Name() string {
    return "MyCustomFilter"
}

Filtry funkcí jsou registrovány jejich poskytnutím při vytváření FeatureManager. Pokud vlastní filtr funkcí potřebuje nějaký kontext, můžete ho předat prostřednictvím parametru FeatureFilterEvaluationContext .

// Register custom filters
options := &featuremanagement.Options{
    Filters: []featuremanagement.FeatureFilter{
        &MyCustomFilter{},
    },
}

// Create feature manager with custom filters
featureManager, err := featuremanagement.NewFeatureManager(featureFlagProvider, options)
if err != nil {
    log.Fatalf("Error creating feature manager: %v", err)
}

Atribut aliasu filtru

Pokud je filtr funkcí zaregistrovaný pro příznak funkce, použije se jeho název jako výchozí alias. Tento identifikátor můžete přepsat implementací Name() metody, která určuje název, který se má použít v konfiguraci při odkazování na filtr v rámci příznaku funkce.

Chybějící filtry funkcí

Pokud je funkce nakonfigurovaná tak, aby byla povolená pro určitý filtr funkcí a tento filtr funkcí není zaregistrovaný, vrátí se při vyhodnocení funkce chyba.

Předdefinované filtry funkcí

Existují dva filtry funkcí, které jsou součástí featuremanagement balíčku: TimeWindowFiltera TargetingFilter.

Každý z předdefinovaných filtrů funkcí má vlastní parametry. Tady je seznam filtrů funkcí spolu s příklady.

Microsoft.TimeWindow

Tento filtr poskytuje možnost povolit funkci na základě časového intervalu. Pokud je zadán pouze End, bude funkce považována za zapnutou až do toho okamžiku. Pokud je zadáno pouze Start, bude tato funkce považována za zapnutou ve všech bodech po uplynutí této doby.

"client_filters": [
    {
        "name": "Microsoft.TimeWindow",
        "parameters": {
            "Start": "Wed, 01 May 2019 13:59:59 GMT",
            "End": "Mon, 01 Jul 2019 00:00:00 GMT"
        }
    }
]

Microsoft.Targeting

Tento filtr poskytuje možnost povolit funkci cílové cílové skupině. Podrobné vysvětlení cílení je vysvětleno v části cílení níže. Parametry filtru zahrnují Audience objekt, který popisuje uživatele, skupiny, vyloučené uživatele/skupiny a výchozí procento uživatelské základny, které by měly mít přístup k této funkci. Každý objekt skupiny, který je uveden v oddílu Groups , musí také určit, jaké procento členů skupiny by mělo mít přístup. Pokud je uživatel zadaný v oddílu Exclusion , buď přímo, nebo pokud je uživatel ve vyloučené skupině, je tato funkce zakázaná. Jinak platí, že pokud je uživatel zadán přímo v oddílu Users, nebo pokud je uživatel zahrnut v procentech zavádění některé skupiny, nebo pokud spadá do výchozího procenta zavádění, bude mít tento uživatel povolenou funkci.

"client_filters": [
    {
        "name": "Microsoft.Targeting",
        "parameters": {
            "Audience": {
                "Users": [
                    "Jeff",
                    "Alicia"
                ],
                "Groups": [
                    {
                        "Name": "Ring0",
                        "RolloutPercentage": 100
                    },
                    {
                        "Name": "Ring1",
                        "RolloutPercentage": 50
                    }
                ],
                "DefaultRolloutPercentage": 20,
                "Exclusion": {
                    "Users": [
                        "Ross"
                    ],
                    "Groups": [
                        "Ring2"
                    ]
                }
            }
        }
    }
]

Targeting

Cílení je strategie správy funkcí, která vývojářům umožňuje postupně zavádět nové funkce do uživatelské základny. Strategie je založená na konceptu cílení na skupinu uživatelů, kteří se označují jako cílová skupina. Cílová skupina se skládá z konkrétních uživatelů, skupin, vyloučených uživatelů/skupin a určeného procenta celé uživatelské základny. Skupiny, které jsou součástí cílové skupiny, je možné dále rozdělit do procent jejich celkových členů.

Následující kroky ukazují příklad postupného zavedení nové funkce Beta:

  1. Jednotlivým uživatelům Jeff a Alicia jsou udělen přístup k beta verzi.
  2. Jiný uživatel, Mark, žádá, aby se přihlásil a je zahrnutý.
  3. Do beta verze je zahrnuta dvacet procent skupiny, která se označuje jako "Ring1".
  4. Počet uživatelů v okruhu "Ring1" zahrnutých v beta verzi se zvýší na 100 procent.
  5. Součástí beta verze je pět procent uživatelské základny.
  6. Procento zavedení se zvýší na 100 procent a funkce je zcela zavedena.

Tato strategie pro zavádění funkce je součástí knihovny prostřednictvím zahrnutého filtru funkcí Microsoft.Targeting .

Cílení na uživatele

Filtr cílení spoléhá na kontext cílení a vyhodnocuje, jestli má být funkce zapnutá. Tento kontext cílení obsahuje informace, jako je například aktuálně vyhodnocený uživatel a v jakých skupinách se uživatel nachází. Kontext cílení musí být předán přímo při zavolání IsEnabledWithAppContext.

// ... ...
// Create targeting context
targetingCtx := featuremanagement.TargetingContext{
    UserID: "test_user",
    Groups: []string{"Ring1"},
}

// Check if feature is enabled for the user
enabled, err := featureManager.IsEnabledWithAppContext("Beta", targetingCtx)
if err != nil {
    log.Printf("Error checking feature: %v", err)
    return
}

if enabled {
    // Feature is enabled for this user
}

Vyloučení z cílení

Při definování cílové skupiny mohou být uživatelé a skupiny vyloučeni z cílové skupiny. Vyloučení jsou užitečná pro to, když se funkce zavádí do skupiny uživatelů, ale z zavedení je potřeba vyloučit několik uživatelů nebo skupin. Vyloučení je definováno přidáním seznamu uživatelů a skupin do Exclusion vlastnosti cílové skupiny.

"Audience": {
    "Users": [
        "Jeff",
        "Alicia"
    ],
    "Groups": [
        {
            "Name": "Ring0",
            "RolloutPercentage": 100
        }
    ],
    "DefaultRolloutPercentage": 0,
    "Exclusion": {
        "Users": [
            "Mark"
        ]
    }
}

V předchozím příkladu je funkce povolena pro uživatele pojmenované Jeff a Alicia. Je také povolená pro uživatele ve skupině s názvem Ring0. Pokud je však uživatel pojmenován Mark, je funkce zakázaná bez ohledu na to, jestli jsou ve skupině Ring0 nebo ne. Vyloučení mají přednost před zbytkem filtru cílení.

Varianty

Když se do aplikace přidají nové funkce, může přijít čas, kdy má funkce několik různých navrhovaných možností návrhu. Běžným řešením pro rozhodování o návrhu je určitá forma testování A/B. Testování A/B zahrnuje poskytnutí jiné verze funkce různým segmentům uživatelské základny a výběru verze na základě interakce uživatele. V této knihovně je tato funkce povolena reprezentací různých konfigurací funkce s variantami.

Varianty umožňují, aby se příznak funkce stal více než jednoduchým příznakem zapnuto/vypnuto. Varianta představuje hodnotu příznaku funkce, který může být řetězec, číslo, logická hodnota nebo dokonce objekt konfigurace. Příznak funkce, který deklaruje varianty, by měl definovat za jakých okolností se má každá varianta použít, která je podrobněji popsána v části Přidělování variant .

type Variant struct {
	// Name uniquely identifies this variant
	Name string

	// ConfigurationValue holds the value for this variant
	ConfigurationValue any
}

Získání variant

Pro každou funkci lze variantu načíst pomocí metody FeatureManager objektu GetVariant. Přiřazení varianty závisí na uživateli, kterého se právě vyhodnocuje, a informace se získávají z kontextu cílení, který jste předali.

targetingCtx := featuremanagement.TargetingContext{
    UserID: "Adam",
}

variant, err := featureManager.GetVariant("TestVariants", targetingCtx)
if err != nil {
    log.Printf("Error getting variant: %v", err)
    return
}

if variant != nil {
    variantConfiguration := variant.Configuration

    // Do something with the resulting variant and its configuration
}

Deklarace funkčního příznaku varianty

Ve srovnání s normálními příznaky funkcí mají příznaky varianty dvě další vlastnosti: variants a allocation. Vlastnost variants je pole, které obsahuje varianty definované pro tuto funkci. Vlastnost allocation definuje, jak mají být tyto varianty přiděleny pro tuto funkci. Stejně jako deklarování normálních příznaků funkcí můžete v souboru JSON nastavit příznaky variant funkcí. Tady je příklad variantního přepínače funkce.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "enabled": true,
                "allocation": {
                    "default_when_enabled": "Small",
                    "group": [
                        {
                            "variant": "Big",
                            "groups": [
                                "Ring1"
                            ]
                        }
                    ]
                },
                "variants": [
                    { 
                        "name": "Big"
                    },  
                    { 
                        "name": "Small"
                    } 
                ]
            }
        ]
    }
}

Definování variant

Každá varianta má dvě vlastnosti: název a konfiguraci. Název se používá k odkazování na konkrétní variantu a konfigurace je hodnota této varianty. Konfiguraci lze nastavit pomocí configuration_value vlastnosti. configuration_value je vložená konfigurace, která může být řetězec, číslo, logická hodnota nebo objekt konfigurace. Pokud configuration_value není zadána, vrácená vlastnost varianty Configuration je nil.

Seznam všech možných variant je definován pro každou funkci v rámci variants vlastnosti.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "variants": [
                    { 
                        "name": "Big", 
                        "configuration_value": {
                            "Size": 500
                        }
                    },  
                    { 
                        "name": "Small", 
                        "configuration_value": {
                            "Size": 300
                        }
                    } 
                ]
            }
        ]
    }
}

Přidělování variant

Proces přidělování variant funkce je určen allocation vlastností funkce.

"allocation": { 
    "default_when_enabled": "Small", 
    "default_when_disabled": "Small",  
    "user": [ 
        { 
            "variant": "Big", 
            "users": [ 
                "Marsha" 
            ] 
        } 
    ], 
    "group": [ 
        { 
            "variant": "Big", 
            "groups": [ 
                "Ring1" 
            ] 
        } 
    ],
    "percentile": [ 
        { 
            "variant": "Big", 
            "from": 0, 
            "to": 10 
        } 
    ], 
    "seed": "13973240" 
},
"variants": [
    { 
        "name": "Big", 
        "configuration_value": "500px"
    },  
    { 
        "name": "Small", 
        "configuration_value": "300px"
    } 
]

Nastavení allocation funkce má následující vlastnosti:

Vlastnictví Description
default_when_disabled Určuje, která varianta se má použít, když se vyžaduje varianta, zatímco je tato funkce považována za zakázanou.
default_when_enabled Určuje, která varianta se má použít, když je varianta požadována, zatímco je funkce považována za povolenou a uživateli nebyla přiřazena žádná jiná varianta.
user Určuje variantu a seznam uživatelů, kterým má být tato varianta přiřazena.
group Určuje variantu a seznam skupin. Varianta je přiřazena, pokud je uživatel alespoň v jedné ze skupin.
percentile Určuje variantu a procentní rozsah, do kterého musí zapadat vypočítané procento uživatele, aby mu byla tato varianta přiřazena.
seed Hodnota, na které jsou založeny procentuální výpočty percentile . Procento výpočtu pro konkrétního uživatele bude stejné ve všech funkcích, pokud se použije stejná seed hodnota. Pokud není zadána žádná seed hodnota, vytvoří se výchozí počáteční hodnota na základě názvu funkce.

Pokud tato funkce není povolená, správce funkcí přiřadí variantu označenou aktuálnímu default_when_disabled uživateli, což je Small v tomto případě.

Pokud je tato funkce povolená, správce funkcí zkontroluje přidělení user, group, a percentile ve zmíněném pořadí, aby přiřadil variantu. V tomto konkrétním příkladu platí, že pokud je vyhodnocený uživatel pojmenovaný Marsha, ve skupině s názvem Ring1nebo se stane, že uživatel spadá mezi 0 a 10. percentil, pak je zadaná varianta přiřazena uživateli. V takovém případě by variantu Big vrátili všichni přiřazení uživatelé. Pokud se žádné z těchto přidělení neshoduje, přiřadí se uživateli varianta default_when_enabled , což je Small.

Logika přidělení je podobná filtru funkcí Microsoft.Targeting , ale existují některé parametry, které jsou přítomné v cílení, které nejsou v přidělení, a naopak. Výsledky cílení a přidělování nesouvisí.

Přepsání povoleného stavu variantou

Varianty můžete použít k přepsání povoleného stavu příznaku funkce. Přepsání dává variantám příležitost rozšířit vyhodnocení funkční vlajky. Při volání IsEnabledWithAppContext příznaku s variantami správce funkcí zkontroluje, jestli je varianta přiřazená aktuálnímu uživateli nakonfigurovaná tak, aby přepsala výsledek. Přepsání se provádí pomocí volitelné vlastnosti varianty status_override. Ve výchozím nastavení je tato vlastnost nastavena na None, což znamená, že varianta nemá vliv na to, zda je příznak považován za povolený nebo zakázaný. Nastavení status_override na Enabled umožňuje, aby zvolená varianta přepsala příznak, který se má povolit. Nastavení status_override na Disabled poskytuje opačnou funkčnost, a tím pádem zakáže příznak při výběru varianty. Funkci s nastaveným stavem enabledfalse nelze přepsat.

Pokud používáte příznak funkce s binárními variantami, status_override může být tato vlastnost užitečná. Umožňuje vám i nadále používat rozhraní API, jako je IsEnabledaWithAppContext ve vaší aplikaci a zároveň těžit z nových funkcí, které přinášejí varianty, jako je přidělení percentilu a počáteční semeno.

{
    "id": "MyVariantFeatureFlag",
    "enabled": true,
    "allocation": {
        "percentile": [
            {
                "variant": "On",
                "from": 10,
                "to": 20
            }
        ],
        "default_when_enabled":  "Off",
        "seed": "Enhanced-Feature-Group"
    },
    "variants": [
        {
            "name": "On"
        },
        {
            "name": "Off",
            "status_override": "Disabled"
        }
    ]
}

Ve výše uvedeném příkladu je funkce vždy povolená. Pokud je aktuální uživatel v počítaném rozsahu percentilu 10 až 20, vrátí se varianta On . V opačném případě se varianta Off vrátí a protože status_override je rovna Disabled, funkce bude nyní považována za zakázanou.

Další kroky

Pokud chcete zjistit, jak ve svých aplikacích používat příznaky funkcí, pokračujte na následující rychlé návody.

Webová aplikace Go Gin

Pokud se chcete dozvědět, jak používat filtry funkcí, pokračujte následujícími kurzy.

Povolování podmíněných funkcí pomocí filtrů funkcí

Povolení funkcí podle plánu

Zavedení funkcí cílovým skupinám

  • Last updated on