agentic-awesome-skills 之 API 设计原则实战手册：REST 与 GraphQL 的工程化落地指南

agentic-awesome-skills 之 API 设计原则实战手册REST 与 GraphQL 的工程化落地指南【免费下载链接】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,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills本指南以 implementation-playbook.md 为核心骨架系统讲解资源导向的 REST 架构、Schema-First 的 GraphQL 设计、三种主流 API 版本化策略以及分页过滤、错误处理、HATEOAS、DataLoader 防 N1 等可直接落地的设计模式。读完本文你将能够在自己的项目中直接复用文中的 FastAPI 分页/错误处理代码、Relay 风格 GraphQL Schema 与 Resolver 模板并借助仓库自带的实现清单与检查表在编码前完成 API 契约评审。在 agentic-awesome-skills 仓库中该能力以可加载的技能Skill形式存在技能入口 SKILL.md 定义了何时使用 / 何时不使用 / 操作流程而本手册则是其引用的详细实现模式库同时存在于plugins/agentic-awesome-skills与plugins/agentic-awesome-skills-claude两个插件发行版中结构完全一致可直接对照查阅。核心概念RESTful 设计原则资源导向架构Resource-Oriented ArchitectureREST 的核心是把系统能力建模为资源而非动作。四个要点资源是名词users、orders、products不是动词getUser、createOrder用 HTTP 方法表达动作GET、POST、PUT、PATCH、DELETEURL 表达资源层级关系如/api/users/{id}/orders命名保持一致同一资源在所有端点中的命名不得摇摆。HTTP 方法语义方法语义幂等性安全性GET检索资源幂等安全POST创建新资源非幂等非安全PUT整体替换资源幂等非安全PATCH部分更新资源字段非幂等非安全DELETE移除资源幂等非安全幂等Idempotent意味着同一请求重复执行多次结果一致安全Safe意味着不改变服务器状态。破坏 HTTP 语义例如用 POST 做幂等操作、用 GET 产生副作用会破坏调用方的预期是手册常见陷阱中明确点名的错误。核心概念GraphQL 设计原则Schema-First 开发GraphQL 的起点不是代码而是类型定义类型Types定义领域模型是客户端与服务端的唯一契约Query用于读取数据Mutation用于修改数据Subscription用于实时更新推送。查询结构特征客户端按需取数只请求真正需要的字段天然解决 REST 的 over-fetching / under-fetching单端点多操作所有操作都通过同一个 endpoint通常是/graphql完成强类型 Schema字段与参数在编译/解析期即可校验内建内省Introspection客户端工具可自动发现 Schema 结构。API 版本化策略手册给出三种主流版本化方案并说明取舍# 1. URL 版本化最直观推荐 /api/v1/users /api/v2/users # 2. Header 版本化URL 干净但不易见、难测试 Accept: application/vnd.apijson; version1 # 3. Query 参数版本化易测试但参数可能被遗忘 /api/users?version1配套参考 rest-best-practices.md 进一步总结URL 版本化清晰、易路由但同一资源会存在多个 URLHeader 版本化URL 干净但可发现性差Query 参数版本化易测试但可选参数易被忽略。无论选择哪种版本化策略都应从第一天起就纳入规划Best Practice 第 4 条为未来的破坏性变更预留空间。REST API 设计模式模式 1资源集合设计# Good: Resource-oriented endpoints GET /api/users # List users (with pagination) POST /api/users # Create user GET /api/users/{id} # Get specific user PUT /api/users/{id} # Replace user PATCH /api/users/{id} # Update user fields DELETE /api/users/{id} # Delete user # Nested resources GET /api/users/{id}/orders # Get users orders POST /api/users/{id}/orders # Create order for user # Bad: Action-oriented endpoints (avoid) POST /api/createUser POST /api/getUserById POST /api/deleteUser关于嵌套资源的深度参考文档给出明确指引优先浅层嵌套避免超过两层。例如GET /api/users/{id}/orders合理但GET /api/users/{id}/orders/{orderId}/items/{itemId}/reviews应重构为GET /api/order-items/{id}/reviews。模式 2分页与过滤手册给出基于 Pydantic 的完整分页/过滤参数模型以及 FastAPI 端点示例from typing import List, Optional from pydantic import BaseModel, Field class PaginationParams(BaseModel): page: int Field(1, ge1, descriptionPage number) page_size: int Field(20, ge1, le100, descriptionItems per page) class FilterParams(BaseModel): status: Optional[str] None created_after: Optional[str] None search: Optional[str] None class PaginatedResponse(BaseModel): items: List[dict] total: int page: int page_size: int pages: int property def has_next(self) - bool: return self.page self.pages property def has_prev(self) - bool: return self.page 1 # FastAPI endpoint example from fastapi import FastAPI, Query, Depends app FastAPI() app.get(/api/users, response_modelPaginatedResponse) async def list_users( page: int Query(1, ge1), page_size: int Query(20, ge1, le100), status: Optional[str] Query(None), search: Optional[str] Query(None) ): # Apply filters query build_query(statusstatus, searchsearch) # Count total total await count_users(query) # Fetch page offset (page - 1) * page_size users await fetch_users(query, limitpage_size, offsetoffset) return PaginatedResponse( itemsusers, totaltotal, pagepage, page_sizepage_size, pages(total page_size - 1) // page_size )需要注意的参数约束page最小为 1page_size默认 20、下限 1、上限 100——所有集合端点都必须分页、必须定义默认页大小、必须强制执行最大页大小正是 api-design-checklist.md 中的硬性检查项。分页并不只有 offset 一种形态。参考文档补充了三种方案对比Offset 分页GET /api/users?page2page_size20响应携带items/total/page/page_size/pages实现简单Cursor 分页适合大数据集GET /api/users?limit20cursoreyJpZCI6MTIzfQ响应携带items/next_cursor/has_more数据插入或删除时游标稳定、不会出现跳页Link Header 分页纯 REST 风格通过 HTTP 响应头Link: ...?page3; relnext, ...?page1; relfirst, ...?page8; rellast表达翻页关系。过滤、排序与搜索统一走 Query 参数?statusactive过滤、?sortcreated_at/?sort-created_at升序/降序、?sortname,created_at多字段、?searchjohn全文搜索、?fieldsid,name,email稀疏字段集只返回指定字段。模式 3错误处理与状态码手册要求所有错误响应使用统一结构并给出模型与辅助函数from fastapi import HTTPException, status from pydantic import BaseModel class ErrorResponse(BaseModel): error: str message: str details: Optional[dict] None timestamp: str path: str class ValidationErrorDetail(BaseModel): field: str message: str value: Any # Consistent error responses STATUS_CODES { success: 200, created: 201, no_content: 204, bad_request: 400, unauthorized: 401, forbidden: 403, not_found: 404, conflict: 409, unprocessable: 422, internal_error: 500 } def raise_not_found(resource: str, id: str): raise HTTPException( status_codestatus.HTTP_404_NOT_FOUND, detail{ error: NotFound, message: f{resource} not found, details: {id: id} } ) def raise_validation_error(errors: List[ValidationErrorDetail]): raise HTTPException( status_codestatus.HTTP_422_UNPROCESSABLE_ENTITY, detail{ error: ValidationError, message: Request validation failed, details: {errors: [e.dict() for e in errors]} } ) # Example usage app.get(/api/users/{user_id}) async def get_user(user_id: str): user await fetch_user(user_id) if not user: raise_not_found(User, user_id) return user状态码选用的完整指导见 rest-best-practices.md200 OKGET/PATCH/PUT 成功201 CreatedPOST 创建成功204 No ContentDELETE 成功400 Bad Request请求格式错误401 Unauthorized未认证/凭据缺失403 Forbidden已认证但权限不足401 与 403 的区分是高频考点404 Not Found资源不存在409 Conflict状态冲突如邮箱重复422 Unprocessable Entity字段校验失败429 Too Many Requests触发限流500 Internal Server Error服务器内部错误503 Service Unavailable临时不可用。错误响应体建议采用如下统一 JSON 结构含code、字段级details、timestamp便于客户端程序化处理{ 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 } }仓库中 rest-api-template.py 提供了生产级落地版本通过全局app.exception_handler(HTTPException)把任意 HTTPException 统一转换为ErrorResponse包含error、message、可选的字段级details从而保证所有端点错误格式一致。模式 4HATEOAS超媒体作为应用状态引擎HATEOAS 让 API 响应自描述——客户端根据_links发现下一步可执行的操作无需硬编码 URLclass UserResponse(BaseModel): id: str name: str email: str _links: dict classmethod def from_user(cls, user: User, base_url: str): return cls( iduser.id, nameuser.name, emailuser.email, _links{ self: {href: f{base_url}/api/users/{user.id}}, orders: {href: f{base_url}/api/users/{user.id}/orders}, update: { href: f{base_url}/api/users/{user.id}, method: PATCH }, delete: { href: f{base_url}/api/users/{user.id}, method: DELETE } } )GraphQL 设计模式模式 1Schema 设计手册给出的完整 Schema 体现了几个关键决策非空类型!表达必填约束、关系字段内置分页参数、枚举保证类型安全、自定义标量承载领域语义、Mutation 统一使用 Input/Payload 模式# schema.graphql # Clear type definitions type User { id: ID! email: String! name: String! createdAt: DateTime! # Relationships orders(first: Int 20, after: String, status: OrderStatus): OrderConnection! profile: UserProfile } type Order { id: ID! status: OrderStatus! total: Money! items: [OrderItem!]! createdAt: DateTime! # Back-reference user: User! } # Pagination pattern (Relay-style) type OrderConnection { edges: [OrderEdge!]! pageInfo: PageInfo! totalCount: Int! } type OrderEdge { node: Order! cursor: String! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } # Enums for type safety enum OrderStatus { PENDING CONFIRMED SHIPPED DELIVERED CANCELLED } # Custom scalars scalar DateTime scalar Money # Query root type Query { user(id: ID!): User users(first: Int 20, after: String, search: String): UserConnection! order(id: ID!): Order } # Mutation root type Mutation { createUser(input: CreateUserInput!): CreateUserPayload! updateUser(input: UpdateUserInput!): UpdateUserPayload! deleteUser(id: ID!): DeleteUserPayload! createOrder(input: CreateOrderInput!): CreateOrderPayload! } # Input types for mutations input CreateUserInput { email: String! name: String! password: String! } # Payload types for mutations type CreateUserPayload { user: User errors: [Error!] } type Error { field: String message: String! }参考文档 graphql-schema-design.md 对这些模式做了更深一层的展开非空与可空的设计决策——从可空开始确有保证再改非空type User { id: ID! # Always required email: String! # Required phone: String # Optional (nullable) posts: [Post!]! # Non-null array of non-null posts tags: [String!] # Nullable array of non-null strings }接口Interface处理多态配合全局node(id: ID!)实现通用节点查询interface Node { id: ID! createdAt: DateTime! } type User implements Node { id: ID! createdAt: DateTime! email: String! } type Post implements Node { id: ID! createdAt: DateTime! title: String! } type Query { node(id: ID!): Node }联合类型Union承载异构结果如跨类型的搜索union SearchResult User | Post | Comment type Query { search(query: String!): [SearchResult!]! } # Query example { search(query: graphql) { ... on User { name email } ... on Post { title content } ... on Comment { text author { name } } } }输入类型Input Types所有 Mutation 必须使用 input 类型接收参数嵌套输入用profileInput: ProfileInput表达组合结构更新类输入中所有字段均可选UpdateUserInput中email、name均不带!。模块化 Schema通过extend type Query/extend type Mutation按领域拆分成user.graphql、post.graphql等多个文件每个领域自治避免单个巨型 Schema 文件。模式 2Resolver 设计手册基于 Ariadne 展示了 Query/Mutation/ObjectType 三种 resolver 的写法其中分页 resolver 有一个实用技巧——多取一条记录判断 hasNextPagefrom typing import Optional, List from ariadne import QueryType, MutationType, ObjectType from dataclasses import dataclass query QueryType() mutation MutationType() user_type ObjectType(User) query.field(user) async def resolve_user(obj, info, id: str) - Optional[dict]: Resolve single user by ID. return await fetch_user_by_id(id) query.field(users) async def resolve_users( obj, info, first: int 20, after: Optional[str] None, search: Optional[str] None ) - dict: Resolve paginated user list. # Decode cursor offset decode_cursor(after) if after else 0 # Fetch users users await fetch_users( limitfirst 1, # Fetch one extra to check hasNextPage offsetoffset, searchsearch ) # Pagination has_next len(users) first if has_next: users users[:first] edges [ { node: user, cursor: encode_cursor(offset i) } for i, user in enumerate(users) ] return { edges: edges, pageInfo: { hasNextPage: has_next, hasPreviousPage: offset 0, startCursor: edges[0][cursor] if edges else None, endCursor: edges[-1][cursor] if edges else None }, totalCount: await count_users(searchsearch) } user_type.field(orders) async def resolve_user_orders(user: dict, info, first: int 20) - dict: Resolve users orders (N1 prevention with DataLoader). # Use DataLoader to batch requests loader info.context[loaders][orders_by_user] orders await loader.load(user[id]) return paginate_orders(orders, first) mutation.field(createUser) async def resolve_create_user(obj, info, input: dict) - dict: Create new user. try: # Validate input validate_user_input(input) # Create user user await create_user( emailinput[email], nameinput[name], passwordhash_password(input[password]) ) return { user: user, errors: [] } except ValidationError as e: return { user: None, errors: [{field: e.field, message: e.message}] }注意 mutation resolver 的错误处理不抛异常而是在 payload 的errors数组中返回结构化错误——这是 GraphQL 错误处理的核心约定参考文档称之为 Errors in Payload 模式并建议给错误附加code: ErrorCode!枚举VALIDATION_ERROR / UNAUTHORIZED / NOT_FOUND / INTERNAL_ERROR。模式 3DataLoaderN1 问题预防N1 问题查询 N 个用户再逐个查其订单会产生 N1 次数据库查询。手册的解法是用 DataLoader 把多次单查合并为一次批量查询并按输入顺序回填结果顺序一致性是批量加载器的关键约束from aiodataloader import DataLoader from typing import List, Optional class UserLoader(DataLoader): Batch load users by ID. async def batch_load_fn(self, user_ids: List[str]) - List[Optional[dict]]: Load multiple users in single query. users await fetch_users_by_ids(user_ids) # Map results back to input order user_map {user[id]: user for user in users} return [user_map.get(user_id) for user_id in user_ids] class OrdersByUserLoader(DataLoader): Batch load orders by user ID. async def batch_load_fn(self, user_ids: List[str]) - List[List[dict]]: Load orders for multiple users in single query. orders await fetch_orders_by_user_ids(user_ids) # Group orders by user_id orders_by_user {} for order in orders: user_id order[user_id] if user_id not in orders_by_user: orders_by_user[user_id] [] orders_by_user[user_id].append(order) # Return in input order return [orders_by_user.get(user_id, []) for user_id in user_ids] # Context setup def create_context(): return { loaders: { user: UserLoader(), orders_by_user: OrdersByUserLoader() } }参考文档补充了该模式的通用写法resolver 通过info.context[loaders][post]取到 loader再调用loader.load_many(user[post_ids])完成批量加载PostLoader用{id: {$in: post_ids}}一次查询再以post_map.get(pid)保持顺序。最佳实践清单REST API 最佳实践命名一致集合用复数名词/users不是/user无状态每个请求自包含全部所需信息正确使用 HTTP 状态码2xx 成功、4xx 客户端错误、5xx 服务端错误尽早版本化从第一天起就为破坏性变更做规划分页大型集合必须分页限流用 rate limit 保护 API文档化用 OpenAPI/Swagger 提供交互式文档。参考文档把限流与文档化落实为可运行代码。限流需配合响应头与 429 状态码X-RateLimit-Limit: 1000、X-RateLimit-Remaining: 742、X-RateLimit-Reset: 1640000000被限流时返回429 Too Many Requests并带Retry-After: 3600滑动窗口实现如下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: [...]}文档化方面参考文档给出 FastAPI 的 OpenAPI 集成方式——在应用初始化时配置title、description、version、docs_url、redoc_url并用summary、response_description、tags与 docstring 让端点自文档化app FastAPI( titleMy API, descriptionAPI for managing users, version1.0.0, docs_url/docs, redoc_url/redoc )GraphQL API 最佳实践Schema First先设计 Schema再写 Resolver避免 N1用 DataLoader 高效取数输入校验在 Schema 与 Resolver 两个层面校验错误处理在 mutation payload 中返回结构化错误分页使用游标分页Relay 规范弃用用deprecated指令平滑迁移监控跟踪查询复杂度与执行时间。参考文档对第 2、5、6 条给出了更细的实现Relay 游标分页是推荐形态Query 同时支持first/after与last/before四个参数PageInfo返回hasNextPage/hasPreviousPage/startCursor/endCursor而 Offset 分页users(page: Int 1, pageSize: Int 20): UserList!只适合简单场景。弃用与 Schema 演进分三步走v1 只有name→ v2 新增可空字段email向后兼容→ v3 弃用name并新增firstName/lastName# v1 - Initial type User { name: String! } # v2 - Add optional field (backward compatible) type User { name: String! email: String } # v3 - Deprecate and add new field type User { name: String! deprecated(reason: Use firstName/lastName) firstName: String! lastName: String! email: String }复杂度防护深度限制校验器检查len(ancestors) max_depth即抛GraphQLError复杂度分析对列表字段按get_list_size_arg倍数累加防止客户端构造爆炸性查询。自定义指令用于权限声明如directive auth(requires: Role USER) on FIELD_DEFINITION配合enum Role在字段定义层面声明auth(requires: ADMIN)。**订阅Subscription**定义实时通道postAdded: Post!、postUpdated(postId: ID!): Post!、userStatusChanged(userId: ID!): UserStatus!。常见陷阱速查Over-fetching / Under-fetchingRESTGraphQL 可解决但需要 DataLoader 配合破坏性变更必须版本化或采用弃用策略错误格式不一致标准化错误响应缺少限流没有限制的 API 易被滥用攻击文档缺失未文档化的 API 让开发者沮丧忽略 HTTP 语义用 POST 做幂等操作破坏调用方预期紧耦合API 结构不应镜像数据库表结构。此外参考文档补充了几个工程级注意点缓存通过Cache-Controlpublic, max-age3600/no-cache, no-store, must-revalidate与条件请求ETagIf-None-Match→304 Not Modified实现批量操作可提供POST /api/users/batch端点逐项返回{id, status, error}结果数组幂等性用Idempotency-Key请求头实现——重复请求直接返回缓存的首次响应健康检查提供/healthstatus/version/timestamp与/health/detailed数据库、Redis、外部 API 分项探活两个端点。实现前评审清单api-design-checklist.md 提供了一份可直接用于评审的核对表覆盖编码前应确认的全部契约问题资源设计资源是名词而非动词、集合用复数、层级不超过两层、CRUD 正确映射 HTTP 方法HTTP 方法与状态码GET/POST/PUT/PATCH/DELETE 语义正确200/201/204/400/401/403/404/422/429/500 各就各位含 429 限流分页与过滤集合端点全部分页、默认页大小如 20、最大页大小如 100、分页元数据齐全、游标或 offset 方案已选定支持过滤、排序、搜索与稀疏字段集版本化策略已定义URL/Header/Query、所有端点含版本、弃用策略已文档化错误处理响应格式一致、含字段级错误、错误码、时间戳认证与授权认证方式Bearer/API Key已定、所有端点有鉴权、401 与 403 区分正确、令牌过期处理限流按端点/用户限流、响应头齐备、429 与 Retry-After 提供文档OpenAPI 规格已生成、请求/响应/错误示例齐全测试单元/集成/错误场景/边界/性能测试覆盖安全输入校验、SQL 注入与 XSS 防护、CORS 正确配置、强制 HTTPS、敏感数据不进 URL、响应不泄密性能查询优化、防 N1、缓存策略与缓存头监控日志、错误追踪、性能指标、健康检查端点、告警GraphQL 专项Schema-First、非空决策、接口/联合、自定义标量、查询深度与复杂度限制、DataLoader、mutation 的 input/payload/乐观更新/幂等、持久化查询、内省开关。清单条目与手册中的代码模式一一对应例如默认页大小 20、上限 100正是PaginationParams中page_size的Field(20, ge1, le100)字段级校验错误正是ValidationErrorDetail与raise_validation_error的实现目标。建议在编写任何端点前逐项勾选该清单。生产级 FastAPI 模板与使用方式仓库提供了一份可直接启动的生产级模板 rest-api-template.py它是本手册所有 REST 模式的汇总实现包含安全中间件TrustedHostMiddleware防 HTTP Host 头攻击生产环境应配置allowed_hosts[api.example.com]CORSMiddleware配置跨域生产环境应收敛allow_origins仅在需要 Cookie/认证头时开启allow_credentialsTruePydantic 模型UserStatus枚举、UserCreatepassword最小长度 8、UserUpdate全字段可选、User含created_at/updated_atConfigDict(from_attributesTrue)支持 ORM 映射统一分页PaginationParams与PaginatedResponse统一错误ErrorResponse 全局HTTPExceptionhandler完整 CRUDGET /api/users分页过滤、POST /api/users返回 201、GET/PATCH/DELETE /api/users/{user_id}Path参数描述、exclude_unsetTrue只更新传入字段、DELETE 返回 204。启动方式pip install fastapi uvicorn[standard] pydantic email-validator uvicorn rest-api-template:app --host 0.0.0.0 --port 8000然后访问/api/docs模板中配置为/api/docs查看交互式 OpenAPI 文档。该技能在仓库中的完整资源映射如下均为仓库根目录相对路径资源路径技能入口何时使用/流程SKILL.md本实现手册implementation-playbook.mdREST 参考文档rest-best-practices.mdGraphQL 参考文档graphql-schema-design.md实现前评审清单api-design-checklist.mdFastAPI 生产模板rest-api-template.py同一技能的完整副本同时存在于 plugins/agentic-awesome-skills/skills/api-design-principles 发行版中目录结构完全一致可按需对照。小结本文围绕api-design-principles技能的实现手册完整覆盖了资源导向 REST 架构、HTTP 方法语义、GraphQL Schema-First 查询结构、三种版本化策略、四个 REST 设计模式资源集合、分页过滤、错误处理、HATEOAS、三个 GraphQL 设计模式Schema、Resolver、DataLoader以及双范式最佳实践、常见陷阱、实现前评审清单与生产模板。实操建议设计阶段先用清单冻结契约编码阶段直接复用 FastAPI/DataLoader 模板发布后配合 OpenAPI 文档与健康检查端点持续迭代——这正是手册先定契约、再写实现、后做评审的完整闭环。【免费下载链接】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,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考