Title: 常见问题
Locale: zh
URL: https://sensorswave.com/docs/feature-gates/faq/
Description: 功能开关使用过程中的常见问题解答
本文汇总了功能开关使用过程中的常见问题和解答。

## 基础问题

### 功能开关和 A/B 测试有什么区别？

**功能开关**：
- 控制功能的开启和关闭
- 用于降低发布风险
- 不需要统计显著性检验

**A/B 测试**：
- 对比不同方案的效果
- 用于验证假设和优化决策
- 需要随机分组和统计检验

详见 [功能开关与 A/B 测试](gates-vs-experiments.mdx)。

### 什么时候应该使用功能开关？

以下场景推荐使用功能开关：

1. **新功能灰度发布**：逐步验证稳定性
2. **功能降级保障**：快速关闭有问题的功能
3. **付费功能控制**：不同用户等级的权限管理
4. **季节性功能**：节日促销等临时功能
5. **用户定向**：为特定用户群体开启功能

详见 [使用场景与案例](use-cases.mdx)。

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

**影响极小**：

- SDK 使用本地缓存，避免频繁网络请求
- 配置更新采用增量推送
- 规则匹配在本地完成，毫秒级响应

**优化建议**：

- 控制功能开关总数在 100 个以内
- 使用批量查询减少调用次数
- 应用启动时预加载配置

