FlexPrice 功能（Feature）与权益（Entitlement）定义指南：从计费指标到计划级权限控制

【免费下载链接】flexpriceUsage-based pricing and billing for developers Cloud or self-hosted ⚙️ No-code UI Realtime usage metering Credits top-ups Control feature access项目地址https://gitcode.com/gh_mirrors/fl/flexprice点击查看免费下载本指南以 FlexPrice 的 PRD 文档《Defining features》为核心骨架系统讲解如何在 FlexPrice 中定义计费指标Billable Metric、三类 FeatureBoolean / Metered / Config及其在计划Plan中的权益Entitlement配置方式。读完本文你将掌握 Feature 类型体系、usage_reset_period 重置周期、Grant 优先级燃烧顺序、软/硬限额等关键概念并能结合源码理解其底层实现直接用于设计自己的按量计费与权限控制方案。一、从计费指标到 FeatureFlexPrice 的核心抽象FlexPrice 将「客户能从计划中获得什么」抽象为两层概念计费指标Billable Metric描述“用量是什么、如何被计量”是 Meter 与事件流层面的定义。Feature功能描述“客户被授予了什么”是对计费指标的业务化包装一个 Feature 可以关联一个 Meter计量型也可以只是一个布尔开关布尔型或一段自定义配置配置型。PRD 文档给出了一条完整链路先定义计费指标再把指标包装成 Feature最后通过 Entitlement权益把 Feature 绑定到具体计划上形成类似下表的能力矩阵Basic planPro planPricing (Monthly)$10/ month$20/monthPricing (Annual)$8/ month$18/monthFeaturesAuthNoYesGPT 4o model1M tokensUnlimitedPageviews5k per month10k per monthSLATicket / Email Support 12-24 HoursTicket / Email Support 12 Hours表中 Auth 对应 Boolean Feature有/无GPT 4o model 与 Pageviews 对应 Metered Feature带额度上限SLA 则适合用 Config Feature 表达结构化差异。二、定义计费指标Billable Metric以 tokens_total 为例PRD 中定义计费指标的核心步骤Event name事件名tokens_totalKey计量键modelValues取值集合gpt-4o、4o-mini这意味着每当系统上报tokens_total事件时FlexPrice 会依据事件中的model字段取值如gpt-4o对 token 用量进行聚合统计。后续创建 Metered Feature 时通过meter_id直接引用该计费指标实现「指标即数据来源、Feature 即业务语义」的解耦。在 ent/schema/feature.go 中Feature 的meter_id字段是可选外键且 Postgres 类型为varchar(50)、可空Nillable印证了「Metered Feature 关联计量指标、Boolean/Config Feature 不关联」的设计。ent/schema/feature.go的索引idx_feature_tenant_env_meter_id也只对meter_id IS NOT NULL的记录生效进一步说明该关联是按需建立的。三、Feature 的三种类型Boolean / Metered / ConfigPRD 把 Feature 分为三类这与 internal/types/feature.go 中定义的枚举完全一致const ( FeatureTypeMetered FeatureType metered // 计量型按用量授权 FeatureTypeBoolean FeatureType boolean // 布尔型有/无 FeatureTypeStatic FeatureType static // 静态值 FeatureTypeConfig FeatureType config // 配置型自定义结构 )3.1 Boolean布尔型表示“客户是否有权访问某功能”只有 yes/no 两种取值。例Basic 计划没有Auth 访问权Pro 计划有Auth 访问权。建模字段Feature Name AuthFeature type Boolean。对应到权益侧ent/schema/entitlement.go 中的is_enabled字段默认false正是 Boolean Feature 的实现载体——值为true表示放行。这类 Feature 不关联 Meter不产生用量计量。3.2 Metered计量型表示“通过施加额度上限limit来授予访问权”是配额控制的入口。PRD 中的例子Limited access 场景如 ChatGPT 场景下仅允许访问 o1 和 o1-mini 模型。配额场景Basic 计划可访问 gpt-4o 模型额度为 1M tokensPro 计划可访问无限量 gpt-4o 模型。建模字段Feature Name GPT 4o modelFeature type MeteredMeter type tokens_totalFilter GPT 4o。这里的Filter是关键计量指标tokens_total是通用的但只有命中 Filter如 model gpt-4o的用量才计入该 Feature 的配额。通过meter_id关联指标、在 Feature/Meter 层配置过滤条件即可实现「同一指标、不同模型、不同配额」的精细化控制。3.3 Config配置型用于表达无法用布尔或单纯数值表达的复杂计划能力例如 SLA 条款、响应时间承诺等结构化配置。对应 ent/schema/entitlement.go 中的config_valuejsonb类型与 ent/schema/feature.go 中的metadatajsonb类型字段。它可以承载任意 JSON 结构是计划差异化的弹性容器。在 internal/types/feature.go 中FeatureType.Validate()会对类型做白名单校验metered/boolean/static/config不合法取值直接返回ErrValidation错误防止脏数据进入系统。四、Feature 建模的源码细节LookupKey、单位与上报单位一个 Feature 在 ent/schema/feature.go 中拥有完整的字段体系除类型与 meter_id 外值得关注的还有lookup_keyvarchar(255)Immutable面向外部系统的稳定标识。库内提供了 GenerateLookupKey 辅助函数将名称小写化、非字母数字字符替换为下划线、去除首尾下划线例如GPT 4o model→gpt_4o_model。namevarchar(255)NotEmpty展示名如Auth、GPT 4o model。unit_singular / unit_plural计量单位如token/tokens。reporting_unit上报展示单位及换算率。在 internal/types/feature.go 中定义为{ unit_singular, unit_plural, conversion_rate }换算公式为reporting_unit_value unit_value × conversion_rate。示例基础单位是msconversion_rate 0.001时 5000 ms 显示为 5 seconds。换算实现见 internal/domain/feature/model.go 的ToReportingValue()。alert_settingsjsonb阈值告警配置critical / info用于接近配额时的预警。metadatajsonb任意自定义键值。group_idFeature 分组便于 UI 按组展示。唯一性约束见 ent/schema/feature.go对已发布status published且非空lookup_key的记录(tenant_id, environment_id, lookup_key)全局唯一避免同一租户下重复定义同名 Feature。五、权益Entitlement与重置周期月度额度如何落到年度计划上PRD 提出了两个经典问题如果计划的账单周期是年度yearly能否按月粒度提供权益如何判断权益是按月还是按年提供FlexPrice 的答案是权益粒度由usage_reset_period独立于账单周期显式指定。在 ent/schema/entitlement.go 中该字段的取值集合定义于 internal/types/entitlement.goconst ( ENTITLEMENT_USAGE_RESET_PERIOD_MONTHLY MONTHLY // 月度重置 ENTITLEMENT_USAGE_RESET_PERIOD_ANNUAL ANNUAL // 年度重置 ENTITLEMENT_USAGE_RESET_PERIOD_WEEKLY WEEKLY // 周度重置 ENTITLEMENT_USAGE_RESET_PERIOD_DAILY DAILY // 日度重置 ENTITLEMENT_USAGE_RESET_PERIOD_QUARTER QUARTERLY // 季度重置 ENTITLEMENT_USAGE_RESET_PERIOD_HALF_YEAR HALF_YEARLY // 半年重置 ENTITLEMENT_USAGE_RESET_PERIOD_NEVER NEVER // 永不过期 )因此一个年度计费的 Pro 计划完全可以配置一个usage_reset_period MONTHLY、usage_limit 10k的 Pageviews 权益实现“年付、月配额”的组合。系统不依赖账单周期推断权益周期而是由权益自身字段精确表达杜绝歧义。六、用量结转Preserve Usage / Overages未用完的额度能否顺延PRD 中的场景购买了年度 Basic 计划第一个月用了 3k 页面浏览量第二个月能否顺延上月未用的 2k 额度这类「unused 结转」语义需要显式建模。从 internal/domain/entitlement/model.go 的源码看FlexPrice 的 Entitlement 支持Grant配额授予机制HasGrantConfig()判断权益是否携带grant_quota/grant_duration_value/grant_measure/grant_duration_unit配置IsUnlimitedGrant()表示无上限授权grant_quota为 nil 即无限。是否顺延、顺延规则取决于 Grant 的aggregation_mode叠加模式与grant_allocation_behavior起始锚定行为见 ent/schema/entitlement.go并最终实例化为entitlement_grants表中的具体授予记录。设计结转能力时应结合「月度滚动授予 结转规则」组合实现而不是修改重置周期本身。七、用量优先级Usage Priority多 Grant 的燃烧顺序PRD 给出了一个非常具体的高价值场景——客户按用量计量 token订阅内每月可得 10,000 tokens另以额外费用购买每年 100,000 tokens 的增量包。希望客户先消费月度余额月度余额耗尽后再消费年度余额。做法是创建两个 GrantGrant 110,000 tokens随月度周期滚动priority 5Grant 2100,000 tokens每年循环授予priority 10燃烧消耗规则如下高优先级 Grant 先被消耗priority 数值更大者优先优先级相同时最接近到期日expiration date的 Grant 先被消耗优先级与到期日都相同时创建时间最早的 Grant 先被消耗。这套确定性排序规则保证了「额度耗尽顺序可预测」是钱包/配额系统正确性的基石——月度 10k 额度有明确的过期时间更接近到期因此天然优先于年度 100k 额度被消耗恰好满足「先用月度、后用年度」的业务诉求。实现侧权益的授予窗口由 GrantDuration 计算其中subscription_period单元无固定时长窗口等于订阅周期本身需在调用方按grant_duration_unit分支处理。八、软限额 vs 硬限额Soft Limit vs Hard LimitPRD 明确提出了软/硬限额的区分这正是 ent/schema/entitlement.go 中is_soft_limit字段默认false要解决的语义Hard Limit硬限额用量达到usage_limit后系统直接拒绝或停止服务。适用于“未付费不服务”的场景如免费版访问权。Soft Limit软限额用量超过usage_limit仍被允许但会触发告警、计费加成或降级提示。适用于“超量可继续使用、但需额外计费或通知”的场景如超出 1M tokens 后按量付费。在 internal/domain/entitlement/model.go 的领域模型中IsSoftLimit与UsageLimit、UsageResetPeriod并列说明限额语义由「额度数值 重置周期 软硬性质」三者共同定义。结合 ent/schema/feature.go 的alert_settingscritical / info 两级阈值软限额场景通常搭配阈值告警使用接近额度时发 info 预警超过软限额时发 critical 告警。九、权益的完整字段与订阅级覆盖除上述核心字段外ent/schema/entitlement.go 还提供以下能力完整对应 PRD 中“把 Feature 落到计划/订阅”的诉求entity_type / entity_id权益挂载主体。默认ENTITLEMENT_ENTITY_TYPE_PLAN计划级也可为SUBSCRIPTION订阅级实现“计划默认权益 订阅个性化覆盖”。parent_entitlement_id / start_date / end_date订阅级权益的父权益引用与时间窗口支持限时权益见 ent/schema/entitlement.go 的注释与idx_entitlement_subscription_time部分索引。display_orderUI 展示排序。aggregation_mode默认additive多个 Grant 配额如何叠加。grant_measureGrant 计量的口径取值quantity原始数量或amount金额定义于 internal/types/entitlement_grant.go。权益的查重也已在数据层兜底ent/schema/entitlement.go 对(tenant_id, environment_id, entity_type, entity_id, feature_id)建了唯一索引排除parallel聚合模式与未发布记录防止同一计划对同一 Feature 重复授权。十、落地建议Feature 配置页的检查清单PRD 末尾列出的“明天要做的三件事”可直接转化为 Feature 管理 UI 的功能验收清单更新页面文案Copies让 Feature 的创建、编辑、删除交互语义清晰。创建 Feature 标签页Feature Tab按类型提供差异化表单Boolean名称、lookup_key、是否启用is_enabledMetered关联 Metermeter_id 过滤器Filter选项、usage_limit、usage_reset_period、is_soft_limit、告警设置Config名称 自由 JSONconfig_value / metadata。计划对比展示以「Basic vs Pro」矩阵形式见上文表格呈现各 Feature 的布尔开关、计量配额与配置差异。若需通过 API 操作可对照 internal/domain/feature/model.go 与 internal/domain/entitlement/model.go 中的 JSON 字段定义构造请求体其中FeatureType、EntitlementUsageResetPeriod等枚举的合法值均已在 internal/types/feature.go 与 internal/types/entitlement.go 中做了 Validate 校验入参不合法会直接报错可放心按本文的取值组合进行配置。赞分享【免费下载链接】flexpriceUsage-based pricing and billing for developers Cloud or self-hosted ⚙️ No-code UI Realtime usage metering Credits top-ups Control feature access项目地址https://gitcode.com/gh_mirrors/fl/flexprice点击查看免费下载相关推荐FlexPrice 权益授权按比例分摊Entitlement Grant Proration设计解析Addon 附加与解绑的 ERD 与控制流FlexPrice 权益授权按比例分摊Entitlement Grant Proration设计解析Addon 附加与解绑的 ERD 与控制流 导读 本文Flexprice 简化版 Entitlements权益系统设计从订阅计划到按量额度动态计算Flexprice 简化版 Entitlements权益系统设计从订阅计划到按量额度动态计算 本技术指南围绕 Flexprice 开源仓库中的 entit如何快速掌握Qwerty Learner提升英语肌肉记忆的完整指南如何快速掌握Qwerty Learner提升英语肌肉记忆的完整指南 Qwerty Learner是一款专为键盘工作者设计的单词记忆与英语肌肉记忆锻炼软件通过前端教育创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考