【规范】资源协作接口设计合规性必检指南

Interface SIG
1

背景

本文档为社区开发者提供资源协作接口的标准化设计规范，确保接口的可维护性、安全性与协作效率。

合规审计条目

  • 属性采用大驼峰命名，其中基本属性采用名词或形容词+名词（如DiskSize、ActiveStatus），布尔属性采用Is/Has+形容词或名词（如 IsActive、HasPermission），特殊属性要求：
属性类型 命名规则 示例
状态属性 名词+ Status CommunicationStatus
标识符 Id 后缀 ResourceId
集合类属性 复数名词 ConnectedDevices
使能状态 必须使用Enabled，禁止使用Enable ServiceEnabled
  • 属性命名禁止使用Info等模糊词汇，必须采用领域精准术语替代，常见替代方案：
场景 推荐命名 反例
基础信息 UserDetails UserInfo
配置参数 Configuration ConfigInfo
元数据 FileMetadata FileInfo
度量数据 ThermalMetrics ThermalInfo
状态扩展 RuntimeStatus/RuntimeContext RuntimeInfo
  • 当属性值包含物理量单位或特殊语义时，必须在属性名称后缀明确标注单位标识符，禁止无量纲属性（如状态码、比率值）和枚举型属性（如HealthStatus）添加单位后缀。常见单位属性示例：
单位名称 标准后缀 示例属性
瓦特 Watts PowerWatts
伏特 Volts ReadingVolts
电量 kWh EnergykWh
摄氏度 Celsius TemperatureCelsius
每分转速 RPM RotationSpeedRPM
带宽 Mbps、Gbps PortSpeedMbps、LinkSpeedGbps
CPU速度 MHz ProcessorSpeedMHz
毫秒 Milliseconds SensorPollingIntervalMilliseconds
秒 Seconds KeepaliveIntervalSeconds
分钟 Minutes HeartbeatIntervalMinutes
小时 Hours PowerOnHours
天 Days PasswordExpirationDays
周 Weeks BackupIntervalWeeks
月 Months BillingCycleMonths
年 Years WarrantyYears
位 bit TransferInhibit
字节 Bytes MemoryBytes
Kibibyte KiB FreeStorageSpaceKiB
Mebibyte MiB MemorySizeMiB
Gibibyte GiB TotalSystemMemoryGiB
Tebibyte TiB TotalCapacityTiB
百分比 Percent PowerLoadPercent
计数 Count ProcessorCount
资源状态 State PowerState
  • 当属性存在预定义枚举值时，应优先使用字符串枚举（历史兼容与性能敏感场景除外），并在enum字段中显式声明取值范围（持久化场景例外）。枚举值类型必须与属性类型严格匹配，且禁止删除已发布的枚举值。
  • 属性的emitsChangedSignal字段定义规范：
取值 含义 适用场景
"true" 属性值变化时自动发送PropertiesChanged信号 非常量且不频繁变化的属性。此外，还包括少数频繁变化的关键属性（例如：用于实时告警的温度传感器读数），频繁变化定义：变化间隔低于3秒。
"false" 不自动发送属性变更信号，需开发者手动触发 1. 需要精确控制信号时序，避免无效通知干扰总线 2. 非关键的频繁变化属性（关键属性举例：用于实时告警的温度传感器读数），频繁变化定义：变化间隔低于3秒
"const" 属性为常量，值永不改变，无需发送变更信号 常量属性（如设备固件版本号、固定序列号），在首次赋值后即不可修改。谨慎使用（优先用false取代），主要原因在于：若首次赋值失败，后续将无法通过重试机制完成正常赋值。
"invalidates" 属性变化时仅发送信号但不携带新值 接收方收到信号即可，不关注具体变更内容，比如只记录时间戳，完全不读数据
  • 属性的description字段为必填，描述属性在业务或系统中的核心作用，禁止使用"相关"、"等"等模糊术语。
  • 属性的example字段为可选描述性字段，用于说明属性值的合法格式或典型取值，基础类型（string/number/boolean）无特殊格式要求时无须添加example，枚举型属性必须通过enum字段定义取值范围，禁止使用example替代，符合要求的格式样例：
数据类型 示例
十六进制数值 "0x1A3F"
日期时间 "2025-07-18T14:30:00Z"
正则约束 "/^[A-Z]{3}-\\d{4}$/"
  • 属性的constraint为可选字段，用于声明以下核心约束关系：
    1. 互斥关系： 多个属性不可同时存在或赋值（如PowerState与StandbyMode）
    2. 依赖关系： 属性存在性或取值依赖其他属性（如GPUEnabled依赖PCIE3.0Support）
    3. 唯一性要求：属性值需全局唯一标识实体（如SerialNumber）
    4. 兼容性要求： 需满足外部系统/协议/硬件的交互规则（如FileFormat需兼容FAT32/NTFS）
  • 所有方法的错误返回优先通过错误引擎统一处理，禁止在方法响应体中自定义error_id或其他冗余错误标识字段。（例外情况额外审视）
  • 在资源协作接口中，涉及创建资源的方法时，其响应消息体必须包含唯一标识字段（如Id），且该标识在资源的整个生命周期内禁止修改。
  • 新增类型资源时，应直接继承标准接口定义（如板卡类资源必须复用bmc.kepler.Systems.Board接口），禁止重复定义语义相同的接口。
3

赞。。