Title: 创建和配置功能开关
Locale: zh
URL: https://sensorswave.com/docs/feature-gates/create-and-configure/
Description: 详细了解如何创建和配置功能开关的各项设置
本文详细介绍如何创建和配置功能开关，包括基本信息设置、目标规则配置等内容。

## 前提条件

在创建功能开关前，请确保：

- 您具有创建功能开关的权限
- 已了解 [核心概念](core-concepts.mdx)
- 明确功能开关的使用场景和目标用户

## 创建功能开关

### 步骤 1：进入创建页面

1. 登录 Sensors Wave 控制台
2. 点击左侧菜单的 **功能开关**
3. 点击右上角的 **新建功能开关** 按钮

### 步骤 2：配置基本信息

创建功能开关时需要填写以下必填字段：

#### 名称（必填）

控制台中显示的友好名称，使用中文或英文。

**示例**：
- 新推荐算法
- 微信支付开关
- 用户资料页改版

#### 功能开关 Key（必填）

代码中使用的唯一标识符。

**命名规范**：
- 使用小写字母、数字和下划线
- 采用 snake_case 格式
- 使用描述性名称，易于理解
- 建议加上功能模块前缀

**示例**：
- ✅ `recommendation_new_algorithm`
- ✅ `payment_wechat_pay_enabled`
- ✅ `user_profile_redesign`
- ❌ `flag1`（过于简单）
- ❌ `NewFeature`（应使用小写）
- ❌ `test`（不够具体）

> **注意**：功能开关 Key 创建后不可修改，请谨慎命名。

#### 描述（必填）

详细说明功能开关的用途、背景和预期效果。

**建议包含**：
- 功能的简要说明
- 为什么需要这个开关
- 预期的使用周期
- 相关的需求或任务链接

**示例**：
```
基于深度学习的商品推荐算法，预期可提升点击率 15%。
用于灰度发布，验证算法稳定性和效果。
预计 2 周完成灰度，全量后删除此开关。
相关需求：PROJ-1234
```

#### ID 类型（必填）

选择功能开关使用的用户标识类型：

- **LoginID（登录 ID）**：已登录用户的唯一标识
- **AnonymousID（匿名 ID）**：未登录用户的设备标识

> **提示**：大多数场景使用 LoginID，需要跨设备追踪或支持未登录用户时使用 AnonymousID。

### 步骤 3：设置默认值

默认值是当用户不满足任何规则时返回的值。

#### 布尔型开关

- **开启（true）**：默认对所有用户生效
- **关闭（false）**：默认对所有用户不生效

#### 默认值设置建议

| 使用场景 | 推荐默认值 | 原因 |
|---------|-----------|------|
| 新功能灰度 | 关闭（false） | 通过规则逐步开启，控制风险 |
| 付费功能 | 关闭（false） | 默认不开放，满足条件才开启 |
| 运维开关 | 开启（true） | 默认正常运行，故障时关闭 |

> **提示**：默认值也是 SDK 无法连接服务器时的降级方案。

### 步骤 4：保存开关

1. 检查所有配置是否正确
2. 点击 **保存**
3. 开关创建成功，状态为 **草稿**

> **注意**：草稿状态的开关不会对用户生效，需要配置规则并发布后才会生效。

## 配置目标规则

目标规则决定哪些用户能看到功能开关。

### 添加新规则

1. 进入功能开关详情页
2. 点击 **添加新规则** 按钮
3. 配置规则条件和返回值

### 规则类型详解

当前系统支持以下规则类型（共 5 类）：

1. **通用** - 全部用户规则
2. **属性** - 系统预定义属性（如 App Version、Browser Name、Device Model、IP Address、Operating System、Country、Province、$city 等）
3. **主体 ID** - Login ID 或 Anonymous ID
4. **自定义** - 自定义属性
5. **Gates** - Passes Target Gate（通过目标开关）、Fails Target Gate（未通过目标开关）

#### 1. 属性规则

基于系统预定义属性或自定义属性判断是否开启功能。

**配置步骤**：
1. 规则名称：内部测试用户
2. 选择规则类型：**自定义** → **自定义属性**
3. 输入属性 key：`is_internal_user`
4. 选择条件：**等于（=）**
5. 输入值：`1`（或 `true`）
6. 分流设置：
   - **通过**：`100%`（满足条件的用户全部通过）
   - **不通过**：`0%`
7. 点击保存

**说明**：
- 每个规则都需要设置分流百分比
- 分流百分比决定了满足条件的用户中，有多少比例通过开关
- `100%通过 + 0%不通过` = 所有满足条件的用户都通过
- `50%通过 + 50%不通过` = 满足条件的用户中随机50%通过

**支持的条件操作符**：

从系统实际支持的操作符来看，主要包括：

- **=**（等于）：精确匹配
- 其他操作符根据属性类型自动提供

**示例**：
```
条件：is_employee = 1
→ 匹配 is_employee 属性值为 1 的用户
```

#### 2. 主体 ID 规则

基于用户 ID 进行匹配。

**配置步骤**：
1. 规则名称：指定测试用户
2. 选择规则类型：**主体 ID** → **Login ID** 或 **Anonymous ID**
3. 输入用户 ID（满足条件）
4. 分流设置：
   - **通过**：`100%`
   - **不通过**：`0%`

**使用场景**：
- 内部测试用户
- 特定客户定制
- 快速问题验证

