基于FastAPI的AI智能体Web系统构建（一）
目录一.FastAPI介绍二.FastAPI环境搭建三.FastAPI第一个 API与启动项目四.用AI生成API接口五.FastAPI路径参数六.FastAPI查询参数七.FastAPI请求体1.Query方式2.Path方式3.Field方式一.FastAPI介绍FastAPI 是目前 Python ASGI 原生异步框架里使用量、社区生态、下载量最高的主流框架底层基于轻量 ASGI 框架Starlette原生 ASGI、默认 async/await主打高性能 API 开发、类型校验、自动 OpenAPI 文档、适配 AI / 模型部署场景社区活跃度极高、企业应用非常广泛大模型后端、微服务、流式接口其他重要 ASGI 异步框架Quart语法高度兼容 Flask 的纯 ASGI 异步微框架适合 Flask 老项目迁移全异步Starlette底层轻量 ASGI 基础框架FastAPI 的基座适合自建轻量异步服务Litestar / Sanic / BlackSheep高性能备选 ASGI 异步框架各有侧重但整体普及度不及 FastAPIDjangoASGI 模式属于混合架构非从头原生 ASGI不是纯异步框架ASGI 服务器≠框架Uvicorn/Hypercorn/Daphne 是 ASGI服务器不是开发框架不要混淆一句话总结做 API/AI 后端首选FastAPI是当下最主流的原生 ASGI 异步 Web 框架flask 和 Django 现在支持异步了吗Flask✅有部分异步支持从 Flask 2.0 版本开始可以编写async def异步视图、错误处理器、请求钩子before_request/after_request 等需要安装flask[async]用 ASGI 服务器如 Uvicorn/Hypercorn运行才能真正发挥异步价值Flask❗不是原生全栈异步框架底层基础架构最初是 WSGI 同步模型并非从头到尾 asyncio 架构默认 WSGI 运行时无法实现真正协程并发。如需完整异步体验官方生态可参考Quart语法和 Flask 高度兼容的纯 ASGI 异步框架Django✅支持异步从 Django 3.1 开始引入异步视图、ASGI 部署能力后续版本持续完善Django可写async def异步视图、中间件、信号、缓存、ORM 异步接口支持 ASGI 部署Uvicorn/Daphne实现全异步请求栈提供sync_to_async/async_to_sync工具做同步 / 异步代码适配逐步完善异步 ORM、表单、模板等组件新版持续完善中WSGI 模式也能跑异步视图但性能不佳必须 ASGI 部署才能获得完整异步收益Django❗不是一开始就是纯异步架构还有部分老组件是同步实现存在异步安全限制不能直接在异步上下文随意调用旧同步接口会报SynchronousOnlyOperation错误需要适配处理Django总结两者都支持 async/await 异步写法和 ASGI 部署但都不属于原生从头设计的纯异步框架Flask异步视图可用但整体架构仍以 WSGI 同步为基础异步能力有限Django具备成熟 ASGI 异步视图 / ORM 能力但仍有历史同步组件需要适配追求极致全栈异步开发FastAPI、Quart 这类原生 ASGI 框架会更合适FastAPI是一个现代、高性能的Python Web框架用于构建API。 它基于Starlette异步Web框架和Pydantic数据验证 库结合了异步编程和类型提示兼顾开发效率与运行性能。文档https://fastapi.tiangolo.com源码https://github.com/tiangolo/fastapiFastAPI的核心优势高性能FastAPI基于异步I/O性能接近Node.js和Go。 使用UvicornASGI服务器支持高并发请求。性能对比基于TechEmpower等基准测试简化为每秒请求 数FastAPI~3000请求/秒异步轻量Flask~1000请求/秒同步受WSGI限制Django~800请求/秒同步ORM和中间件开销较大类型提示提升开发效率FastAPI使用Python类型提示通过Pydantic进行数据验证减少手动校验代码。类型提示使代码更易读IDE如VSCode提供自动补全和错误提示。示例定义一个带类型提示的API端点提示上述代码自动验证请求体中的name字符串、price浮点数和 is_offer布尔值可选无需手动解析JSON。自动生成API文档FastAPI内置Swagger UI和ReDoc自动生成交互式API文档。开发者只需编写代码文档即自动生成减少维护成本。异步支持支持async/await语法适合高并发场景如实时聊天、流处理。比传统同步框架如Flask更适合现代Web应用。为什么选择FastAPI开发速度快类型提示和自动文档减少重复工作。性能优异异步架构支持高并发适合生产环境。社区活跃快速增长的生态兼容Starlette和Pydantic的扩展。易于上手Python开发者只需掌握基本类型提示即可快速构建API。CGI/WSGI/ASGI了解CGI是最早的通用接口解决服务器与动态内容生成程序的通信问题但性能低下。WSGI针对Python生态优化取代CGI成为Python Web开发的主流标准专注于同步Web应用。ASGI是WSGI的升级适应异步编程和现代Web需求如WebSocket、HTTP/2兼容WSGI 应用。现在 python 的 web 框架都开始从同步转向异步了还是说异步和同步以后都会存在都有各自适用的场景不是全部转向纯异步而是两条路线长期共存存量全栈网站 / 后台继续以 WSGI 同步为主高并发 IO / 长连接 / AI 接口业务越来越多用原生 ASGI 异步框架异步 ≠ 更好只是适合 IO 密集高并发 / 长连接场景同步更适合传统全栈 Web 和低并发内部系统二.FastAPI环境搭建uv和conda创建虚拟环境的区别uv venv 轻量 Python-only 虚拟环境基于 PyPI 生态、共享解释器、超快、适合纯 Python 云原生开发conda 全量跨语言前缀环境每个虚拟环境都有完整独立解释器 底层二进制库、适合 GPU / 科研数值计算uv venv 适合纯 Python Web 开发FastAPI、Quart 等 ASGI 服务、后端微服务、云原生容器部署日常 Python 开发、CI/CD 自动化构建、快速迭代原型不涉及复杂 GPU 底层库、纯 Python 业务代码现代 Python 项目pyproject.toml uv.lock 工程化管理Conda 适合深度学习 GPU 训练、科研数据分析、数值计算、生物信息、R 语言混合开发Windows 科学计算开发、需要精准匹配 CUDA、MKL、OpenBLAS 等底层二进制 ABI 版本长期稳定科研环境、可复现实验环境、跨语言混合项目所以conda占用磁盘空间大更笨重本文开发场景选择uv来创建虚拟环境。和刚写的小说系统里一样的操作uv inituv venv .venv然后激活。然后安装FastAPIuv pip install fastapi[standard]三.FastAPI第一个API与启动项目三种启动方式前两种为命令行第三种为编辑器运行如下# 第一个fastapi程序 import uvicorn from fastapi import FastAPI app01 FastAPI() app01.get(/) def read_root(): return {Hello: World123} # 启动服务 # 1. 通过命令: uvicorn filename:app_name --reload #启动服务并reload自动重新加载代码内容 #eg : uvicorn main01:app01 --reload # 如果被系统的安全软件阻止的话改用 Python 模块方式启动python -m uvicorn main01:app01 --reload # 2. 通过调试: fastapi dev filename.py # 需要安装fastapi[standard] #eg : fastapi dev main01.py 默认重新加载代码改动部分 # 3. 通过py运行: python filename.py eg:python main01.py # 要有运行项目的代码如下 if __name__ __main__: #第一种写法可以加reload参数代码修改后会自动重新加载 uvicorn.run(main01:app01, host127.0.0.1, port8000, reloadTrue) #第二种写法不能加reload参数代码修改后不会自动重新加载 # uvicorn.run(app01, host127.0.0.1, port8000) #不让加reload访问结果如图所示四.用AI生成API接口使用AI生成FastAPI代码AI工具可以通过自然语言提示生成代码。我们将模拟使用AI生成一个简单的FastAPI应用。deepseekhttps://chat.deepseek.com/豆包https://www.doubao.com/chat/通义https://www.tongyi.com/qianwen/Kimihttps://kimi.moonshot.cn/等等注意事项AI生成的代码可能存在小错误如缺少字段约束需手动检查AI的生成的问题1AI生成代码的局限性缺乏上下文理解AI生成的代码可能符合语法但未必适配实际业务逻辑如身份验证流程、数据库设计。难以维护与调试若学生只会“复制粘贴”遇到错误或需求变更时将束手无策。部署与运维盲区AI通常不涉及服务器配置、性能优化、监控等生产环境关键环节。2核心能力的不可替代性架构设计思维如何划分模块、设计REST API、管理依赖关系需系统性训练。调试与问题定位理解上下文机制、请求生命周期才能快速排查异常。安全与性能意识防止SQL注入、XSS攻击或优化数据库查询需人工介入设计。方式一网页版方式二插件版五.FastAPI路径参数和Java差不多自己看看吧# 路径参数 from fastapi import FastAPI app FastAPI() app.get(/args1/1) def path_args1(): return {message: id1} #非固定参数 app.get(/args2/{id}) def path_args2(id): return {message: id} app.get(/args3/{id}) def path_args3(id): return {message2: id} app.get(/args4/{id}/{name}) #可以指定参数类型也可以是多个参数 def path_args4(id: int, name): return {message: id, name: name} if __name__ __main__: import uvicorn uvicorn.run(main03:app, host127.0.0.1, port8000, reloadTrue)六.FastAPI查询参数查询参数查询字符串是键值对的集合这些键值对位于URL的?之后以分隔例如http://127.0.0.1:8000/items/?page1limit10# 查询参数 from fastapi import FastAPI app FastAPI() app.get(/query1) def page_limit(page, limit): return {page: page, limit: limit} app.get(/query2) def page_limit2(page: int, limitNone): if limit: return {page: page, limit: limit} return {page: page} # 路径参数和查询参数同时使用 app.get(/query3/{page}) def page_limit3(page: int, limitNone): if limit: return {page: page, limit: limit} return {page: page} if __name__ __main__: import uvicorn uvicorn.run(main04:app, host127.0.0.1, port8000, reloadTrue)七.FastAPI请求体FastAPI使用请求体从客户端例如浏览器向API发送数据。请求体是客户端发送给API的数据。发送数据使用POST最常用、PUT、DELETE、PATCH等操作。# 请求体 传参数 from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class User(BaseModel): name: str age: int #要么是 str 要么是 None pwd: str | None sex: str 男 app.post(/users) def create_user(user: dict): return user app.post(/users2) def create_user2(user: User): return user if __name__ __main__: import uvicorn uvicorn.run(main05:app, host127.0.0.1, port8000, reloadTrue)1.Query方式用于校验查询参数。# 查询参数Query from fastapi import FastAPI, Query app FastAPI() app.get(/items1) def read_item1(item_id: str Query(123)): # 默认值是123,如果不传递参数返回的就是123 return {item_id: item_id} app.get(/items2) def read_item2(item_id: str Query(...)): 三个点代表必须传递 return {item_id: item_id} app.get(/items3) def read_item3(item_id: str Query(..., min_length3, max_length6)): 必须传递,限制内容长度 return {item_id: item_id} app.get(/items4) def read_item4(item_id: int Query(..., gt0, lt100)): 必须传递,限制内容大小例子中为大于0小于100 return {item_id: item_id} app.get(/items5) def read_item5(item_id: int Query(..., aliasid)): 必须传递,修改名称例子中为id但是返回的还是item_id即用id来引用item_id return {item_id: item_id} app.get(/items6) def read_item6(item_id: int Query(..., description这个字段是来筛选产品的ID)): 必须传递,说明描述 return {item_id: item_id} app.get(/items7) def read_item7(item_id: int Query(..., deprecatedTrue)): 必须传递,被抛弃了做说明用的让人家知道这个不用了 return {item_id: item_id} app.get(/items8) def read_item8(item_id: str Query(..., regex^a\d{2}$)): 必须传递,通过正则匹配同功能参数pattern,regex return {item_id: item_id} if __name__ __main__: import uvicorn uvicorn.run(main07:app, host127.0.0.1, port8000, reloadTrue)2.Path方式用于校验路径参数。# 路径参数Path from typing import Annotated from pydantic import BeforeValidator from enum import Enum from fastapi import FastAPI, Path app FastAPI() # python原生类型注解 app.get(/items1/{item_id}) def read_item1(item_id: int): return {item_id: item_id} # 必填 app.get(/items2/{item_id}) def read_item2(item_id: int Path(...)): return {item_id: item_id} # 限制范围 app.get(/items3/{item_id}) def read_item3(item_id: int Path(..., lt100, gt18)): return {item_id: item_id} # 正则匹配 app.get(/items4/{item_id}) def read_item4(item_id: str Path(..., patternr^a\d{2}$)): regex或者pattern return {item_id: item_id} class ModelName(str, Enum): alexnet alexnet resnet resnet lenet lenet # 等价于如下的写法类里面的成员是str类型 from enum import StrEnum class ModelName(StrEnum): alexnet alexnet resnet resnet lenet lenet # 枚举类型model只能是alexnet、resnet、lenet app.get(/items5/{model}) def read_item5(model: ModelName): return {model: model} # 自定义类型 def validate(value): if not value.startswith(P-): raise ValueError(必须以P-开头) return value # 创建带验证的类型别名 Item Annotated[str, BeforeValidator(validate)] app.get(/items6/{item_id}) def read_item6(item_id: Item): return {item_id: item_id} if __name__ __main__: import uvicorn uvicorn.run(appmain09:app, host127.0.0.1, port8000, reloadTrue)3.Field方式FastAPI中的Field是Pydantic提供的核心验证工具用于为模型字段添加校验规则和元数据。前两个和函数搭配这个和类搭配。# Field验证方式 from enum import Enum from pydantic import field_validator from fastapi import FastAPI from pydantic import BaseModel, Field app FastAPI() class User(BaseModel): name: str Field(default吕布) age: int Field(...) # 必填 app.post(/users/) def create_user(user: User): return user class Product(BaseModel): price: float Field(..., gt0, le1000, description价格) app.post(/products/) def create_product(product: Product): return product class Account(BaseModel): username: str Field(..., min_length3, max_length20) password: str Field(..., patternr^\w{6,}$) app.post(/accounts/) def create_account(account: Account): return account class Item(BaseModel): name: str Field(..., title商品名称, description必填长度不要超过50字符, example手机) app.post(/items/) def create_item(item: Item): return item class User2(BaseModel): email: str field_validator(email) def email_validator(cls, v): if not in v: raise ValueError(邮箱格式错误) return v app.post(/users2/) def create_user2(user: User2): return user class Order(BaseModel): items: list Field(..., min_items1) address: str Field(..., description配送地址) app.post(/orders/) def create_order(order: Order): return order class Status(str, Enum): ACTIVE active INACTIVE inactive class Task(BaseModel): status: Status Field(defaultStatus.ACTIVE) app.post(/tasks/) def get_task(): return Task() if __name__ __main__: import uvicorn uvicorn.run(appmain10:app, host127.0.0.1, port8000, reloadTrue)
