Bitwarden 贡献文档
⮐ Bitwarden Contributing Documentation我的博客联系我
  • 关于
  • 入门
    • 概述
    • 工具
    • 服务器
      • 设置指南
      • 高级服务器设置
      • 数据库
        • MSSQL
        • 实体框架
      • 事件日志
      • Ingress 隧道
      • SCIM
      • 自托管指南
      • 系统管理门户
      • 单点登录 (SSO)
        • 本地 IdP
        • Okta
      • 故障排除
      • 用户机密
      • 公共 API
    • 网页客户端
      • 网页密码库
        • WebAuthn
      • 浏览器端
        • 生物识别解锁
        • Firefox 隐私模式
      • 桌面端
        • Mac App Store Dev
        • Microsoft Store
        • Native Messaging Test Runner
        • 更新测试
      • CLI
      • 故障排除
    • 移动端
      • Android
        • F-Droid
      • iOS
      • .NET MAUI (legacy)
        • Android
        • iOS
        • watchOS
    • SDK
      • 内部 SDK
      • Secrets Manager
        • Integrations
          • Kubernetes
    • 业务 App
      • 目录连接器
        • JumpCloud
        • OpenLDAP Docker 服务器
      • Key Connector
      • Splunk App
  • 贡献
    • 贡献
    • 代码样式
      • =Android & Kotlin
      • Angular & TypeScript
      • C#
      • =Rust
      • T-SQL
      • =Swift
      • Tailwind
    • 数据库迁移
      • 进化数据库设计
    • 提交签名
    • 拉取请求
      • =贡献审查程序
      • 分支
      • 代码审查
      • UI 审查 - Chromatic
    • 无障碍
    • 依赖管理
    • 功能标记
    • 模板存储库
    • 测试
      • =数据库集成测试
      • 负载测试
      • 单元测试
        • 命名约定
        • 测试结构
    • 修改用户机密
  • 架构
    • 架构
    • 架构决策记录 (ADR)
      • 0001 - Angular Reactive Forms
      • 0002 - Public API for modules
      • 0003 - Adopt Observable Data Services for Angular
      • 0004 - Refactor State Service
      • 0005 - Refactor Api Service
      • 0006 - Clients: Use Jest Mocks
      • 0007 - Manifest V3 sync Observables
      • 0008 - Server: Adopt CQRS
      • 0009 - Composition over inheritance
      • 0010 - Angular Modules
      • 0011 - Scalable Angular Clients folder structure
      • 0012 - Angular Filename convention
      • 0013 - Avoid layered folder structure for request/response models
      • 0014 - Adopt Typescript Strict flag
      • 0015 - Short Lived Browser Services
      • 0016 - Move Decryption and Encryption to Views
      • 0017 - Use Swift to build watchOS app
      • 0018 - Feature management
      • 0019 - Adoption of Web Push
      • 0020 - Observability with OpenTelemetry
      • 0021 - Logging to Standard Output
      • =0022 - Authorization
      • =0023 - Identifying Integrated Clients
    • 移动客户端架构
      • =Android
      • =iOS
        • =推送通知故障排除提示
      • =.NET MAUI (legacy)
        • =概述
        • watchOS
    • =SDK 架构
      • =数据模型
      • =依赖
      • Password Manager
        • Web
          • =互操作性
      • =Secrets Manager
      • =服务器绑定
      • =版本控制和破坏性更改
    • 网络客户端架构
      • 概述
      • 数据模型
      • 表示层
        • Angular
        • CLI
      • =依赖注入
      • 服务层
        • Vision
        • 实现
    • 服务器架构
    • 深度剖析
      • 身份验证
        • 双重身份验证
      • =授权
      • =浏览器自动填充
        • 收集页面详细信息
        • 生成并执行填充脚本
        • 表单提交检测
        • Shadow DOM
        • =内联自动填充菜单
      • Captcha
      • =只读数据库副本
      • 事件日志
      • =FIDO2 和通行密钥
        • =凭据
        • =操作
        • =命名惯例
        • =实现
          • =提供程序
            • =浏览器扩展
          • =依赖方
            • =用于解密的通行密钥
        • =术语表
      • 推送通知
        • 移动端推送通知
        • 其他客户端推送通知
      • =SSH 密钥和代理
        • =SSH 代理
      • =状态提供程序框架
        • =派生状态
    • =安全
      • =定义
      • =原则
        • =P01 - 锁定的密码库是安全的
        • =P02 - 半受损设备密码库的有限安全性
        • =P03 - 完全损坏的系统没有安全性
        • =P04 - 控制密码库数据的访问权限
        • =P05 - 将安全漏洞的影响降至最低
      • =要求
