后端文档教程【免费下载链接】system-design-101Explain complex systems using visuals and simple terms. Help you prepare for system design interviews.项目地址https://gitcode.com/GitHub_Trending/sy/system-design-101点击查看免费下载在 System Design 101 仓库的 how-do-we-design-effective-and-safe-apis.md 中作者用一张购物车shopping cart示例图揭示了 API 设计的核心论断API 设计绝不只是 URL 路径设计。本文以该论断为骨架结合仓库中 API 设计速查表、8 条高效 API 设计技巧、API 网关 101 与 12 条 API 安全建议 等文档系统拆解资源命名、标识符、路径模式、HTTP 头字段与网关限流五条设计主线帮助你交付既高效又安全、既易用又抗攻击的对外 API。一、核心前提API 设计不止是 URL 路径设计原文档明确指出设计 API 时大多数时候我们需要选择恰当的资源名称resource names、标识符identifiers和路径模式path patterns同样重要的是设计恰当的 HTTP 头字段以及在 API 网关内设计有效的限流规则。这意味着一份合格的 API 设计清单至少覆盖四个层面设计层面关注点对应仓库文档资源与路径资源命名、嵌套关系、语义化路径、版本号8 条高效 API 设计技巧、REST API 速查表标识符唯一 ID、API Key 分级、签名与防重放API 设计速查表HTTP 头字段认证凭据、幂等键、时间戳、nonceHTTP 头字段的重要细节网关与限流路由、鉴权、限流、缓存、API 聚合API 网关 101、API 网关的职责下文依次展开这四条主线并在每条主线中给出可直接落地的示例与参数说明。二、资源命名、标识符与路径模式以购物车为例原文档以购物车为例展示典型 API 设计。结合 8 条高效 API 设计技巧 中的领域模型驱动Domain Model Driven语义化路径Semantic Paths两条原则购物车场景的 RESTful 路径可以这样组织# 领域模型驱动 语义化路径 POST /carts # 创建购物车 GET /carts/{cart_id} # 查询购物车 PATCH /carts/{cart_id} # 更新购物车信息如收货地址、优惠券 DELETE /carts/{cart_id} # 清空购物车 GET /carts/{cart_id}/items # 列出购物车条目 POST /carts/{cart_id}/items # 向购物车添加商品 PATCH /carts/{cart_id}/items/{item_id} # 修改某商品数量 DELETE /carts/{cart_id}/items/{item_id} # 移除某商品 POST /carts/{cart_id}/checkout # 结算动作型端点这套路径的设计要点每条都对应仓库文档中的明确原则资源名用名词复数、语义自解释/carts、/items表达的是资源集合而不是动作。用户无需阅读文档也能凭路径语义找到正确端点这正是语义化路径让 API 更易理解的目的。嵌套关系表达从属/carts/{cart_id}/items表达购物车条目从属于某购物车。原文档强调要谨慎选择路径模式path patterns嵌套层级不宜过深一般不超过两层资源否则路径会迅速膨胀、难以维护。HTTP 方法语义化仓库文档特别提醒只需定义少量基础 HTTP 方法即可简化设计——GET 用于读取、POST 用于创建、PATCH 用于部分更新、DELETE 用于删除并指出PATCH 常常是团队协作的痛点需要在 API 规范中提前约定其语义。提前设计版本号在路径中加入版本号如/v1/carts可以把升级成本提前摊薄避免将来为兼容旧客户端而做破坏性变更。这一点同样来自 8 条高效 API 设计技巧。关于标识符identifiers原文档强调要选择恰当的标识符。API 设计速查表 给出了两个可操作方向为每个客户端生成一个唯一 app ID并针对不同授权级别生成多对密钥一对公钥access key私钥secret key用于只读访问另一对用于读写访问——即分级 API KeyLeveled API Keys从而把泄露风险限制在单一授权级别内。资源 ID 本身建议使用全局唯一、不可枚举的标识仓库中另有 分布式系统中的 5 种唯一 ID 生成器 与 唯一 ID 生成器 可作延伸阅读避免使用自增整数暴露业务规模、被遍历抓取。三、HTTP 头字段把元数据设计出安全与幂等原文档将设计恰当的 HTTP 头字段与路径设计并列说明头的设计同样需要深思熟虑而非随手一填。API 设计速查表 明确列出了请求参数中必须包含的内容其中大部分恰好是通过头字段承载的请求要素承载方式作用认证凭据Authentication CredentialsAuthorization头证明调用者身份与权限时间戳Timestamp自定义头如X-Timestamp或签名串内防止重放攻击replay attack请求特有数据请求体或查询参数处理请求所需如用户 ID、交易明细、搜索词随机串Nonce自定义头如X-Nonce保证每个请求唯一进一步防止重放攻击防重放攻击的标准组合拳是时间戳 nonce时间戳限制请求的有效窗口例如 5 分钟内nonce 保证同一窗口内的请求也互不相同配合下文提到的 HMAC 签名服务器可以同时校验谁发的、何时发的、有没有被篡改。在购物车结算这类写操作场景另一个值得优先设计的头是幂等键POST /v1/carts/{cart_id}/checkout Idempotency-Key: 9f8e7d6c-5b4a-3c21-0fed-cba9876543218 条高效 API 设计技巧 指出GET 天然幂等但POST 必须经过专门设计才能具备幂等性。让客户端为每次结算生成一个Idempotency-Key服务端对相同键的重复请求返回首次处理的结果就能从根本上避免重复扣款这类事故。HTTP 头字段的更多细节如缓存头、内容协商头、自定义头的最佳实践可参考仓库文档 关于 HTTP 头字段你可能不知道的重要细节。四、API 网关内的限流规则保护后端的第一道闸门原文档特别强调要在API 网关内设计有效的限流规则effective rate-limiting rules。API 网关 101 将 API 网关定位为客户端与服务器之间的中间人接收 API 请求、强制节流与安全策略、转发给后端服务、再返回结果。其关键职责包括请求路由Request Routing把请求导向正确的后端服务负载均衡Load Balancing跨多台服务器分发流量避免单点过载安全Security实施认证、授权与数据加密限流与节流Rate Limiting and Throttling控制客户端在单位时间内的请求数量API 聚合API Composition把多个后端请求合并为一次前端请求缓存Caching暂存响应减少重复计算。限流规则的设计要点可以归纳为四个维度限流对象按客户端app ID / API Key、按用户、按 IP还是按子资源通常以客户端维度为主辅以 IP 维度兜底防爬。限流窗口固定窗口、滑动窗口还是令牌桶token bucket窗口粒度直接影响突发流量容忍度与实现复杂度。限额数值如每个 app 每分钟 100 次请求每次请求最多返回 50 条条目——限额需要结合后端容量测试来定仓库 学习缓存 等文档也提示了限流与缓存配合保护后端的思路。超限响应返回429 Too Many Requests并在响应头中告知客户端剩余配额与重试时间Retry-After让限流从惩罚变成可预期的约束。在设计限流时还可参考仓库中 缓存系统的常见误区 与 缓存使用前要考虑的因素因为网关内限流计数器通常依赖缓存/内存存储分布式网关节点的限流一致性本身就是一道设计题。五、把安全设计进默认值认证、签名与输入校验原文档标题中的安全Safe并非口号12 条 API 安全建议 给出了可逐条落地的清单使用 HTTPS、OAuth2、WebAuthn、分级 API Key、授权、限流、API 版本化、白名单、核对 OWASP API 安全风险、使用 API 网关、错误处理、输入校验。设计安全系统 亦将 API 安全列为系统级安全的关键支柱之一。其中与安全 API 请求直接相关的是签名机制Signature Generation。API 设计速查表 描述了用私钥secret key生成签名的四个步骤收集参数Collect parameters将所有参与签名的参数按约定排序构造待签名字符串Create a string to sign把参数拼接为规范化字符串哈希签名Hash the string用HMAC基于哈希的消息认证码 SHA-256结合私钥对字符串做哈希发送请求Send the requests把签名附在请求中一并发出。服务器用公钥/共享密钥对相同规则重新计算签名并比对即可同时验证请求的真实性authenticity与完整性integrity——任何参数被篡改都会导致签名不匹配。再结合上一节的时间戳 nonce可进一步抵御重放攻击。同时仓库文档反复强调的两个廉价但致命的实践是输入校验Input Validation对用户 ID、交易金额、商品数量等请求参数做类型、范围与格式校验是抵御注入与畸形请求的第一道防线谨慎的错误处理Error Handling错误信息不应泄露内部堆栈、SQL 片段或服务拓扑避免成为攻击者的情报源。仓库中 5 个本不该被发明的 HTTP 状态码 与 你应该知道的 HTTP 状态码 可帮助你为每种错误选择语义准确的状态码。六、高效的另一半幂等、批量与查询语言有效Effective与安全Safe是一体两面。除前文已述的幂等设计外8 条高效 API 设计技巧 还给出了三条提升效率的设计约定同样适用于购物车示例批量处理Batch Processing用batch/bulk作为关键字放在路径末尾例如POST /v1/carts/{cart_id}/items/batch一次提交多条商品减少往返次数查询语言Query Language为列表类端点设计统一的分页、排序、过滤规则例如GET /v1/carts/{cart_id}/items?limit20offset0sort-pricefilteravailabletrue让 API 更灵活而不必为每种组合新建端点恰当地实现幂等Implement Idempotence ProperlyGET 天然幂等POST 需要借助Idempotency-Key头实现见第三节。这些原则在仓库的 REST API 速查表 中也有呼应可作为设计时的对照清单。七、落地检查清单与延伸阅读综合原文档论断与仓库各篇 API 相关指南一份高效且安全的 API 在发布前应通过以下检查资源名、标识符、路径模式是否符合领域模型路径是否语义化且层级可控HTTP 方法语义是否统一尤其 PATCH 的用法是否已被团队约定写操作是否设计了幂等键POST 是否具备幂等性认证凭据、时间戳、nonce 是否进入请求参数/头字段签名HMAC-SHA256是否校验真实性HTTPS、OAuth2、分级 API Key、白名单、输入校验、安全错误处理是否就位网关内限流规则是否覆盖客户端维度超限是否返回 429 且带Retry-After是否提前设计版本号列表端点是否有统一的分页、排序、过滤规则。若想继续深入仓库中与本主题直接相关的文档包括API 设计速查表、8 条高效 API 设计技巧、API 网关 101、API 网关的职责、12 条 API 安全建议、设计安全系统、REST API 速查表以及电子商务流程类文档 e-commerce-workflow 可作为购物车场景的补充背景。把路径、头、限流与安全四条线同时纳入设计评审你的 API 才能真正做到既高效又安全。赞分享后端文档教程【免费下载链接】system-design-101Explain complex systems using visuals and simple terms. Help you prepare for system design interviews.项目地址https://gitcode.com/GitHub_Trending/sy/system-design-101点击查看免费下载相关推荐Cap免费开源录屏工具一键录屏停止录制即得分享链接Cap免费开源录屏工具一键录屏停止录制即得分享链接 周一上午开发群里丢来一段30秒录屏复现路径、报错页面、网络面板全在里头不用约会人人能复现。这就是屏幕录制音视频桌面应用后端前端视频处理AI 应用移动开发System Design 101 之 API 设计速查表从密钥生成、签名验收到安全加固的完整实战指南System Design 101 之 API 设计速查表从密钥生成、签名验收到安全加固的完整实战指南 API 将业务逻辑与数据暴露给外部系统因此安全、高效后端文档教程System Design 101 的 API 安全速查表从 HTTPS 到 RBAC 的六层防护实践System Design 101 的 API 安全速查表从 HTTPS 到 RBAC 的六层防护实践 导读 本文以 a cheatsheet to buil后端文档教程上一篇无线定位基础方法全解从 TOA/AOA/RSS 到指纹定位与滤波优化ESP-CSI 实践视角下一篇NeuPAN ROS/ROS2封装器使用指南如何将NeuPAN集成到ROS机器人系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考