入门 · Cloudflare Flagship docs

在本指南中，您将在 Flagship 中创建一个功能标志，并在 Cloudflare Worker 中进行评估。

创建应用程序和标志

在此示例中，您将创建一个名为 new-checkout 的布尔标志，该标志控制用户是否能看到全新的结账体验。

登录 Cloudflare 仪表板 ↗并选择您的账户。
转到 Compute（计算） > Flagship。
选择 Create app（创建应用程序）。为该应用程序指定一个与您的项目或服务相匹配的名称（例如，checkout-service）。
在该应用程序内部，选择 Create flag（创建标志）。
创建一个键名为 new-checkout 的布尔标志。您可以选择性地添加目标定位规则以控制谁能看到此标志。
开启该标志，然后选择 Save（保存）。

在 Worker 中添加 Flagship 绑定

在您的 Wrangler 配置文件中添加 Flagship 绑定，这样您的 Worker 就可以通过绑定来评估标志了。

{
	"flagship": [
		{
			"binding": "FLAGS",
			"app_id": "<APP_ID>",
		},
	],
}

[[flagship]]
binding = "FLAGS"
app_id = "<APP_ID>"

将 <APP_ID> 替换为 Cloudflare 仪表板 ↗ 中显示的应用程序 ID。binding 字段设置您在 Worker 代码中用于访问 Flagship 的名称。在此示例中，该绑定可作为 env.FLAGS 使用。

更新 Wrangler 配置后，运行 npx wrangler types 来为该绑定生成 TypeScript 类型。

在 Worker 中评估标志

使用 env.FLAGS 绑定来评估标志。绑定提供了类型安全的方法，它们会返回标志值，并且如果评估失败，会回退到您提供的默认值。

export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		const userId = url.searchParams.get("userId") ?? "anonymous";

		const showNewCheckout = await env.FLAGS.getBooleanValue(
			"new-checkout",
			false,
			{ userId },
		);

		if (showNewCheckout) {
			return new Response("欢迎体验新的结账流程！");
		}

		return new Response("标准结账流程。");
	},
};

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const userId = url.searchParams.get("userId") ?? "anonymous";

		const showNewCheckout = await env.FLAGS.getBooleanValue(
			"new-checkout",
			false,
			{ userId },
		);

		if (showNewCheckout) {
			return new Response("欢迎体验新的结账流程！");
		}

		return new Response("标准结账流程。");
	},
};

getBooleanValue 的第三个参数是评估上下文。Flagship 使用上下文属性来匹配目标定位规则。在本示例中，传递了 userId 属性，以便百分比部署和针对特定用户的目标定位能够正常运作。

部署并测试

部署您的 Worker：

npx wrangler deploy

通过发送请求来测试标志评估：

curl "https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/?userId=user-42"

在仪表板中更改标志值或目标定位规则，然后观察更新后的响应。标志更改会在几秒钟内在全球传播生效。

(可选) 使用 OpenFeature SDK

如果您更喜欢 OpenFeature ↗ 标准接口，或者如果您在 Cloudflare Worker 之外的环境中运行，您可以使用 @cloudflare/flagship ↗ SDK 代替绑定。

安装 SDK：

npm i @cloudflare/flagship @openfeature/server-sdk

yarn add @cloudflare/flagship @openfeature/server-sdk

pnpm add @cloudflare/flagship @openfeature/server-sdk

bun add @cloudflare/flagship @openfeature/server-sdk

使用 OpenFeature 客户端来评估标志：

直接将 Flagship 绑定传递给提供程序 (provider)。这避免了额外的 HTTP 开销，也是在 Worker 内部推荐的做法。绑定会自动处理身份验证。

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

export default {
	async fetch(request, env) {
		await OpenFeature.setProviderAndWait(
			new FlagshipServerProvider({ binding: env.FLAGS }),
		);

		const client = OpenFeature.getClient();

		const showNewCheckout = await client.getBooleanValue(
			"new-checkout",
			false,
			{ targetingKey: "user-42" },
		);

		return new Response(showNewCheckout ? "新的结账流程！" : "标准结账流程。");
	},
};

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		await OpenFeature.setProviderAndWait(
			new FlagshipServerProvider({ binding: env.FLAGS }),
		);

		const client = OpenFeature.getClient();

		const showNewCheckout = await client.getBooleanValue(
			"new-checkout",
			false,
			{ targetingKey: "user-42" },
		);

		return new Response(
			showNewCheckout ? "新的结账流程！" : "标准结账流程。",
		);
	},
};

在 Worker 之外运行（例如，在 Node.js 中）时，使用应用程序 ID、账户 ID 和 API 令牌。从您的 Cloudflare 账户生成具有 Flagship Evaluate 权限的 API 令牌。

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);

const client = OpenFeature.getClient();

const showNewCheckout = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
});

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);

const client = OpenFeature.getClient();

const showNewCheckout = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
});

有关详细的设置说明，请参阅 SDK 文档。

后续步骤

从命令行使用 wrangler flagship 命令管理标志。
了解目标定位规则，以根据用户属性提供不同的值。
探索所有评估方法的完整绑定 API 参考。
阅读有关用于逐步发布功能的百分比部署的内容。
查阅 Flagship API 参考以编程方式管理 Flagship。