由 GitBook 提供支持
在本页
  • 背景​
  • 标记数据源​
  • 本地配置:用户机密​
  • 本地配置:JSON 文件​
  • 本地配置:代码修改​
  • 创建一个新标记​
  • 本地开发
  • LaunchDarkly 中的定义​
  • 在代码中使用功能标记​
  • 客户​端
  • 服务器​
  • 功能标志生命周期​
  • 自托管注意事项​
  1. 贡献

功能标记

上一页依赖管理下一页模板存储库

最后更新于1个月前

对应的

背景​

基于 添加了对功能标记的支持。一些亮点:

  • 当请求标记的状态时提供。我们目前允许针对用户、组织和服务账户进行定位。仅将 ID 发送到 LaunchDarkly,以避免 PII 共享。

  • 所有可用的功能标记状态都提供给调用 的客户端。

  • 环境(目前是生产、质量保证 (QA) 和开发)的存在可以进一步细分标记状态。这将根据代码运行的位置自动进行。

标记数据源​

在客户端或服务器代码中使用功能标记时,了解标记的来源非常重要。

标志的来源取决于正在使用的 Bitwarden 服务器实例,对于客户端开发,标记由 Bitwarden API 提供。

服务器配置
标记来源

本地开发

本地应用程序设置、JSON 文件或代码修改

自托管

除非提供上述本地配置,否则标记为「off」

QA Cloud

LaunchDarkly QA

Production Cloud

LaunchDarkly Production

自托管支持

自托管客户未正式支持功能标记。在 Bitwarden 内部测试之外,不支持使用应用程序设置或 JSON 文件来获取功能标记值。请参阅,了解功能标记如何应用于自托管。

本地开发服务器实例不会查询 LaunchDarkly 的功能标记值。

如果您需要在本地开发期间更改任何功能标记值的默认值,则需要设置本地应用程序设置或基于文件的数据源。如果没有本地数据存储,所有标记值都将解析为其默认(「off」)值。

本地配置:用户机密​

要通过应用程序设置设置数据源,请将以下内容放入您的用户机密中:

{
  "globalSettings": {
    "launchDarkly": {
      "flagValues": {
        "example-boolean-key": true,
        "example-string-key": "value"
      }
    }
  }
}

将 example-boolean-key 和 example-string-key 替换为您的标记名称,并相应地更新标记值。

请记住运行 dev/setup_secrets.ps1 并重新启动服务器以使新的机密生效。

环境变量也可以像其他应用程序设置覆盖一样使用。

本地配置:JSON 文件​

要通过本地文件设置数据源,请创建一个 flags.json 文件,如下所示:

{
  "flagValues": {
    "example-boolean-key": true,
    "example-string-key": "value"
  }
}

将 example-boolean-key 和 example-string-key 替换为您的标记名称,并相应地更新标记值。

默认情况下,LaunchDarkly 启动将在根项目目录中查找此文件(例如 Api 项目的 /src/Api/),并将其部署到构建输出目录。但是,如果您希望将文件存储在其他位置,则可以使用 FlagDataFilePath 配置设置来覆盖它。该文件必须在构建解决方案之前存在,但一旦存在,您就可以更改文件内容并在运行/调试代码时立即查看结果。

本地配置:代码修改​

return new Dictionary<string, string>()
{
    { ExampleBooleanKey, "true" }
};

这只能暂时使用,并作为功能标记清理过程的一部分,以及为不使用或不了解替代配置方法的安装启用快速功能可用性。

客户端中使用的标记的本地数据源

为了在客户端中使用功能标记,上述设置应在 Api 项目中定义 - 这是因为客户端用来查询功能标记的 /config 端点位于 Api。这样做将确保检索到正确的标记值并将其发送到客户端。

创建一个新标记​

当开始开发新功能时,请与您的团队讨论是否应将其放在功能标记后面。团队应该就标记内容的范围以及应该应用标记的位置(客户端和服务器端)达成一致。虽然对于“功能”的构成没有明确的规则,但应共同努力实现标记及其各自用途的最佳平衡。

一旦您确定需要一个功能标记,第一步就是确定一个名称。命名的建议是:

  • 使用短横线命名该标记(小写字母和破折号分隔,例如 enable-feature)。

  • 对于布尔标记,不必包含 enable 动词,因为它暗示它是一个功能标记。例如,建议使用 new-feature 而不是 enable-new-feature。

  • 保持键名简洁。

本地开发

当您开始使用该功能时,请使用本地配置选项之一将标记显示给您的使用代码,以确保所有支持的标记值的行为都是正确的。由于初始开发的功能标记不必存在于 LaunchDarkly 中,因此在确定最终实现之前不要在线创建它们。

本地客户端开发

请记住,对于客户端本地开发,功能标记的来源取决于您正在使用的服务器实例。例如,如果您正在开发客户端代码并引用 QA Cloud Bitwarden API,则必须在此处配置该标记,而不是在本地数据存储中。

LaunchDarkly 中的定义​

