API设计与开发

news2024/11/25 9:27:07

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框架实现。

# app/main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Dict

app = FastAPI()

# 模拟数据库
fake_db: Dict[int, Dict[str, str]] = {}

class User(BaseModel):
    id: int
    name: str
    email: 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]
        return
    raise 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

示例代码：

# 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 None

schema = graphene.Schema(query=Query)

app = FastAPI()

from starlette.graphql import GraphQLApp

app.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 {
    id
    name
    email
  }
}

获取特定用户：

query {
  user(userId: 1) {
    id
    name
    email
  }
}

注意：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.coloradmin.cn/o/2247202.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

如何安全删除 Linux 用户帐户和主目录 ？

如何安全删除 Linux 用户帐户和主目录 ？

Linux 以其健壮性和灵活性而闻名，是全球服务器和桌面的首选。管理用户帐户是系统管理的一个基本方面，包括创建、修改和删除用户帐户及其相关数据。本指南全面概述了如何在 Linux 中安全地删除用户帐户及其主目录，以确保系统的安全性和完整性。…
阅读更多...
如何利用ros搭建虚拟场景通过仿真机器人完成一次简单的SLAM建图、导航规划（超简单）？——学习来源：机器人工匠阿杰

如何利用ros搭建虚拟场景通过仿真机器人完成一次简单的SLAM建图、导航规划（超简单）？——学习来源：机器人工匠阿杰

一：什么是SLAM，SLAM和导航规划又有什么关系？ SLAM（Simultaneous Localization and Mapping，即同时定位与建图）是一种在未知或动态环境中自行驶的重要技术。主要通过设备上的传感器（如激光雷达、…
阅读更多...
shell脚本（完结）

shell脚本（完结）

声明：学习视频来自b站up主 泷羽sec，如涉及侵权马上删除文章 感谢泷羽sec 团队的教学 视频地址：shell编程（完结）_哔哩哔哩_bilibili 本文主要讲解不同shell脚本中的相互调用以及输入输出重定向操作。 一、不同脚本之间…
阅读更多...
禁用达梦DEM的agent

禁用达梦DEM的agent

agent占用内存较多，实际没什么使用，考虑停止agent 应该切换到root执行停止 cd /dm/dmdbms/tool/dmagent/service/ ./DmAgentService stop禁用
阅读更多...
使用ChatGPT生成和优化电子商务用户需求规格说明书

使用ChatGPT生成和优化电子商务用户需求规格说明书

在电子商务项目开发中，用户需求规格说明书（User Requirement Specification, URS）是团队沟通与项目成功的基石。然而，面对复杂多变的需求，如何快速生成清晰、完整且具备说服力的文档？这正是AI工具的用武之地…
阅读更多...
产品研发管理和研发项目管理的区别是什么

产品研发管理和研发项目管理的区别是什么

产品研发管理与研发项目管理有显著的区别，主要体现在管理范围、目标导向和执行方法上。产品研发管理侧重于产品生命周期的规划与执行，强调产品的创新性和市场需求对接，而研发项目管理则更注重具体项目的执行过程，聚焦项目时间、成…
阅读更多...
摆烂仙君传——深度学习秘境奇缘

摆烂仙君传——深度学习秘境奇缘

第一章：深度学习秘境 在修仙界与科技交织的边缘，八荒六合九天无上摆烂仙君在其高科技修炼室中感应到一股神秘的召唤。这股力量似乎与他的灵魂产生了共鸣，引导他前往传说中的深度学习秘境。在那里，古老的仙法与前沿的算法交织&…
阅读更多...
【FPGA开发】Vivado自定义封装IP核，绑定总线

【FPGA开发】Vivado自定义封装IP核，绑定总线

支持单个文件的封装、整个工程的封装，这里用单个文件举例。 在文件工程目录下，自建一个文件夹，里面放上需要封装的verilog文件。 选择第三个，指定路径封装，找到文件所在目录 取个名，选择封装IP的路径 会…
阅读更多...
【CS61A 2024秋】Python入门课，全过程记录P2（Week3开始，更新中2024/11/24）

【CS61A 2024秋】Python入门课，全过程记录P2（Week3开始，更新中2024/11/24）

文章目录 关于基本介绍👋Week 3Mon Environments阅读材料Lab 02: Higher-Order Functions, Lambda ExpressionsQ1: WWPD: The Truth Will PrevailQ2: WWPD: Higher-Order FunctionsQ3: WWPD: Lambda 关于 个人博客，里面偶尔更新，最近比较忙。…
阅读更多...
在Linux下配置gitee与Github的远程仓库

