《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, requestapp = 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"}), [e-mail]('/tasks', methods=['POST'])
def create_task():new_task = request.jsonnew_task["id"] = len(tasks) + 1tasks.append(new_task)return jsonify(new_task), 201if __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, Mutationapp = 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 tasksdef 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 {idtitledone}
}

示例变更：

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

---

6. 总结

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

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

---

图示

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

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