REST

URL 指认目标资源，请求方法描述客户端希望源站执行的操作。服务器、缓存、代理、爬虫和重试客户端都会读取这个动词，因此方法不是路径上的装饰，而是关于预期效果的一份承诺。只有当承诺诚实时，外围设施才能做出安全的缓存、预取、重试和监控决定。同一个 URL 配上不同方法，对下游来说就是不同请求。 安全与幂等不是一回事 安全方法的定义是“本质上只读”：GET 和 HEAD 都不应要求源站改变目标资源状态。服务器仍可能写访问日志、计费或更新观测计数，但这些附带动作不改变方法的安全语义。幂等则表示，把完全相同的请求发送多次，服务器的预期效果与发送一次相同。PUT 和 DELETE 在协议上具有幂等意图，可是第一次请求可能已经到达而响应在途中丢失，客户端仍需结合版本、条件头和业务结果判断是否重试。 POST 通常表示创建从属资源或执行一次动作；它不会因为当前处理器恰好没有重复副作用，就自动变成幂等。PATCH 表示部分修改，也不天然保证重放安全。OPTIONS 用来询问通信选项，TRACE 有专门的诊断用途。具体资源允许哪些方法由源站决定；已知但不支持的方法应返回 405，并用 Allow 说明可用集合。未知方法则可能得到 501，不能把两个状态码混成一个“失败”。 让动词帮助基础设施判断 GET 与 HEAD 是否可缓存，要结合响应的缓存规则，但它们可被预取、重复读取，正是因为请求意图是只读。若把登出、购买或删除藏在 GET 地址后面，浏览器预取、链接扫描器、爬虫或缓存都可能触发不该发生的动作。重试库可以优先考虑幂等请求，却仍需检查认证、期限、请求体能否重放、条件版本和服务端是否已经提交。幂等不是分布式事务，也不保证客户端永远只看见一份响应。 PUT 请求创建或替换指定目标的状态，重复请求保持相同预期效果；DELETE 移除目标 URI 与其当前功能的关联，不保证物理删除底层数据。本例中条目变成不存在，第一次可能返回 204，后续可能返回 404。若服务端要选择新 ID 并创建对象，用 POST 加幂等键或单独的占位记录更准确，不能仅为了方便重试就假装它是 PUT。API 文档应同时写清方法、状态码、前置条件、版本冲突和重试策略，不能只写一个“请求成功”。 幂等性约束请求的预期效果，不要求响应文本、访问日志或修订历史完全一致。附带记录中的时间戳变化，不会自动破坏幂等性；但重复执行请求明确要求的购买或递增，是另一回事。重试需保留正文与适用的 If-Match 条件。幂等也不防止并发覆盖：无条件重放旧值，仍可能覆盖其他写入者刚提交的更新，必要时应核对条件失败后的权威状态。 ...