网站 API 集成基础指南：从 REST 到 GraphQL

API（应用程序接口）是现代网站的骨架。前端需要从后端获取数据、提交表单、与第三方服务交互——这些都通过 API 完成。

RESTful API 基础

REST（Representational State Transfer）是最流行的 API 设计风格。

核心原则

  • 资源导向：每个 URL 代表一个资源（/api/users、/api/articles）
  • HTTP 方法语义：GET 读取、POST 创建、PUT 更新、DELETE 删除
  • 无状态：每个请求包含所有必要信息
  • 统一接口：一致的 URL 结构和响应格式

设计示例

方法 端点 说明
GET /api/articles 获取文章列表
GET /api/articles/:id 获取单篇文章
POST /api/articles 创建文章
PUT /api/articles/:id 更新文章
DELETE /api/articles/:id 删除文章

前端调用示例

// 使用 Fetch API 调用 REST 接口
async function getArticles() {
  const response = await fetch('/api/articles');
  if (!response.ok) throw new Error('Failed to fetch');
  return response.json();
}

// POST 请求
async function createArticle(data) {
  const response = await fetch('/api/articles', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  });
  return response.json();
}

GraphQL 入门

GraphQL 是 REST 的替代方案，由 Facebook 开发，允许客户端精确指定需要的数据。

REST vs GraphQL

特性 REST GraphQL
数据获取 固定结构 客户端自定义
过度获取 常见 不会
多次请求 可能需要多次请求 单次请求
学习曲线 低 中
缓存 原生 HTTP 缓存 需要额外配置
工具生态 成熟 快速发展

GraphQL 查询示例

# 查询：只获取需要的数据
query {
  articles(first: 10) {
    id
    title
    author {
      name
    }
  }
}

# 变更：创建数据
mutation {
  createArticle(title: "Hello", content: "World") {
    id
    title
  }
}

前端调用

// 使用 Apollo Client 调用 GraphQL
import { ApolloClient, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: '/graphql',
});

const GET_ARTICLES = gql`
  query GetArticles {
    articles {
      id
      title
    }
  }
`;

const { data } = await client.query({ query: GET_ARTICLES });

API 安全最佳实践

身份认证

// JWT Token 认证
const response = await fetch('/api/protected', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

速率限制

API 端点应配置速率限制（Rate Limiting），防止滥用。

输入验证

所有 API 输入必须在服务端进行验证。

字段 验证规则
email 有效邮箱格式
title 1-200 字符
content 1-50000 字符
file 限制大小和类型

16IDC 观察

对于大多数中小型网站，RESTful API 是最实用、最容易上手的选择。GraphQL 适合数据结构复杂、需要灵活数据获取的场景。建议新项目从 REST 开始，当出现「过度获取」或「多次请求」问题时再考虑引入 GraphQL。