深入剖析 FastAPI 示例应用：从零构建随机数生成与条目管理 Web API-北京尧图网络

示例工程教程【免费下载链接】materialsBonus materials, exercises, and example projects for our Python tutorials项目地址https://gitcode.com/gh_mirrors/ma/materials点击查看免费下载本篇技术指南以 fastapi-python-web-apis 仓库中的示例应用为核心带你逐行解析一个完整可运行的 FastAPI 项目它同时涵盖了随机数生成与条目管理两类业务场景演示了路由设计、参数校验、Pydantic 响应模型、异常处理与 CORS 配置等 FastAPI 的核心能力。读完本文你将掌握如何从安装依赖、组织应用元数据开始一步步搭建并调试一个具备增删改查能力的实战型 API。环境安装用[standard]扩展依赖一步到位仓库 README.md 给出了官方推荐的安装方式——使用 FastAPI 的[standard]扩展依赖$ python -m pip install fastapi[standard]之所以要加上双引号是因为fastapi[standard]中的方括号在部分终端如 zsh里属于特殊字符会被 shell 解释为通配或语法标记导致安装失败用引号包裹后即可在各类终端和操作系统上稳定执行。这条命令不只是安装 FastAPI 核心库本身还会一并带来开发 API 时常用的配套工具FastAPI CLI提供fastapi dev、fastapi run等便捷命令可用于启动应用与热重载开发uvicornFastAPI 官方依赖的 ASGI 服务器负责真正把应用跑起来并处理网络请求。如果你希望锁定精确的依赖版本也可以直接使用仓库内的 requirements.txt$ python -m pip install -r requirements.txt该文件以冻结版本方式列出了完整依赖链包括fastapi0.119.0、pydantic2.12.3、uvicorn0.38.0、starlette0.48.0以及httpx、Jinja2等间接依赖适合需要可复现环境的场景。项目全貌一个随机数条目管理的完整示例本仓库结构非常精简只有三个文件文件作用README.md安装说明与依赖指引main.pyFastAPI 应用的全部源码requirements.txt冻结版本的依赖清单应用名为Randomizer API业务上分为两大块对应源码中定义的tags_metadata见 main.pyRandom Playground随机游乐场生成随机数字演示路径参数与查询参数Random Items Management随机条目管理对内存中的条目列表做创建、乱序、读取、更新和删除演示完整的增删改查循环。这套设计非常适合作为学习 FastAPI 的切入点代码量小、无外部数据库依赖却几乎覆盖了 FastAPI 官方文档中最常用的特性。应用初始化与 OpenAPI 元数据示例应用通过FastAPI(...)构造函数一次性配置了四项元数据见 main.pyapp FastAPI( titleRandomizer API, descriptionShuffle lists, pick random items, generate random numbers., version1.0.0, openapi_tagstags_metadata, )参数取值示例作用titleRandomizer APIAPI 的名称会显示在自动文档页面上description一段英文描述在文档页展示的功能概述version1.0.0接口版本号便于发布管理openapi_tagstags_metadata列表为接口分组每个分组带名称与描述让/docs页面按业务模块组织其中openapi_tags是 FastAPI 组织接口文档的利器当路由数量变多时为每个路由标注tags参数即可让文档自动按标签分组本例将接口划分成了 Random Playground 与 Random Items Management 两组。启动应用后访问/docsSwagger UI和/redocReDoc即可看到基于这些元数据自动生成的交互式 API 文档。响应模型用 Pydantic 定义数据契约FastAPI 与 Pydantic 深度集成示例中定义了五个数据模型见 main.py它们既承担请求体校验又负责约束响应结构class Item(BaseModel): name: str Field( min_length1, max_length100, descriptionThe item name )Item是唯一的请求模型接收 JSON 请求体并校验name字段——长度必须在 1 到 100 个字符之间。其余四个均为响应模型ItemResponse返回message与新增的itemItemListResponse返回original_order原顺序、randomized_order乱序后的列表与count条目数ItemUpdateResponse返回message、old_item与new_itemItemDeleteResponse返回message、deleted_item与剩余条目数remaining_items_count。在路由装饰器中通过response_model...声明后FastAPI 会自动完成响应数据的序列化与结构校验确保返回给客户端的 JSON 始终符合模型契约——这是它相比普通函数返回 dict 的一大优势字段拼写错误或类型不符会在开发阶段就被暴露。路由设计从路径参数到查询参数示例最值得学习的地方在于三种不同的参数传递方式全部集中在 Random Playground 分组中。1. 无参数路由见 main.pyapp.get(/, tags[Random Playground]) def home(): return {message: Welcome to the Randomizer API}最基础的GET /接口作为服务健康检查或首页说明。2. 路径参数见 main.pyapp.get(/random/{max_value}, tags[Random Playground]) def get_random_number(max_value: int): return {max: max_value, random_number: random.randint(1, max_value)}{max_value}是路径模板变量函数签名中的类型注解int让 FastAPI 自动完成字符串到整数的转换与校验——如果传入非数字会直接返回 422 校验错误而非抛异常。3. 带校验的查询参数见 main.pyapp.get(/random-between, tags[Random Playground]) def get_random_number_between( min_value: Annotated[ int, Query( titleMinimum Value, descriptionThe minimum random number, ge1, le1000, ), ] 1, max_value: Annotated[ int, Query( titleMaximum Value, descriptionThe maximum random number, ge1, le1000, ), ] 99, ):这是现代 FastAPI 推荐的写法用Annotated把Query的校验元数据直接挂在类型注解上。各参数含义如下配置含义title/description文档页中该参数的人类可读名称与说明ge1、le1000数值范围校验大于等于 1、小于等于 1000 1/ 99默认值调用方未传参数时生效接口内部还演示了业务级校验与 FastAPI 异常机制if min_value max_value: raise HTTPException( status_code400, detailmin_value cant be greater than max_value )当min_value大于max_value时抛出HTTPException(400)并携带可读的错误说明——这正是参数格式校验交给框架、业务约束校验写在代码里的典型分工。资源管理接口增删改查与状态码语义Random Items Management 分组用四个端点完整演示了对内存列表items_db见 main.py的增删改查并且每个端点都精心选择了语义化的 HTTP 状态码创建条目POST /items见 main.pyapp.post(/items, response_modelItemResponse, tags[Random Items Management]) def add_item(item: Item): if item.name in items_db: raise HTTPException(status_code400, detailItem already exists) items_db.append(item.name) return ItemResponse(messageItem added successfully, itemitem.name)重复添加同名条目时返回400成功时返回带message的响应模型。读取并乱序GET /items见 main.pyapp.get(/items, response_modelItemListResponse, tags[Random Items Management]) def get_randomized_items(): randomized items_db.copy() random.shuffle(randomized) return ItemListResponse( original_orderitems_db, randomized_orderrandomized, countlen(items_db), )先通过items_db.copy()复制列表再执行random.shuffle避免打乱原始数据响应中同时返回原顺序与乱序结果便于客户端对比验证。更新条目PUT /items/{update_item_name}见 main.pyif update_item_name not in items_db: raise HTTPException(status_code404, detailItem not found) if item.name in items_db: raise HTTPException(status_code409, detailAn item with that name already exists)这里展示了两个关键状态码目标条目不存在时返回404新名称与已有条目冲突时返回409资源冲突语义区分非常清晰。删除条目DELETE /items/{item}见 main.pyapp.delete(/items/{item}, response_modelItemDeleteResponse, ...) def delete_item(item: str): if item not in items_db: raise HTTPException(status_code404, detailItem not found) items_db.remove(item) return ItemDeleteResponse(...)删除不存在的条目同样返回404成功后响应中附带剩余条目数方便客户端同步状态。至此四个端点共同构成了一个完整、自洽的 REST 资源管理循环状态码语义400/404/409也符合业界约定。中间件为跨域请求配置 CORS如果这个 API 要提供给运行在localhost:3000的前端应用调用就必须处理浏览器的跨域限制。示例通过add_middleware注册了 FastAPI 内置的 CORS 中间件见 main.pyapp.add_middleware( CORSMiddleware, allow_origins[http://localhost:3000, https://example.com], allow_credentialsTrue, allow_methods[GET, POST, PUT, DELETE], allow_headers[*], )各配置项含义如下配置项取值说明allow_origins白名单列表仅允许列出的源跨域访问如本地前端http://localhost:3000allow_credentialsTrue允许请求携带 Cookie 等凭据allow_methods方法列表允许的 HTTP 方法本例按需放行增删改查allow_headers[*]允许携带任意自定义请求头从源码结构看CORS 中间件对跨域请求会自动附加Access-Control-Allow-*响应头浏览器据此决定是否放行——将来源收紧到白名单而非*全放行是保障生产环境安全的良好实践。运行与验证把示例应用跑起来安装依赖后在项目目录下有两种启动方式$ uvicorn main:app --reloadmain指 main.py 模块名app是该模块中创建的 FastAPI 实例--reload开启热重载改完代码保存即可自动生效适合开发调试。也可以使用 README 中提到的 FastAPI CLI$ fastapi dev main.py启动成功后访问以下地址验证地址内容http://127.0.0.1:8000/首页欢迎信息http://127.0.0.1:8000/random/10生成 110 之间的随机数http://127.0.0.1:8000/random-between?min_value5max_value50指定范围生成随机数http://127.0.0.1:8000/docsSwagger UI 交互式文档可在线调试每个接口http://127.0.0.1:8000/redocReDoc 风格的接口文档例如向POST /items发送{name: apple}即可创建条目随后通过GET /items观察原顺序与乱序结果当访问DELETE /items/not_exist时则能亲眼看到 404 与错误消息的返回。小结从示例中带走的设计要点通过逐段阅读 main.py可以提炼出几条可复用到自己项目中的核心经验元数据一次配齐title、description、version、openapi_tags让自动文档开箱即用参数校验交给类型注解路径参数、AnnotatedQuery的查询参数让 FastAPI 自动完成转换与范围校验响应模型即文档response_model约束返回结构前后端契约一目了然状态码承载语义400参数/业务错误、404不存在、409冲突各有明确用途中间件按需注册CORS 等中间件通过add_middleware一行接入白名单策略要从严。如果你希望进一步验证这套模式在真实服务中的表现还可以参考本仓库中其他 FastAPI 实战项目如 fastapi-url-shortener、fastapi-jinja2-template进行对比学习。赞分享示例工程教程【免费下载链接】materialsBonus materials, exercises, and example projects for our Python tutorials项目地址https://gitcode.com/gh_mirrors/ma/materials点击查看免费下载相关推荐Riverpod 示例精读用 Notifier NotifierProvider 构建随机数生成器Riverpod 示例精读用 Notifier NotifierProvider 构建随机数生成器本指南以仓库中的 random_number 示例 h前端移动开发Elm架构教程随机数生成示例解析Elm架构教程随机数生成示例解析还在为前端状态管理中的副作用处理而头疼吗Elm语言的函数式架构为你提供了优雅的解决方案本文将深入解析Elm架构中随机数生FastHTML 官方示例深度解析从零构建全栈 Python Web 应用FastHTML 官方示例深度解析从零构建全栈 Python Web 应用导读本篇文章围绕 FastHTML 仓库中的 examples 示例目录 htt后端Web框架上一篇【亲测免费】 Mistral 项目常见问题解决方案下一篇Android模块化路由终极指南ARouter与WMRouter深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

深入剖析 FastAPI 示例应用：从零构建随机数生成与条目管理 Web API

相关推荐

foobar2000 DUI 皮肤 foobox-cn：3 步完成安装并切换布局的入门配置指南

LibreCAD 图层树视图（Layer Tree View）详解：基于命名约定的层次化图层管理

AscendC Reg 矢量计算比较与选择（Compare/Compares/Select/Squeeze）API 实战指南

更多资讯

Raft算法实战指南：从原理到生产落地的分布式一致性详解

PAT甲级1104：连续子段求和的贡献法推导与long double精度坑

OpenAI SDK平滑迁移，如何零代码重构接入新API？

程序员英语词汇宝典精讲：consumption（消耗）——资源监控、消息消费与性能分析中的高频技术词汇

车辆动力学标定实战：从参数辨识到模型验证的完整流程

Apereo CAS 指标导出 Datadog 实战：Micrometer Registry 配置与运维指南

今日更新

防关联浏览器哪个好？三款产品实测差异解析

2026钢铁行业AI转型系统选型对比：多基地排产、大宗原燃料采购与质量追溯，六家厂商能力差异在哪里

影刀RPA深度实战：大模型Fine-tuning定制RPA专用Prompt与指令生成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？