API设计与开发

ops/2024/11/28 23:50:46/

7. API设计与开发

API（应用程序编程接口）是前后端通信的桥梁，良好的API设计能够提升应用的可用性、可维护性和扩展性。以下内容将深入探讨RESTful API原则、GraphQL的基本概念以及使用Postman进行API测试的方法。

7.1 理解RESTful API原则

REST（Representational State Transfer） 是一种架构风格，用于设计网络应用程序的API。RESTful API遵循一系列约束，使得API具备良好的可扩展性和易用性。

REST的六大约束

  1. 客户端-服务器架构（Client-Server）
    • 定义：客户端和服务器分离，客户端负责用户界面和用户体验，服务器负责数据存储和业务逻辑。
    • 优点：提升系统的可维护性和可扩展性，客户端和服务器可以独立开发和部署。
  2. 无状态（Stateless）
    • 定义：每个请求都包含了所有必要的信息，服务器不存储客户端的会话状态。
    • 优点：简化服务器设计，提高可扩展性，增强系统的可靠性。
  3. 可缓存性（Cacheable）
    • 定义：响应数据应该被标记为可缓存或不可缓存，允许客户端或中间层缓存响应以减少服务器负载。
    • 优点：提升性能，减少延迟，提高用户体验。
  4. 统一接口（Uniform Interface）
    • 定义：通过统一的接口简化和解耦客户端与服务器。包括资源的标识、资源的表现形式、资源的自描述消息和超媒体作为应用状态的引擎（HATEOAS）。
    • 优点：简化架构，提高系统的可理解性和可互操作性。
  5. 分层系统（Layered System）
    • 定义：系统可以由多个层组成，每一层只与相邻层交互，客户端无法感知到系统的具体层次结构。
    • 优点：提升系统的可扩展性和安全性，允许中间层实现负载均衡、缓存等功能。
  6. 按需代码（Code on Demand）（可选）
    • 定义：服务器可以通过传输可执行代码（如JavaScript）来扩展客户端的功能。
    • 优点：提高系统的灵活性，但由于安全性和复杂性较高，通常不推荐广泛使用。

RESTful API的核心概念

  1. 资源（Resources）
    • 定义：API中的每一个实体都是一个资源，资源通过URI（统一资源标识符）进行标识。
    • 示例：/users 表示用户资源，/products 表示产品资源。
  2. HTTP方法（HTTP Methods）
    • GET：获取资源
    • POST：创建资源
    • PUT：更新资源
    • PATCH：部分更新资源
    • DELETE：删除资源
  3. 状态码（Status Codes）
    • 2xx：成功（如200 OK, 201 Created）
    • 4xx：客户端错误（如400 Bad Request, 404 Not Found）
    • 5xx：服务器错误（如500 Internal Server Error）
  4. 表示（Representations）
    • 定义：资源的具体表现形式，常见格式包括JSON、XML。
    • 示例：客户端请求 /users/1，服务器返回用户1的JSON表示。

RESTful API设计示例

假设我们要设计一个简单的用户管理API，使用FastAPI框架实现。

python"># app/main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Dictapp = FastAPI()# 模拟数据库
fake_db: Dict[int, Dict[str, str]] = {}class User(BaseModel):id: intname: stremail: str@app.get("/users/{user_id}", response_model=User)
def get_user(user_id: int):if user_id in fake_db:return fake_db[user_id]raise HTTPException(status_code=404, detail="User not found")@app.post("/users/", response_model=User, status_code=201)
def create_user(user: User):if user.id in fake_db:raise HTTPException(status_code=400, detail="User already exists")fake_db[user.id] = user.dict()return user@app.put("/users/{user_id}", response_model=User)
def update_user(user_id: int, user: User):if user_id not in fake_db:raise HTTPException(status_code=404, detail="User not found")fake_db[user_id] = user.dict()return user@app.delete("/users/{user_id}", status_code=204)
def delete_user(user_id: int):if user_id in fake_db:del fake_db[user_id]returnraise HTTPException(status_code=404, detail="User not found")

运行API

使用Uvicorn运行FastAPI应用：

uvicorn app.main:app --reload

