任务重试次数重置的REST风格PATCH端点设计方案选型咨询

我们拥有REST资源：

/tasks/{task-type} 

目前仅支持GET方法：

GET /tasks/{task-type} 
GET /tasks/{task-type}/{id}

Task实体包含创建时间、完成时间、状态、引用键、定时任务重试次数等元信息。当前遇到问题：部分任务因数据错误持续执行失败，调度器每5分钟触发一次任务，导致日志中错误量极大，重试次数最高达50万。我们计划将重试次数限制为5次，同时需要手动将指定任务的重试次数重置为0，为此提出以下方案：

方案分析 #

• 方案1：

  PATCH /tasks/{task-type}/{id}/discard-try-count - no response body
  

  实现简单，但违反REST规范（命名中使用动词），且若需修改其他字段会产生大量同类端点，扩展性极差。

• 方案2a：

  PATCH /tasks/{task-type}/{id}
  body:
  {
     "tryCounts": int
  }
  

  符合REST风格且易于扩展，但客户端可设置任意重试次数值，存在数据篡改风险，可能再次引发日志暴增的问题。

• 方案2b：

  PATCH /tasks/{task-type}/{id}
  body:
  {
     "tryCounts": int // 校验值只能为0
  }
  

  在2a基础上增加校验逻辑，仅允许将tryCounts设为0。

结论：方案2b是当前场景的最优选择 #

理由如下：

1. 契合REST设计原则：以资源为核心，通过PATCH操作修改资源的部分属性，端点命名简洁合规，没有冗余的动词。
2. 安全性有保障：服务端校验严格限制修改值为0，彻底避免客户端随意设置重试次数带来的风险。
3. 扩展性强：后续如果需要修改Task的其他字段（如任务状态），直接复用该PATCH端点即可，无需新增大量专用接口。

如果未来有更复杂的修改需求（比如允许特定角色设置非0的重试次数），也可以在现有校验逻辑基础上扩展权限控制，保留接口的灵活性。

内容的提问来源于stack exchange，提问作者Артём Власов