← Cloudflare Flagship / flagship / binding

Методы

Привязка Flagship предоставляет следующие методы для оценки флагов функций. Все методы асинхронны и возвращают Promise. При известных ошибках оценки типизированные методы возвращают defaultValue который вы предоставляете.

См. справочник по типам для определений FlagshipEvaluationContext и FlagshipEvaluationDetails.

`get()`

Возвращает необработанное значение флага без проверки типа. Используйте этот метод, когда тип флага неизвестен на этапе компиляции.

Если вы укажете defaultValue, get() возвращает это значение при известных ошибках оценки, например при отсутствии флага. Если вы не укажете defaultValue, известные ошибки оценки выбрасываются.

get(flagKey: string, defaultValue?: unknown, context?: FlagshipEvaluationContext): Promise<unknown>

Параметр	Тип	Обязательный	Описание
`flagKey`	`string`	Да	Ключ флага, который нужно оценить.
`defaultValue`	`unknown`	Нет	Резервное значение, которое возвращается, если оценка завершается ошибкой или флаг не найден.
`context`	`FlagshipEvaluationContext`	Нет	Атрибуты в формате ключ-значение для правил таргетинга.

const value = await env.FLAGS.get("checkout-flow", "v1", {
	userId: "user-42",
});

`getBooleanValue()`

Возвращает значение флага в виде boolean.

getBooleanValue(flagKey: string, defaultValue: boolean, context?: FlagshipEvaluationContext): Promise<boolean>

Параметр	Тип	Обязательный	Описание
`flagKey`	`string`	Да	Ключ флага, который нужно оценить.
`defaultValue`	`boolean`	Да	Резервное значение, которое возвращается, если оценка завершается ошибкой или флаг не найден.
`context`	`FlagshipEvaluationContext`	Нет	Атрибуты в формате ключ-значение для правил таргетинга.

const enabled = await env.FLAGS.getBooleanValue("dark-mode", false, {
	userId: "user-42",
});

`getStringValue()`

Возвращает значение флага в виде string.

getStringValue(flagKey: string, defaultValue: string, context?: FlagshipEvaluationContext): Promise<string>

Параметр	Тип	Обязательный	Описание
`flagKey`	`string`	Да	Ключ флага, который нужно оценить.
`defaultValue`	`string`	Да	Резервное значение, которое возвращается, если оценка завершается ошибкой или флаг не найден.
`context`	`FlagshipEvaluationContext`	Нет	Атрибуты в формате ключ-значение для правил таргетинга.

const variant = await env.FLAGS.getStringValue("checkout-flow", "v1", {
	userId: "user-42",
	country: "US",
});

`getNumberValue()`

Возвращает значение флага в виде number.

getNumberValue(flagKey: string, defaultValue: number, context?: FlagshipEvaluationContext): Promise<number>

Параметр	Тип	Обязательный	Описание
`flagKey`	`string`	Да	Ключ флага, который нужно оценить.
`defaultValue`	`number`	Да	Резервное значение, которое возвращается, если оценка завершается ошибкой или флаг не найден.
`context`	`FlagshipEvaluationContext`	Нет	Атрибуты в формате ключ-значение для правил таргетинга.

const maxRetries = await env.FLAGS.getNumberValue("max-retries", 3, {
	plan: "enterprise",
});

`getObjectValue()`

Возвращает значение флага в виде типизированного объекта. Используйте обобщённый параметр T чтобы указать ожидаемую структуру.

getObjectValue<T extends object>(flagKey: string, defaultValue: T, context?: FlagshipEvaluationContext): Promise<T>

Параметр	Тип	Обязательный	Описание
`flagKey`	`string`	Да	Ключ флага, который нужно оценить.
`defaultValue`	`T`	Да	Резервное значение, которое возвращается, если оценка завершается ошибкой или флаг не найден.
`context`	`FlagshipEvaluationContext`	Нет	Атрибуты в формате ключ-значение для правил таргетинга.

interface ThemeConfig {
	primaryColor: string;
	fontSize: number;
}

const theme = await env.FLAGS.getObjectValue<ThemeConfig>(
	"theme-config",
	{ primaryColor: "#000", fontSize: 14 },
	{ userId: "user-42" },
);

`getBooleanDetails()`

Возвращает значение флага в виде boolean с метаданными оценки.