API文档：

FastAPI自动生成的Swagger UI和ReDoc可以访问以下地址查看和测试API：

  • Swagger UI：http://127.0.0.1:8000/docs
  • ReDoc：http://127.0.0.1:8000/redoc

7.2 熟悉GraphQL（可选）

GraphQL 是由Facebook开发的一种用于API的查询语言，与REST相比，它提供了更灵活和高效的数据获取方式。

GraphQL的核心概念

  1. 查询（Queries）
    • 定义：客户端定义所需的数据结构，服务器根据查询返回精确的数据。
    • 优点：减少数据过载和欠载，客户端可按需获取数据。
  2. 变更（Mutations）
    • 定义：用于修改服务器端数据的操作，如创建、更新、删除。
  3. 订阅（Subscriptions）
    • 定义：用于实时获取数据更新，类似于WebSocket。
  4. 类型系统（Type System）
    • 定义：GraphQL使用强类型系统定义API的数据结构，确保客户端和服务器之间的数据契约。

GraphQL与REST的对比

特性RESTGraphQL
数据获取方式多个端点，每个端点返回固定数据单一端点，根据查询返回所需数据
数据灵活性客户端获取固定结构的数据，可能过载或欠载客户端定义数据结构，按需获取数据
请求数量可能需要多个请求来获取关联数据单个请求即可获取所有相关数据
学习曲线相对简单，基于HTTP标准需要理解查询语言和类型系统

GraphQL在Python中的实现

使用Graphene库，可以在Python中快速构建GraphQL API。

安装Graphene：

pip install graphene
pip install graphene-fastapi

示例代码：

python"># app/graphql_api.py
import graphene
from fastapi import FastAPI
from graphene import ObjectType, String, Int, Field, List# 模拟数据库
fake_db = {1: {"id": 1, "name": "Alice", "email": "alice@example.com"},2: {"id": 2, "name": "Bob", "email": "bob@example.com"},
}class User(graphene.ObjectType):id = Int()name = String()email = String()class Query(ObjectType):users = List(User)user = Field(User, user_id=Int(required=True))def resolve_users(root, info):return [User(**user) for user in fake_db.values()]def resolve_user(root, info, user_id):user = fake_db.get(user_id)if user:return User(**user)return Noneschema = graphene.Schema(query=Query)app = FastAPI()from starlette.graphql import GraphQLAppapp.add_route("/graphql", GraphQLApp(schema=schema))

运行API：

uvicorn app.graphql_api:app --reload

访问GraphQL Playground：

访问 http://127.0.0.1:8000/graphql 使用GraphQL Playground进行查询和测试。

GraphQL查询示例

获取所有用户：

query {users {idnameemail}
}

获取特定用户：

query {user(userId: 1) {idnameemail}
}

注意：GraphQL适用于需要灵活查询和高效数据获取的场景，但其复杂性较高，建议在理解其优势和适用场景后再选择是否使用。

7.3 使用工具如Postman进行API测试

Postman 是一款流行的API开发和测试工具，提供了直观的界面和强大的功能，适用于开发、测试和调试API。

Postman的主要功能

  1. 发送HTTP请求
    • 支持各种HTTP方法（GET, POST, PUT, DELETE, etc.）
    • 配置请求头、参数和主体
  2. 环境与变量管理
    • 定义环境变量，简化不同环境下的测试配置
    • 使用变量在请求中动态替换值
  3. 集合与文档
    • 创建请求集合，组织和共享API测试用例
    • 自动生成API文档，便于团队协作
  4. 测试脚本
    • 使用JavaScript编写自动化测试脚本
    • 验证响应数据、状态码和其他条件
  5. 监控与自动化
    • 定时运行API测试，监控API性能和可用性
    • 集成CI/CD流程，实现持续测试

使用Postman测试RESTful API

以下以之前的FastAPI用户管理API为例，展示如何使用Postman进行测试。

1. 安装Postman

访问 Postman官网 下载并安装适合您操作系统的版本。

2. 创建请求