为了在任何部署的环境中测试功能标记,必须首先在 LaunchDarkly Web 应用程序中定义它。为此,请向您的工程经理请求标记- 他们将拥有适当的访问权限。你们应该讨论:

  • 标记的数据类型。

  • 标记的默认值。

  • 标记的可能值(对于非布尔类型)。

  • 任何应驱动标记行为的基于上下文的规则。

我什么时候应该在 LAUNCHDARKLY 中请求标记?

作为一般规则,应请求在 LaunchDarkly 中创建功能标记,作为使用该标记将代码合并到主线分支的一部分。由于使用自托管实例进行本地开发和 QA 测试将使用本地数据源,因此第一次引用 LaunchDarkly 中的标记是在代码部署到云环境时。

在代码中使用功能标记​

当针对功能标记进行编码时,尽可能默认为「off」状态 - 进行防御性编码,以便在标记完全不可用时维护现有功能。当接口支持它时,还应向功能标记访问器提供暗示「off」的默认值。

离线模式使默认值变得更加重要,本地开发以及自托管安装意味着离线。不仅在 LaunchDarkly 的在线标记定义中设置安全默认值,而且还要在代码中设置。

客户​端

所有客户端都通过查询 Bitwarden API 上的 /config 端点来检索其功能标记。客户端不直接引用LaunchDarkly客户端SDK。

为了优化功能标记的使用,不会在每次请求标记值时从服务器检索它们。相反,按照以下时间间隔从服务器检索标记:

  • 在应用程序启动时。

  • 应用程序启动后每小时一次。

  • 同步(自动和手动)。

  • 在环境变化时。

从下面定义的服务请求标记值将为使用组件提供来自这些检索事件之一的最新值。

网络​端

定义后,可以通过注入 ConfigService 并使用其中一种检索方法来检索该值:

  • getFeatureFlagBool()

  • getFeatureFlagString()

  • getFeatureFlagNumber()

移动端

通过 ConfigService 上的 GetAsync() 方法检索功能标记值。

要使用功能标记,您应该首先在 Constants 文件中将新功能标记定义为字符串常量值。

定义后,可以通过注入 IConfigService 并使用其中一种检索方法来检索该值:

  • GetFeatureFlagBoolAsync()

  • GetFeatureFlagStringAsync()

  • GetFeatureFlagNumberAsync()

服务器​

  1. 在需要功能标记的地方注入 IFeatureService。请注意,访问功能状态时您还需要 ICurrentContext。

  2. 在要素服务上通过适当的方法使用上述关键常量:

    • IsEnabled 用于布尔值,false 为假定的默认值。

    • GetIntVariation 用于整数,0 为假定的默认值。

    • GetStringVariation 用于字符串,null 为假定的默认值。

功能标志生命周期​

当您需要更改 LaunchDarkly 内的在线功能时,请让您的管理层知道。只有少数用户拥有 LaunchDarkly 账户,以节省许可成本。

功能标记不一定需要从 LaunchDarkly 中删除,只是未使用即可。将它们链接到 Jira 有助于创建该功能的历史记录,并且可以保留大量的在线日志和审计记录。长时间未访问的功能标记将自动转至「非活动」状态,这也有助于识别需要清理的技术债务。

在定义故事的子任务时,请务必包含一个清理任务,用于从代码中删除功能标记- 重要的是这些任务不要保留太久并假设永久存在。一旦功能成功启动,请在稍后阶段解决该任务。

自托管注意事项​

自托管实例将无法访问 LaunchDarkly,因此从 API 检索的服务器配置会将所有功能标记评估为其默认状态,除非服务器进行了其他配置。这在实践中意味着,在该功能可用于自托管实例之前,必须从代码中删除该功能标记。这意味着分阶段的功能发布周期,如下所示:

  1. 发布云并自托管,功能已关闭

  2. 打开功能标记,仅针对云实例启用该功能

  3. 发布云和移除功能标记的自托管,从而为自托管实例启用该功能

在某些情况下,可能需要在清理活动完全完成之前将功能标记值更改为默认状态以外的值,特别是当已部署的客户端仍然依赖于返回的标记值来确保某些功能时。在服务器代码库中,除了功能标记之外,还存在一个方法 GetLocalOverrideFlagValues() ,其中可以将覆盖作为字典键值对放置:

名称确定后,将功能标记添加到服务器上的 常量文件中。这将允许通过您在下面配置的任何数据源从 LaunchDarkly 检索标记。

通过 上的 fetchServerConfig() 方法检索功能标记值。

要使用功能标记,您应该首先将新功能标记定义为 枚举中的枚举值。

在 列表中查找您计划使用的密钥的常量。它应该在添加。

自托管安装可以选择配置替代以更快地采用功能。

FeatureFlagKeys
ConfigService
FeatureFlags
FeatureFlagKeys
创建新标记时
官方页面地址
ADR 0018
上下文
配置 API
自托管注意事项
常量定义
数据源