getBooleanDetails(flagKey: string, defaultValue: boolean, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<boolean>>

Параметр	Тип	Обязательный	Описание
`flagKey`	`string`	Да	Ключ флага, который нужно оценить.
`defaultValue`	`boolean`	Да	Резервное значение, которое возвращается, если оценка завершается ошибкой или флаг не найден.
`context`	`FlagshipEvaluationContext`	Нет	Атрибуты в формате ключ-значение для правил таргетинга.

const details = await env.FLAGS.getBooleanDetails("dark-mode", false, {
	userId: "user-42",
});
console.log(details.value); // true
console.log(details.reason); // "TARGETING_MATCH"

`getStringDetails()`

Возвращает значение флага в виде string с метаданными оценки.

getStringDetails(flagKey: string, defaultValue: string, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<string>>

Параметр	Тип	Обязательный	Описание
`flagKey`	`string`	Да	Ключ флага, который нужно оценить.
`defaultValue`	`string`	Да	Резервное значение, которое возвращается, если оценка завершается ошибкой или флаг не найден.
`context`	`FlagshipEvaluationContext`	Нет	Атрибуты в формате ключ-значение для правил таргетинга.

const details = await env.FLAGS.getStringDetails("checkout-flow", "v1", {
	userId: "user-42",
});
console.log(details.value); // "v2"
console.log(details.variant); // "new"
console.log(details.reason); // "TARGETING_MATCH"

`getNumberDetails()`

Возвращает значение флага в виде number с метаданными оценки.

getNumberDetails(flagKey: string, defaultValue: number, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<number>>

Параметр	Тип	Обязательный	Описание
`flagKey`	`string`	Да	Ключ флага, который нужно оценить.
`defaultValue`	`number`	Да	Резервное значение, которое возвращается, если оценка завершается ошибкой или флаг не найден.
`context`	`FlagshipEvaluationContext`	Нет	Атрибуты в формате ключ-значение для правил таргетинга.

const details = await env.FLAGS.getNumberDetails("max-retries", 3, {
	plan: "enterprise",
});
console.log(details.value); // 5
console.log(details.reason); // "TARGETING_MATCH"

`getObjectDetails()`

Возвращает значение флага в виде типизированного объекта с метаданными оценки. Используйте обобщённый параметр T чтобы указать ожидаемую структуру.

getObjectDetails<T extends object>(flagKey: string, defaultValue: T, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<T>>

Параметр	Тип	Обязательный	Описание
`flagKey`	`string`	Да	Ключ флага, который нужно оценить.
`defaultValue`	`T`	Да	Резервное значение, которое возвращается, если оценка завершается ошибкой или флаг не найден.
`context`	`FlagshipEvaluationContext`	Нет	Атрибуты в формате ключ-значение для правил таргетинга.

interface ThemeConfig {
	primaryColor: string;
	fontSize: number;
}

const details = await env.FLAGS.getObjectDetails<ThemeConfig>(
	"theme-config",
	{ primaryColor: "#000", fontSize: 14 },
	{ userId: "user-42" },
);
console.log(details.value); // { primaryColor: "#0051FF", fontSize: 16 }
console.log(details.variant); // "brand-refresh"

Обработка ошибок

Типизированные методы вычисления возвращают defaultValue которое вы указали, при известных ошибках оценки, например при отсутствии флага или несовпадении типов. Непредвиденные ошибки времени выполнения всё равно могут вызвать исключение. Используйте *Details методы для проверки известных ошибок оценки.

Несоответствие типов

Если вы вызываете типизированный метод для флага другого типа (например, getBooleanValue для строкового флага), метод возвращает значение по умолчанию. *Details методы задают errorCode к "TYPE_MISMATCH".

// Flag "checkout-flow" is a string flag, but you call getBooleanDetails.
const details = await env.FLAGS.getBooleanDetails("checkout-flow", false);
console.log(details.value); // false (the default value)
console.log(details.errorCode); // "TYPE_MISMATCH"

Ошибка оценки

Если оценка не удаётся по другой причине, метод возвращает значение по умолчанию. *Details методы включают errorCode например, "FLAG_NOT_FOUND", "INVALID_CONTEXT", "PARSE_ERROR", или "GENERAL".

const details = await env.FLAGS.getStringDetails(
	"nonexistent-flag",
	"fallback",
);
console.log(details.value); // "fallback"
console.log(details.errorCode); // "FLAG_NOT_FOUND"

Справочник по параметрам

В следующей таблице приведены параметры, общие для всех методов оценки.

Параметр	Тип	Обязательный	Описание
`flagKey`	`string`	Да	Ключ флага, который нужно оценить.
`defaultValue`	зависит	Да (кроме `get`)	Резервное значение, которое возвращается, если оценка завершается ошибкой или флаг не найден.
`context`	`FlagshipEvaluationContext`	Нет	Атрибуты в формате ключ-значение для правил таргетинга (например, `{ userId: "user-42", country: "US" }`).