后端前端【免费下载链接】flagsmithFlagsmith is an open-source feature flag platform with remote config, experimentation, and self-hosted or cloud deployment options.项目地址https://gitcode.com/gh_mirrors/fl/flagsmith点击查看免费下载Flagsmith 正在实验一套全新的功能开关Feature Flag更新端点用于替代传统分散的 Feature State、Segment Override 等 REST 操作为最常见的开关读写场景提供更统一的开发体验。本文以官方文档 updating-flags.md 为主线结合仓库内api/features/future/的完整源码实现带你掌握如何通过GET /api/__future__/...读取一个 flag 在环境中的完整服务状态如何用PATCH/PUT切换开关、修改默认值、按 Segment 定向发布、删除 Segment 覆盖与重配 A/B/n 多变量权重以及理解这些操作在特性版本化Feature Versioning与变更请求Change Requests下的行为边界。这些端点当前被标记为experimental官方计划先在自有 Dashboard 与 CLI 中内部使用dogfood最终使其成为正式接口因此语义与参数可能在正式化之前调整。在开启变更请求的环境中写入操作会被拒绝读取不受影响且端点不支持下发的 identity override身份覆盖。一、实验端点在哪里路由与入口这套端点对应的路由定义位于 api/api/urls/future.py包含两个 URL 模式均挂在api/__future__/前缀之下见 api/app/urls.py 中的include(api.urls.future, namespaceapi-future)# api/api/urls/future.py urlpatterns [ path( environments/str:environment_key/features/int:feature_id/, FlagAPIView.as_view(), nameflag, ), path( environments/str:environment_key/features/int:feature_id /segment-overrides/int:segment_id/, SegmentOverrideAPIView.as_view(), namesegment-override, ), ]由此可以得到两个基础资源方法路径用途GET/PATCH/PUT/api/__future__/environments/{environment_key}/features/{feature_id}/读取或更新 flag 在环境中的完整状态DELETE/api/__future__/environments/{environment_key}/features/{feature_id}/segment-overrides/{segment_id}/删除某个 Segment 的覆盖对应的视图类FlagAPIView与SegmentOverrideAPIView定义在 api/features/future/views.py。两个视图都要求通过IsAuthenticated认证Server-side SDK 场景通常使用Authorization: Api-Key {api_key}头传递环境 API Key然后按操作类型做环境级权限校验PATCH、PUT与DELETE还会先检查变更请求是否开启见下文变更请求与版本化限制。二、读取一个 flag 的当前状态GETGET返回 flag 在该环境中服务的一切内容响应结构与更新方法完全一致因此你可以先读、再改、再校验。curl https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/ \ -H Authorization: Api-Key {api_key}HTTP/1.1 200 OK Content-Type: application/json { environment_default: {enabled: true, value: {type: string, value: hello}, variants: []}, segment_overrides: [] }响应体由两个顶层属性构成environment_defaultflag 面向未命中任何 Segment 覆盖的默认服务状态包含enabled是否启用、value带类型的值对象、variants多变量权重列表segment_overrides按 Segment 定向的覆盖列表每个元素额外带有segment.id与priority。从源码看get_flagapi/features/future/services.py会读取环境中该 feature 的全部 FeatureState排除identity__isnullTrue之外的下发记录正是文档所说不支持 identity override的实现依据把无feature_segment的那条作为环境默认值其余按(priority, segment.id)排序映射为覆盖列表。响应中的value统一以字符串形式返回布尔值会被序列化为true/false类型则映射为string/integer/boolean见 api/features/future/mappers.py。三、更新一个 flagPATCH 与 PUT 的语义差异更新同样作用于上述资源PATCH与PUT均接受可选的environment_default与segment_overrides两个属性区别在于覆盖语义PATCH部分更新请求中未出现的属性保持不变适合逐项修改PUT整体替换请求中出现的每个属性都会被完整替换未列出的内容按重置处理——例如用PUT发送environment_default时会把它整个替换掉用PUT发送segment_overrides时会删除所有未列出的覆盖。文档明确提示use it with caution。源码中的对应实现在 api/features/future/views.pypatch调用_update_flag(..., replaceFalse)put调用_update_flag(..., replaceTrue)随后统一交给update_flagservices.py。一个值得注意的细节是空请求不会产生任何写入——集成测试 test_flag_endpoint.py 验证了PATCH {}、environment_default: {}、segment_overrides: []这类什么都不改的请求不会创建新版本、不写审计日志直接返回当前状态。值对象value objectvalue必须以带类型的对象传递由调用方声明类型、以字符串承载值从而保证往返round trip后类型不丢失Type示例string{type: string, value: hello}integer{type: integer, value: 42}boolean{type: boolean, value: true}序列化器 api/features/future/serializers.py 中type是FeatureValueType的枚举选择value是允许为空的字符串字段validate_value会调用FeatureStateValue().set_value(...)真正落库前做一次类型合法性校验例如给integer传入abc会被拒绝。1. 切换开关Toggle a flag on or off最典型的场景——在某个环境中启用或关闭一个 flag只需发送environment_default.enabledcurl -X PATCH https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/ \ -H Authorization: Api-Key {api_key} \ -H Content-Type: application/json \ -d { environment_default: {enabled: true} }HTTP/1.1 200 OK Content-Type: application/json { environment_default: {enabled: true, value: {type: string, value: hello}, variants: []}, segment_overrides: [] }注意响应返回的是 flag 在环境中的完整状态无论请求里发了哪些属性正好可以当作下一步操作的输入。2. 修改功能值Update a feature value改变 flag 在环境中的默认值curl -X PATCH https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/ \ -H Authorization: Api-Key {api_key} \ -H Content-Type: application/json \ -d { environment_default: { value: {type: integer, value: 1000} } }HTTP/1.1 200 OK Content-Type: application/json { environment_default: {enabled: true, value: {type: integer, value: 1000}, variants: []}, segment_overrides: [] }底层的写入逻辑在_write_environment_defaultservices.pyPATCH只写请求中出现的字段enabled、value、variants各自独立判断而PUT会把未提供的enabled重置为false、把未提供的value清空_clear_value会同时置空 string/integer/boolean 三个存储列把未提供的variants按多变量规则处理见下文。四、按 Segment 定向发布Roll out to a segment典型的灰度场景让 flag 只对某些 Segment 生效其余用户保持关闭。curl -X PATCH https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/ \ -H Authorization: Api-Key {api_key} \ -H Content-Type: application/json \ -d { environment_default: { enabled: false }, segment_overrides: [ { segment: {id: 101}, enabled: true, priority: 10 }, { segment: {id: 202}, enabled: true, priority: 20 } ] }HTTP/1.1 200 OK Content-Type: application/json { environment_default: {enabled: false, value: {type: string, value: standard}, variants: []}, segment_overrides: [ { segment: {id: 101}, priority: 10, enabled: true, value: {type: string, value: standard}, variants: [] }, { segment: {id: 202}, priority: 20, enabled: true, value: {type: string, value: standard}, variants: [] } ] }Segment 覆盖的继承与优先级规则这是整套 API 中语义最丰富的地方务必理解以下几点文档原文全部有据可查实现细节与 services.py、serializers.py 对应继承Segment 覆盖在未显式给出enabled、value、variants时直接继承环境默认值——它服务环境默认服务的一切内容直到你给它自己的配置。PUT在替换覆盖时对未提供的属性同样会恢复为继承环境默认值。新增 vs 更新PATCH中列出的覆盖按 Segment 增量新增或更新未列出的覆盖保持不变。新增覆盖时若省略priority默认取该覆盖在segment_overrides列表中的位置从 0 开始已存在的覆盖保持其原优先级除非你显式发送新的priority。优先级数字越小越靠前且不允许两个覆盖共享同一优先级会导致两个覆盖先后顺序不确定的请求会被拒绝400对应 api/features/future/exceptions.py 中的DuplicatePriorityError校验在_check_priorities完成。Segment 必须属于该 feature 所在项目SegmentReferenceSerializer.validate_id会校验Segment.live_objects.filter(idid, project_idfeature.project_id)跨项目引用会被拒绝同一个请求中重复引用同一 Segment 也会被validate_segment_overrides拒绝。让 Segment 覆盖值Segment 不仅可以覆盖开关状态也可以覆盖 feature 的值curl -X PATCH https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/ \ -H Authorization: Api-Key {api_key} \ -H Content-Type: application/json \ -d { segment_overrides: [ { segment: {id: 101}, value: {type: string, value: enterprise} } ] }HTTP/1.1 200 OK Content-Type: application/json { environment_default: {enabled: false, value: {type: string, value: standard}, variants: []}, segment_overrides: [ { segment: {id: 101}, priority: 10, enabled: true, value: {type: string, value: enterprise}, variants: [] }, { segment: {id: 202}, priority: 20, enabled: true, value: {type: string, value: standard}, variants: [] } ] }上面示例中Segment 101 获得值enterprise而 Segment 202 保持继承环境默认值standard。五、删除 Segment 覆盖删除单个覆盖有两种等价途径。方式一按 SegmentDELETE——删除后返回 flag 完整状态curl -X DELETE https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/segment-overrides/{segment_id}/ \ -H Authorization: Api-Key {api_key}HTTP/1.1 200 OK Content-Type: application/json { environment_default: {enabled: false, value: {type: string, value: standard}, variants: []}, segment_overrides: [ { segment: {id: 101}, priority: 10, enabled: true, value: {type: string, value: enterprise}, variants: [] } ] }删除后剩余的覆盖保持各自优先级。若该 flag 在该 Segment 上本来就没有覆盖则响应404SegmentOverrideNotFoundErrordetail 为 Segment override not found.。方式二用PUT提交完整覆盖列表——PUT会整体替换覆盖集合删除所有未列出的覆盖curl -X PUT https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/ \ -H Authorization: Api-Key {api_key} \ -H Content-Type: application/json \ -d { segment_overrides: [ { segment: {id: 101}, priority: 10, value: {type: string, value: enterprise} } ] }HTTP/1.1 200 OK Content-Type: application/json { environment_default: {enabled: false, value: {type: string, value: standard}, variants: []}, segment_overrides: [ { segment: {id: 101}, priority: 10, enabled: false, value: {type: string, value: enterprise}, variants: [] } ] }注意上面响应中 Segment 101 的enabled变成了false由于PUT替换覆盖时会把未提供的enabled重置为继承环境默认值此例环境默认enabled: false这正是文档PUTrestores that for whatever it omits的体现。六、多变量Multivariate与 A/B/n 权重调整对于已配置的多变量功能如实验可以通过variants属性在环境级与 Segment 级调整每个变体的权重。weight是 0100 之间的百分比允许小数如10.5未分配给任何变体的权重份额会被用于服务 flag 的默认value即对照组份额。调整环境级变体权重curl -X PATCH https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/ \ -H Authorization: Api-Key {api_key} \ -H Content-Type: application/json \ -d { environment_default: { variants: [ {id: 33, weight: 10}, {id: 34, weight: 10.5} ] } }HTTP/1.1 200 OK Content-Type: application/json { environment_default: { enabled: true, value: {type: string, value: control}, variants: [ {id: 33, weight: 10}, {id: 34, weight: 10.5} ] }, segment_overrides: [] }同时或单独调整 Segment 级权重curl -X PATCH https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/ \ -H Authorization: Api-Key {api_key} \ -H Content-Type: application/json \ -d { segment_overrides: [ { segment: {id: 101}, variants: [ {id: 33, weight: 25}, {id: 34, weight: 25} ] } ] }HTTP/1.1 200 OK Content-Type: application/json { environment_default: { enabled: true, value: {type: string, value: control}, variants: [ {id: 33, weight: 10}, {id: 34, weight: 10.5} ] }, segment_overrides: [ { segment: {id: 101}, priority: 0, enabled: true, value: {type: string, value: control}, variants: [ {id: 33, weight: 25}, {id: 34, weight: 25} ] } ] }多变量更新的三条硬性规则列表必须完整只要variants出现无论位于environment_default还是segment_overrides就必须包含该 feature 的所有变体即使某个变体权重为 0 也不能省略。校验逻辑见 serializers.py变体 id 必须在 feature 的多变量选项中缺任何一个都会报 Must include all features variants.总权重超过 100 也会被拒绝。PUT的environment_default必须携带variants因为PUT会整体替换environment_default对多变量 feature 而言省略variants等同于清空权重配置因此EnvironmentDefaultSerializer.validate会在replaceTrue且未提供variants时直接报错同样提示 Must include all features variants.。Segment 覆盖的继承规则PATCH更新已有覆盖时省略variants会保留该覆盖自己的权重新增覆盖或PUT替换覆盖时省略variants则继承环境默认值的权重。底层写入_write_variantsservices.py会按变体 id 更新或创建MultivariateFeatureStateValue的percentage_allocation真实落盘的是变体对应的分配百分比。七、变更请求与版本化限制重要文档开头的警告明确列出当前实验期的两条限制在源码中都能找到对应实现开启变更请求Change Requests的环境无法写入。views.py中的_check_change_requests_disabled会在environment.is_workflow_enabled为真时抛出ChangeRequestsEnabledError并记录flag.update_rejected结构日志GET不受影响集成测试 test_flag_endpoint.py 验证了变更请求开启时读取仍返回 200。这与平台的治理与合规机制相关可参考 change-requests.md。不支持 identity override身份覆盖。_get_feature_states固定使用identity__isnullTrue过滤services.py即端点只处理环境默认值 Segment 覆盖两层不会触碰任何按 identity 下发的记录。另外这套端点是版本化无关的update_flag与delete_segment_override内部会根据环境是否开启 V2 特性版本化environment.use_v2_feature_versioning创建草稿版本EnvironmentFeatureVersion再发布调用方无需关心 Feature Versioning 的细节详见 Feature Versioning 文档 与 services.py 中的_create_draft_version/_publish_version。八、权限模型与错误语义从 api/features/future/permissions.py 可以看到这套端点精细的权限拆分属性级权限environment_default需要UPDATE_FEATURE_STATEsegment_overrides需要MANAGE_SEGMENT_OVERRIDES读取只要具备VIEW_ENVIRONMENT或上述任一写权限即可GET写入逐属性校验——只允许写你有权限的属性如果你对请求中的所有属性都无权限响应为404不暴露环境存在性对部分属性无权限则返回403 PermissionDenied。集成测试 test_flag_endpoint.py 验证了无权限用户GET返回 404。常见错误码汇总场景HTTP 状态依据请求体不是对象400 Expected an object.views.py值类型非法如 integer 传非数字400FeatureValueError校验变体列表不完整 / 权重超 100 / 非多变量 feature 传 variants400serializers.pySegment 不在同一项目 / 重复 Segment400SegmentReferenceSerializer/validate_segment_overrides覆盖优先级冲突400DuplicatePriorityErrorexceptions.py删除不存在的 Segment 覆盖404SegmentOverrideNotFoundError变更请求环境写入4xxChangeRequestsEnabledErrorviews.py结语这套__future__更新端点把读一个 flag 在环境中的完整状态、改它的开关与默认值、按 Segment 定向发布、删覆盖、调多变量权重收敛到两条 REST 资源上同时保持对 Feature Versioning 的透明与对 Change Requests 的敬畏。虽然当前仍处于 experimental 阶段但它代表了 Flagsmith 在 API 易用性上的演进方向以flag 在环境中的完整状态为最小读写单元让 Dashboard、CLI 与自动化脚本可以用一致的方式操作功能开关。对于希望深度参与验证的读者可以从 api/features/future/ 目录的源码与 test_flag_endpoint.py 集成测试入手观察其完整的行为契约。赞分享后端前端【免费下载链接】flagsmithFlagsmith is an open-source feature flag platform with remote config, experimentation, and self-hosted or cloud deployment options.项目地址https://gitcode.com/gh_mirrors/fl/flagsmith点击查看免费下载相关推荐Flagsmith 实验功能端到端实战从 PayPal 按钮多变量 Flag 到转化率验证与全量发布Flagsmith 实验功能端到端实战从 PayPal 按钮多变量 Flag 到转化率验证与全量发布 本篇技术指南以一个真实可复现的 A/B 实验为线索完整后端前端DataHub OpenAPI 使用指南REST API 端点、批量读写与通用 Patching 实战DataHub OpenAPI 使用指南REST API 端点、批量读写与通用 Patching 实战 本篇技术指南围绕 DataHubThe Contex数据目录数据治理数据血缘后端前端数据工程数据集成Flagsmith 功能开关生命周期Flag Lifecycle最佳实践短生命周期与长生命周期开关的完整管理指南Flagsmith 功能开关生命周期Flag Lifecycle最佳实践短生命周期与长生命周期开关的完整管理指南 在 Flagsmith 中功能开关F后端前端上一篇如何用5分钟掌握在线图表编辑Mermaid编辑器的零门槛指南下一篇微信聊天记录永久保存终极指南免费工具WeChatExporter完整使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考