Communitygithub.com

majiayu000/claude-skill-registry-data

精通 REST 與 GraphQL API 設計原則,建立直觀、可擴展且易於維護的 API,以取悅開發者。適用於設計新 API、審查 API 規格或制定 API 設計標準。

claude-skill-registry-data 是什麼?

這項技能提供了一套完整的 REST 與 GraphQL API 設計指南,專為開發者與 AI 代理(如 Claude Code)打造。它能協助你設計直觀、可擴展且易於維護的 API。技能內容涵蓋了 REST 資源導向架構、GraphQL 表單優先開發、API 版本管理策略,以及真實世界的最佳實踐。透過詳細的 Python 範例(例如使用 FastAPI)和 GraphQL 表單範例,你可以學習到如何處理分頁、錯誤訊息、HATEOAS、DataLoader 等核心模式。這項技能特別適用於設計新 API、重構既有 API、制定團隊標準或進行 API 審查,並能顯著減少常見陷阱,如過度/不足擷取、破壞性變更與不一致的錯誤格式。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/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 設計原則

表單優先開發

  • 類型定義你的領域模型
  • 查詢用於讀取資料
  • 變更用於修改資料
  • 訂閱用於即時更新

查詢結構:

  • 用戶端只請求他們需要的內容
  • 單一端點,多種操作
  • 強型別表單
  • 內建自省機制

3. API 版本管理策略

URL 版本管理:

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

標頭版本管理:

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.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)

        # 依使用者 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. 表單優先:在撰寫解析器前設計表單
  2. 避免 N+1:使用 DataLoader 進行高效資料擷取
  3. 輸入驗證:在表單和解析器兩個層級進行驗證
  4. 錯誤處理:在變更酬載中回傳結構化錯誤
  5. 分頁:使用基於游標的分頁(Relay 規範)
  6. 棄用:使用 @deprecated 指令進行漸進式遷移
  7. 監控:追蹤查詢複雜度和執行時間

常見陷阱

  • 過度擷取/不足擷取(REST):GraphQL 已解決,但需要使用 DataLoader
  • 破壞性變更:為 API 設定版本或使用棄用策略
  • 不一致的錯誤格式:標準化錯誤回應
  • 缺少速率限制:沒有限制的 API 容易受到濫用
  • 不佳的文件:未記錄的 API 會讓開發者感到沮喪
  • 忽略 HTTP 語意:對冪等操作使用 POST 會破壞預期
  • 緊密耦合:API 結構不應鏡像資料庫結構

資源

  • references/rest-best-practices.md:完整的 REST API 設計指南
  • references/graphql-schema-design.md:GraphQL 表單模式與反模式
  • references/api-versioning-strategies.md:版本管理方法與遷移路徑
  • assets/rest-api-template.py:FastAPI REST API 範本
  • assets/graphql-schema-template.graphql:完整的 GraphQL 表單範例
  • 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-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

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-data

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-data

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-data

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-data

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-data

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

majiayu000/claude-skill-registry-data

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-data

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

majiayu000/claude-skill-registry-data

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-data

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-data

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-data

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

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

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".

相關技能