在Linux下配置gitee与Github的远程仓库

目录 前言 云服务器下载git 检测是否下载成功git Linux下配置gitee远程仓库 代码提交演示 git三板斧 Linux下配置Github远程仓库 最后的提醒 前言 那么本篇文章将是在，你已经创建了本地仓库的基础上，在Linux下配置gitee的远程仓库的步骤&#xff…
阅读更多...
Mac配置maven环境及在IDEA中配置Maven

Mac配置maven环境及在IDEA中配置Maven

Mac配置maven环境及在IDEA中配置Maven 1. 介绍 Maven是一款广泛用于Java等JVM语言项目的工具，它以项目对象模型（POM）为基础进行项目管理，通过POM文件来定义项目信息和依赖关系。同时，它也是构建自动化工具&#xff0…
阅读更多...
硬中断关闭后的堆栈抓取方法

硬中断关闭后的堆栈抓取方法

一、背景 性能和稳定性是一个计算机工程里的一个永恒的主题。其中尤其稳定性这块的问题发现和问题分析及问题解决就依赖合适的对系统的观测的手段，帮助我们发现问题，识别问题原因最后才能解决问题。稳定性问题里尤其底层问题里，除了panic问题…
阅读更多...
STL关联式容器之hashtable

STL关联式容器之hashtable

hashtable的桶子与节点 下图为开链法(separate chaining)完成hashtable的图形表述。为了剖析SGI STL源码，我们遵循SGI的命名，称hash table表格内的元素为桶(bucket),此名称的大约意义是，表格内的每个单元，涵盖的不只是个节点(元素…
阅读更多...
基于python的长津湖评论数据分析与可视化，使用是svm情感分析建模

基于python的长津湖评论数据分析与可视化，使用是svm情感分析建模

引言 研究背景及意义 上世纪初开始，中国电影就以自己独有的姿态登上了世界电影史的舞台。中国电影作为国家文化和思想观念的反映与延伸，能够增强文化自信，在文化输出方面有着极其重要的作用1[1]。 改革开放以来，随着生产力的提高…
阅读更多...
阿里云oss转发上线-实现不出网钓鱼

阿里云oss转发上线-实现不出网钓鱼

本地实现阿里云oss转发上线，全部代码在文末，代码存在冗余 实战环境 被钓鱼机器不出网只可访问内部网络包含集团oss 实战思路 若将我们的shellcode文件上传到集团oss上仍无法上线，那么就利用oss做中转使用本地转发进行上线，先发送…
阅读更多...
预测未来 | MATLAB实现Transformer时间序列预测未来

预测未来 | MATLAB实现Transformer时间序列预测未来

预测未来 | MATLAB实现Transformer时间序列预测未来 预测效果 基本介绍 1.Matlab实现Transformer时间序列预测未来； 2.运行环境Matlab2023b及以上，data为数据集，单变量时间序列预测； 3.递归预测未来数据，可以控制预…
阅读更多...
局域网与广域网：探索网络的规模与奥秘（3/10）

局域网与广域网：探索网络的规模与奥秘（3/10）

一、局域网的特点 局域网覆盖有限的地理范围，通常在几公里以内，具有实现资源共享、服务共享、维护简单、组网开销低等特点，主要传输介质为双绞线，并使用少量的光纤。 局域网一般是方圆几千米以内的区域网络，其特点丰富…
阅读更多...
可视化建模与UML《协作图实验报告》

可视化建模与UML《协作图实验报告》

有些鸟儿毕竟是关不住的。 一、实验目的： 1、熟悉协作图的构件事物。 2、掌握协作图的绘制方法。 二、实验环境： window7 | 10 | 11 EA15 三、实验内容： 下面列出了打印文件时的工作流： 用户通过计算机指定要打印的文件。(2)打…
阅读更多...
docker搭建私有的仓库

docker搭建私有的仓库

docker搭建私有仓库 一、为什么要搭建私有的仓库？ 因为在国内，访问：https://hub.docker.com/ 会出现无法访问页面。。。。（已经使用了魔法） 当然现在也有一些国内的镜像管理网站，比如网易云镜像服务、Dao…
阅读更多...
微信小程序条件渲染与列表渲染的全面教程

微信小程序条件渲染与列表渲染的全面教程

微信小程序条件渲染与列表渲染的全面教程 引言 在微信小程序的开发中，条件渲染和列表渲染是构建动态用户界面的重要技术。通过条件渲染，我们可以根据不同的状态展示不同的内容，而列表渲染则使得我们能够高效地展示一组数据。本文将详细讲解这两种渲染方式的用法，结合实例…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023