零度AI
进阶16 分钟阅读

Claude Code API 设计最佳实践

学习如何设计高质量的 API，包括 RESTful、GraphQL、API 版本控制等

Claude CodeAPI 设计RESTfulGraphQL

API 设计原则

1. RESTful 架构风格

REST (Representational State Transfer) 是目前最流行的 API 架构风格。

REST 核心原则

  • 资源：万物皆资源，每个资源有唯一的 URI
  • 动词：使用 HTTP 方法表示操作
  • 状态：无状态通信，每次请求包含完整信息
  • 表示：通过 JSON/XML 表示资源状态

2. RESTful API 示例

javascript
// GET 获取资源
GET /api/posts
GET /api/posts/123

// POST 创建资源
POST /api/posts
{
  "title": "文章标题",
  "content": "文章内容"
}

// PUT 更新资源
PUT /api/posts/123
{
  "title": "新标题",
  "content": "新内容"
}

// DELETE 删除资源
DELETE /api/posts/123

API 设计最佳实践

1. 命名规范

资源命名

javascript
// 好的做法
GET /api/users
GET /api/products
GET /api/orders

// 避免
GET /api/getUsers
GET /api/retrieveProducts
GET /api/deleteOrder

复数 vs 单数

javascript
// 推荐：使用复数
GET /api/users
GET /api/users/123

// 避免
GET /api/user
GET /api/user/123

2. HTTP 方法

| 方法 | 操作 | 幂等性 | 安全性 | |------|------|--------|--------| | GET | 获取资源 | 是 | 是 | | POST | 创建资源 | 否 | 否 | | PUT | 更新资源 | 是 | 否 | | DELETE | 删除资源 | 是 | 否 | | PATCH | 部分更新 | 否 | 否 |

3. 响应格式

javascript
// 成功响应
{
  "data": {
    "id": 123,
    "title": "文章标题",
    "content": "文章内容"
  },
  "meta": {
    "timestamp": "2024-03-30T10:00:00Z",
    "version": "1.0"
  }
}

// 错误响应
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求参数错误",
    "details": [
      {"field": "email", "message": "邮箱格式不正确"}
    ]
  },
  "meta": {
    "timestamp": "2024-03-30T10:00:00Z"
  }
}

API 版本控制

1. 路径版本控制

javascript
// 版本 1
GET /api/v1/posts

// 版本 2
GET /api/v2/posts

2. 查询参数版本控制

javascript
GET /api/posts?version=1
GET /api/posts?version=2

3. Header 版本控制

javascript
GET /api/posts
Accept-Version: 1.0

API 文档

1. OpenAPI/Swagger

yaml
# swagger.yml
openapi: 3.0.0
info:
  version: 1.0.0
  title: 博客 API
  description: 简单的博客管理 API

paths:
  /api/posts:
    get:
      summary: 获取文章列表
      responses:
        '200':
          description: 成功
    post:
      summary: 创建文章
      responses:
        '201':
          description: 文章创建成功
  /api/posts/{id}:
    get:
      summary: 获取单个文章
      parameters:
        - name: id
          in: path
          required: true
          description: 文章 ID
          schema:
            type: integer
      responses:
        '200':
          description: 成功

2. 自动生成文档

javascript
// 使用 swagger-jsdoc
const swaggerJsdoc = require('swagger-jsdoc')
const swaggerUi = require('swagger-ui-express')

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API 文档',
      version: '1.0.0'
    }
  },
  apis: ['./src/routes/*.js']
}

const specs = swaggerJsdoc(options)
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs))

API 安全

1. API 密钥

javascript
// 使用 API 密钥
const apiKey = req.headers['x-api-key']
if (!apiKey || apiKey !== process.env.API_KEY) {
  return res.status(401).json({ error: '无效的 API 密钥' })
}

2. JWT 认证

javascript
// 生成和验证 JWT
const jwt = require('jsonwebtoken')

function generateToken(user) {
  return jwt.sign({ id: user.id }, process.env.JWT_SECRET, { expiresIn: '1h' })
}

function verifyToken(token) {
  try {
    return jwt.verify(token, process.env.JWT_SECRET)
  } catch (error) {
    return null
  }
}

3. 速率限制

javascript
// 使用 express-rate-limit
const rateLimit = require('express-rate-limit')

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分钟
  max: 100, // 每个 IP 100 次请求
  message: '请求过于频繁，请稍后再试'
})

app.use('/api', limiter)

API 性能优化

1. 分页

javascript
// 查询参数方式
GET /api/posts?page=1&limit=10

// 响应
{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "pages": 10
  }
}

2. 选择性字段

javascript
// 查询参数
GET /api/posts?fields=title,content,publishedAt

// 响应
{
  "data": [
    {
      "title": "文章标题",
      "content": "文章内容",
      "publishedAt": "2024-03-30"
    }
  ]
}

3. 缓存

javascript
// 设置缓存头
app.get('/api/posts', (req, res) => {
  res.set('Cache-Control', 'public, max-age=3600')
  res.json(posts)
})

实战案例：博客 API

1. 设计阶段

定义资源

确定需要的资源：

  • posts（文章）
  • comments（评论）
  • tags（标签）
  • users（用户）

API 设计

javascript
// 文章管理
GET /api/posts
POST /api/posts
GET /api/posts/:id
PUT /api/posts/:id
DELETE /api/posts/:id

// 评论管理
GET /api/posts/:id/comments
POST /api/posts/:id/comments
DELETE /api/comments/:id

// 标签管理
GET /api/tags
POST /api/tags
GET /api/tags/:id

实现 API

javascript
// 文章控制器
class PostController {
  static async getAllPosts(req, res) {
    const posts = await Post.find()
    res.json({
      data: posts,
      meta: { total: posts.length }
    })
  }

  static async getPostById(req, res) {
    const { id } = req.params
    const post = await Post.findById(id)
    res.json({ data: post })
  }

  static async createPost(req, res) {
    const post = await Post.create(req.body)
    res.status(201).json({ data: post })
  }
}

常见问题

Q: 如何处理关系数据？

javascript
// 获取文章及其作者
GET /api/posts/123?include=author

Q: 如何处理复杂查询？

javascript
// 搜索和筛选
GET /api/posts?search=关键词&category=技术&published=true

Q: 如何设计文件上传接口？

javascript
// 文件上传
POST /api/upload
Content-Type: multipart/form-data

// 响应
{
  "data": { "url": "/uploads/file.jpg" }
}

下一步

掌握了 API 设计后，接下来可以学习：

  • Claude Code API 测试 - 自动化 API 测试
  • Claude Code API 监控 - API 性能监控
  • Claude Code 微服务架构 - 微服务通信

API 设计是产品设计

好的 API 设计就像产品设计，要考虑开发者的使用体验。Claude Code 可以帮助你设计出优秀的 API！