GitHub Copilot都惊呆了！这套API设计原则让我的代码优雅十倍🚀

核心功能

这个Skill不是一个空洞的理论集，而是一套涵盖了现代API开发两大主流范式（REST和GraphQL）的完整实战手册。它能帮你掌握以下核心要点：

• RESTful设计精髓：学习如何以资源为中心进行架构，而不是过程。正确使用HTTP动词（GET, POST, PUT, PATCH, DELETE），建立清晰、可预测的URL结构，并采用一致的命名规范。告别`/getUserById`这种充满“过程味”的接口吧！
• GraphQL设计哲学：深入理解Schema优先的开发模式。通过定义类型（Types）、查询（Queries）、变更（Mutations）和订阅（Subscriptions），让前端能够精确获取所需数据，彻底解决REST中常见的“过度获取”和“获取不足”问题。
• 灵活的API版本策略：无论是通过URL路径（`/v1/users`）、请求头还是查询参数进行版本控制，这个Skill都为你提供了清晰的示例和优缺点分析，帮助你在项目初期就做出明智决策，避免未来的重构地狱。
• 标准化的分页与过滤：面对海量数据，如何设计高效的分页和过滤机制？这里提供了基于Pydantic的FastAPI代码范例，教你如何构建健壮、易于扩展的分页响应模型和过滤参数。
• 优雅的错误处理：向混乱的错误码和模糊的错误信息说再见！学习如何设计统一、信息丰富的错误响应结构，让API的调用方能够清晰地知道问题出在哪里。
• 高级设计模式：探索HATEOAS（超媒体作为应用状态引擎）如何让你的REST API变得更具探索性，以及DataLoader在GraphQL中如何巧妙解决N+1查询问题，显著提升性能。

适用平台

这个Skill简直是为现代AI辅助编程时代量身定做的！它完美适配所有主流的AI编程助手，包括但不限于：Cursor, GitHub Copilot, Claude Code, OpenAI Codex, Gemini Code Assist, 文心快码, 腾讯云CodeBuddy, 以及华为云CodeArts。

它并非要取代这些强大的AI工具，而是作为它们的“最强外挂”。当你需要AI生成API相关代码时，可以先将这些设计原则喂给AI，它能显著提升AI对上下文的理解能力，确保生成的代码不仅能跑，而且漂亮、规范，符合团队标准。这才是真正的人机协作！

实操代码示例

光说不练假把式，来看看具体的代码实践。这些模式可以直接应用到你的项目中。

REST API：资源集合设计模式

感受一下“以资源为中心”和“以动作为中心”的巨大差异：

# 推荐：面向资源的端点设计 (Good)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  # 获取某个用户的所有订单# 应避免：面向动作的端点设计 (Bad)POST   /api/createUserPOST   /api/getUserByIdPOST   /api/deleteUser

GraphQL：Schema优先设计

一个设计良好的GraphQL Schema本身就是一份完美的文档：

# schema.graphql# 清晰的类型定义type User {  id: ID!  email: String!  name: String!  createdAt: DateTime!  # 关联关系  orders(first: Int = 20, after: String): OrderConnection!}# 用于变更操作的输入类型input CreateUserInput {  email: String!  name: String!  password: String!}# 变更操作的返回载荷，包含数据和可能的错误type CreateUserPayload {  user: User  errors: [Error!]}# 统一的错误类型type Error {  field: String  message: String!}# 根变更类型type Mutation {