Resources 实施手册

# API 设计原则实施手册 本文件包含该技能引用的详细模式、检查清单和代码示例。 ## 核心概念 ### 1. RESTful 设计原则 **面向资源的架构** - 资源是名词（用户、订单、产品），而非动词 - 使用 HTTP 方法执行操作（GET, POST, PUT, PATCH, DELETE） - URL 代表资源层级 - 统一的命名约定 **HTTP 方法语义：** - `GET`: 获取资源（幂等，安全） - `POST`: 创建新资源 - `PUT`: 替换整个资源（幂等） - `PATCH`: 部分资源更新 - `DELETE`: 删除资源（幂等） ### 2. GraphQL 设计原则 **模式优先开发 (Schema-First)** - 类型定义领域模型 - 查询 (Query) 用于读取数据 - 变更 (Mutation) 用于修改数据 - 订阅 (Subscription) 用于实时更新 **查询结构：** - 客户端按需获取数据 - 单一端点，多种操作 - 强类型模式 - 内置自省功能 ### 3. API 版本控制策略 **URL 版本控制：** /api/v1/users /api/v2/users **Header 版本控制：** Accept: application/vnd.api+json; version=1 **查询参数版本控制：** /api/users?version=1 ## REST API 设计模式 ### 模式 1：资源集合设计 python # 推荐：面向资源的端点 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：分页与过滤 python 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: