40 lines
1.5 KiB
Markdown
40 lines
1.5 KiB
Markdown
# 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、持久磁盘等资源，默认删除行为必须保守并显式表达。
|