Communitygithub.com

API设计原则

掌握REST和GraphQL API的设计原则,构建直观、可扩展且易于维护的API,令开发者满意。适用于设计新API、审查API规范或建立API设计标准。

API设计原则 是什么?

这项技能旨在帮助开发者掌握REST和GraphQL API的设计原则,以构建直观、可扩展且易于维护的API,并确保其经得起时间考验。它详细涵盖了从核心概念到具体模式的最佳实践,支持设计新API、重构现有API、为团队建立设计标准以及审查API规范等多种场景。技能内容以FastAPI和Ariadne(Python)为例,展示了资源导向架构、分页过滤、错误处理、HATEOAS、GraphQL Schema与DataLoader等关键实现模式。此外,还提供了常见陷阱与丰富的参考资源(如模板、清单、脚本),帮助开发者避免常见错误并提升API质量。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/api/api-design-principles-algusaem-algusaem-portfolio

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

API设计原则 是做什么的?

掌握REST和GraphQL API的设计原则,构建直观、可扩展且易于维护的API,令开发者满意并经得起时间考验。

何时使用此技能

  • 设计新的REST或GraphQL API时
  • 重构现有API以提升可用性
  • 为团队建立API设计标准
  • 在实施前审查API规范
  • 在API范式之间迁移(如从REST到GraphQL等)
  • 创建开发者友好的API文档
  • 针对特定用例(移动端、第三方集成)优化API

核心概念

1. RESTful设计原则

面向资源架构

  • 资源是名词(用户、订单、产品),而不是动词
  • 使用HTTP方法表示动作(GET, POST, PUT, PATCH, DELETE)
  • URL表示资源层级结构
  • 一致的命名约定

HTTP方法语义:

  • GET:检索资源(幂等、安全)
  • POST:创建新资源
  • PUT:替换整个资源(幂等)
  • PATCH:部分更新资源
  • DELETE:删除资源(幂等)

2. GraphQL设计原则

Schema优先开发

  • 类型定义你的领域模型
  • 查询(Query)用于读取数据
  • 变更(Mutation)用于修改数据
  • 订阅(Subscription)用于实时更新

查询结构:

  • 客户端精确请求所需内容
  • 单个端点,多种操作
  • 强类型schema
  • 内建自省机制

3. API版本化策略

URL版本化:

/api/v1/users
/api/v2/users

Header版本化:

Accept: application/vnd.api+json; version=1

查询参数版本化:

/api/users?version=1

REST API设计模式

模式1:资源集合设计

# 好:面向资源的端点
GET    /api/users              # 列出用户(带分页)
POST   /api/users              # 创建用户
GET    /api/users/{id}         # 获取特定用户
PUT    /api/users/{id}         # 替换用户
PATCH  /api/users/{id}         # 更新用户字段
DELETE /api/users/{id}         # 删除用户

# 嵌套资源
GET    /api/users/{id}/orders  # 获取用户订单
POST   /api/users/{id}/orders  # 为用户创建订单

# 差:面向动作的端点(避免使用)
POST   /api/createUser
POST   /api/getUserById
POST   /api/deleteUser

模式2:分页与过滤

from typing import List, Optional
from pydantic import BaseModel, Field

class PaginationParams(BaseModel):
    page: int = Field(1, ge=1, description="页码")
    page_size: int = Field(20, ge=1, le=100, description="每页条目数")

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端点示例
from fastapi import FastAPI, Query, Depends

app = FastAPI()

@app.get("/api/users", response_model=PaginatedResponse)
async def list_users(
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=100),
    status: Optional[str] = Query(None),
    search: Optional[str] = Query(None)
):
    # 应用过滤
    query = build_query(status=status, search=search)

    # 计算总数
    total = await count_users(query)

    # 获取当前页
    offset = (page - 1) * page_size
    users = await fetch_users(query, limit=page_size, offset=offset)

    return PaginatedResponse(
        items=users,
        total=total,
        page=page,
        page_size=page_size,
        pages=(total + page_size - 1) // page_size
    )

模式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

# 一致的错误响应
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_code=status.HTTP_404_NOT_FOUND,
        detail={
            "error": "NotFound",
            "message": f"{resource} 未找到",
            "details": {"id": id}
        }
    )

def raise_validation_error(errors: List[ValidationErrorDetail]):
    raise HTTPException(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        detail={
            "error": "ValidationError",
            "message": "请求验证失败",
            "details": {"errors": [e.dict() for e in errors]}
        }
    )

# 示例用法
@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

模式4:HATEOAS(超媒体作为应用状态引擎)