详见 [SDK 集成 - 性能优化](sdk-integration.mdx#性能优化)。

### 功能开关的配置多久生效？

SDK 每 10 分钟检查配置更新，客户端收到更新后立即生效。

**验证方法**：

1. 修改功能开关配置
2. 等待 SDK 下次配置更新（最多 10 分钟）
3. 或等待 SDK 自动更新配置（每 10 分钟）
4. 验证新配置是否生效

## SDK 相关

### SDK 无法连接服务器时会怎样？

**降级策略**：

1. 使用本地缓存的配置（如果有）
2. 如果没有缓存，使用代码中指定的默认值
3. 记录日志，便于排查问题

**最佳实践**：

```javascript
// 始终提供降级逻辑
const isEnabled = await SensorsWave.checkFeatureGate('new_feature');
// checkFeatureGate 在无法获取配置时返回 false
```

### 如何在代码中检查功能开关？

**JavaScript**：

```javascript
const isEnabled = await SensorsWave.checkFeatureGate('feature_name');
```

**Go**：

```go
user := sensorswave.User{
    LoginID: "user_id",
}
isEnabled, err := client.CheckFeatureGate(user, "feature_name")
```

**Android (Kotlin)**：

```kotlin
Sensorswave.getInstance().checkFeatureGate("feature_name") { isEnabled ->
    // 使用 isEnabled
}
```

**iOS (Swift)**：

```swift
Sensorswave.getInstance().checkFeatureGate(key: "feature_name") { isEnabled in
    // 使用 isEnabled
}
```

详见 [SDK 集成](sdk-integration.mdx)。

### 如何查询多个功能开关？

逐个调用 `checkFeatureGate` 方法查询各个功能开关：

```javascript
const feature1Enabled = await SensorsWave.checkFeatureGate('feature_1');
const feature2Enabled = await SensorsWave.checkFeatureGate('feature_2');
const feature3Enabled = await SensorsWave.checkFeatureGate('feature_3');
```

> **提示**：SDK 使用本地缓存，多次调用 `checkFeatureGate` 的性能开销极小。

## 配置和规则

### 如何创建功能开关？

1. 登录 Sensors Wave 控制台
2. 点击左侧菜单的 **功能开关**
3. 点击 **新建功能开关**
4. 填写基本信息和规则
5. 点击 **保存**，然后点击 **启动**

详见 [快速开始](quick-start.mdx)。

### 规则的匹配顺序是什么？

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

**示例**：

| 顺序 | 规则 | 返回值 |
|-----|------|--------|
| 1 | 内部测试用户 | 开启 |
| 2 | VIP 用户 | 开启 |
| 3 | 10% 灰度 | 开启 |
| - | 默认值 | 关闭 |

**建议顺序**：

1. 白名单规则（最高优先级）
2. 用户属性规则
3. 主体 ID 规则
4. 百分比灰度规则（最低优先级）

详见 [核心概念 - 规则优先级](core-concepts.mdx#规则组合)。

### 百分比灰度是如何分配的？

**分配算法**：

```
hash(user_id + gate_key) % 100  **注意**：规则修改后，SDK 会在下次检查配置更新时获取最新规则，请谨慎操作。

### 用户属性是什么时候设置的？

用户属性需要在使用功能开关前设置：

```javascript
// 设置用户属性
SensorsWave.profileSet({
  user_level: 'VIP',
  subscription_tier: 'professional',
  country: 'CN'
});

// 之后检查功能开关，会根据用户属性匹配规则
const isEnabled = await SensorsWave.checkFeatureGate('vip_feature');
```

详见 [用户标识](../data-integration/user-identification.mdx)。

## 灰度发布

### 灰度发布需要多长时间？

**典型时间表**：

| 阶段 | 覆盖用户 | 观察周期 |
|-----|---------|---------|
| 内部测试 | 0.1% | 1-2 天 |
| 1% 灰度 | 1% | 2-3 天 |
| 10% 灰度 | 10% | 2-3 天 |
| 50% 灰度 | 50% | 1-2 天 |
| 全量发布 | 100% | 1-2 周 |

**总计**：2-4 周

时间可根据功能重要程度和风险级别调整。

时间可根据功能重要程度和风险级别调整。

### 如何快速回滚功能？

**方法一：修改规则**

1. 进入功能开关详情页
2. 将百分比规则改为 0%
3. 或删除所有规则，默认值保持关闭

**方法二：停用开关**

1. 进入功能开关详情页
2. 点击 **停用** 按钮
3. 所有用户立即看到旧功能

**生效时间**：SDK 在 10 分钟内更新缓存

### 如何观察灰度发布的效果？

使用 [事件分析](../analytics/event-analysis.mdx) 关注以下指标：

**技术指标**：错误率、响应时间、崩溃率

**业务指标**：转化率、留存率、用户满意度

### 什么时候应该回滚？

**立即回滚的情况**：

- 错误率显著上升（> 10%）
- 出现严重 Bug
- 关键指标显著下降（> 5%）
- 收到大量负面反馈

**谨慎推进的情况**：

- 轻微的性能下降
- 少量用户反馈问题
- 指标波动在正常范围内

**继续推进的情况**：

- 各项指标稳定
- 用户反馈整体正面
- 无严重问题

## 管理和维护

### 如何查看功能开关的使用情况？

1. 进入功能开关详情页
2. 点击 **使用分析** 标签
3. 查看：
   - 覆盖用户数
   - 检查次数
   - 规则命中情况

详见 [管理功能开关 - 使用分析](management-and-monitoring.mdx#使用分析)。

### 如何清理不再使用的功能开关？

**清理步骤**：

1. **移除代码中的开关判断**：
   ```javascript
   // 删除功能开关检查，直接使用新功能
   const recommendations = await getRecommendationsV2(userId);
   ```

2. **删除旧代码**：
   ```javascript
   // 可以安全删除旧实现
   ```

3. **归档功能开关**：
   在控制台点击 **归档** 按钮

4. **部署代码**：
   部署移除了功能开关的新代码

**清理时机**：

- 临时开关在全量发布后 1-2 个月
- 确认功能稳定，不再需要回滚

详见 [最佳实践 - 生命周期管理](best-practices.mdx#生命周期管理)。

### 功能开关数量有限制吗？

**没有硬性限制**，但建议：

- 单个项目 < 100 个功能开关
- 定期清理不再使用的开关
- 避免为每个小改动都创建开关

**原因**：

- 过多开关影响性能
- 增加维护成本
- 代码难以理解

### 功能开关的配置会被记录吗？

**是的**，所有操作都会记录：

- 操作时间
- 操作人
- 操作类型（创建、编辑、发布、停用等）
- 变更内容（配置对比）

**查看方式**：

1. 进入功能开关详情页
2. 点击 **历史记录** 标签
3. 查看完整的变更历史

详见 [管理功能开关 - 历史记录](management-and-monitoring.mdx#历史记录)。

## 故障排查

### 功能开关不生效怎么办？

**排查步骤**：

1. **确认功能开关已发布**：
   - 检查状态是否为 **已启用**
   - 草稿状态的开关不会生效

2. **检查用户是否满足规则**：
   - 查看用户属性是否正确
   - 验证规则配置是否有误

3. **检查 SDK 配置**：
   - 确认 SDK 已正确初始化
   - 升级到最新版本

4. **检查网络连接**：
   - 确认 SDK 能连接到服务器
   - 查看 SDK 日志

5. **等待配置更新**：
   SDK 每 10 分钟自动更新配置，修改后请等待下一次更新生效。

### 用户看到的功能开关状态不一致？

**可能原因**：

1. **规则配置问题**：
   - 用户属性不同，命中不同规则
   - 百分比灰度导致部分用户开启

2. **缓存问题**：
   - 配置刚更新，部分用户还在使用旧配置
   - 等待配置更新生效（最多 10 分钟）

**解决方法**：

- 检查规则配置是否正确
- 等待配置更新生效

### SDK 报错怎么办？

**查看错误日志**：

```javascript
// 启用调试模式
SensorsWave.init('YOUR_SOURCE_TOKEN', {
  debug: true  // 输出详细日志
});
```

**常见错误**：

| 错误信息 | 原因 | 解决方法 |
|---------|------|---------|
| `Invalid API key` | API key 错误 | 检查 API key 是否正确 |
| `Network error` | 网络连接失败 | 检查网络连接和防火墙设置 |
| `Gate not found` | 功能开关不存在 | 检查开关名称是否正确 |
| `User not identified` | 用户未标识 | 调用 `SensorsWave.identify()` 标识用户 |

### 如何联系技术支持？

如果遇到无法解决的问题：

1. **查看文档**：
   - 阅读相关文档
   - 查看常见问题

2. **联系支持团队**：
   - 邮件：wave-support@sensorsdata.cn

3. **提供信息**：
   - 详细的问题描述
   - 错误信息和日志
   - SDK 版本信息
   - 复现步骤

## 其他问题

### 功能开关可以用于移动端吗？

**支持**：

- Android SDK
- iOS SDK

详见 [SDK 集成](sdk-integration.mdx)。

### 功能开关支持离线模式吗？

**部分支持**：

- SDK 会缓存最后一次获取的配置
- 离线时使用缓存配置
- 无缓存时使用代码中的默认值

**建议**：

- 始终指定默认值
- 应用启动时预加载配置

### 功能开关可以用于后端服务吗？

**可以**：

功能开关不仅适用于前端，也适用于后端服务：

- 服务端 SDK（Go, Java, Python 等）
- 微服务架构
- API 降级

**示例**：

```go
// 检查推荐服务是否启用
user := sensorswave.User{LoginID: userId}
enabled, err := client.CheckFeatureGate(user, "recommendation_service_enabled")
if err != nil {
    log.Printf("CheckFeatureGate error: %v", err)
}

if enabled {
    // 调用推荐服务
    recommendations := callRecommendationService(userId)
} else {
    // 降级：返回默认推荐
    recommendations := getDefaultRecommendations()
}
```

### 功能开关有使用限制吗？

**没有严格限制**，但建议：

- 功能开关数量 < 100 个
- 规则数量（每个开关）< 20 条
- 检查频率合理（避免过度调用）

**超出建议值**：

- 可能影响性能
- 增加维护成本
- 建议优化和清理

## 下一步

如果您还有其他问题：

1. 查看 [概述](overview.mdx) 了解功能开关基础
2. 参考 [快速开始](quick-start.mdx) 创建第一个功能开关
3. 联系技术支持获取帮助

---

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