背景
本文档旨在为Redfish接口设计提供全面的合规性审计指导，结合DMTF Redfish规范（DSP0266）和业界实践，涵盖协议基础、数据模型、安全性、扩展机制等关键维度，并针对常见设计缺陷提供解决方案。
合规审计条目
《标准化属性定义原则》
所有资源必须 100% 遵循 DMTF 发布的 Redfish Schema 定义，禁止任何形式的标准属性篡改；厂商扩展必须严格限定于 Oem/{{OemIdentifier}} 对象内，且需显示声明 @odata.type 标识 Schema 版本（例如：若 AccountService 资源实现了 1.3.0 版本引入的 ActiveDirectory 属性，则其 @odata.type 属性必须更新为对应的版本）。
《易变属性识别与Etag管理原则》
设计Redfish接口时，必须前置识别易变属性（如传感器读数、实时状态），并在接口映射的IgnoreEtags配置中显式声明这些属性，避免因高频数据变更引发事件风暴。
《Redfish资源连通性与可发现性原则》
所有资源必须构成以Service Root为起点的连通资源树，通过@odata.id绝对路径识别自身位置，确保客户端能通过标准方式遍历整个资源树，禁止出现不可达资源。资源关联必须严格遵循：
| 关联类型 | 适用场景 | 实现方式 |
|---|---|---|
| 嵌套资源 | 直接父子关系 | 父资源嵌套子资源@odata.id |
| 集合成员 | 资源集合中的成员 | Members数组引用 |
| Links关联 | 跨层级/跨集合引用 | Links对象引用 |
规范依据： Redfish DSP0266 6.1
《OEM自定义查询参数命名规范》
所有OEM自定义查询参数必须采用 OEM-<厂商唯一标识>-<参数名> 格式，参数名不得与标准Redfish查询参数（如：$select/$expand）同名，禁止包含 &、?、= 等解析冲突字符。
规范依据： Redfish DSP0266 7.3.1
《集合资源纯净性原则》
集合资源的核心职责是提供成员资源的导航服务，禁止响应体扩展 OEM 属性。
规范依据： Redfish DSP0266 9.3
《属性 OEM 扩展三通道隔离原则》
属性 OEM 扩展必须且仅能通过 OEM、 Links、 Actions 三个独立通道实现，三者均允许直接作用于任意标准资源（即使该资源未预定义 Links 或 Actions 字段）和自定义资源。严禁在 Oem 对象内部嵌套扩展 Links 或 Actions 字段，所有扩展必须严格遵循通道隔离。规则解析表：
| 扩展通道 | 扩展场景 |
|---|---|
| Oem | 数据属性扩展（添加厂商自定义状态/配置） |
| Links | 资源关联扩展（添加导航链接/外部引用） |
| Actions | 操作行为扩展（添加厂商专属操作命令） |
规范依据： Redfish DSP0266 9.4
《Redfish枚举设计原则》
Redfish枚举设计约束：
- 类型强制：必须使用字符串类型（
string），禁止使用数字或布尔值替代枚举。 - 状态数量策略：
二元状态 → 优先采用布尔类型（boolean）
三元及以上 → 必须使用枚举类型（enum） - 值域纯净性：不建议定义
"unknown"（未知）、"other"（其他）等通用占位值，此类值会显著降低系统互操作性。
规范依据： Redfish DSP0266 9.5.2、Redfish DSP0266 9.7.1
《字符串属性未初始化值空字符串返回原则》
当Redfish接口的字符串属性由用户/外部服务配置且未设置初始值时，必须返回空字符串 "" 以标识属性受支持但未初始化；仅当服务端发生读取错误等异常时，才允许返回null表示错误状态。禁止使用N/A、 <Empty>等非标准占位符。
| 场景 | 返回值 | 语义 |
|---|---|---|
| 属性受支持且未初始化 | "" |
有效空值，等待用户配置 |
| 属性因故障无法读取 | null |
服务端错误状态 |
| 属性不受支持/未实现/集合资源部分实例不支持 | 不返回该属性 | 客户端应忽略 |
规范依据： Redfish DSP0266 9.5.3
《Redfish null值使用规范》
严格遵循Schema类型定义：所有属性的空值处理必须完全依据其在Redfish Schema中的类型定义，区分包含null类型与不包含null类型两种情况。
- Schema定义包含null类型的属性
| 场景 | 处理方式 | 示例 |
|---|---|---|
| 系统异常 | 返回null表示取值失败 |
“Temperature”: null（传感器读取失败） |
| 数据未就绪 | 返回null表示临时状态 字符串例外：返回空串"" |
“PowerWatts”: null（功率数据获取中） “HostName”: “”（主机名未配置） |
| 特殊语义 | 按Schema定义，null可具有业务含义 |
“PowerLimit”: null表示无功率限制 |
| PATCH操作 | 允许使用null进行"重置"或"清除" |
PATCH {“Description”: null} |
- Schema定义不包含null类型的属性
| 场景 | 处理方式 | 示例 |
|---|---|---|
| 系统异常 | 不返回该属性 | 省略异常属性而非返回null |
| 数据未就绪 | 不返回该属性 | 临时不可用属性从响应中移除 |
| PATCH操作 | 禁止设置为null |
返回400 Bad Request错误 |
备注：在Web接口层面，系统异常和数据未就绪等临时状态均返回null
规范依据： Redfish DSP0266 9.5.1 、Redfish DSP0266 9.6.1
《量纲属性单位后缀强制标注原则》
当属性值包含物理量单位或特殊语义时，必须在属性名称后缀明确标注单位标识符，禁止无量纲属性（如 状态码、比率值）和枚举型属性（如HealthStaus）添加单位后缀。常见单位属性示例：
| 单位名称 | 标准后缀 | 示例属性 |
|---|---|---|
| 瓦特 | 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 |
规范依据： Redfish DSP0266 9.7.1
《复杂对象拆分子资源原则》
属性避免嵌套超过 5 层（Oem/{{OemIdentifier}} 不纳入层级计算）的JSON结构，复杂对象应拆分为子资源。
违规反例
# 早期redfish资源设计（深层嵌套JSON）
GET /redfish/v1/Chassis/1/Thermal
{
"Id": "Thermal",
"Fans": [
{
"MemberId": "Fan1",
"Reading": 12000,
"Status": {
"Health": "OK",
"State": "Enabled"
}
}
]
}
合规设计
# 1. 拆分为子系统资源（减少主资源层级）
GET /redfish/v1/Chassis/1/ThermalSubsystem
{
"Id": "ThermalSubsystem",
"Fans": {
"@odata.id": "/redfish/v1/Chassis/1/ThermalSubsystem/Fans"
}
}
# 2. 复杂对象独立为子资源集合（扁平化）
GET /redfish/v1/Chassis/1/ThermalSubsystem/Fans
{
"Members": [
{
"@odata.id": "/redfish/v1/Chassis/1/ThermalSubsystem/Fans/1"
}
]
}
# 3. 属性展开为独立资源（深度控制）
GET /redfish/v1/Chassis/1/ThermalSubsystem/Fans/1
{
"FanDiameterMm": 80,
"SpeedPercent": {
"SpeedRPM": 6660
}
}
规范依据： Redfish DSP0266 9.8.2
《响应敏感数据置空原则》
任何通过 GET 操作返回的响应中，敏感数据属性（如密码、密钥、令牌）必须显式设置为 null；POST/PATCH 请求中允许传输明文值，且服务端日志必须脱敏处理。此规则对标准资源和 Oem 扩展均强制生效。
规范依据： Redfish DSP0266 13.2