class UserResponse(BaseModel):
    id: str
    name: str
    email: str
    _links: dict

    @classmethod
    def from_user(cls, user: User, base_url: str):
        return cls(
            id=user.id,
            name=user.name,
            email=user.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设计模式

模式1:Schema设计

# schema.graphql

# 清晰的类型定义
type User {
  id: ID!
  email: String!
  name: String!
  createdAt: DateTime!

  # 关系
  orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!

  profile: UserProfile
}

type Order {
  id: ID!
  status: OrderStatus!
  total: Money!
  items: [OrderItem!]!
  createdAt: DateTime!

  # 反向引用
  user: User!
}

# 分页模式(Relay风格)
type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type OrderEdge {
  node: Order!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# 枚举用于类型安全
enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

# 自定义标量
scalar DateTime
scalar Money

# 查询根节点
type Query {
  user(id: ID!): User
  users(first: Int = 20, after: String, search: String): UserConnection!

  order(id: ID!): Order
}

# 变更根节点
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!

  createOrder(input: CreateOrderInput!): CreateOrderPayload!
}

# 变更的输入类型
input CreateUserInput {
  email: String!
  name: String!
  password: String!
}

# 变更的载荷类型
type CreateUserPayload {
  user: User
  errors: [Error!]
}

type Error {
  field: String
  message: String!
}

模式2:解析器设计

from 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]:
    """按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:
    """解析分页的用户列表。"""
    # 解码游标
    offset = decode_cursor(after) if after else 0

    # 获取用户
    users = await fetch_users(
        limit=first + 1,  # 多取一条以检查hasNextPage
        offset=offset,
        search=search
    )

    # 分页
    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(search=search)
    }

@user_type.field("orders")
async def resolve_user_orders(user: dict, info, first: int = 20) -> dict:
    """解析用户订单(使用DataLoader防止N+1问题)。"""
    # 使用DataLoader批量请求
    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:
    """创建新用户。"""
    try:
        # 验证输入
        validate_user_input(input)

        # 创建用户
        user = await create_user(
            email=input["email"],
            name=input["name"],
            password=hash_password(input["password"])
        )

        return {
            "user": user,
            "errors": []
        }
    except ValidationError as e:
        return {
            "user": None,
            "errors": [{"field": e.field, "message": e.message}]
        }

模式3:DataLoader(N+1问题预防)

from aiodataloader import DataLoader
from typing import List, Optional

class UserLoader(DataLoader):
    """按ID批量加载用户。"""

    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
        """在单个查询中加载多个用户。"""
        users = await fetch_users_by_ids(user_ids)

        # 将结果映射回输入顺序
        user_map = {user["id"]: user for user in users}
        return [user_map.get(user_id) for user_id in user_ids]

class OrdersByUserLoader(DataLoader):
    """按用户ID批量加载订单。"""

    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
        """在单个查询中加载多个用户的订单。"""
        orders = await fetch_orders_by_user_ids(user_ids)

        # 按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 [orders_by_user.get(user_id, []) for user_id in user_ids]

# 上下文设置
def create_context():
    return {
        "loaders": {
            "user": UserLoader(),
            "orders_by_user": OrdersByUserLoader()
        }
    }

最佳实践

REST API

  1. 一致命名:集合使用复数名词(/users, 而不是 /user)
  2. 无状态:每个请求包含所有必要信息
  3. 正确使用HTTP状态码:2xx表示成功,4xx表示客户端错误,5xx表示服务器错误
  4. 版本化你的API:从第一天起就规划好破坏性变更
  5. 分页:大型集合始终分页
  6. 速率限制:通过速率限制保护你的API
  7. 文档:使用OpenAPI/Swagger提供交互式文档

GraphQL API

  1. Schema优先:先设计schema,再编写解析器
  2. 避免N+1:使用DataLoader高效获取数据
  3. 输入验证:在schema和解析器层面进行验证
  4. 错误处理:在变更载荷中返回结构化错误
  5. 分页:使用基于游标的分页(Relay规范)
  6. 弃用:使用 @deprecated 指令进行渐进式迁移
  7. 监控:跟踪查询复杂度和执行时间

常见陷阱

  • 过度获取/不足获取(REST):在GraphQL中已解决,但需要DataLoader
  • 破坏性变更:对API进行版本化或使用弃用策略
  • 不一致的错误格式:标准化错误响应
  • 缺少速率限制:没有限制的API容易受到滥用
  • 文档不足:未文档化的API会令开发者沮丧
  • 忽略HTTP语义:对幂等操作使用POST会打破预期
  • 紧耦合:API结构不应镜像数据库schema

资源

  • references/rest-best-practices.md:全面的REST API设计指南
  • references/graphql-schema-design.md:GraphQL schema模式与反模式
  • references/api-versioning-strategies.md:版本化方法与迁移路径
  • assets/rest-api-template.py:FastAPI REST API模板
  • assets/graphql-schema-template.graphql:完整的GraphQL schema示例
  • assets/api-design-checklist.md:实施前审查清单
  • scripts/openapi-generator.py:从代码生成OpenAPI规范

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

相关技能