📚 课程目录第4章资源模型设计原则

4. 资源模型设计原则：单一职责原则、不可变基础设施原则、声明式与命令式资源对比

在 IDP 自助门户的资源模型设计中，遵循经过验证的架构原则是保障平台可扩展性、可维护性与安全性的基石。本章聚焦于三项核心原则：单一职责原则、不可变基础设施原则，以及声明式与命令式资源的对比与选择。

在资源模型上下文中，单一职责原则要求每个资源类型只负责一个明确的业务概念或基础设施组件。一个资源不应同时描述应用、数据库、网络策略和监控告警。

  核心观点： 资源模型中的“职责”是指该资源在平台中管理的唯一原子单元。例如，Deployment 只负责应用实例的声明与生命周期，Service 只负责网络访问的抽象。

遵循 SRP 的收益：

实践建议： 在设计资源模型时，如果发现一个资源描述中包含“且”、“或”、“同时”等连接词，通常意味着职责已经过载，需要拆分为更细粒度的资源。

不可变基础设施原则强调：一旦资源被创建并投入使用，就不应再对其进行原地修改。任何变更都应通过创建新版本或新实例来替代旧实例，而非对现有实例进行修补。

在 IDP 资源模型中的体现：

传统可变方式	不可变方式	资源模型影响
SSH 登录服务器，手动修改配置文件	提交新的资源 YAML，触发滚动更新或蓝绿部署	资源版本化，`spec` 字段不可变，只允许通过 `apiVersion` 升级
原地升级数据库补丁	创建新的数据库实例，切换流量后销毁旧实例	资源 `name` 或 `uid` 变更，依赖资源需重新绑定
修改负载均衡规则	更新资源定义，控制器自动重建配置	资源 `spec` 的变更触发 `reconcile` 循环，而非原地编辑

关键约束： 不可变原则要求资源模型在设计时，必须将 spec 视为只读输入。任何对 spec 的修改都应被视为创建新资源对象的请求，而非对现有对象的属性更新。这直接影响了资源控制器的实现逻辑。

下图展示了不可变基础设施在资源模型中的核心流程：

资源模型的设计哲学决定了开发者与平台交互的方式。声明式与命令式是两种根本不同的范式。

声明式（Declarative）： 用户描述期望状态，平台负责将实际状态收敛至期望状态。用户不关心具体执行步骤。

命令式（Imperative）： 用户发出具体指令，平台按指令执行操作。用户需要了解执行步骤和顺序。

对比维度	声明式资源	命令式资源
用户输入	YAML/JSON 描述期望状态（`spec`）	CLI 命令或 API 调用（`create`, `update`, `delete`）
幂等性	天然幂等，多次提交同一 `spec` 结果一致	非幂等，重复执行可能导致错误或状态不一致
错误恢复	控制器自动重试，持续调和至期望状态	需要用户手动处理失败步骤或回滚
适用场景	长期运行的服务、基础设施配置、策略定义	一次性任务、调试操作、紧急修复
IDP 推荐度	⭐⭐⭐⭐⭐（首选）	⭐⭐（仅限运维调试）

  IDP 设计决策： 自助门户的资源模型应全面采用声明式 API。开发者只需在门户表单中填写期望的配置（如副本数、存储大小、环境变量），平台后端自动生成对应的声明式资源对象并提交给底层编排引擎。这降低了开发者的认知负担，同时保证了平台的可审计性和自愈能力。

下图对比了两种范式在资源生命周期中的交互差异：

三项原则并非孤立存在，而是相互协同，共同构建健壮的资源模型基础：

设计检查清单： 在定义新的资源类型前，请逐项确认：

如果以上任一答案为“否”，请重新审视资源模型的设计。