能力集合建模指南_能力对象与KeyValue查询模式对比当系统需要表达“设备/平台支持什么”时常见有两种建模方式能力对象Capability Object与Key-Value 查询Capability Key。本文从抽象模型、适用场景、演进路径与混合架构出发给出可落地的选型建议。目录问题背景能力语义分层术语表两种主流模型核心差异对照为什么会出现两种模型混合模式才是常态选型决策树演进策略先 Key 后对象Schema 版本治理与兼容规则通用接口草图常见反模式附录Android / iOS / Web 能力模型映射表免责声明延伸阅读问题背景在 Android、iOS、Web 与服务端系统里“能力集合”通常用于回答三类问题当前设备/环境支持哪些功能在特定参数组合下是否可配置新增能力后如何保持兼容与可演进典型实践会落入两条路线能力对象模型一次性返回结构化能力描述对象Key-Value 查询模型通过 key 逐项查询是否支持能力语义分层术语表为避免“支持但不可用”的误判建议在设计评审中统一以下术语术语含义常见来源典型误区Declared Capability平台/设备声明具备的能力HAL、Framework、浏览器接口存在性把“声明支持”当“当前可用”Runtime Availability当前运行时是否可用会话状态、资源占用、系统温控、前后台态忽略动态变化导致线上偶发失败Config Feasibility指定参数组合是否可行编码器约束、分辨率×帧率×格式组合仅看单个能力字段做决策Policy Allowed权限/策略层是否允许权限、企业策略、浏览器安全上下文通过能力探测但实际被策略拒绝推荐判定顺序Declared→Policy→Runtime→Feasibility。对外 API 可同时返回四层状态避免业务层自行拼凑。两种主流模型1) 能力对象模型Capability Object Model代表思路返回一个只读能力对象包含静态规格、范围与约束。CameraCharacteristics ├─ supportedHardwareLevel ├─ availableFpsRanges ├─ availableFormats └─ ...特点能力表达结构化、层次化适合“初始化阶段一次决策”对“组合约束”表达更自然如分辨率 × 帧率 × 编码2) Key-Value 查询模型Capability Key Model代表思路把能力离散化为 key调用方按需查询。FEATURE_CAMERA FEATURE_NFC FEATURE_BLUETOOTH_LE特点扁平、轻量、便于扩展新增能力通常只需新增 key调用方只关心“有/无”时成本最低核心差异对照维度能力对象模型Key-Value 查询模型表达能力结构化、可表达层级与范围离散化、布尔或简单值获取方式一次获取后续只读按需多次查询组合约束强适合复杂约束弱需额外规则层扩展性改结构可能牵动面大新增 key 通常较平滑兼容策略需谨慎处理字段演进天然向前兼容较好典型场景硬件规格、驱动能力、编解码参数功能开关、插件特性、平台特征为什么会出现两种模型能力对象模型常见动因能力彼此关联不能割裂判断初始化时要做一次完整配置决策业务需要“能力空间全貌”而非单点特性Key-Value 模型常见动因能力彼此独立可离散判断平台长期演进新增能力频繁调用方只需isSupported(key)级别答案混合模式才是常态现实系统常是“对象 key”并存外层对象承载能力上下文与生命周期内层 key承载演进与细粒度扩展渲染错误:Mermaid 渲染失败: Parse error on line 5: ... D -- E[isSupported(key)] -----------------------^ Expecting SQE, DOUBLECIRCLEEND, PE, -), STADIUMEND, SUBROUTINEEND, PIPE, CYLINDEREND, DIAMOND_STOP, TAGEND, TRAPEND, INVTRAPEND, UNICODE_TEXT, TEXT, TAGSTART, got PS这种结构兼顾了复杂约束表达向前兼容与增量扩展API 面稳定性选型决策树是否是否是否能力之间是否存在明显组合约束优先能力对象模型调用方是否只关心有/无优先 Key-Value 查询模型是否预计能力高速演进Key 为主 对象封装混合对象模型可直接承载一句话经验像“规格表”就用对象像“功能开关列表”就用 key两者都需要时用混合模型演进策略先 Key 后对象很多系统的可控路径是早期能力少先用 Key-Value 低成本起步中期能力增多出现范围/组合约束后期引入能力对象做快照并保留 key 体系阶段推荐模型目标初期Key-Value快速落地、低耦合成长期Key 规则层承载组合限制稳定期对象快照 Key 扩展兼顾表达力与演进Schema 版本治理与兼容规则能力协议长期运行时建议把版本治理写成“硬规则”变更类型兼容级别推荐策略新增可选字段/新 key向前兼容允许旧客户端忽略默认值语义必须明确字段语义变更破坏性高禁止原地改语义新增字段并标记旧字段 deprecated字段删除破坏性高至少经历 2 个版本窗口标记弃用 → 删除类型变更int→string破坏性高新字段承载新类型旧字段保留兼容读取发布建议双读期新旧字段并存服务端/SDK 同时支持。双写期若有回传链路写新字段同时回填旧字段。观测闸门按版本统计字段命中率达到阈值再下线旧字段。失败回退schemaVersion不可识别时降级到最小能力集而非直接崩溃。通用接口草图// 能力 key 查询演进友好interfaceCapabilityQuery{isSupported(key:string):boolean;getInt?(key:string):number|undefined;getRange?(key:string):[number,number]|undefined;}// 能力对象快照配置决策友好interfaceCapabilitySnapshot{version:string;constraints:Recordstring,unknown;features:Recordstring,unknown;}落地建议对外 API 保持稳定查询接口与对象字段分层对内统一能力注册表避免多处重复定义 key对“组合可行性”提供显式校验函数避免业务层拼凑判断常见反模式反模式风险修正方式全部能力都塞进一个超大对象字段膨胀、兼容困难按域拆分对象保留 key 扩展全部能力都做布尔 key无法表达范围与约束引入范围型/结构化字段业务层自行拼能力规则规则散落、结果不一致下沉到统一可行性判定层无版本语义线上升级行为不可预测增加 capability schema/version附录Android / iOS / Web 能力模型映射表平台典型 API偏对象模型偏 Key/查询模型建模建议AndroidCamera2 / PackageManagerCameraCharacteristics含范围、枚举、组合约束PackageManager.hasSystemFeature(...)、feature string/version 查询硬件链路用对象快照系统特性与可选模块用 feature keyiOSAVFoundation / 运行时能力判断AVCaptureDevice、formats/ranges 等结构化能力通过 selector、availability、is*Supported类方法做离散判断媒体能力用对象格式集系统版本差异通过 availability/feature flag 补充WebNavigator / Media / PermissionsMediaCapabilities、MediaTrackCapabilities等对象化结果serviceWorker in navigator、CSS.supports(...)、权限/接口探测浏览器差异大优先 feature detection需要参数可行性时再引入对象能力探测跨端 SDK自研抽象层CapabilitySnapshot一次拉取带版本isSupported(key)轻量判定对外暴露双层 API对象用于配置决策key 用于快速守卫映射后的统一实践初始化阶段拉取一次对象快照并缓存可带版本/时间戳。业务分支阶段用isSupported(key)做快速路径守卫。复杂组合阶段走validate(config, snapshot)做可行性校验。跨端一致性维护一份平台无关 key 字典与字段映射表避免业务层直接耦合平台原生命名。免责声明不同平台 API 的命名、生命周期和线程模型差异较大本文给出的是建模方法论而非单平台手册。能力数据若来自底层固件/驱动实际可用性仍需运行时校验与错误回退。延伸阅读Android Developers: Camera2 API (CameraCharacteristics)Android Developers: PackageManager featuresApple Developer Documentation: AVFoundationMDN Web Docs: Feature detection