多资源关联REST API设计咨询：跨域虚拟机作业执行场景

最优方案选择 #

调整优化后的方案2最适配当前需求，同时预留方案4的调度器资源应对后续扩展即可。 #

各方案优劣分析 #

• 方案1：PUT /domains/{dname} 完全不符合REST设计规范，/domains/{dname}对应的资源是单个域，将虚拟机操作、作业执行逻辑耦合到域资源的更新接口中，职责混乱，后续维护成本极高，直接排除。
• 方案3：PUT /jobs 不符合现有资源定义，当前/jobs接口对应已持久化存储的作业，而需求中是执行非存储的自定义作业，不需要提前持久化作业记录；且将域、虚拟机标识全部塞入请求体，完全没有体现层级资源关系，后续也无法通过URL路径做过滤查询，排除。
• 方案4：新增/scheduler调度器资源本身具备合理性，但仅针对当前两个作业执行需求属于过度设计。如果后续有定时调度、批量作业、调度属性更新这类扩展需求，可以直接新增该顶层资源，不需要改动现有接口。
• 方案2：PUT /domains/{dname}/vms/{vm_name} 是最适配当前需求的设计，仅需做小范围优化即可：
  1. 路径完全符合现有「域→域下虚拟机」的层级资源定义，语义清晰，可直接通过URL定位到目标资源
  2. PUT方法天生具备幂等创建语义，刚好匹配需求：如果对应虚拟机已存在则直接执行作业，不存在则自动创建后执行
  3. 优化建议：如果担心和虚拟机本身的属性更新逻辑冲突，可以调整为POST /domains/{dname}/vms/{vm_name}/run-job，POST更符合「触发执行作业」的动作语义，也不需要修改虚拟机本身的state字段，避免和虚拟机的正常运行/关机等状态定义冲突。

通用多资源关联REST API设计原则 #

• 优先遵循层级路径规则：从属资源必须跟在父资源路径之后，比如A资源属于B资源，路径统一设计为/B/{b_id}/A/{a_id}，不要将父资源标识全部塞入请求体，可读性和可维护性会大幅提升
• 动作类操作加子资源后缀：如果是触发某资源的非CRUD类动作，不要硬改主资源的状态字段，通过/动作名的子资源+POST请求实现，语义更清晰
• 跨独立资源操作抽新顶层资源：如果操作不属于任何一个从属资源（比如跨多域批量调度作业），再单独抽象新的顶层资源（比如scheduler），不要硬塞到现有资源的接口中
• 请求方法匹配幂等性：需要幂等创建/更新用PUT，触发一次性非幂等动作用POST，只读操作用GET，删除操作用DELETE

内容的提问来源于stack exchange，提问作者ca9163d9