MDS 配置规则 ​

文档说明 ​

本文用于整理 MDS 配置中的字段约束、组合约束、引用关系和跨配置一致性要求，重点说明 配置需要满足什么条件 以及 哪些配置关系需要同时成立。本文主要面向需要进行 MDS 模型配置的开发者。

本文涉及的主要配置文件为：

• service.json：组件基本信息、构建/测试依赖、运行态依赖和代码生成策略；
• model.json：类、资源树路径、接口、属性、方法、私有属性、权限和持久化约束；
• types.json：组件自定义类型及其引用关系。

1. service.json 配置规则 ​

1.1 组件基本字段 ​

1.2 构建依赖与测试依赖 ​

dependencies 下的 test 和 build 均按对象数组进行约束。

1.3 运行态依赖 required ​

required 为对象数组，可包含 0 到多个依赖项。每个依赖项必须包含 path 和 interface，并可按需配置 properties、optional 和 stage。

运行态依赖除字段格式正确外，还必须满足以下关系：

1. path 对应资源树对象实现所依赖的 interface；
2. 被依赖的资源树路径由其它组件的 MDS 管理；
3. 组件不应依赖自己管理的资源树对象；
4. 组件之间不能形成循环依赖。

1.4 codeGenPolicy ​

codeGenPolicy 必须为对象类型，其中包含 version 字段，且 version 为大于 0 的数字。

1.5 文件格式 ​

service.json 必须是合法 JSON 文件。

2. model.json 配置规则 ​

2.1 类定义 ​

类级 privilege 的允许值为：

UserMgmt、BasicSetting、KVMMgmt、VMMMgmt、SecurityMgmt、PowerMgmt、DiagnoseMgmt、ReadOnly、ConfigureSelf。

当类管理的资源树属性或方法被接口映射引用时，需要保证相应权限已经配置：可以由所在 Path 提供权限；Path 未配置权限时，需要在具体属性或方法上配置权限。

2.2 类级持久化配置 ​

tableType 允许值：

• PermanentPer
• PoweroffPer
• ResetPer
• TemporaryPer
• PoweroffPerRetain
• ResetPerRetain
• TemporaryPerRetain
• Memory
• SHM

类配置 tableName 后，至少需要一个资源树属性或私有属性配置 primaryKey=true。

2.3 资源树接口 interfaces ​

interfaces 需要满足以下约束：

1. 只有类存在 path 时才可以配置；
2. 必须为对象类型；
3. 每个接口 key 必须是有效定义的资源树接口，且不能重复；
4. 接口必须由类的 path 对应资源树对象实现；
5. 接口对象中明确受规则约束的子项为 properties 和 methods。

显式管理的资源树接口还应存在实际引用关系，至少满足以下一种情况：

• 被某个组件的 service.json 依赖；
• 被接口映射引用；
• 接口下存在属性在 CSR 中被其它对象引用。

否则该接口配置属于需要检查的无效管理关系。

2.4 资源树属性 ​

2.4.1 属性配置 ​

资源树属性必须已在对应资源树接口中定义，并且在当前接口配置中不能重复。

规则明确列出的属性配置项包括：

• privilege
• usage
• default
• alias
• primaryKey
• uniqueKey
• notAllowNull
• deprecated

2.4.2 属性 privilege ​

属性级 privilege 为选填对象。配置后必须同时包含 read 和 write，权限值只能使用：

UserMgmt、BasicSetting、KVMMgmt、VMMMgmt、SecurityMgmt、PowerMgmt、DiagnoseMgmt、ReadOnly、ConfigureSelf。

2.4.3 属性 usage ​

usage 为选填字符串数组，数组元素允许：

• CSR
• PermanentPer
• PoweroffPer
• ResetPer
• TemporaryPer
• PoweroffPerRetain
• ResetPerRetain
• TemporaryPerRetain
• SHM

2.4.4 属性 default ​

default 为选填字段，需要同时满足：

• 默认值类型与属性定义类型一致；
• 默认值处于属性类型允许范围内；
• 属性存在校验规则时，默认值满足对应校验规则。

2.4.5 属性 alias ​

alias 需要满足：

1. 为长度不大于 64 的非空字符串；
2. 使用大驼峰格式；
3. 在当前类中唯一；
4. 不得与当前类管理的资源树属性或私有属性重名；
5. 配置 alias 的属性，至少存在一个由该类管理的其它接口具有同名属性，否则属于无效配置；
6. 不同接口存在同名属性，且该属性在 CSR 中配置或被其它属性引用时，最多允许其中一个同名属性不配置 alias。

2.5 资源树属性和私有属性共用的持久化约束 ​

2.6 资源树方法 ​

接口下的 methods 若配置：

• 必须为对象类型；
• 方法必须已在对应资源树接口中定义；
• 每个方法的 value 必须为对象；
• value 中只能配置 privilege。

方法 privilege 必须为字符串数组，允许值与类级权限相同。

2.7 私有属性 ​

2.7.1 属性名称与类型 ​

私有属性名称必须为长度不大于 64 的非空字符串，使用大驼峰格式，并在当前类的私有属性中命名唯一。

baseType 为必填字段。基础类型允许：

U8、U16、U32、U64、S8、S16、S32、S64、Boolean、Double、String。

同时允许引用本组件或资源树接口中的 Dictionary、Struct、Enum 自定义类型。

数组类型满足以下形式：

• 基础类型数组：在类型后增加 []，例如 U8[]；
• 自定义类型数组：baseType 使用 Array，通过 items 引用自定义类型。

2.7.2 数值范围校验 ​

minimum、maximum 仅数字类型可以配置。配置值必须位于对应数据类型的有效范围内；同时存在时满足：

minimum <= maximum

2.7.3 字符串校验 ​

minLength、maxLength 仅字符串类型可以配置，同时存在时满足：

minLength <= maxLength

pattern 仅字符串类型可以配置，取值必须为非空字符串。

2.7.4 enum ​

enum 仅字符串、数字、浮点数类型可以配置；必须为数组；数组元素类型需要与属性类型一致，并满足对应类型的取值范围。

2.7.5 校验规则组合 ​

私有属性校验规则分为：

• 范围校验：minimum / maximum；
• 长度校验：minLength / maxLength；
• 正则校验：pattern；
• 枚举校验：enum。

只有长度校验与正则校验允许同时存在，其它不同类别的校验规则不能同时配置。

2.7.6 default、description 与 refInterface ​

私有属性 default 需要与属性类型一致、位于对应类型允许范围内，并在存在校验规则时满足对应校验。

description 为必填字段，必须是长度不超过 1024 的非空字符串。

refInterface 为选填字段。配置后需要同时满足：

1. 取值为有效定义的资源树接口；
2. 该接口已经在当前组件 service.json 中声明依赖。

2.8 文件格式 ​

model.json 必须是合法 JSON 文件。

3. types.json 与自定义类型规则 ​

3.1 基本约束 ​

MDS 自定义类型需要满足以下要求：

• 定义的自定义类型原则上应被当前 APP 的私有属性引用；
• 自定义类型之间不能形成循环依赖，包括结构体与结构体、结构体与字典、字典与字典之间的循环依赖；
• types.json 必须为合法 JSON 文件。

3.2 自定义类型结构 ​

4. 跨配置一致性检查 ​

MDS 配置除单字段合法性外，还需要保证不同文件、对象和字段之间的关系一致。