AAS 技能深度解读：api-patterns 之 API 设计决策指南（REST / GraphQL / tRPC、响应、版本化、认证、限流与安全测试）-北京尧图网络

AI 技能AI 插件人工智能【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills点击查看免费下载本文以 api-patterns 技能为骨架系统讲解 API 设计中的风格选型REST vs GraphQL vs tRPC、响应格式、版本化、认证、限流、文档与安全测试的完整决策框架。文章结合仓库内配套的 10 个子文档与api_validator.py启发式扫描脚本的源码实现帮助你从照抄固定模板转向依据消费方与部署约束进行思考在真实项目中做出可落地、可验证的 API 契约决策。读完你将掌握一套从需求采集 → 风格选择 → 契约定义 → 防护设计 → 文档 → 安全测试的完整工作流。一、核心理念Learn to THINK, not copy fixed patterns该技能的开篇原则即点明主旨API 设计决策应绑定到消费方consumers与部署约束deployment constraints而不是机械复制某一种固定模式。任何 API 风格本身都不是银弹REST 不是默认答案GraphQL 与 tRPC 也各有适用边界。在开始任何设计之前技能给出了一份可勾选的Decision Checklist是否询问过用户 API 的消费方是谁是否为当前上下文选择了 API 风格REST / GraphQL / tRPC是否定义了一致的响应格式是否规划了版本化策略是否考虑了认证需求是否规划了限流是否确定了文档方案同时技能明确列出反模式清单作为设计红线DONT不要对一切场景默认使用 REST在 REST 端点中使用动词如/getUsers返回不一致的响应格式向客户端暴露内部错误跳过限流DO应该根据上下文选择 API 风格询问客户端需求充分编写文档使用恰当的状态码二、第一步选择 API 风格——REST vs GraphQL vs tRPCapi-style.md 提供了完整的决策树它是整个技能的第一个分叉点Who are the API consumers? │ ├── Public API / Multiple platforms │ └── REST OpenAPI (widest compatibility) │ ├── Complex data needs / Multiple frontends │ └── GraphQL (flexible queries) │ ├── TypeScript frontend backend (monorepo) │ └── tRPC (end-to-end type safety) │ ├── Real-time / Event-driven │ └── WebSocket AsyncAPI │ └── Internal microservices └── gRPC (performance) or REST (simplicity)2.1 三者的横向对比因素RESTGraphQLtRPC最适合公共 API复杂应用TS monorepo学习曲线低中低如果熟悉 TS过度/不足获取为消费方定制端点形状客户端选择字段需强制执行成本限制取决于过程procedure设计类型安全手动OpenAPI基于 Schema自动缓存HTTP 原生复杂基于客户端2.2 风格选择五问API 的消费方是谁前端是否是 TypeScript数据关系有多复杂缓存是否关键是公共 API 还是内部 API判断要点公共 API 追求最广泛兼容性 → REST OpenAPI复杂互联数据且多前端 → GraphQLTS 全栈 monorepo → tRPC。注意选择问题存在顺序依赖消费方是谁永远应最先回答。三、REST 设计原则名词而非动词rest.md 聚焦资源型 API 设计核心是nouns not verbs用名词不用动词。3.1 资源命名规则Principles: ├── 使用 NOUNS 而非 verbs资源而非动作 ├── 使用 PLURAL 复数形式/users 而非 /user ├── 使用小写与连字符/user-profiles ├── 为关系嵌套/users/123/posts └── 保持浅层最多 3 层深度3.2 HTTP 方法选型方法用途幂等请求体GET读取资源是否POST创建新资源否是PUT整体替换资源是是PATCH部分更新否是DELETE删除资源是否3.3 状态码选型场景状态码原因成功读取200标准成功已创建201新资源已创建无内容204成功无返回体错误请求400请求格式错误未认证401缺失/无效认证禁止访问403认证有效但无权限未找到404资源不存在冲突409状态冲突如重复校验失败422语法有效但数据无效限流429请求过多服务器错误500服务端过错四、响应格式与错误处理response.md 强调一致性是核心选定一种格式后要坚持到底。4.1 常见响应模式Choose one三选一: ├── Envelope 信封模式 ({ success, data, error }) ├── Direct data 直接返回资源本体 └── HAL/JSON:API超媒体 hypermedia4.2 错误响应应包含的要素Include: ├── Error code错误码供程序化处理 ├── User message用户消息供界面展示 ├── Details细节供调试字段级错误 ├── Request ID请求 ID供售后支持 └── NOT internal details绝不包含内部细节——安全4.3 分页类型对比类型最适合权衡Offset偏移简单、可跳页大数据集性能差Cursor游标大数据集无法直接跳页Keyset键集性能敏感需要可排序的键分页选择三问数据集多大用户是否需要跳转到特定页数据是否频繁变化五、GraphQL 原则为互联数据而生graphql.md 描述其适用边界与设计要点。5.1 何时适用✅ 合适: ├── 复杂、互联的数据 ├── 多个前端平台 ├── 客户端需要灵活查询 ├── 数据需求持续演进 └── 减少过度获取很重要 ❌ 不合适: ├── 简单 CRUD 操作 ├── 文件上传密集 ├── HTTP 缓存很重要 └── 团队不熟悉 GraphQL5.2 Schema 设计原则Principles: ├── 以图而非端点为思考单位 ├── 面向可演进性设计无版本 ├── 用 connections 做分页 ├── 类型要具体不要泛化的 data └── 谨慎处理 nullability5.3 安全考虑Protect against: ├── 查询深度攻击 → 设置最大深度 max depth ├── 查询复杂度 → 计算成本 cost ├── 批量滥用 → 限制批量大小 ├── Introspection 内省 → 针对受众设定策略它不是授权边界六、tRPC 原则TypeScript monorepo 的端到端类型安全trpc.md 面向全栈 TypeScript 场景。6.1 何时适用✅ 完美契合: ├── 两端都是 TypeScript ├── Monorepo 结构 ├── 内部工具 ├── 快速开发 └── 类型安全至关重要 ❌ 不合适: ├── 非 TypeScript 客户端 ├── 公共 API ├── 需要 REST 约定 └── 多语言后端6.2 关键收益Why tRPC: ├── 共享 TypeScript 类型但运行时输入仍需验证validate untrusted runtime input ├── 端到端类型推断 ├── 跨栈 IDE 自动补全 ├── 针对共享契约重建的客户端会暴露类型错误 └── 无需代码生成步骤6.3 集成模式Common setups: ├── Next.js tRPC最常见 ├── 带共享类型的 Monorepo ├── Remix tRPC └── 任意 TS 前端后端重要提醒技能原文共享类型仅在构建期保证兼容无法保证独立部署的客户端在运行时仍兼容——这需要配合部署测试验证。七、版本化策略从第一天起规划 API 演进versioning.md 强调版本化应从项目启动之初就纳入计划。7.1 四种策略对比策略实现方式权衡URI/v1/users清晰、易缓存HeaderAccept-Version: 1URL 更干净但发现难度高Query?version1易添加但显得杂乱None不版本化谨慎演进最适合内部公共 API 有风险7.2 版本化哲学Consider: ├── 公共 API→ 在 URI 中版本化 ├── 仅内部→ 可能无需版本化 ├── GraphQL→ 通常无版本演进 schema ├── tRPC→ 测试已部署客户端的兼容性类型仅在构建期有帮助八、认证模式选型auth.md 提供基于用例的认证选型指南。8.1 认证模式选择表模式最适合JWT无状态、微服务Session传统 Web、简单场景OAuth 2.0第三方集成API Keys服务间通信、公共 APIPasskey无密码用户认证8.2 JWT 使用原则Important: ├── 始终验证签名 ├── 仅允许预期算法并校验 issuer/audience ├── 要求并检查过期时间 ├── 仅包含最小化 claims ├── 使用短有效期刷新令牌refresh tokens └── 绝不在 JWT 中存储敏感数据九、限流保护 API 免受滥用与过载rate-limiting.md 给出限流的动机与策略选择。9.1 为什么要限流Protect against: ├── 暴力破解攻击 ├── 资源耗尽 ├── 成本超支按量付费场景 └── 不公平使用9.2 策略选择类型机制适用时机Token bucket令牌桶允许突发随时间补充大多数 APISliding window滑动窗口平滑分布严格限额Fixed window固定窗口每窗口简单计数基础需求9.3 响应头约定Include in headers: ├── X-RateLimit-Limit最大请求数 ├── X-RateLimit-Remaining剩余请求数 ├── X-RateLimit-Reset限额重置时间 └── 超限时返回 429十、文档OpenAPI / Swagger 最佳实践documentation.md 的核心观点是好文档开心的开发者 API 采纳率。10.1 OpenAPI/Swagger 必含内容Include: ├── 全部端点及示例 ├── 请求/响应 schema ├── 认证要求 ├── 错误响应格式 └── 限流信息10.2 一份好文档应具备Essentials: ├── 快速开始 / Getting started ├── 认证指南 ├── 完整 API 参考 ├── 错误处理指南 ├── 多语言代码示例 └── Changelog十一、API 安全测试OWASP Top 10 与系统化测试security-testing.md 提供面向攻击者思维的测试框架并强调只对授权的本地/测试目标、使用隔离账号与明确范围执行安全测试。11.1 OWASP API Security Top 10漏洞测试重点API1: BOLA对象级授权失效访问其他用户资源API2: Broken AuthJWT、会话、凭据API3: Property Auth属性级授权失效批量赋值、数据暴露API4: Resource Consumption限流、DoSAPI5: Function Auth管理端点、角色绕过API6: Business Flow逻辑滥用、自动化API7: SSRF内网访问API8: Misconfiguration调试端点、CORSAPI9: Inventory影子 API、旧版本API10: Unsafe Consumption第三方 API 信任11.2 JWT 与会话测试JWT 测试检查项测试内容算法none、算法混淆密钥弱密钥、暴力破解Claims过期时间、issuer、audience签名篡改、密钥注入会话测试检查项测试内容生成可预测性存储客户端侧安全性过期超时强制执行失效登出有效性11.3 授权测试与 BOLA/IDOR 流程测试类型方法水平Horizontal访问同级用户数据垂直Vertical访问更高权限功能上下文Context访问允许范围外的数据BOLA/IDOR 测试四步在请求中识别资源 ID用用户 A 的会话捕获请求用用户 B 的会话重放检查是否存在未授权访问11.4 输入验证与限流测试注入类型测试重点SQL查询操纵NoSQL文档查询Command系统命令LDAP目录查询测试方法测试所有参数、尝试类型强制转换、测试边界、检查错误消息。限流测试三方面是否存在限额、能否绕过Headers、IP 轮换、作用域每用户/每 IP/全局。常见绕过手法包括X-Forwarded-For头、不同 HTTP 方法、大小写变体、API 版本化。11.5 GraphQL 安全与最终清单GraphQL 安全测试内省schema 泄露、批量查询 DoS、嵌套深度 DoS、授权字段级访问。安全测试清单认证测试绕过、检查凭据强度、验证令牌安全授权测试 BOLA/IDOR、检查提权、验证功能访问输入测试所有参数、检查注入配置检查 CORS、验证响应头、测试错误处理技能结语APIs are the backbone of modern apps. Test them like attackers will.API 是现代应用的支柱要用攻击者的心态去测试。十二、配套工具本地启发式 API 扫描器该技能并非仅有理论框架还附带了可直接执行的 Python 辅助脚本 api_validator.py。注意它的定位是本地启发式heuristic源码扫描而非 schema 校验。12.1 运行方式python3 plugins/agentic-awesome-skills-claude/skills/api-patterns/scripts/api_validator.py project_path12.2 源码实现剖析从源码看脚本的执行链路分三步文件发现find_api_files通过 glob 模式扫描项目匹配**/*api*.{ts,js,py}、routes/、controllers/、endpoints/目录以及*.openapi.json、swagger.*、openapi.*等文件并排除node_modules、.git、dist、build、__pycache__目录且跳过符号链接。注意脚本实现明确限制最多处理15 个匹配文件api_files[:15]因此输出是抽样 triage而非全量审计。规范文件检查check_openapi_spec对.json后缀文件做json.loads深度检查验证是否存在openapi/swagger版本声明、infotitle/version/description、paths端点数量以及每个端点的responses与summary/description对 YAML 文件仅做浅层文本检查openapi:、paths:、components:/definitions:关键词。代码文件检查check_api_code使用正则分别检测错误处理try/catch/except、HTTP 状态码status(403)、statusCode、HttpStatus.等、输入校验validate/zod/joi/pydantic/Body(、认证中间件jwt/bearer/guard、限流rateLimit/throttle与日志console.log/logger.。12.3 输出与退出码扫描结果按文件分组打印[OK]/[!]/[X]标记最后汇总[RESULTS] N passed, M heuristic issues存在[X]级问题时以退出码1结束并提示 Fix heuristic issues before deployment否则以0结束若完全未找到 API 相关文件则提示 No API files found 并以 0 退出。使用边界必须牢记该脚本输出只是分流提示triage hint不是 OpenAPI 校验、不是授权审计、也不是部署批准。它不能替代对契约的全面校验与安全测试。十三、实战工作示例分页游标契约设计技能文档用一个完整的 worked example 演示如何将上述原则应用到真实契约决策中输入场景一个公共订单列表在客户端翻页过程中持续变化。决策过程选择分页方案采用有界页大小基于稳定排序键(created_at, id)的游标keyset/cursor 分页避免 offset 在大数据集上的性能问题与数据变化导致的重叠/丢失定义契约细节明确 next-cursor 的格式、授权过滤规则以及记录被删除或游标无效时的行为设计测试用例测试两个相同时间戳的记录、以及两页之间发生插入的情况预期结果在承诺的快照语义snapshot semantics内不得出现重复 ID同时文档化新插入的行是否可能出现在结果中让消费方对一致性有明确预期。这个例子完整体现了技能的核心方法论先记录消费方与部署版本、预期负载大小、访问规则、兼容性义务和一个具体操作再对照内容地图阅读相关文件、比较现实可行的选项最后给出请求/响应示例与拒绝rejection场景。十四、适用时机与局限性声明14.1 何时使用该技能根据 SKILL.md 的 When to Use 说明在定义新的端点契约、为已知消费方选择 REST/GraphQL/tRPC、或变更分页、错误、认证、兼容性行为时使用如果是在已有契约中发现 bug除非任务明确授权变更否则应保留原契约避免破坏兼容性。14.2 明确局限Python 辅助脚本最多扫描 15 个匹配文件基于正则与浅层 JSON/YAML 检查其输出只是分流提示不能替代 OpenAPI 校验、授权审计或部署批准GraphQL 查询形状、tRPC 类型推断与 HTTP 方法名本身不强制执行资源授权或向后兼容——授权必须独立设计并测试限流单独无法阻止所有资源耗尽问题大小、并发、时间与按供应商计费的成本上限都取决于具体操作安全测试仅可针对授权的本地/测试目标使用隔离账号并定义明确范围。十五、关联技能与进阶路径在 SKILL.md 的 Related Skills 中该技能与仓库内其他技能形成互补需求关联技能API 实现backend-architect数据结构database-design安全细节api-security-best-practices建议的学习路径是先用本文的决策框架完成风格选型与契约定义再进入backend-architect落实具体实现通过api_validator.py做本地启发式扫描最后用api-security-best-practices与security-testing.md的清单完成安全加固与测试。整条链路遵循同一原则——先思考消费方与部署约束再决定用哪种模式而不是为所有 API 套用同一个模板。赞分享AI 技能AI 插件人工智能【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills点击查看免费下载相关推荐AAS 仓库 api-fuzzing-bug-bounty 技能深度解析面向 Bug Bounty 的 REST / SOAP / GraphQL API 模糊测试实战指南AAS 仓库 api fuzzing bug bounty 技能深度解析面向 Bug Bounty 的 REST / SOAP / GraphQL API 模AI 技能AI 插件人工智能AAS API Patterns 之 REST 设计原则资源命名、HTTP 方法与状态码实战指南AAS API Patterns 之 REST 设计原则资源命名、HTTP 方法与状态码实战指南本篇指南以 AASagentic awesome skilAI 技能AI 插件人工智能Buzz 离线转写指南Whisper 本地运行2 小时会议音频如何变字幕Buzz 离线转写指南Whisper 本地运行2 小时会议音频如何变字幕录了两小时的会想把内容变成能搜索、能引用的文字又不想把音频传到任何云服务。Bu语音AI 应用本地部署桌面应用上一篇在 goose 中接入 Fetch MCP 扩展让 AI Agent 自主抓取并处理网页内容下一篇Woodpecker CLI工具使用指南从入门到精通创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

AAS 技能深度解读：api-patterns 之 API 设计决策指南（REST / GraphQL / tRPC、响应、版本化、认证、限流与安全测试）

相关推荐

贾子猜想的伟大意义：从高维数论到人类认知边界的探索

openai-openapi 实战指南：12 万行 OpenAI API 的 OpenAPI 规范，如何读懂并落地使用

Simulink与AUTOSAR协同建模的三大断层及工程化破局方案

更多资讯

Rensheng d jngrjeg《人生的境界》汉语拼音字母标调拼写实测案例

【化学实验室｜14】HarmonyOS ArkTS 主导航实战：统一页面入口、返回路径和参数校验

【信息科学与工程学】计算机科学与自动化——第二十四篇编译器05

【化学实验室｜15】HarmonyOS ArkTS 本地状态持久化实战：让保存、删除和页面返回后的数据即时一致

如何读穿招聘简章？工业通信嵌入式岗位情报拆解指南

自动驾驶黄埔军校：4500人培养体系与行业技术扩散

今日更新

微信云开发旅游小程序实战：LBS打卡+UGC社交全栈方案

金融AI代理平台核心拆解：从多代理协作到财报分析实战

基于大数据的智慧旅游推荐与可视化平台架构实践

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？