REST

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