# API 设计原则

## 合理抽象

API 应当比后端简单，但不能剥夺自用场景真正需要的控制力。

- 用户主动做出的资源决策进入产品 API。
- 平台稳定的运维策略进入 Profile、Class 或 Policy。
- 能够稳定推导的机械参数由 adapter 生成。
- 罕见但合理的特殊需求使用受控 override。
- 解析结果、外部 ID 和后端摘要通过只读 status 展示。

例如 VM 用户可以指定 CPU、内存、磁盘、存储、镜像和逻辑网络；QEMU machine type、
cloud-init 设备、bridge/VLAN 映射和默认 placement 由平台维护。

## 不做虚假可移植性

允许 API 表达当前真实后端的有用能力，但不接受任意 `rawConfig` 透传。未来出现第二个
真实实现时，根据已经观察到的共同语义抽象，而不是预先猜测最低公分母。

## 引用与依赖

- 使用 typed reference 表达资源依赖，不复制动态地址和外部 ID。
- 被引用资源暂时不存在或未 Ready 时，controller 应等待而不是要求 apply 顺序。
- 长期依赖通过 API 关系推导；Flux `dependsOn` 只用于确实需要的提交顺序。

## 生命周期基线

所有受管资源必须定义：

- `observedGeneration`
- 结构化 `status.conditions`
- ownership 与外部资源标识
- finalizer 与删除策略
- import/adopt/observe 行为
- controller 重启后的恢复行为
- 可重试错误与需要人工介入错误的区别

对数据库、bucket、持久磁盘等资源，默认删除行为必须保守并显式表达。