a. 创建用户（POST请求）

  • 方法：POST

  • URL：http://127.0.0.1:8000/users/

  • Headers：

    • Content-Type: application/json

  • Body（选择raw，格式为JSON）：

    {"id": 1,"name": "Alice","email": "alice@example.com"
}

  • 发送请求：

    • 点击Send按钮。

    • 预期响应（状态码201）：

      {"id": 1,"name": "Alice","email": "alice@example.com"
}

b. 获取用户（GET请求）

  • 方法：GET

  • URL：http://127.0.0.1:8000/users/1

  • 发送请求：

    • 点击Send按钮。

    • 预期响应（状态码200）：

      {"id": 1,"name": "Alice","email": "alice@example.com"
}

c. 更新用户（PUT请求）

  • 方法：PUT

  • URL：http://127.0.0.1:8000/users/1

  • Headers：

    • Content-Type: application/json

  • Body：

    {"id": 1,"name": "Alice Smith","email": "alice.smith@example.com"
}

  • 发送请求：

    • 点击Send按钮。

    • 预期响应（状态码200）：

      {"id": 1,"name": "Alice Smith","email": "alice.smith@example.com"
}

d. 删除用户（DELETE请求）

  • 方法：DELETE
  • URL：http://127.0.0.1:8000/users/1
  • 发送请求：
    • 点击Send按钮。
    • 预期响应（状态码204，无内容）
3. 创建请求集合

为了组织和复用API测试用例，建议将相关请求创建为一个集合。

  • 步骤：
    1. 在Postman左侧栏，点击Collections。
    2. 点击New Collection，命名为User Management API。
    3. 将上述创建的各个请求添加到该集合中。
4. 使用环境变量

在不同环境（开发、测试、生产）下，API的基URL可能不同。通过环境变量，可以简化配置和切换。

  • 步骤：

    1. 点击Postman右上角的Manage Environments。

    2. 点击Add，创建一个新的环境，例如Local。

    3. 添加变量：

      • base_url: http://127.0.0.1:8000

    4. 在请求URL中使用变量：

      {{base_url}}/users/

    5. 选择对应的环境，Postman会自动替换变量。

5. 编写测试脚本

Postman允许在请求发送前后编写脚本，进行自动化测试和验证。

  • 示例：验证创建用户响应

    在创建用户的请求中，切换到Tests标签，添加以下脚本：

    pm.test("Status code is 201", function () {pm.response.to.have.status(201);
});pm.test("Response has id, name, and email", function () {var jsonData = pm.response.json();pm.expect(jsonData).to.have.property("id");pm.expect(jsonData).to.have.property("name");pm.expect(jsonData).to.have.property("email");
});

    解释：

    • 第一个测试：检查响应状态码是否为201。
    • 第二个测试：检查响应体中是否包含id、name和email字段。

  • 运行测试：

    • 发送请求后，切换到Tests标签，查看测试结果。
6. 运行集合测试

Postman支持批量运行请求集合，适用于回归测试和持续集成。

  • 步骤：
    1. 在左侧栏，右键点击User Management API集合，选择Run Collection。
    2. 在弹出的窗口中，选择环境（如Local），配置并点击Run。
    3. 查看运行结果，确保所有测试用例通过。
7. 使用Postman进行GraphQL测试（可选）

如果您的项目使用GraphQL，可以使用Postman发送GraphQL查询和变更。

  • 步骤：

    1. 创建一个新的请求，方法选择POST，URL为GraphQL端点（如http://127.0.0.1:8000/graphql）。

    2. 在Headers中添加Content-Type: application/json。

    3. 在Body中选择raw，格式为JSON，输入GraphQL查询：

      {"query": "query { users { id name email } }"
}

    4. 点击Send，查看响应数据。

注意：虽然Postman支持GraphQL测试，但专门的GraphQL工具（如GraphQL Playground、Insomnia）可能提供更丰富的功能和更友好的界面。

总结

作为入门级Python后端开发工程师，掌握API设计与开发的基本原则和工具至关重要。通过理解RESTful API原则、熟悉GraphQL的基本概念（可选）以及使用Postman进行API测试，您可以有效地设计、开发和验证高质量的API，为前后端协作和应用的稳定性提供坚实基础。

