Web API 设计
ABSTRACT
融合四篇 Web 后端素材：RESTful 接口规范（设计层）、GET/POST 三重分析（协议理解层）、CORS 机制（安全层）、微信公众号服务端事故复盘（生产实践层）。覆盖「怎么设计、怎么理解、怎么放行、怎么不翻车」全链路；核心规范至今有效，需补充 HTTP/2/3、SameSite、现代 SDK 等演进。
设计层：RESTful 规范基线
- URI 即资源：小写中杠、名词复数；层级别太深，深导航改查询参数。
- 方法语义：GET 查、POST 建、PUT 全量改、PATCH 部分改、DELETE 删；GET 安全幂等，PUT/DELETE 幂等，POST 皆否。
- 响应直接给数据；标准状态码表意；统一异常拦截区分业务/非业务异常。
- 异步任务建模为任务资源，客户端轮询状态；版本放 URL（/v1/）最实用。
- 国内实践差异：统一
{code, data, message}信封 vs 「body 不包装」，按网关与前端约定取舍。
协议理解层：GET 与 POST 的本质
- 底层同为 TCP 连接，能力无差别；表层区别来自 HTTP 规范约定 + 浏览器/服务器实现限制（URL 长度 2K/64K 的不成文约定）。
- 深层差异：GET 通常一个 TCP 包，POST 通常两个（100 continue）；网络差时两次发包利于完整性校验——语义不可为省一次往返混用。
- 现代语境：HTTP/2 多路复用、HTTP/3 QUIC 改变了「几个包」的图景，但语义层分析不变。
安全层：CORS
- 同源策略限制脚本内跨源请求；CORS 是服务端声明放行的机制，请求常能到达服务器、是响应被浏览器拦。
- 简单请求（GET/HEAD/POST + 安全头 + 三种 Content-Type）直接发；其余先 OPTIONS 预检。
- 带凭证（withCredentials）时响应须 Allow-Credentials: true 且 Allow-Origin 不得为
*。 - 前端只能配合，放行的钥匙始终在服务端响应首部。
生产实践层：微信服务端事故启示
- 微信生态约束：accessToken 7200 秒过期、互相顶号、接口日限额——集群环境必须 Redis 集中存储凭据，单例刷新。
- 第三方 SDK 默认参数不可信：httpclient 默认 maxConnPerRoute=2、超时不设，高并发下线程堆积宕机；连接池与超时必须按生产实测显式配置。
- 排障方法论：监控先行 → jstack 看线程栈（BLOCKED 找锁、WAITING 找资源池）→ 对症下药。
- 铁律：默认配置在恶劣环境可能致命；超时必须设置且不能太大；生产排障依赖充足的日志与监控。
周边
- 前端联调 mock（Mock.js → 现代 MSW/Apifox）实现前后端契约先行、并行开发。
关联概念
- 编码规范与设计模式
- Unity 热更新方案演进（热更资源下发的 HTTP 服务侧）