← Cloudflare Flagship / flagship

Рекомендации

Следуйте этим рекомендациям, чтобы вычисление флагов в Flagship оставалось предсказуемым, быстрым и простым в поддержке.

Используйте привязка Workers внутри Cloudflare Workers. Привязка автоматически обрабатывает аутентификацию и избавляет от необходимости управлять API токенами на уровне приложения.

Используйте OpenFeature SDK когда вы работаете вне Workers или вам нужен независимый от поставщика интерфейс OpenFeature. В Workers вы всё равно можете передать привязку провайдеру сервера OpenFeature, чтобы сохранить производительность привязки при использовании API OpenFeature.

Не оценивайте один и тот же флаг многократно в цикле. Оцените флаг один раз, сохраните результат в локальной переменной и используйте его до конца запроса.

const enabled = await env.FLAGS.getBooleanValue("show-related-items", false, {
	userId,
});

for (const item of items) {
	if (enabled) {
		item.related = await loadRelatedItems(item.id);
	}
}

Таргетинг и процентные развёртывания зависят от контекста оценки, который вы передаёте из своего приложения. Используйте стабильные идентификаторы и одинаковые имена атрибутов везде.

const context = {
	userId: session.user.id,
	plan: session.user.plan,
	country: request.cf?.country ?? "unknown",
};

const enabled = await env.FLAGS.getBooleanValue("new-checkout", false, context);

Для SDK OpenFeature используйте targetingKey в качестве стабильного идентификатора. Для привязки Workers используйте атрибут, настроенный для вашего постепенного релиза, например userId.

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

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

Используйте *Details методы, если вам нужно понять, почему было возвращено то или иное значение. Детали включают итоговое значение, вариант, причину и метаданные ошибки.

const details = await env.FLAGS.getBooleanDetails("new-checkout", false, {
	userId: "user-42",
});

console.log(details.value);
console.log(details.variant);
console.log(details.reason);
console.log(details.errorCode);

Начните с небольшого процентного развёртывания, отслеживайте метрики приложения, а затем постепенно увеличивайте процент.

1. Создайте флаг с небольшим развёртыванием, например 5%.
2. Отслеживайте ошибки, задержки, бизнес-метрики и отзывы пользователей.
3. Увеличивайте до 25%, затем до 50%, затем до 100% по мере роста уверенности.
4. Когда развёртывание достигнет 100%, сделайте победивший вариант значением по умолчанию и удалите временные правила таргетинга.
5. После полного развёртывания функции удалите старый путь кода и сам флаг.

Отключённые или полностью развёрнутые флаги всё равно создают дополнительные затраты на поддержку. Перед удалением флага сначала отключите его, понаблюдайте за неожиданным поведением, удалите код оценки, разверните это изменение и только затем удалите флаг из Flagship.