翼度科技»论坛 编程开发 python 查看内容

FastAPI-3:快速入门

5

主题

5

帖子

15

积分

新手上路

Rank: 1

积分
15
3 快速入门

第二章是python基础,故不做介绍。
FastAPI是一个现代、快速(高性能)的网络框架,用于使用基于标准Python 类型提示的Python 3.6+构建API。
FastAPI的创建者是Sebastián Ramírez。
FastAPI由Sebastián Ramírez于2018年发布。与大多数Python Web框架相比,它在很多方面都更加现代化--充分利用了过去几年中添加到Python 3 中的功能。本章将快速介绍FastAPI的主要功能,重点是您首先需要了解的内容:如何处理Web请求和响应。
3.1 FastAPI简介

与其他网络框架一样,FastAPI 可以帮助您构建网络应用程序。每个框架的设计都是为了通过功能、遗漏和默认设置来简化某些操作。顾名思义,FastAPI的目标是开发网络API,不过您也可以将其用于传统的网络内容应用程序。
FastAPI具有以下优势:

  • 性能:在某些情况下与Node.js和Go一样快,与Python框架不同。
  • 快速开发:容易上手,简单清晰。
  • 代码质量更高:类型提示和模型有助于减少错误。
  • 自动生成文档和测试页面:比手工编辑OpenAPI说明容易得多。
FastAPI 使用以下功能:

  • Python 类型提示
  • 用于网络机制的 Starlette,包括异步支持
  • 用于数据定义和验证的 Pydantic
  • 用于利用和扩展其他工具的特殊集成
这种组合为网络应用程序(尤其是 RESTful 网络服务)提供了令人满意的开发环境。
3.2 FastAPI应用

让我们编写一个小巧的 FastAPI 应用程序--只有一个端点的网络服务。现在,我们处于我所说的网络层,只处理网络请求和响应。首先,安装我们要用到的基本 Python 包:

  • FastAPI 框架: pip install fastapi
  • Uvicorn 网络服务器: pip install uvicorn
  • HTTPie 文本网络客户端: pip install httpie
  • 请求同步网络客户端软件包: pip install requests
  • HTTPX 同步/异步网络客户端软件包: pip install httpx
虽然curl是最著名的文本网络客户端,但我认为HTTPie更容易使用。此外,它默认使用JSON编码和解码,更适合 FastAPI。在本章后面,你会看到一张截图,其中包含访问特定端点所需的curl命令行语法。
hello.py:
  1. from fastapi import FastAPI
  2. app = FastAPI()
  3. @app.get("/hi")
  4. def greet():
  5.     return "Hello? World?"
复制代码

  • app是顶级FastAPI对象,代表整个网络应用程序。
  • @app.get("/hi") 是一个路径装饰器。它告诉 FastAPI 以下内容:

    • 在此服务器上对URL"/hi"的请求应被指向以下函数。
    • 此装饰器仅适用于 HTTP GET verb。您也可以使用其他 HTTP 动词(PUT、POST 等)来响应"/hi"URL,每个动词都有一个单独的函数。

  • def greet()是一个路径函数--HTTP 请求和响应的主要连接点。
下一步是在网络服务器中运行该网络应用程序。FastAPI本身不包含网络服务器,但推荐使用Uvicorn。您可以通过两种方式启动Uvicorn和FastAPI 网络应用程序:外部启动或内部启动。
从外部通过命令行启动Uvicorn 的方法:
  1. $ uvicorn hello:app --reload
复制代码
其中hello指的是hello.py文件,app是其中的FastAPI变量名。内部启动如下:
  1. from fastapi import FastAPI
  2. app = FastAPI()
  3. @app.get("/hi")
  4. def greet():
  5.     return "Hello? World?"if __name__ == "__main__":    import uvicorn    uvicorn.run("hello:app", reload=True, host=r'0.0.0.0', port=8008)
