《Python实战进阶》专栏 No 5：GraphQL vs RESTful API 对比与实现

《Python实战进阶》专栏包括68集，每一集聚焦一个中高级技术知识点，涵盖Python在Web开发、数据处理、自动化、机器学习、并发编程等领域的应用，系统梳理Python开发者的知识集。本集的主题为： No4 : GraphQL vs RESTful API 对比与实现 ，第六集的主题为No6 : OAuth2.0 认证与授权的实现 。

第五集：GraphQL vs RESTful API 对比与实现

---

目录

1. 引言
2. RESTful API 简介与优缺点
3. GraphQL 简介与优缺点
4. GraphQL 与 RESTful API 的对比
5. 实战：构建一个简单的 RESTful API 和 GraphQL API
   • RESTful API 实现
   • GraphQL API 实现
6. 总结

---

1. 引言

在现代 Web 开发中，API 是前后端通信的核心。RESTful API 和 GraphQL 是两种主流的 API 设计方式，它们各有优劣，适用于不同的场景。本节将深入探讨两者的区别，并通过实战代码展示如何实现这两种 API。

---

2. RESTful API 简介与优缺点

RESTful API 是一种基于 HTTP 协议的架构风格，它通过 URL 定义资源，并使用 HTTP 方法（如 GET、POST、PUT、DELETE）对资源进行操作。

优点

• 简单直观：URL 明确表示资源，HTTP 方法清晰定义操作。
• 广泛支持：几乎所有编程语言和框架都支持 RESTful 风格。
• 缓存友好：HTTP 缓存机制可以直接应用于 RESTful API。

缺点

• 过度获取或不足获取数据：客户端无法灵活控制返回的数据结构，可能导致冗余或缺失。
• 版本管理复杂：随着需求变化，可能需要维护多个版本的 API。

---

3. GraphQL 简介与优缺点

GraphQL 是 Facebook 开发的一种查询语言，允许客户端精确指定所需的数据结构，从而避免了 RESTful API 的过度获取问题。

优点

• 灵活性：客户端可以自定义查询，只获取需要的数据。
• 单一入口：所有请求通过一个端点完成，简化了 API 设计。
• 强类型系统：GraphQL 提供了类型定义，便于开发和调试。

缺点

• 学习曲线较高：相比 RESTful API，GraphQL 的概念和实现更复杂。
• 性能问题：复杂的嵌套查询可能导致性能瓶颈。
• 工具生态相对较少：虽然 GraphQL 工具链日益完善，但仍不及 RESTful API 成熟。

---

4. GraphQL 与 RESTful API 的对比

特性	RESTful API	GraphQL
数据获取	固定结构，可能冗余或不足	灵活查询，按需获取
请求方式	多个端点，每个端点对应一个资源	单一端点，统一处理所有请求
缓存支持	原生支持 HTTP 缓存	需要额外实现缓存机制
学习难度	简单直观	概念较复杂，需要学习查询语言
性能优化	较容易优化	需要防止 N+1 查询等问题

---

5. 实战：构建一个简单的 RESTful API 和 GraphQL API

我们将以一个简单的任务管理系统为例，展示如何实现 RESTful API 和 GraphQL API。

环境准备

• Python 3.8+
• Flask（用于 RESTful API）
• Graphene（用于 GraphQL API）

安装依赖：

pip install flask graphene flask-graphql requests

数据模型

假设我们有一个任务列表，每项任务包含以下字段：

• id: 任务 ID
• title: 任务标题
• description: 任务描述
• done: 是否完成

RESTful API 实现

创建文件 rest_api.py：

from flask import Flask, jsonify, request

app = Flask(__name__)

# 模拟的任务数据
tasks = [
    {"id": 1, "title": "Learn Python", "description": "Study Python basics", "done": False},
    {"id": 2, "title": "Write Code", "description": "Practice coding daily", "done": True},
]

@app.route('/tasks', methods=['GET'])
def get_tasks():
    return jsonify(tasks)

