方法 · Cloudflare Flagship docs

Flagship 绑定提供以下评估功能标志的方法。所有方法都是异步的并返回一个 Promise。对于已知的评估失败，类型化方法会返回您提供的 defaultValue。

有关 FlagshipEvaluationContext 和 FlagshipEvaluationDetails 的定义，请参阅类型参考。

`get()`

返回未经类型检查的原始标志值。当在编译时无法确定标志类型时，请使用此方法。

如果您提供了 defaultValue，get() 将在已知评估失败（例如缺失标志）时返回该值。如果您省略了 defaultValue，则已知的评估失败将引发错误。

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

参数	类型	是否必需	描述
`flagKey`	`string`	是	要评估的标志的键。
`defaultValue`	`unknown`	否	如果评估失败或未找到标志，则返回的回退 (fallback) 值。
`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`	是	如果评估失败或未找到标志，则返回的回退 (fallback) 值。
`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`	是	如果评估失败或未找到标志，则返回的回退 (fallback) 值。
`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`	是	如果评估失败或未找到标志，则返回的回退 (fallback) 值。
`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`	是	如果评估失败或未找到标志，则返回的回退 (fallback) 值。
`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`	是	如果评估失败或未找到标志，则返回的回退 (fallback) 值。
`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`	是	如果评估失败或未找到标志，则返回的回退 (fallback) 值。
`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`	是	如果评估失败或未找到标志，则返回的回退 (fallback) 值。
`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`	是	如果评估失败或未找到标志，则返回的回退 (fallback) 值。
`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"。

// "checkout-flow" 标志是一个字符串标志，但您调用了 getBooleanDetails。
const details = await env.FLAGS.getBooleanDetails("checkout-flow", false);
console.log(details.value); // false (默认值)
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` 除外）	如果评估失败或未找到标志，则返回的回退 (fallback) 值。
`context`	`FlagshipEvaluationContext`	否	用于目标定位规则的键值属性（例如，`{ userId: "user-42", country: "US" }`）。