复制代码
无论哪种情况,如果hello.py发生变化,reload都会告诉 Uvicorn 重新启动网络服务器。在本章中,我们将经常使用自动重载功能。默认情况下都会使用你机器上的 8000 端口(名为 localhost)。如果你想使用其他方法,外部方法和内部方法都有主机和端口参数。
现在服务器有了一个端点(/hi),可以随时接受请求了。让我们用多个网络客户端进行测试:

  • 对于浏览器,在顶部位置栏键入URL。


  • HTTPie
  1. $ http localhost:8008/hi
  2. HTTP/1.1 200 OK
  3. content-length: 15
  4. content-type: application/json
  5. date: Thu, 06 Jun 2024 01:41:28 GMT
  6. server: uvicorn
  7. "Hello? World?"
  8. # 使用 -b 参数跳过响应头,只打印正文。
  9. $ http -b localhost:8008/hi
  10. "Hello? World?"
  11. # 使用 -v 获取完整的请求头和响应。
  12. # http -v localhost:8008/hi
  13. GET /hi HTTP/1.1
  14. Accept: */*
  15. Accept-Encoding: gzip, deflate
  16. Connection: keep-alive
  17. Host: localhost:8008
  18. User-Agent: HTTPie/3.2.2
  19. HTTP/1.1 200 OK
  20. content-length: 15
  21. content-type: application/json
  22. date: Thu, 06 Jun 2024 01:51:23 GMT
  23. server: uvicorn
  24. "Hello? World?"
复制代码

  • Requests 或 HTTPX
  1. >>> import requests
  2. >>> r = requests.get("http://localhost:8008/hi")
  3. >>> r.json()
  4. 'Hello? World?'
  5. >>> import httpx
  6. >>> r = httpx.get("http://localhost:8008/hi")
  7. >>> r.json()
  8. 'Hello? World?'
复制代码
3.3 HTTP请求

上面第一个HTTPie请求包含以下内容:

  • 动词 (GET) 和路径 (/hi)
  • 查询参数(此处为"无",有的话跟在问号后面)
  • 其他 HTTP 头信息
  • 正文内容(无请求)
FastAPI 将这些信息归纳为方便的定义:Header、Path、Query、Body。
FastAPI从HTTP请求的各个部分提供数据的方式是其最大的特点之一,也是对大多数Python Web框架的改进。您需要的所有参数都可以直接在path函数中声明和提供,使用前面列表中的定义 (Path、Query 等),以及您编写的函数。这使用了一种名为"依赖注入"的技术,我们将继续讨论这种技术,并在第 6 章中进一步阐述。
3.3.1 URL Path

让我们在前面的应用程序中添加一个名为 who 的参数,向某人发送 Hello? 我们将尝试不同的方法来传递这个新参数:
  1. from fastapi import FastAPI
  2. app = FastAPI()
  3. @app.get("/hi/{who}")
  4. def greet(who):
  5.     return f"Hello? {who}?"
  6. if __name__ == "__main__":
  7.     import uvicorn
  8.     uvicorn.run("hello:app", reload=True, host=r'0.0.0.0', port=8008)
复制代码
在 URL 中(@app.get 之后)添加 {who},会告诉 FastAPI 在 URL 中的该位置期待一个名为 who 的变量。然后,FastAPI 将其赋值给下面 greet() 函数中的 who 参数。这显示了路径装饰器和路径函数之间的协调。
注意不要在此处使用 Python f-string 来表示修改后的 URL 字符串 ("/hi/{who}")。
  1. from fastapi import FastAPI
  2. app = FastAPI()
  3. @app.get("/hi/{who}")
  4. def greet(who):
  5.     return f"Hello? {who}?"
  6. if __name__ == "__main__":
  7.     import uvicorn
  8.     uvicorn.run("hello:app", reload=True, host=r'0.0.0.0', port=8008)
复制代码
执行:
  1. # http -b localhost:8008/hi/test
  2. "Hello? test?"
  3. # http -b localhost:8008/hi
  4. {
  5.     "detail": "Not Found"
  6. }
复制代码
参考资料

3.3.2查询参数

查询参数是 URL中?后面的name=value字符串,用&字符分隔。
  1. from fastapi import FastAPI
  2. app = FastAPI()
  3. @app.get("/hi")
  4. def greet(who):
  5.     return f"Hello? {who}?"
  6. if __name__ == "__main__":
  7.     import uvicorn
  8.     uvicorn.run("hello:app", reload=True, host=r'0.0.0.0', port=8008)
复制代码
执行:
  1. # http localhost:8008/hi?who=Mom
  2. HTTP/1.1 200 OK
  3. content-length: 13
  4. content-type: application/json
  5. date: Thu, 06 Jun 2024 02:58:24 GMT
  6. server: uvicorn
  7. "Hello? Mom?"
  8. # http localhost:8008/hi
  9. HTTP/1.1 422 Unprocessable Entity
  10. content-length: 89
  11. content-type: application/json
  12. date: Thu, 06 Jun 2024 02:58:31 GMT
  13. server: uvicorn
  14. {
  15.     "detail": [
  16.         {
  17.             "input": null,
  18.             "loc": [
  19.                 "query",
  20.                 "who"
  21.             ],
  22.             "msg": "Field required",
  23.             "type": "missing"
  24.         }
  25.     ]
  26. }
  27. # 注意两个等号为GET, 冒号表示HTTP头,一个等号为POST,
  28. # http -b localhost:8008/hi who==Mom
  29. "Hello? Mom?"
复制代码
3.3.3 POST
  1. from fastapi import FastAPI, Body
  2. app = FastAPI()
  3. @app.post("/hi")
  4. def greet(who:str = Body(embed=True)):
  5.     return f"Hello? {who}?"
  6. if __name__ == "__main__":
  7.     import uvicorn
  8.     uvicorn.run("hello:app", reload=True, host=r'0.0.0.0', port=8000)
复制代码
执行:
  1. # /root/code/fastapi/example^C
  2. root@www:~/code/fastapi/example# http -v localhost:8000/hi who=Mom
  3. POST /hi HTTP/1.1
  4. Accept: application/json, */*;q=0.5
  5. Accept-Encoding: gzip, deflate
  6. Connection: keep-alive
  7. Content-Length: 14
  8. Content-Type: application/json
  9. Host: localhost:8000
  10. User-Agent: HTTPie/3.2.2
  11. {
  12.     "who": "Mom"
  13. }
  14. HTTP/1.1 200 OK
  15. content-length: 13
  16. content-type: application/json
  17. date: Thu, 06 Jun 2024 03:25:34 GMT
  18. server: uvicorn
  19. "Hello? Mom?"