> **注意**：建议使用自定义属性来标记测试用户，而非直接使用 ID 列表。

#### 3. 百分比灰度规则（分流）

通过分流百分比实现灰度发布。

**配置步骤**：
1. 规则名称：灰度用户
2. 可以设置条件，也可以不设置（对所有用户生效）
3. 分流设置：
   - **通过**：设置通过的百分比（如 5%）
   - **不通过**：自动计算剩余百分比（如 95%）
4. 点击保存

**特点**：
- 基于用户 ID 哈希，确保同一用户每次结果一致
- 百分比调整时，用户分组保持相对稳定
- 适合渐进式灰度发布

**百分比调整策略**：

从小到大逐步调整：1% → 5% → 10% → 25% → 50% → 100%

> **提示**：百分比从 10% 调整到 20% 时，原来的 10% 用户仍然在新的 20% 中，保证用户体验连续性。

#### 4. Gates 规则（依赖其他开关）

基于其他功能开关的结果来决定当前开关。

**配置步骤**：
1. 规则名称：依赖开关 A
2. 选择规则类型：**Gates** → **Passes Target Gate**（通过目标开关）或 **Fails Target Gate**（未通过目标开关）
3. 选择目标开关
4. 分流设置：
   - **通过**：`100%`
   - **不通过**：`0%`

**使用场景**：
- 功能之间的依赖关系
- 组合多个开关实现复杂逻辑
- 分阶段发布相关功能

**示例**：
```
开关 A：新支付功能
开关 B：新结算功能（依赖开关 A）

规则：Passes Target Gate(开关 A)，分流 100%通过
说明：只有当用户通过了"新支付功能"开关，才能看到"新结算功能"
```

### 白名单功能

白名单是一种特殊的配置方式，可以快速为指定用户开启或关闭功能，**无需设置分流百分比**。

**使用方式**：
1. 点击规则配置区域顶部的 **白名单** 按钮
2. 添加或移除用户 ID
3. 白名单用户直接通过，无需经过规则匹配

**使用场景**：
- 内部测试用户快速开关
- 临时为特定用户开放功能
- 快速问题验证

> **白名单 vs 规则**：
> - 白名单：直接指定用户 ID，自动通过，无需设置百分比
> - 规则：需要设置条件和分流百分比，更灵活但配置稍复杂

### 规则优先级和顺序

#### 规则匹配顺序

规则从上到下依次匹配，命中第一条规则后立即返回，不再继续匹配。

**示例**：

| 顺序 | 规则名称 | 条件 | 返回值 |
|-----|---------|------|--------|
| 1️⃣ | 内部测试用户 | `is_internal_user` = `1` | 通过 |
| 2️⃣ | VIP 用户 | `user_level` = `VIP` | 通过 |
| 3️⃣ | 10% 灰度 | 分流 10% | 通过 |
| - | 默认值 | - | 不通过 |

#### 调整规则顺序

1. 进入功能开关编辑页面
2. 在规则列表中，拖动规则左侧的 **拖动图标**
3. 调整到目标位置
4. 点击 **保存**，然后点击 **启动**

#### 规则顺序最佳实践

**推荐顺序**（从上到下）：

1. **白名单规则**：特定用户（最高优先级）
2. **用户属性规则**：内部测试、特殊用户
3. **主体 ID 规则**：指定用户 ID
4. **百分比灰度规则**：通用灰度（最低优先级）
5. **默认值**：兜底方案

**原则**：
- 特殊规则放在前面
- 通用规则放在后面
- 精准匹配优先于模糊匹配

### 编辑和删除规则

#### 编辑规则

1. 点击规则右侧的 **编辑** 按钮
2. 修改规则配置
3. 点击 **保存**，然后点击 **启动**

> **提示**：规则修改后生效（SDK 在 10 分钟内更新缓存），请谨慎操作。

#### 删除规则

1. 点击规则右侧的 **删除** 按钮
2. 确认删除操作
3. 规则立即失效

> **警告**：删除规则会影响正在使用该规则的用户，请确保了解影响范围。

## 启动和管理

### 启动功能开关

配置完成后，保存并启动功能开关，状态变为 **运行中** 后即可生效。

1. 进入功能开关详情页
2. 检查配置是否正确
3. 点击 **保存** 按钮
4. 功能开关状态变为 **运行中**
5. SDK 在 10 分钟内更新缓存并获取新配置

### 查看开关状态

在功能开关列表和详情页可以看到开关的当前状态：

- **运行中**：功能开关正在生效
- 上线时间：显示功能开关首次上线的时间

> **提示**：SDK 采用定期轮询机制（10 分钟）更新配置，因此配置变更不是即时生效的。

## 注意事项

### 命名规范

- 功能开关 Key 创建后不可修改
- 使用描述性名称，避免歧义
- 团队内统一命名风格

### 规则配置

- 规则修改后生效（SDK 在 10 分钟内更新缓存），请谨慎操作
- 定期审查规则，清理无用规则
- 规则过多会影响匹配性能，建议不超过 20 条

## 下一步

现在您已经了解了如何创建和配置功能开关，接下来可以：

1. **[SDK 集成](sdk-integration.mdx)**：学习如何在代码中使用功能开关
2. **[最佳实践](best-practices.mdx)**：了解功能开关的最佳使用方法

---

**最后更新时间**：2026 年 1 月 28 日