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点击查看免费下载本指南以 agentic-awesome-skills 仓库内 api-design-principles 技能包的 REST Best Practices 参考文档为骨架系统梳理 REST API 设计的核心规范并结合作者随包提供的 rest-api-template.py 与 api-design-checklist.md给出可复制、可运行的生产级实现。读完本文你将掌握资源命名、HTTP 语义、分页/过滤、版本化、限流、错误格式、缓存、幂等性、CORS、OpenAPI 文档与健康检查等一整套 REST 设计方法并能在 FastAPI 中直接落地。该技能包在仓库的 skills_index.json 中被登记为分类backend、风险等级safe、来源community插件目标同时支持 codex 与 claude 两类 Agent参见 skills_index.json说明它属于面向开发者的通用 API 设计方法论而非特定框架绑定正文中的代码示例采用 FastAPI 仅作为演示载体。一、URL 结构资源命名与层级设计1.1 资源命名名词复数杜绝动词REST 将资源建模为名词HTTP 方法表达操作语义因此 URL 中不应出现动词。原文档给出了清晰的对照# Good - Plural nouns GET /api/users GET /api/orders GET /api/products # Bad - Verbs or mixed conventions GET /api/getUser GET /api/user (inconsistent singular) POST /api/createOrder配套的 api-design-checklist.md 在Pre-Implementation Review → Resource Design一节进一步固化了这条检查项Resources are nouns, not verbs、Plural names for collections、Consistent naming across all endpoints并建议把资源层级控制在 2 层以内Clear resource hierarchy (avoid deep nesting 2 levels)。1.2 嵌套资源浅层优先子资源通过嵌套表达从属关系但嵌套过深会让 URL 冗长、路由复杂且难以维护# Shallow nesting (preferred) GET /api/users/{id}/orders GET /api/orders/{id} # Deep nesting (avoid) GET /api/users/{id}/orders/{orderId}/items/{itemId}/reviews # Better: GET /api/order-items/{id}/reviews设计要点当子资源本身需要被独立寻址时如order-item可以直接通过 ID 访问应把它提升为顶层资源用提升实体的方式打断过深的层级而不是无限嵌套下去。二、HTTP 方法与状态码语义原文档对每个 HTTP 方法给出了完整的请求-响应映射这也是 REST 契约中最重要的部分。2.1 GET —— 检索资源安全、幂等GET /api/users → 200 OK (with list) GET /api/users/{id} → 200 OK or 404 Not Found GET /api/users?page2 → 200 OK (paginated)GET 必须是无副作用的集合请求应支持分页见第四节。模板中的列表端点list_users正是按此模式实现见 rest-api-template.py。2.2 POST —— 创建资源POST /api/users Body: {name: John, email: johnexample.com} → 201 Created Location: /api/users/123 Body: {id: 123, name: John, ...} POST /api/users (validation error) → 422 Unprocessable Entity Body: {errors: [...]}要点创建成功返回201 Created并在响应头Location中给出新资源的定位校验失败返回422 Unprocessable Entity而不是笼统的 400因为请求语法本身合法只是语义/业务校验不通过如邮箱格式非法。模板中的create_user端点用status_codestatus.HTTP_201_CREATED显式声明创建语义并用 Pydantic 的EmailStr类型在请求进入业务逻辑前完成字段级校验见 rest-api-template.py。2.3 PUT —— 整体替换幂等PUT /api/users/{id} Body: {complete user object} → 200 OK (updated) → 404 Not Found (doesnt exist) # Must include ALL fieldsPUT 要求客户端提交完整对象服务端整体覆盖重复提交同一 PUT 结果一致因此天然幂等。2.4 PATCH —— 部分更新PATCH /api/users/{id} Body: {name: Jane} (only changed fields) → 200 OK → 404 Not FoundPATCH 只携带发生变更的字段。模板中update_user的实现很好地演示了这一语义用update.model_dump(exclude_unsetTrue)只取出客户端显式设置的字段再逐项应用到既有对象上避免把未传字段误置为空见 rest-api-template.py。2.5 DELETE —— 删除资源DELETE /api/users/{id} → 204 No Content (deleted) → 404 Not Found → 409 Conflict (cant delete due to references)删除成功返回204 No Content无响应体若资源被外键/引用约束而无法删除应返回409 Conflict说明状态冲突。模板中delete_user先调用get_user校验资源存在再返回 204见 rest-api-template.py。2.6 状态码速查表原文档给出的完整状态码指南如下这也是 api-design-checklist.md Status Codes 检查清单的直接依据状态码语义200 OK成功的 GET、PATCH、PUT201 Created成功的 POST204 No Content成功的 DELETE400 Bad Request请求格式错误401 Unauthorized需要认证403 Forbidden已认证但权限不足404 Not Found资源不存在409 Conflict状态冲突如邮箱重复422 Unprocessable Entity校验失败429 Too Many Requests被限流500 Internal Server Error服务端错误503 Service Unavailable临时不可用三、过滤、排序与搜索集合端点通过查询参数承载过滤/排序/搜索能力保持 URL 干净且语义明确# Filtering GET /api/users?statusactive GET /api/users?roleadminstatusactive # Sorting GET /api/users?sortcreated_at GET /api/users?sort-created_at (descending) GET /api/users?sortname,created_at # Searching GET /api/users?searchjohn GET /api/users?qjohn # Field selection (sparse fieldsets) GET /api/users?fieldsid,name,email实现约定排序参数用字段名前缀-表示降序逗号分隔多级排序搜索参数search/q对应全文检索fields允许客户端按需选择返回字段sparse fieldsets减少传输体积。模板中list_users端点把status枚举过滤与search关键词搜索直接建模为可选查询参数并用 FastAPI 的Query附加约束page 1、page_size介于 1 与 100 之间见 rest-api-template.py。四、分页模式4.1 基于偏移量Offset-Based分页适合中小规模数据集实现简单GET /api/users?page2page_size20 Response: { items: [...], page: 2, page_size: 20, total: 150, pages: 8 }模板中通过PaginationParamspage默认 1、page_size默认 20、上限 100与PaginatedResponse两个 Pydantic 模型固化了这套响应结构页数计算采用向上取整(total page_size - 1) // page_size见 rest-api-template.py 与 rest-api-template.py。4.2 基于游标Cursor-Based分页适合大数据集与高频写入场景游标编码了最后一条记录的位置新数据插入不会导致页码漂移、重复或遗漏GET /api/users?limit20cursoreyJpZCI6MTIzfQ Response: { items: [...], next_cursor: eyJpZCI6MTQzfQ, has_more: true }4.3 Link Header 分页纯 RESTful 风格把分页导航放入 HTTP 响应头响应体只含数据本身GET /api/users?page2 Response Headers: Link: https://api.example.com/users?page3; relnext, https://api.example.com/users?page1; relprev, https://api.example.com/users?page1; relfirst, https://api.example.com/users?page8; rellast选择哪种模式应在设计期定下来api-design-checklist.md 的 Pagination 检查项要求所有集合端点均分页、明确默认页大小与上限、携带分页元数据并选择 cursor 或 offset 模式之一。五、版本化策略版本化是 API 演进的护栏。原文档给出三种主流方案及其取舍URL 版本化推荐/api/v1/users /api/v2/users Pros: Clear, easy to route Cons: Multiple URLs for same resourceHeader 版本化GET /api/users Accept: application/vnd.apijson; version2 Pros: Clean URLs Cons: Less visible, harder to test查询参数版本化GET /api/users?version2 Pros: Easy to test Cons: Optional parameter can be forgotten原文档明确推荐 URL 版本化——它直观、易于路由与缓存区分。api-design-checklist.md 同时要求定义版本化策略URL/header/query 三选一、所有端点包含版本、并书面化弃用deprecation政策。六、限流Rate Limiting6.1 限流响应头标准限流头让客户端可以主动感知配额X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 742 X-RateLimit-Reset: 1640000000 Response when limited: 429 Too Many Requests Retry-After: 3600被限流时必须返回429并附Retry-After指示客户端多久后重试。6.2 滑动窗口实现模式原文档给出了一个可直接运行的固定窗口/滑动窗口限流器from fastapi import HTTPException, Request from datetime import datetime, timedelta class RateLimiter: def __init__(self, calls: int, period: int): self.calls calls self.period period self.cache {} def check(self, key: str) - bool: now datetime.now() if key not in self.cache: self.cache[key] [] # Remove old requests self.cache[key] [ ts for ts in self.cache[key] if now - ts timedelta(secondsself.period) ] if len(self.cache[key]) self.calls: return False self.cache[key].append(now) return True limiter RateLimiter(calls100, period60) app.get(/api/users) async def get_users(request: Request): if not limiter.check(request.client.host): raise HTTPException( status_code429, headers{Retry-After: 60} ) return {users: [...]}该实现以客户端 IPrequest.client.host为限流键在窗口内裁剪过期时间戳并计数。它演示了限流的完整形态生产环境建议换用 Redis 等集中式存储以支持多实例部署。api-design-checklist.md 的 Rate Limiting 检查项包括按端点/用户定义限额、返回限流头、超限返回 429、提供Retry-After。七、认证与授权Authorization: Bearer eyJhbGciOiJIUzI1NiIs... 401 Unauthorized - Missing/invalid token 403 Forbidden - Valid token, insufficient permissionsX-API-Key: your-api-key-here两条核心区分原则401 Unauthorized认证缺失或令牌无效你是谁403 Forbidden令牌有效但权限不足你能干什么。两种常见机制Bearer TokenJWT 等承载身份与声明与 API Key常用于服务间调用/第三方集成通过X-API-Key头传递。api-design-checklist.md 的检查项要求在所有端点实施授权检查、正确区分 401/403、并处理令牌过期。八、统一错误响应格式8.1 错误响应结构所有错误返回一致的 JSON 结构客户端才能可靠解析{ error: { code: VALIDATION_ERROR, message: Request validation failed, details: [ { field: email, message: Invalid email format, value: not-an-email } ], timestamp: 2025-10-16T12:00:00Z, path: /api/users } }字段设计要点code机器可读的错误码便于客户端程序化处理message人类可读的概括details字段级错误明细含字段名、原因、错误值timestamp/path便于定位与排查。模板通过 Pydantic 模型与全局异常处理器把这一格式固化为统一出口ErrorDetailfield/message/code与ErrorResponseerror/message/details并在http_exception_handler中把任何HTTPException统一转换成该 JSON 形态见 rest-api-template.py。404 场景在get_user中以detail{message: User not found, details: {id: user_id}}演示了带明细的错误构造见 rest-api-template.py。8.2 状态码选用指南上文 2.6 节的状态码表就是错误语义的骨架。补充两点409 Conflict适用于状态冲突如注册重复邮箱422专用于字段/业务校验失败。这两者与 400语法错误要区分开。九、缓存策略9.1 缓存头# Client caching Cache-Control: public, max-age3600 # No caching Cache-Control: no-cache, no-store, must-revalidate # Conditional requests ETag: 33a64df551425fcc55e4d42a148795d9f25f89d4 If-None-Match: 33a64df551425fcc55e4d42a148795d9f25f89d4 → 304 Not ModifiedCache-Control声明可缓存性与有效期ETag资源内容的指纹客户端带If-None-Match发起条件请求服务端比对未变化时返回304 Not Modified无响应体显著节省带宽。注意区分两类缓存客户端/CDN 缓存上述头与服务端缓存如对高频只读查询做内存/Redis 缓存。api-design-checklist.md 的 Performance 检查项同时覆盖缓存策略定义与缓存头正确设置。十、批量操作当单次请求需要操作多条记录时提供专用批量端点避免客户端发 N 次请求POST /api/users/batch { items: [ {name: User1, email: user1example.com}, {name: User2, email: user2example.com} ] } Response: { results: [ {id: 1, status: created}, {id: null, status: failed, error: Email already exists} ] }批量响应必须逐条报告成功/失败而不是整体成功或整体失败以便客户端精确定位失败项并重试。十一、幂等性Idempotency对容易因重试而重复执行的写操作典型如创建订单引入幂等键POST /api/orders Idempotency-Key: unique-key-123 If duplicate request: → 200 OK (return cached response)客户端为一次业务操作生成唯一键服务端收到重复键时直接返回首次处理的结果通常缓存该响应从而在网络重试、客户端重发等场景下保证业务结果不重复。POST默认非幂等 幂等键组合是支付、下单等场景的标准实践PUT/DELETE 本身就幂等通常无需幂等键。十二、CORS 配置跨域访问是浏览器端调用的必答题。模板给出了 FastAPI 的 CORS 中间件配置并附生产注意事项from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins[https://example.com], allow_credentialsTrue, allow_methods[*], allow_headers[*], )rest-api-template.py 中提供了更保守的默认版allow_origins[*]且allow_credentialsFalse并明确注释了生产化要求——使用具体来源列表如需携带 Cookie/认证头则开启allow_credentialsTrue但必须收紧allow_origins通配符*与凭据不能同时安全使用。同一文件还启用了TrustedHostMiddleware以防 HTTP Host 头攻击见 rest-api-template.py。十三、用 OpenAPI 驱动文档FastAPI 从类型注解自动生成 OpenAPI/Swagger 文档让文档与实现永不脱节from fastapi import FastAPI app FastAPI( titleMy API, descriptionAPI for managing users, version1.0.0, docs_url/docs, redoc_url/redoc ) app.get( /api/users/{user_id}, summaryGet user by ID, response_descriptionUser details, tags[Users] ) async def get_user( user_id: str Path(..., descriptionThe user ID) ): Retrieve user by ID. Returns full user profile including: - Basic information - Contact details - Account status pass文档化实践包括summary/response_description描述端点意图tags分组Path(..., description...)描述路径参数docstring 说明响应内容。模板中app FastAPI(titleAPI Template, version1.0.0, docs_url/api/docs)与各端点的tags[Users]正是这套实践见 rest-api-template.py。api-design-checklist.md 的 Documentation 检查项要求生成 OpenAPI/Swagger 规范、所有端点有文档、提供请求/响应示例、文档化错误响应与认证流程。十四、健康与监控端点运维可观测性的最低要求是健康检查app.get(/health) async def health_check(): return { status: healthy, version: 1.0.0, timestamp: datetime.now().isoformat() } app.get(/health/detailed) async def detailed_health(): return { status: healthy, checks: { database: await check_database(), redis: await check_redis(), external_api: await check_external_api() } }设计约定/health用于负载均衡/编排系统的存活探测轻量、只报整体状态与版本时间戳/health/detailed面向人工排查逐项报告数据库、Redis、外部 API 等依赖的连通性。api-design-checklist.md 的 Monitoring 检查项也把健康检查端点可用列为必需。十五、把这些规范落地为一次设计评审原文档的规范与其配套清单形成了可执行的评审流程建议在设计或评审 API 时按以下次序过一遍资源设计名词复数、集合命名一致、层级 ≤ 2、CRUD 与 HTTP 方法正确映射HTTP 语义GET 安全幂等、POST 创建返回 201、PUT 整体替换、PATCH 部分更新、DELETE 返回 204状态码严格按 2.6 节表格选用尤其区分 400/401/403/404/409/422/429分页与过滤集合端点全部分页、明确默认值与上限、携带分页元数据选 offset 或 cursor 其一版本化选定策略推荐 URL 版本化并书面化弃用政策错误格式统一错误结构、字段级明细、错误码、时间戳认证授权定义认证方式、全端点授权检查、正确区分 401/403限流定义配额、返回限流头、429 Retry-After文档与测试OpenAPI 自动生成、错误场景与边界用例覆盖安全与性能输入校验、SQL 注入/XSS 防护、CORS 收紧、HTTPS、查询优化与 N1 预防、缓存与监控就绪。以上每一条都可以在 api-design-checklist.md 中找到对应的勾选项该清单还额外覆盖 GraphQL 专用检查项Schema 优先、查询深度/复杂度限制、DataLoader 防 N1、Relay 分页、持久化查询等并可用 rest-api-template.py 作为骨架快速搭建符合规范的 FastAPI 服务——在仓库中执行uvicorn运行该模板见文件尾部入口 rest-api-template.py即可本地验证本文所述的分页、过滤、错误处理与文档生成行为。赞分享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点击查看免费下载相关推荐MaterialColorsApp与主流设计工具集成Figma、Sketch、Adobe XD工作流MaterialColorsApp与主流设计工具集成Figma、Sketch、Adobe XD工作流 MaterialColorsApp是一款便捷的Mac应用agentic-awesome-skills 实战基于 FastAPI 模板构建生产级 Python REST API 的完整指南agentic awesome skills 实战基于 FastAPI 模板构建生产级 Python REST API 的完整指南 导读 本文以 agentiAI 技能AI 插件人工智能agentic-awesome-skills 之 API 设计原则实战手册REST 与 GraphQL 的工程化落地指南agentic awesome skills 之 API 设计原则实战手册REST 与 GraphQL 的工程化落地指南 本指南以 implementatioAI 技能AI 插件人工智能上一篇探索未来3D打印新境界Bambu Studio下一篇Enformer深度学习模型终极指南从原理到实战的完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考