复制代码
需要使用 Body(embed=True) 来告 FastAPI,这次我们从JSON格式的请求正文中获取who的值。embed 部分意味着它看起来应该像 {"who": "Mom"},而不仅仅是 "Mom"。
3.3.4 HTTP 头信息
  1. from fastapi import FastAPI, Header
  2. app = FastAPI()
  3. @app.get("/hi")
  4. def greet(who:str = Header()):
  5.     return f"Hello? {who}?"
  6. if __name__ == "__main__":
  7.     import uvicorn
  8.     uvicorn.run("hello:app", reload=True, host=r'0.0.0.0', port=8000)
复制代码
执行:
  1. # http -v localhost:8000/hi who:Mom
  2. GET /hi HTTP/1.1
  3. Accept: */*
  4. Accept-Encoding: gzip, deflate
  5. Connection: keep-alive
  6. Host: localhost:8000
  7. User-Agent: HTTPie/3.2.2
  8. who: Mom
  9. HTTP/1.1 200 OK
  10. content-length: 13
  11. content-type: application/json
  12. date: Thu, 06 Jun 2024 06:09:55 GMT
  13. server: uvicorn
  14. "Hello? Mom?"
复制代码
3.3.5 多重请求数据

你可以在同一个路径函数中使用多个方法。也就是说,你可以从 URL、查询参数、HTTP 主体、HTTP 头文件、cookie等获取数据。你还可以编写自己的依赖函数,以特殊方式处理和组合这些数据,例如用于分页或身份验证。
3.3.6哪种方法最好?

以下是一些建议:

  • 在URL中传递参数时,遵循 RESTful 准则是标准做法。
  • 查询字符串通常用于提供可选参数,如分页。
  • body通常用于较大的输入,如整个或部分模型。
在每种情况下,如果您在数据定义中提供了类型提示,Pydantic就会自动对您的参数进行类型检查。这将确保参数的存在和正确性。
3.4 HTTP响应

默认情况下FastAPI会将返回的内容转换为JSON;HTTP响应的头行内容类型为:application/json。
3.4.1 状态代码

FastAPI默认返回200状态代码;异常会产生4xx代码。在路径装饰器中,指定在一切顺利的情况下应返回的 HTTP 状态代码可以改写返回(异常会生成自己的代码并覆盖它)。
  1. from fastapi import FastAPI, Body
  2. app = FastAPI()
  3. @app.post("/hi")
  4. def greet(who:str = Body(embed=True)):
  5.     return f"Hello? {who}?"
  6. if __name__ == "__main__":
  7.     import uvicorn
  8.     uvicorn.run("hello:app", reload=True, host=r'0.0.0.0', port=8000)
复制代码
执行:
  1. ~# http localhost:8000/happy
  2. HTTP/1.1 200 OK
  3. content-length: 4
  4. content-type: application/json
  5. date: Thu, 06 Jun 2024 06:39:00 GMT
  6. server: uvicorn
  7. ":)"
  8. # http localhost:8000/happy3
  9. HTTP/1.1 404 Not Found
  10. content-length: 22
  11. content-type: application/json
  12. date: Thu, 06 Jun 2024 06:40:32 GMT
  13. server: uvicorn
  14. {
  15.     "detail": "Not Found"
  16. }
复制代码
3.4.2 Headers
  1. from fastapi import FastAPI, Body, Response
  2. app = FastAPI()
  3. @app.get("/header/{name}/{value}")
  4. def header(name: str, value: str, response:Response):
  5.     response.headers[name] = value
  6.     return "normal body"
  7. if __name__ == "__main__":
  8.     import uvicorn
  9.     uvicorn.run("hello:app", reload=True, host=r'0.0.0.0', port=8000)
复制代码
执行:
  1. # http localhost:8000/header/marco/polo
  2. HTTP/1.1 200 OK
  3. content-length: 13
  4. content-type: application/json
  5. date: Thu, 06 Jun 2024 06:48:10 GMT
  6. marco: polo
  7. server: uvicorn
  8. "normal body"
复制代码
3.4.3 响应类型

响应类型(从 fastapi.responses 中导入这些类)包括以下内容:

  • JSONResponse(默认值)
  • HTMLResponse
  • PlainTextResponse
  • RedirectResponse
  • FileResponse
  • StreamingResponse
关于后两种,我将在第15章中详细介绍。对于其他输出格式(也称为 MIME 类型),可以使用通用的 Response 类,它需要以下内容:

  • content:字符串或字节
  • media_type:字符串 MIME 类型
  • status_code:HTTP 整数状态代码
  • headers:字符串
3.4.4 类型转换

路径函数可以返回任何内容,默认情况下(使用 JSONResponse),FastAPI 会将其转换为 JSON 字符串并返回,同时返回与之匹配的 HTTP 响应头 Content-Length 和 Content-Type。这包括任何 Pydantic 模型类。
但它是如何做到这一点的呢?如果您使用过 Python json 库,您可能会发现,当给定某些数据类型(如日期时间)时,它会引发异常。FastAPI 使用名为 jsonable_encoder() 的内部函数将任何数据结构转换为 "JSONable" Python 数据结构,然后调用 json.dumps() 将其转换为 JSON 字符串。
  1. import datetime
  2. import json
  3. import pytest
  4. from fastapi.encoders import jsonable_encoder
  5. @pytest.fixture
  6. def data():
  7.     return datetime.datetime.now()
  8. def test_json_dump(data):
  9.     with pytest.raises(Exception):
  10.         _ = json.dumps(data)
  11. def test_encoder(data):
  12.     out = jsonable_encoder(data)
  13.     assert out
  14.     json_out = json.dumps(out)
  15.     assert json_out
复制代码
3.4.4 模型类型和响应模型

不同的类可能有许多相同的字段,只是一个专门用于用户输入,一个用于输出,还有一个用于内部使用。产生这些变体的原因可能包括以下几点:

  • 从输出中移除一些敏感信息,比如去识别个人医疗数据,如果你遇到《健康保险可携性和责任法案》(HIPAA)的要求。
  • 为用户输入添加字段(如创建日期和时间)。
下列展示了一个假定案例中的三个相关类:

  • TagIn 是定义用户需要提供的内容(在本例中,只是一个名为 tag 的字符串)的类。
  • Tag 是由 TagIn 生成的,并增加了两个字段:created(创建时间)和 secret(内部字符串,可能存储在数据库中,但永远不会向外界公开)。
  • TagOut 是定义可以返回给用户(通过查询或搜索终端)的内容的类。它包含来自原始 TagIn 对象及其派生 Tag 对象的标签字段,以及为 Tag 生成的创建字段,但不是秘密字段。
  1. from datetime import datetime
  2. from pydantic import BaseClass
  3. class TagIn(BaseClass):
  4.     tag: str
  5. class Tag(BaseClass):
  6.     tag: str
  7.     created: datetime
  8.     secret: str
  9. class TagOut(BaseClass):
  10.     tag: str
  11.     created: datetime
复制代码
您可以通过不同方式从FastAPI路径函数返回默认JSON以外的数据类型。其中一种方法是在路径装饰器中使用 response_model 参数,让 FastAPI 返回其他类型的数据。FastAPI 将放弃任何在返回对象中存在但不在 response_model 指定的对象中的字段。
假设你编写了一个名为 service/tag.py 的新服务模块,其中包含 create() 和 get() 函数,为该网络模块提供了调用的内容。这些低层堆栈细节在这里并不重要。重要的是底部的 get_one() 路径函数,以及路径装饰器中的 response_model=TagOut。这会自动将内部 Tag 对象转换为经过消毒的 TagOut 对象。
  1. import datetime
  2. from fastapi import FastAPI
  3. from model.tag import TagIn, Tag, TagOut
  4. import service.tag as service
  5. app = FastAPI()
  6. @app.post('/')
  7. def create(tag_in: TagIn) -> TagIn:
  8.     tag: Tag = Tag(tag=tag_in.tag, created=datetime.utcnow(),
  9.         secret="shhhh")
  10.     service.create(tag)
  11.     return tag_in
  12. @app.get('/{tag_str}', response_model=TagOut)
  13. def get_one(tag_str: str) -> TagOut:
  14.     tag: Tag = service.get(tag_str)
  15.     return tag
复制代码
尽管我们返回的是 Tag,但response_model会将其转换为 TagOut。
3.5 自动化文档

上面3.3.3 POST的自动文档http://localhost:8000/docs。

FastAPI会根据您的代码生成一个OpenAPI规范,并包含这个页面来显示和测试您的所有端点。这只是其秘诀之一。
单击绿色框右侧的向下箭头,打开它进行测试。

点击右侧的 "试用 "按钮。现在你会看到一个区域,可以在正文部分输入数值(。

点击 "字符串"。将其更改为 "Cousin Eddie"(保留双引号)。然后单击底部的蓝色 "执行 "按钮。

3.6复杂数据

这些示例只展示了如何向端点传递单个字符串。许多端点,尤其是 GET 或 DELETE 端点,可能根本不需要参数,或者只需要几个简单的参数,如字符串和数字。但在创建(POST)或修改(PUT 或 PATCH)资源时,我们通常需要更复杂的数据结构。第 5 章展示了 FastAPI 如何使用 Pydantic 和数据模型来简洁地实现这些功能。
3.7小结

在本章中,我们使用 FastAPI 创建了一个只有一个端点的网站。多个网络客户端对其进行了测试:网络浏览器、HTTPie 文本程序、Requests Python 包和 HTTPX Python 包。从简单的 GET 调用开始,请求参数通过 URL 路径、查询参数和 HTTP 标头进入服务器。然后,HTTP 主体被用来向 POST 端点发送数据。随后,本章展示了如何返回各种 HTTP 响应类型。最后,自动生成的表单页面为第四个测试客户端提供了文档和实时表单。

来源:https://www.cnblogs.com/testing-/p/18233400
免责声明:由于采集信息均来自互联网,如果侵犯了您的权益,请联系我们【E-Mail:cb@itdo.tech】 我们会及时删除侵权内容,谢谢合作!

本帖子中包含更多资源

您需要 登录 才可以下载或查看,没有账号?立即注册

x

举报 回复 使用道具