在本指南中,您将在 Flagship 中创建一个功能标志,并在 Cloudflare Worker 中进行评估。
在此示例中,您将创建一个名为 new-checkout 的布尔标志,该标志控制用户是否能看到全新的结账体验。
- 登录 Cloudflare 仪表板 ↗并选择您的账户。
- 转到 Compute(计算) > Flagship。
- 选择 Create app(创建应用程序)。为该应用程序指定一个与您的项目或服务相匹配的名称(例如,
checkout-service)。 - 在该应用程序内部,选择 Create flag(创建标志)。
- 创建一个键名为
new-checkout的布尔标志。您可以选择性地添加目标定位规则以控制谁能看到此标志。 - 开启该标志,然后选择 Save(保存)。
在您的 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 类型。
使用 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("Welcome to the new checkout experience!");
}
return new Response("Standard checkout.");
},
};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("Welcome to the new checkout experience!");
}
return new Response("Standard checkout.");
},
};getBooleanValue 的第三个参数是评估上下文。Flagship 使用上下文属性来匹配目标定位规则。在本示例中,传递了 userId 属性,以便百分比部署和针对特定用户的目标定位能够正常运作。
将 Flag 复制到本地存储,然后启动本地会话:
npx wrangler flagship flags pull <APP_ID>
npx wrangler dev如需改用 Cloudflare Vite 插件,请启动 Vite 开发服务器。在 cf项目中,运行 cf dev,并在 pull 命令中添加 --persist-to .cloudflare/state。无论使用哪种方式,都请先运行 Wrangler pull 命令,因为 cf 无法拉取 Flag。
如果不运行 pull,本地存储将为空,因此评估会返回代码中传入的默认值。有关管理本地 Flag 的其他方式以及如何改用远程应用,请参阅本地开发。
部署您的 Worker:
npx wrangler deploy通过发送请求来测试标志评估:
curl "https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/?userId=user-42"在仪表板中更改标志值或目标定位规则,然后观察更新后的响应。标志更改会在几秒钟内在全球传播生效。
如果您更喜欢 OpenFeature ↗ 标准接口,或者如果您在 Cloudflare Worker 之外的环境中运行,您可以使用 @cloudflare/flagship ↗ SDK 代替绑定。
安装 SDK:
npm i @cloudflare/flagship @openfeature/server-sdkyarn add @cloudflare/flagship @openfeature/server-sdkpnpm add @cloudflare/flagship @openfeature/server-sdkbun 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 ? "New checkout!" : "Standard checkout.",
);
},
};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 ? "New checkout!" : "Standard checkout.",
);
},
};在 Worker 外部运行时(例如在 Node.js 中),请使用应用 ID、账户 ID 和 API 令牌。在 Cloudflare 账户中生成具有 Flagship Evaluate 或 Flagship App 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命令管理标志。 - 使用 Wrangler、Vite 插件或
cf dev针对本地 Flag 存储进行测试。 - 了解目标定位规则,以根据用户属性提供不同的值。
- 探索所有评估方法的完整绑定 API 参考。
- 阅读有关用于逐步发布功能的百分比部署的内容。
- 创建一个 API 令牌,以便在服务器端环境中评估标志。
- 查阅 Flagship API 参考以编程方式管理 Flagship。