关联issue
评审背景
-
当前资源树协作接口关键字使用范围不明确，导致社区开发者以及interface-sig组在评审和维护资源树协作接口时缺少评审和看护标准。
-
当前现状与差距/问题分析：
- 组件模型对属性的约束范围与资源树协作接口属性的约束范围不一致：可能导致开发者基于资源树协作接口开发的属性设置功能失效，例如minLength、maxLength， 接口定义[10, 20]，实现范围[10, 15]。
- 组件模型约定的组件内部实现暴露到资源树协作接口：可能影响开发者基于资源树协作接口的组件二次开发，例如usage、refInterface
评审点
资源树协作接口关键字使用原则
- 资源树接口作为接口规范，开发者基于接口规范的开发行为必须受到保护和满足，在此前提下，组件模型定义不得影响和干扰资源树接口规范的实施
- 私有属性由组件自行管理，不在此原则约束范围
资源树协作接口关键字使用范围
资源协作接口属性关键字
{
"bmc.demo.IDemo": {
"properties": {
"Property1": {
"baseType": "U8",
"default": 0,
"maximum": 127,
"minimum": 1,
"description": "abc"
}
}
}
}
| 属性关键字 | 属性关键字说明 | 决策点及推荐方案 |
|---|---|---|
| baseType | 表示属性的基本类型 | ■仅资源树接口可定义 □仅组件模型可定义 |
| items | 表示结构体数组类型的元素定义，通过$ref指向元素定义 | ■仅资源树接口可定义 □仅组件模型可定义 |
| decription | 表示属性的描述信息 | ■仅资源树接口可定义 □仅组件模型可定义 |
| default | 表示属性的默认值 | □仅资源树接口可定义 □仅组件模型可定义 □资源树接口未定义时允许组件模型定义■允许组件模型定义覆盖资源树接口定义 |
| minimum maximum |
表示数值类型属性的取值范围 | ■仅资源树接口可定义 □仅组件模型可定义 |
| maxLength minLength |
表示字符串类型属性的长度范围 | ■仅资源树接口可定义 □仅组件模型可定义 |
| pattern | 表示字符串类型属性的格式要求，正则式匹配 | ■仅资源树接口可定义 □仅组件模型可定义 |
| enum | 表示属性的枚举值范围 | ■仅资源树接口可定义 □仅组件模型可定义 |
| readOnly | 表示属性是否只读 | ■仅资源树接口可定义 □仅组件模型可定义 |
| deprecated | 表示属性废弃 | ■仅资源树接口可定义 □仅组件模型可定义 |
| privilege | 表示资源树接口属性的访问权限，分为读权限和写权限 | □仅资源树接口可定义 ■仅组件模型可定义 |
| constrait | 表示属性使用约束，包括属性互斥、依赖关系、唯一性要求、兼容性要求等 | ■仅资源树接口可定义 □仅组件模型可定义 |
| example | 表示属性样例，用于描述属性格式等信息 | ■仅资源树接口可定义 □仅组件模型可定义 |
| options/volatile | 表示属性是否易变，如果取值为true，则表示该属性的值不稳定，组件可以选择不监听该属性的变化信号，默认为false； | □仅资源树接口可定义 ■仅组件模型可定义 |
| options/explicit | 表示属性值在属性名明确指定时才可见，如果取值为true，则表示属性在introspect（list操作，不指定属性名）时不显示，只能在单独Get（需要明确属性名）时才显示，默认为false； | □仅资源树接口可定义 ■仅组件模型可定义 |
| options/emitsChangedSignal | 表示是否发送属性变化信号，默认为"true" i） 如果取值为false，表示属性变化时不发送信号； ii）如果取值为const，表示属性永不变化，不需要发送信号； iii) 如果取值为true，表示属性变化时发送信号，信号携带属性值； iv) 如果取值为invalidates，表示属性变化时发送信号，但信号不携带属性值； |
■仅资源树接口可定义 □仅组件模型可定义 |
| primaryKey | 表示该属性在数据库中是否是主键 | □仅资源树接口可定义 ■仅组件模型可定义 |
| uniqueKey | 表示该属性是否是唯一键 | □仅资源树接口可定义 ■仅组件模型可定义 |
| sensitive | 表示属性是否是敏感数据 | □仅资源树接口可定义 ■仅组件模型可定义 |
| critical | 表示属性是否是关键数据 | □仅资源树接口可定义 ■仅组件模型可定义 |
| notAllowNull | 表示属性在数据库中是否可以为空 | □仅资源树接口可定义 ■仅组件模型可定义 |
| usage | 表示属性的用途 | □仅资源树接口可定义 ■仅组件模型可定义 |
| alias | 表示属性的别名，用于CSR配置、持久化等场景解决资源接口属性与其他资源树属性或私有属性同名冲突的问题 | □仅资源树接口可定义 ■仅组件模型可定义 |
| refInterface | 表示属性属性通过该接口下的方法获取或设置对象数据 | □仅资源树接口可定义 ■仅组件模型可定义 |
资源协作接口方法关键字
{
"bmc.demo.IDemo": {
"methods": {
"Method1": {
"req": {
"ReqArg1": {
"baseType": "U8"
}
},
"rsp": {
"RspArg1": {
"baseType": "U16"
}
}
}
}
}
}
| 方法关键字 | 方法关键字说明 | 决策点及推荐方案 |
|---|---|---|
| decription | 表示方法或参数的描述信息 | ■仅资源树接口可定义 □仅组件模型可定义 |
| displayDescription | 表示方法或参数显示描述信息，主要用于组件自定义命令描述，包括方法描述和参数描述 | □仅资源树接口可定义 ■仅组件模型可定义 |
| featureTag | 表示表示资源树公共方法和私有方法对应的特性标签 | □仅资源树接口可定义 ■仅组件模型可定义 |
| baseType | 表示参数的基本类型 | ■仅资源树接口可定义 □仅组件模型可定义 |
| items | 表示结构体数组类型的元素定义，通过$ref指向元素定义 | ■仅资源树接口可定义 □仅组件模型可定义 |
| default | 表示参数的默认值，组件自定义命令 | □仅资源树接口可定义 ■仅组件模型可定义 |
| minimum maximum |
表示数值类型参数的取值范围 | ■仅资源树接口可定义 □仅组件模型可定义 |
| maxLength minLength |
表示字符串类型参数的长度范围 | ■仅资源树接口可定义 □仅组件模型可定义 |
| pattern | 表示字符串类型参数的格式要求，正则式匹配 | ■仅资源树接口可定义 □仅组件模型可定义 |
| enum | 表示参数的枚举值范围 | ■仅资源树接口可定义 □仅组件模型可定义 |
| privilege | 表示资源树接口属性的访问权限，分为读权限和写权限 | □仅资源树接口可定义 ■仅组件模型可定义 |
资源协作接口信号关键字
{
"bmc.demo.IDemo": {
"signals": {
"demoSignal": {
"Property1": {
"baseType": "U32",
"minimum":1,
"maximum":100
}
}
}
}
| 信号关键字 | 信号关键字说明 | 决策点及推荐方案 |
|---|---|---|
| decription | 表示信号或参数的描述信息 | ■仅资源树接口可定义 □仅组件模型可定义 |
| baseType | 表示参数的基本类型 | ■仅资源树接口可定义 □仅组件模型可定义 |
| items | 表示结构体数组类型的元素定义，通过$ref指向元素定义 | ■仅资源树接口可定义 □仅组件模型可定义 |
| default | 表示参数的默认值 | □仅资源树接口可定义 ■仅组件模型可定义 |
| minimum maximum |
表示数值类型参数的取值范围 | ■仅资源树接口可定义 □仅组件模型可定义 |
| maxLength minLength |
表示字符串类型参数的长度范围 | ■仅资源树接口可定义 □仅组件模型可定义 |
| pattern | 表示字符串类型参数的格式要求，正则式匹配 | ■仅资源树接口可定义 □仅组件模型可定义 |
| enum | 表示参数的枚举值范围 | ■仅资源树接口可定义 □仅组件模型可定义 |
评审结论
总体结论
- 同意资源树协作接口关键字使用原则
- 同意资源树协作接口关键字使用范围
问题跟踪
- 基于评审结论，整改资源树接口和组件模型定义，并明确落地计划
- 结论：分解需求到社区项目，通过社区项目运作落地，计划630完成。