接口

同一个资源可以同时提供面向读者的 HTML 视图和面向程序的 JSON 表示。共用 URL 的前提是源站与中间层始终保留这种区别。端点需要选择可用格式、正确序列化、说明缓存变化维度，并验证本次选中的表示，而不是拿同一资源的另一种版本来代替它。单一地址不会自动完成这些工作。 先选择，再序列化与验证 对于 GET 响应，请求中的 Accept 表达希望接收哪些媒体类型，请求中的 Content-Type 则描述请求内容本身。把后者写成 JSON，并不等于要求服务器返回 JSON。质量值与通配符匹配应交给框架已有的媒体范围解析器。应用还需要分别规定：没有 Accept 时默认返回什么，以及字段存在却匹配不到任何可用表示时如何处理。 下面的端点只在 Accept 缺失时默认选择 HTML。如果客户端明确表达的偏好没有可接受候选，就返回 406，并列出可用类型。这是一项刻意选择的接口策略，因为 HTTP 也允许忽略偏好。不要把它换成 415，后者针对的是请求内容格式不受支持。分清错误方向，客户端才能知道应该修改希望接收的类型，还是自己发送的正文及其声明。 完成选择后，Content-Type 应由实际使用的序列化方式确定。HTML 中插入数据需要适当转义，JSON 则应通过 JSON 序列化器生成，而不是塞进 HTML 模板。该路由的各类表示，包括默认表示，都需要 Vary: Accept。但 Vary 不授予存储资格，也不保护个人信息；实验中的公开缓存指令只适用于这份对所有调用者完全相同、没有敏感信息的固定状态记录，不能直接复制到账户接口。 坏掉的样子 只测源站，可能看不出缓存正在把之前的 HTML 发给现在的 JSON 请求。需要通过完整交付路径检查响应头和解析后的正文，并交换请求顺序。新响应补上正确的 Vary，不会自动修复此前已经缓存、却缺失选择元数据的条目。应使用受控测试地址或已获批准的失效流程，不要为了验证一个端点而随意清空共享缓存。 ...