Title: 核心概念
Locale: zh
URL: https://sensorswave.com/docs/feature-gates/core-concepts/
Description: 深入了解功能开关的工作原理和核心概念
本文介绍功能开关的核心概念，帮助您深入理解功能开关的工作原理，更好地使用和管理功能开关。

## 功能开关的基本组成

一个完整的功能开关包含以下核心元素：

### 开关标识

每个功能开关都有唯一的标识符，用于在代码中引用：

- **开关名称（Key）**：代码中使用的标识符，如 `new_recommendation_algorithm`
- **显示名称（Display Name）**：控制台中显示的友好名称，如"新推荐算法"
- **描述（Description）**：说明功能开关的用途和背景

### 默认值

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

- **默认值为 `false`（关闭）**
- **兜底保障**：SDK 无法连接服务器时，也使用默认值 `false`

> **提示**：功能开关的默认值为 `false`（关闭），通过规则逐步开启。

### 目标规则

目标规则决定哪些用户能看到功能开关。详见 [目标规则（Targeting）](#目标规则targeting) 章节。

## 目标规则（Targeting）

目标规则决定哪些用户能看到功能开关。Sensors Wave 支持多种规则类型，可以组合使用。

### 规则类型

#### 1. 通用规则（全部用户）

对所有用户生效的规则，适用于全量发布或全量关闭。

**示例**：
```javascript
// 规则配置：全部用户通过
const hasFeature = await SensorsWave.checkFeatureGate('global_feature');
// 返回：true
```

#### 2. 属性规则（系统预定义属性）

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

**支持的属性**：App Version、Browser Name、Browser Version、Device Model、IP Address、Operating System、Country、Province、$city 等。

**支持的条件**：
- **等于**：`App Version` 等于 `2.0.0`
- **不等于**：`Country` 不等于 `CN`
- **包含**：`Browser Name` 包含 `Chrome`
- **大于/小于**：`App Version` 大于等于 `2.0.0`

**示例**：
```javascript
// 规则配置：App Version >= 2.0.0
const hasFeature = await SensorsWave.checkFeatureGate('new_version_feature');
// 返回：true（如果用户 App 版本 >= 2.0.0）
```

#### 3. 主体 ID 规则

基于用户 ID（Login ID 或 Anonymous ID）进行精准匹配。

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

**示例**：
```javascript
// 规则配置：用户 ID 在指定列表中
const hasFeature = await SensorsWave.checkFeatureGate('test_feature');
```

#### 4. 自定义规则（自定义属性）

基于自定义的用户属性进行判断，可灵活配置条件和分流百分比。

**使用场景**：
- 基于业务自定义属性定向
- 灵活的灰度发布

**示例**：
```javascript
// 规则配置：自定义属性 user_level = "VIP"，分流 100%
const hasFeature = await SensorsWave.checkFeatureGate('vip_feature');
// 返回：true（如果用户 user_level 为 VIP）
```

#### 5. Gates 规则

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

| 规则类型 | 说明 |
|----------|------|
| **Passes Target Gate** | 用户通过了目标开关时，匹配此规则 |
| **Fails Target Gate** | 用户未通过目标开关时，匹配此规则 |

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

**示例**：
```javascript
// 规则配置：用户通过了 base_feature 开关时，开启 advanced_feature
const hasFeature = await SensorsWave.checkFeatureGate('advanced_feature');
```

### 分流配置

每个规则都需要设置分流百分比，决定满足条件的用户中有多少比例通过开关：

| 配置 | 效果 |
|------|------|
| 通过 100%，不通过 0% | 所有满足条件的用户都通过 |
| 通过 50%，不通过 50% | 满足条件的用户中随机 50% 通过 |
| 通过 10%，不通过 90% | 满足条件的用户中随机 10% 通过（灰度发布） |

> **提示**：分流基于用户 ID 哈希，确保同一用户每次结果一致。

### 规则组合

多条规则可以组合使用，提供更灵活的控制能力。

#### 规则优先级

规则按照从上到下的顺序匹配，一旦命中某条规则，立即返回该规则的值，不再继续匹配。

**示例配置**：

| 优先级 | 规则名称 | 条件 | 返回值 |
|-------|---------|------|--------|
| 1 | 内部测试用户 | 主体 ID 匹配 | 开启 |
| 2 | VIP 用户 | 自定义属性 `user_level` = `VIP` | 开启 |
| 3 | 10% 灰度 | 通用规则，分流 10% | 开启 |
| - | 默认值 | - | 关闭 |

**匹配流程**：

```
用户 A: 主体 ID 在测试列表中, user_level = VIP
→ 命中规则 1，返回 开启

用户 B: 主体 ID 不在列表中, user_level = VIP
→ 跳过规则 1，命中规则 2，返回 开启

用户 C: 主体 ID 不在列表中, user_level = Basic
→ 跳过规则 1, 2，进入规则 3 百分比判断
→ 如果在 10% 范围内，返回 开启，否则继续

用户 D: 不满足任何规则
→ 返回 默认值：关闭
```

#### 规则顺序建议

1. **主体 ID 规则**：内部测试、指定用户等放在最前面
2. **属性规则 / 自定义规则**：精准定向规则
3. **通用规则（灰度）**：通用灰度放在最后
4. **默认值**：兜底方案，返回 `false`

> **最佳实践**：将特殊规则放在前面，通用规则放在后面，确保特殊用户优先匹配。

## 开关状态

功能开关有以下 5 种状态：

| 状态 | 说明 |
|------|------|
| **草稿** | 开关已创建但未发布，不会对用户生效 |
| **调试** | 开关处于调试模式，用于内部测试验证 |
| **运行中** | 开关已发布并正在生效 |
| **已发布** | 开关已完成发布流程，功能稳定运行 |
| **结束** | 开关生命周期已结束，功能已全量或已下线 |

### 状态转换流程

```
草稿 → 调试 → 运行中 → 已发布 → 结束
```

## SDK 工作原理

了解 SDK 的工作原理有助于更好地使用功能开关。

### 配置获取与缓存

1. **应用启动时**：SDK 从服务器获取功能开关配置
2. **本地缓存**：配置存储在本地，后续查询直接读取缓存
3. **定期更新**：SDK 每 10 分钟检查配置更新

### 降级策略

当 SDK 无法连接服务器时：

1. 使用本地缓存的配置（如果有）
2. 如果没有缓存，使用默认值 `false`

```javascript
// 检查功能开关，降级时返回默认值 false
const hasFeature = await SensorsWave.checkFeatureGate('new_feature');
```

### 性能优化

- **本地缓存**：避免每次都请求服务器
- **异步更新**：配置更新不阻塞主流程
- **轻量级判断**：规则匹配在本地完成，毫秒级响应

## 下一步

现在您已经了解了功能开关的核心概念，接下来可以：

1. **[创建和配置](create-and-configure.mdx)**：学习如何创建和配置功能开关
2. **[SDK 集成](sdk-integration.mdx)**：了解如何在代码中使用功能开关

---

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