古法编程

Appearance

Everything Claude Code API Design Skill 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）场景设计的 REST API 设计规范与落地流程。它解决了接口命名混乱、状态码滥用、分页/过滤/错误响应不一致等常见问题，极大提升了生产级 API 的一致性、可维护性和开发效率。Skill 支持自动检测、建议与生成规范化 API 合约，适用于新建、评审和重构各类后端服务，兼容 TypeScript、Python、Go 等主流技术栈。

Everything Claude Code API Design Skill：REST 资源命名、状态码、分页、错误响应与速率限制规范 ​

在使用 Claude Code、Codex、Cursor 等 AI 编程助手开发后端接口时，API 设计规范往往是影响团队协作、系统扩展性和对外开放能力的关键因素。API Design Skill 正是为此而生，它将业界最佳实践（如 RESTful 资源命名、HTTP 状态码、分页、过滤、错误响应、速率限制、版本管理等）以可操作的 Skill 形式，深度集成进 AI 辅助开发流程。

相比传统“凭经验”或“抄模板”式的 API 设计，API Design Skill 提供了结构化、可复用、可自动化检测的标准方案，极大降低了接口设计的出错率和后期维护成本。无论你是初次接触 REST API，还是需要为已有项目补齐规范，这一 Skill 都能作为 Claude Code Agent 的“API 设计大脑”，贯穿接口全生命周期。

适用场景与触发时机 ​

API Design Skill 可在以下典型场景自动激活或手动调用：

  • 新建 API 端点时：AI 生成接口代码前，Skill 自动补全资源命名、路径结构、方法与状态码建议。
  • 接口评审与重构：对现有 API 合约进行一致性检查，发现并修复命名、状态码、响应格式等问题。
  • 实现分页、过滤、排序：Skill 自动给出 offset/cursor 分页、字段筛选、排序参数等标准实现方式。
  • 错误响应与速率限制：为接口生成统一的错误码、错误体结构和速率限制响应，避免自定义风格混乱。
  • API 版本管理：规划 URL/头部版本号、弃用流程和兼容策略，支持长期演进。
  • 对外开放/合作 API：Skill 输出适合文档化和合作伙伴对接的标准 API 合约。

提示：API Design Skill 可与 Claude Code 快速上手指南 中的 Agent、Skill、Hook 体系无缝集成，支持自动检测和批量修复。

Step by Step：在实际项目中用好 API Design Skill ​

1. 设计资源与 URL 路径结构 ​

Skill 会建议所有资源使用复数、kebab-case、小写命名，避免动词、单数和 snake_case。例如：

http
# 推荐
GET /api/v1/users
POST /api/v1/users
GET /api/v1/users/{id}
GET /api/v1/users/{id}/orders

# 反例
GET /api/v1/getUsers
GET /api/v1/user
GET /api/v1/team_members

Skill 会自动检测并纠正不规范的路径，确保接口风格统一。

2. 选择合适的 HTTP 方法与状态码 ​

API Design Skill 内置了标准的 HTTP 方法-状态码语义映射：

  • GET：200 OK（查询成功），404 Not Found（资源不存在）
  • POST：201 Created（创建成功，需 Location 头），400/422（参数错误）
  • PUT/PATCH：200/204（更新成功），400/422（校验失败）
  • DELETE：204 No Content（删除成功），404（未找到）

Skill 会阻止“所有请求都返回 200”或“用 500 表示所有错误”等反模式，并自动生成如下响应结构：

json
// 成功
{
  "data": { "id": "abc-123", "name": "Alice" }
}
// 错误
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address" }
    ]
  }
}

3. 实现分页、过滤与排序 ​

Skill 支持两种主流分页模式：

  • Offset 分页（适合小数据集、后台管理）：

    http
    GET /api/v1/users?page=2&per_page=20

  • Cursor 分页（适合大数据量、前台无限滚动）：

    http
    GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20

响应示例：

json
{
  "data": [...],
  "meta": {
    "total": 142,
    "page": 2,
    "per_page": 20,
    "total_pages": 8
  },
  "links": {
    "self": "...",
    "next": "...",
    "last": "..."
  }
}

