· 全部指南
URL 结构速览
URL 不只是地址栏里的字符串，而是由 scheme、authority（userinfo、host、port）、path、query、fragment 组成的结构化标识。集成 bug 常源于误解结构：尾部斜杠改变路由；query 参数顺序理论上无关但某些实现有关；fragment（#section）不会到达服务器。
API 返回 404 或 400 时，第一步应解析客户端实际发出的 URL 与文档示例逐字对比。url-parser 可在本地拆解完整 URL：scheme https、host api.example.com、path /v2/users、query limit=10&filter=active、fragment 为空。与可用的 curl 示例逐字符对照。
url-encoder 对保留字符或非 ASCII 做百分号编码。示例：搜索 résumé PDF 须按技术栈正确编码重音与空格。流程：url-parser 拆解 → 判断需编码的组件（多为 query 值，有时为 path 段）→ url-encoder 编码 → 重组并重试。
常见错误：对整个 URL 双重编码；手工拼 query 时忘了第一个参数前的 ?；假定 Docker 网络中 localhost 与 127.0.0.1 等价。
编码陷阱
百分号编码用 %HH 表示字节。query 值中的空格应为 %20；application/x-www-form-urlencoded 历史上用 + 表示空格——混用两种约定会破坏 OAuth 回调签名校验。
JavaScript 中 encodeURIComponent 用于单个 query 键/值，encodeURI 用于完整 URI 并保留 :、/ 等结构字符。用错函数会过度编码斜杠（破坏 path）或编码不足使 & 错误切分 query。
双重编码是经典生产 bug：客户端把 / 编成 %2F，中间代理再把 % 编成 %25，得到 %252F。日志里解码一次仍见 %2F 即应怀疑双重编码。url-parser 与 url-encoder 配合可安全往返调试。
OAuth 实例：redirect URI https://app.example.com/callback?next=/dashboard 须按身份提供商要求注册精确编码形式——有的要求对 next 中的 ?、/ 编码，有的禁止过度编码。
HTTP 状态码
状态码分类结果。http-status-codes 可在读日志或写错误处理时快速查阅。301/302 重定向影响 OAuth 与 webhook 验证——用 curl -L 跟踪链并注意 POST 是否被降级为 GET。401 表示未认证或认证失败；403 表示已认证但无权限——客户端文案搞反会使用户走错修复路径。
429 表示限速——应指数退避并尊重 Retry-After。502/503/504 多为上游故障，非客户端 bug。CORS 失败在浏览器里像普通网络错误，即使服务器返回了 200 但缺少 Access-Control-Allow-Origin——须看开发者工具 Network，不能只看应用日志。
联调工作流
从浏览器开发者工具、curl 或移动代理日志复制失败 URL，粘贴 url-parser 核对 host、path 与各 query 键。用 url-encoder 修正编码。与经 openapi-formatter 整理的 OpenAPI servers 与 path 模板对照。用 curl 重放，测试受保护预发路由时可加 basic-auth-generator 生成的 Authorization 头。
在工单分享 URL 前脱敏 token、session id 与带签名的 query——Towalles 本地解析，但 Slack 历史永久保留。在 API 指南文档化 canonical URL 模式，使 SDK 生成器与人工集成方对尾部斜杠、默认端口、大小写敏感性达成一致。