关键点回顾：

  1. 理解RESTful API原则：
    • 遵循REST的六大约束，设计清晰、可维护的API。
    • 了解资源、HTTP方法、状态码和表示的概念。
  2. 熟悉GraphQL（可选）：
    • 理解GraphQL的查询、变更和订阅机制。
    • 掌握GraphQL与REST的区别和适用场景。
  3. 使用工具如Postman进行API测试：
    • 学会创建和管理请求，使用环境变量简化测试配置。
    • 编写测试脚本，自动化验证API响应。
    • 组织请求集合，进行批量测试和持续集成。

http://www.ppmy.cn/ops/137509.html

相关文章

C++设计模式之组合模式在解决层次性问题中的好处

C++设计模式之组合模式在解决层次性问题中的好处

采用组合模式在处理层次型问题时，会带来以下重要好处： 简化客户端操作： 客户端代码可以统一地处理单个对象和组合对象，而无需区分它们。这意味着客户端可以使用相同的操作来对待所有对象，无论它们是简单的叶子节点还是…
阅读更多...
数据结构2：顺序表

数据结构2：顺序表

目录 1.线性表 2.顺序表 2.1概念及结构 2.2接口实现 1.线性表 线性表是n个具有相同特性的数据元素的有限序列。线性表是一种在实际中广泛使用的数据结构，常见的线性表：顺序表、链表、栈、队列、字符串 线性表在逻辑上是线性结构，也就说…
阅读更多...
UPLOAD LABS | UPLOAD LABS 靶场初识

UPLOAD LABS | UPLOAD LABS 靶场初识

关注这个靶场的其它相关笔记：UPLOAD LABS —— 靶场笔记合集-CSDN博客 0x01：UPLOAD LABS 靶场简介 UPLOAD LABS 靶场是一个专门用于学习文件上传漏洞攻击和防御的靶场。它提供了一系列文件上传漏洞的实验环境，用于帮助用户了解文件上传漏洞的…
阅读更多...
Redis设计与实现 学习笔记 第二十一章 排序

Redis设计与实现 学习笔记 第二十一章 排序

Redis的SORT命令可以对列表键、集合键、有序集合键的值进行排序。 以下代码展示了SORT命令对列表键进行排序的例子： 以下代码展示了SORT命令使用ALPHA选项（ALPHA选项使SORT命令按字典顺序排序，默认SORT命令会将元素当作数字排序&#xff0c…
阅读更多...
基于Matlab实现Gabo滤波器（源码）

基于Matlab实现Gabo滤波器（源码）

Gabor滤波器是一种在图像处理和计算机视觉领域广泛应用的线性滤波器，它结合了空间局部性和频率选择性，能够较好地模拟人类视觉系统对图像特征的感知。在Matlab中实现Gabor滤波器，可以有效地提取图像的纹理、边缘和方向信息，对于图…
阅读更多...
Spring Boot 整合 Prometheus 实现资源监控

Spring Boot 整合 Prometheus 实现资源监控

引言 在微服务架构流行的今天，服务的监控和管理变得尤为重要。Prometheus 作为一个开源的监控和告警工具，以其强大的数据采集、存储和查询能力，受到了众多开发者的青睐。Spring Boot 作为 Java 领域快速构建微服务的框架，与 Prom…
阅读更多...
【自动化】如何从列表中找到图片并命名保存下来

【自动化】如何从列表中找到图片并命名保存下来

以下是对这段 Python 代码的分析： 代码功能概述 这段代码主要使用了 DrissionPage 库（看起来是用于自动化网页操作相关的库）来与浏览器（基于 Chromium 内核）进行交互，实现以下功能： 打开豆瓣…
阅读更多...
ARM（安谋） China处理器

ARM（安谋） China处理器

0 Preface/Foreword 0.1 参考博客 Cortex-M23/M33与STAR-MC1星辰处理器 ARM China，2018年4月established，独立运行。 1 处理器类型 1.1 周易AIPU 1.2 STAR-MC1（星辰处理器） STAT-MC1，主要为满足AIOT应用性能、功…
阅读更多...
最新文章

Copyright @ 2022~2023