Skill 还支持标准的过滤、排序、字段筛选参数：

http
GET /api/v1/orders?status=active&created_at[after]=2025-01-01&sort=-created_at
GET /api/v1/users?fields=id,name,email

4. 错误响应与速率限制标准化 ​

Skill 统一输出错误响应 envelope，包含 code/message/details，便于前端和第三方集成：

json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}

速率限制响应自动带上标准头部：

http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000000
Retry-After: 60

Skill 支持按 IP、用户、API Key 等多层级配置速率限制，并建议合理的分层限流策略。

5. 版本管理与演进 ​

Skill 推荐采用 URL 路径版本号（如 /api/v1/），并内置弃用流程（Sunset 头、410 Gone）。对非兼容性变更，Skill 会自动建议新版本并输出迁移建议。

6. 多语言实现模板 ​

Skill 可根据项目语言自动生成规范接口代码（如 TypeScript/Next.js、Python/DRF、Go），并集成参数校验与标准响应。例如：

typescript
import { z } from "zod";
import { NextRequest, NextResponse } from "next/server";

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
});

export async function POST(req: NextRequest) {
  const body = await req.json();
  const parsed = createUserSchema.safeParse(body);

  if (!parsed.success) {
    return NextResponse.json({
      error: {
        code: "validation_error",
        message: "Request validation failed",
        details: parsed.error.issues.map(i => ({
          field: i.path.join("."),
          message: i.message,
          code: i.code,
        })),
      },
    }, { status: 422 });
  }

  // ...创建用户逻辑

  return NextResponse.json(
    { data: user },
    {
      status: 201,
      headers: { Location: `/api/v1/users/${user.id}` },
    },
  );
}

Skill 也支持 Python（Django REST Framework）、Go（net/http）等主流后端，保证接口风格一致。

7. Skill Checklist 与自动化集成 ​

每次新建或修改 API，Skill 会输出一份 checklist，自动检测：

  • 路径命名是否规范
  • 方法与状态码是否匹配
  • 是否有分页、过滤、排序
  • 错误响应格式是否统一
  • 是否配置速率限制与鉴权
  • 文档（如 OpenAPI）是否同步

Skill 可与 Everything Claude Code Hooks 实战 联动，在 PreToolUse/PostToolUse 阶段自动插入检测与修复。

输出示例 ​

自动生成的接口代码片段（TypeScript/Next.js）：

typescript
export async function POST(req: NextRequest) {
  // ...参数校验
  if (!parsed.success) {
    return NextResponse.json({
      error: {
        code: "validation_error",
        message: "Request validation failed",
        details: [...],
      },
    }, { status: 422 });
  }
  // ...业务逻辑
  return NextResponse.json({ data: user }, { status: 201, headers: { Location: `/api/v1/users/${user.id}` } });
}

自动补全的 API 文档片段：

yaml
paths:
  /api/v1/users:
    post:
      summary: Create a new user
      responses:
        '201':
          description: Created
          headers:
            Location:
              description: URL of the created user
              schema:
                type: string
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

常见配套 Agent 与 Skill 协作 ​

  • 与 Code Reviewer Agent 配合：自动审查 API 合约是否符合规范，发现并修正不一致之处，详见 Everything Claude Code Code Reviewer Agent。
  • 与 Backend Patterns Skill 协同：结合 Node.js/Express/Next.js 等后端最佳实践，形成完整的 API 开发流水线，参见 Backend Patterns Skill。
  • 与 Verification Loop Skill 联动：在端到端测试与自动化验证中，确保接口设计规范被实际遵守，详见 Verification Loop Skill。

FAQ ​

Q: API Design Skill 能自动修复已有接口的不规范问题吗？
A: 可以。Skill 支持自动检测并输出重构建议，部分场景可直接生成修正版代码或 OpenAPI 文档。

Q: Skill 支持哪些主流后端技术栈？
A: Skill 内置 TypeScript（Next.js/Express）、Python（Django/DRF）、Go（net/http）等模板，其他语言可扩展。

Q: 如何与团队协作统一接口风格？
A: Skill 输出的 checklist、合约和文档可作为团队规范，配合 Agent 自动审查，确保多人协作时风格一致。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策