Title: 快速开始
Locale: zh
URL: https://sensorswave.com/docs/feature-gates/quick-start/
Description: 创建和使用您的第一个功能开关
本指南将帮助您快速创建和使用第一个功能开关。通过这个示例，您将了解功能开关的完整使用流程。

## 前提条件

在开始之前，请确保您已经：

- 完成了 [SDK 集成](../data-integration/client-sdks/javascript.mdx)
- 具有创建功能开关的权限
- 了解基本的 [用户标识](../data-integration/user-identification.mdx) 概念

## 示例场景

假设您正在开发一个电商应用的新推荐算法，希望先向内部测试用户开放，验证稳定性后再逐步推广。

## 步骤 1：创建功能开关

### 1. 进入功能开关管理页面

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

### 2. 配置基本信息

填写以下信息：

- **开关名称**：`new_recommendation_algorithm`
- **显示名称**：新推荐算法
- **描述**：基于深度学习的商品推荐算法，提升推荐准确率
- **默认值**：关闭（false）

> **提示**：开关名称使用小写字母和下划线，便于在代码中使用。

### 3. 配置目标规则

创建第一条规则，向内部测试用户开放：

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

### 4. 保存和启动

1. 点击 **保存** 按钮
2. 检查配置无误后，点击 **启动** 按钮
3. 功能开关状态变为 **运行中**

## 步骤 2：在代码中使用

在您的应用代码中检查功能开关状态：

### JavaScript 示例

```javascript
// 检查新推荐算法是否开启
const isNewAlgorithmEnabled = await SensorsWave.checkFeatureGate(
  'new_recommendation_algorithm'
);

if (isNewAlgorithmEnabled) {
  // 使用新推荐算法
  const recommendations = await getRecommendationsV2(userId);
} else {
  // 使用旧推荐算法
  const recommendations = await getRecommendationsV1(userId);
}

// 展示推荐商品
displayRecommendations(recommendations);
```

### Go 示例

```go
// 检查新推荐算法是否开启
user := sensorswave.User{LoginID: userId}
isNewAlgorithmEnabled, err := client.CheckFeatureGate(
    user,
    "new_recommendation_algorithm",
)
if err != nil {
    // 错误处理
    log.Printf("CheckFeatureGate error: %v", err)
}

var recommendations []Product
if isNewAlgorithmEnabled {
    // 使用新推荐算法
    recommendations = getRecommendationsV2(userId)
} else {
    // 使用旧推荐算法
    recommendations = getRecommendationsV1(userId)
}

// 展示推荐商品
displayRecommendations(recommendations)
```

### Android 示例

```kotlin
// 检查新推荐算法是否开启
Sensorswave.getInstance().checkFeatureGate("new_recommendation_algorithm") { isNewAlgorithmEnabled ->
    val recommendations = if (isNewAlgorithmEnabled) {
        // 使用新推荐算法
        getRecommendationsV2(userId)
    } else {
        // 使用旧推荐算法
        getRecommendationsV1(userId)
    }

    // 展示推荐商品
    displayRecommendations(recommendations)
}
```

### iOS 示例

```swift
// 检查新推荐算法是否开启
Sensorswave.getInstance().checkFeatureGate(key: "new_recommendation_algorithm") { isNewAlgorithmEnabled in
    let recommendations: [Product]
    if isNewAlgorithmEnabled {
        // 使用新推荐算法
        recommendations = getRecommendationsV2(userId: userId)
    } else {
        // 使用旧推荐算法
        recommendations = getRecommendationsV1(userId: userId)
    }

    // 展示推荐商品
    displayRecommendations(recommendations)
}
```

## 步骤 3：验证效果

### 1. 测试功能开关

使用内部测试账号登录应用：

1. 确保测试账号的 `is_internal_user` 属性设置为 `true`
2. 刷新应用，查看是否使用了新推荐算法
3. 检查功能是否正常工作

### 2. 查看使用数据

在 Sensors Wave 控制台：

1. 进入功能开关详情页
2. 查看 **数据** 标签
3. 查看报告数据：
   - Pass/Fail 累计流量
   - 各规则命中情况

## 步骤 4：扩大灰度范围

验证稳定后，逐步扩大开放范围：

### 1. 添加 1% 灰度规则

1. 进入功能开关编辑页面
2. 点击 **添加新规则**
3. 规则名称：1% 灰度用户
4. 不设置条件（或设置通用条件）
5. 分流设置：
   - **通过**：`1%`
   - **不通过**：`99%`
6. 拖动规则顺序，放在"内部测试用户"之后
7. 点击 **保存**

### 2. 监控关键指标

在 [事件分析](../analytics/event-analysis.mdx) 中创建监控图表：

- 新推荐算法的点击率
- 转化率变化
- 系统性能指标
- 错误率

### 3. 逐步扩大范围

如果指标正常，继续扩大灰度：

- 1% → 10% → 50% → 100%
- 每次扩大后观察 1-2 天

### 4. 全量发布

当灰度达到 100% 且运行稳定后：

1. 删除灰度规则
2. 将默认值改为 **通过（true）**
3. 功能对所有用户生效

## 步骤 5：清理功能开关

功能稳定运行一段时间后，可以清理功能开关：

### 1. 移除代码中的开关判断

```javascript
// 删除功能开关检查，直接使用新算法
const recommendations = await getRecommendationsV2(userId);
displayRecommendations(recommendations);
```

### 2. 归档功能开关

1. 在控制台进入功能开关详情页
2. 点击 **归档**
3. 功能开关不再生效，但保留历史记录

### 3. 删除旧代码

```javascript
// 可以安全删除旧推荐算法的代码
// const recommendations = await getRecommendationsV1(userId);
```

## 示例演示

[TODO: 添加截图]

1. 创建功能开关界面
2. 配置目标规则
3. 数据面板
4. 灰度发布过程

## 注意事项

### 开关命名

- 使用清晰描述性的名称，便于理解
- 使用小写字母和下划线（snake_case）
- 避免使用过于简短的名称（如 `flag1`、`test`）

### 默认值设置

- 新功能默认值通常设置为 **关闭**，通过规则逐步开启
- SDK 无法连接服务器时，会使用默认值作为降级方案

### 规则优先级

- 规则按照从上到下的顺序匹配
- 一旦命中某条规则，就返回该规则的值，不再继续匹配
- 将特殊规则（如内部测试）放在前面，通用规则（如百分比灰度）放在后面

### 性能考虑

- SDK 会在本地缓存功能开关配置，不会每次都请求服务器
- 配置变更后，SDK 会在 10 分钟内更新缓存
- 建议在应用启动时预加载功能开关配置

## 常见问题

### 功能开关不生效？

检查以下几点：

1. 确认功能开关已保存并启动
2. 检查用户是否满足规则条件
3. 查看 SDK 是否正确初始化
4. 检查网络连接是否正常

### 如何确保测试不影响生产数据？

1. 通过用户属性区分测试用户和正式用户
2. 在数据分析时过滤测试用户

### 功能开关会影响性能吗？

- SDK 使用本地缓存，对性能影响极小
- 建议控制功能开关总数在 100 个以内
- 定期清理不再使用的功能开关

## 下一步

现在您已经完成了第一个功能开关的创建和使用，接下来可以：

1. **[核心概念](core-concepts.mdx)**：深入了解功能开关的工作原理
2. **[创建和配置](create-and-configure.mdx)**：学习更多配置选项

---

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