@app.route('/tasks/<int:task_id>', methods=['GET'])
def get_task(task_id):
    task = next((task for task in tasks if task["id"] == task_id), None)
    if task:
        return jsonify(task)
    return jsonify({"error": "Task not found"}), 404

@app.route('/tasks', methods=['POST'])
def create_task():
    new_task = request.json
    new_task["id"] = len(tasks) + 1
    tasks.append(new_task)
    return jsonify(new_task), 201

if __name__ == '__main__':
    app.run(debug=True)

运行 RESTful API：

python rest_api.py

测试1：

curl http://127.0.0.1:5000/tasks  
#或者在浏览器输入：
http://127.0.0.1:5000/tasks  

程序输出：

[
  {
    "description": "Study Python basics",
    "done": false,
    "id": 1,
    "title": "Learn Python"
  },
  {
    "description": "Practice coding daily",
    "done": true,
    "id": 2,
    "title": "Write Code"
  }
]

测试2：

curl http://127.0.0.1:5000/tasks/1  
#或者在浏览器输入：
http://127.0.0.1:5000/tasks/1 

程序输出：

{
  "description": "Study Python basics",
  "done": false,
  "id": 1,
  "title": "Learn Python"
}

测试3：

curl -X POST http://127.0.0.1:5000/tasks -H "Content-Type: application/json" -d "{\"title\":\"New Task\", \"description\": \"This is a new task\", \"done\": false}"

程序输出：

{
  "description": "This is a new task",
  "done": false,
  "id": 4,
  "title": "New Task"
}

GraphQL API 实现

创建文件 graphql_api.py：

from flask import Flask
from flask_graphql import GraphQLView
from graphene import ObjectType, String, Boolean, List, Schema, Field, Int, Mutation

app = Flask(__name__)

# 定义任务类型
class Task(ObjectType):
    id = Int()
    title = String()
    description = String()
    done = Boolean()

# 模拟的任务数据
tasks = [
    Task(id=1, title="Learn Python", description="Study Python basics", done=False),
    Task(id=2, title="Write Code", description="Practice coding daily", done=True),
]

# 查询根类型
class Query(ObjectType):
    tasks = List(Task)
    task = Field(Task, id=Int())

    def resolve_tasks(self, info):
        return tasks

    def resolve_task(self, info, id):
        return next((task for task in tasks if task.id == id), None)

# 变更根类型
class CreateTask(Mutation):
    class Arguments:
        title = String()
        description = String()
        done = Boolean()

    task = Field(Task)

    def mutate(self, info, title, description, done):
        new_task = Task(id=len(tasks) + 1, title=title, description=description, done=done)
        tasks.append(new_task)
        return CreateTask(task=new_task)

class Mutation(ObjectType):
    create_task = CreateTask.Field()

schema = Schema(query=Query, mutation=Mutation)

# 添加 GraphQL 视图
app.add_url_rule(
    '/graphql',
    view_func=GraphQLView.as_view('graphql', schema=schema, graphiql=True)
)

if __name__ == '__main__':
    app.run(debug=True)

运行 GraphQL API：

python graphql_api.py

访问 http://127.0.0.1:5000/graphql，使用 GraphiQL 测试查询和变更。

示例查询：

{
  tasks {
    id
    title
    done
  }
}

示例变更：

mutation {
  createTask(title: "New Task", description: "Description", done: false) {
    task {
      id
      title
    }
  }
}

---

6. 总结

通过本节的学习，我们了解了 RESTful API 和 GraphQL 的核心概念及优缺点，并通过实战代码实现了两种 API。选择哪种技术取决于具体需求：如果需要简单易用的 API，RESTful 是不错的选择；如果需要灵活的数据查询能力，GraphQL 更加适合。

在下一集《OAuth2.0 认证与授权的实现》中，我们将探讨如何为 API 添加安全保护机制，敬请期待！

---

图示

• 图1：RESTful API 请求流程图
• 图2：GraphQL 查询流程图

希望本节内容对你有所帮助！