FastAPI快速入门：环境搭建+第一个接口

FastAPI快速入门环境搭建第一个接口文章信息标题FastAPI快速入门环境搭建第一个接口字数4200字预估阅读时间18分钟难度⭐☆☆☆☆一、为什么选择FastAPI在2026年的Python Web框架生态中FastAPI已经成为继Django之后最受欢迎的框架。FastAPI 已成为 AI 工程领域最主流的 Web 框架之一主要原因有三自动生成API文档启动服务即拥有Swagger UI和ReDoc无需手动编写文档基于类型提示的验证Pydantic深度集成数据验证和序列化的代码量减少60%异步原生支持基于StarletteASGI Web框架同步/异步代码写法一致性能对标Node.js和Go本文将带你从零搭建FastAPI开发环境完成第一个接口并配置完整的开发工作流。二、环境准备2.1 Python版本选择FastAPI 0.115 支持Python 3.10。推荐使用Python 3.12或3.13因为PEP 709推导式内联Inlined comprehensions列表推导等性能提升PEP 695内置type语句简化类型别名定义性能提升3.12比3.11快15-25%来源Python 3.12 Release Notes2.2 虚拟环境创建有两种方式创建虚拟环境方式1uv推荐# 安装uv如果未安装curl-LsSfhttps://astral.sh/uv/install.sh|sh# 创建项目目录mkdirfastapi-ai-columncdfastapi-ai-column# 初始化项目生成pyproject.tomluv init--python3.12# 创建虚拟环境uv venv# 激活虚拟环境source.venv/bin/activate# Linux/macOS# 或 .venv\Scripts\Activate.ps1 # Windows PowerShell# 或 .venv\Scripts\activate.bat # Windows CMD方式2venv标准库python3.12-mvenv .venvsource.venv/bin/activate特性uvvenv创建速度秒级10-30秒依赖安装并行缓存单线程锁文件支持uv.lock无跨平台★★★★★★★★★☆2.3 安装FastAPI和Uvicorn# 安装FastAPI和uvicorn带热重载版本uv pipinstallfastapi uvicorn[standard]# 验证安装python-cimport fastapi; print(fastapi.__version__)# 输出0.115.0 或更高版本版本说明到2026年5月FastAPI最新稳定版为0.115.x。如果你想体验最新功能可以使用uv pip install fastapi --pre安装预览版。三、第一个API接口3.1 项目结构fastapi-ai-column/ ├── .env # 环境变量 ├── .env.example # 环境变量模板 ├── app/ │ ├── __init__.py │ ├── main.py # 主应用入口 │ ├── config.py # 配置管理 │ └── routers/ │ ├── __init__.py │ └── hello.py # 示例路由 ├── tests/ # 测试目录 ├── pyproject.toml # 项目配置uv生成 └── uv.lock # 依赖锁文件uv生成3.2 最小可运行应用创建app/main.py先初始化应用实例fromfastapiimportFastAPI appFastAPI(titleFastAPI AI助手,descriptionAI应用后端服务,version1.0.0,docs_url/docs,# Swagger UI地址redoc_url/redoc# ReDoc地址)FastAPI()的几个关键参数title/description出现在自动生成的 API 文档顶部用户打开/docs就能看到docs_urlSwagger UI 的路径默认就是/docs可以自定义或设为None禁用然后添加两个路由——一个根路径返回欢迎信息一个健康检查接口K8s/Docker 常用app.get(/)asyncdefroot():return{message:欢迎使用FastAPI AI助手,version:1.0.0,docs:/docs}app.get(/health)asyncdefhealth_check():return{status:healthy,service:fastapi-ai-column}为什么要有/health接口容器编排系统Docker、K8s通过定期请求健康检查端点来判断服务是否存活。如果返回非 200容器会被自动重启。3.3 运行应用方式1命令行运行推荐开发使用# 基本启动uvicorn app.main:app--host0.0.0.0--port8000# 带热重载的启动开发环境uvicorn app.main:app--reload--port8000# 指定workers数量uvicorn app.main:app--workers4启动输出INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRLC to quit) INFO: Swagger UI available at http://localhost:8000/docs INFO: ReDoc available at http://localhost:8000/redoc方式2代码内启动调试用if__name____main__:importuvicorn uvicorn.run(app.main:app,host0.0.0.0,port8000,reloadTrue,log_levelinfo)踩坑记录1在Windows的PowerShell中运行uvicorn --reload可能会遇到Permission denied错误。解决方案升级uvicorn到最新版本通常可解决此问题或尝试以管理员权限运行PowerShell。四、路由装饰器详解4.1 装饰器基础FastAPI的路由装饰器基于HTTP方法命名格式为app.method(path)。fromfastapiimportFastAPIfrompydanticimportBaseModel appFastAPI()# GET请求 - 查询app.get(/users/{user_id})asyncdefget_user(user_id:int):return{user_id:user_id,name:张三}# POST请求 - 创建classUserCreate(BaseModel):name:stremail:strapp.post(/users)asyncdefcreate_user(user:UserCreate):return{id:1,**user.model_dump()}# PUT请求 - 完整更新app.put(/users/{user_id})asyncdefupdate_user(user_id:int,user:UserCreate):return{user_id:user_id,**user.model_dump()}# PATCH请求 - 部分更新app.patch(/users/{user_id})asyncdefpatch_user(user_id:int,user:UserCreate):return{user_id:user_id,**user.model_dump()}# DELETE请求 - 删除app.delete(/users/{user_id})asyncdefdelete_user(user_id:int):return{deleted:user_id}4.2 路径参数类型FastAPI 会自动把路径中的{参数}转换为函数参数并根据类型注解自动做类型转换和验证fromfastapiimportFastAPI,PathfromtypingimportAnnotated appFastAPI()# int 类型 → 自动把 URL 中的字符串转为整数app.get(/users/{user_id})asyncdefget_user(user_id:int):return{user_id:user_id}# str 类型 → 直接接收字符串app.get(/users/by-name/{username})asyncdefget_user_by_name(username:str):return{username:username}如果传/users/abcFastAPI 会自动返回 422 错误因为abc不能转为int。这就是类型提示即验证的核心理念。进阶用法——用AnnotatedPath添加更精细的验证规则app.get(/users/validated/{user_id})asyncdefget_user_validated(user_id:Annotated[int,Path(gt0,le1000,description用户ID)]):return{user_id:user_id}gt0表示大于 0le1000表示小于等于 1000。访问/users/0会返回验证错误。4.3 查询参数fromfastapiimportFastAPI,QueryfromtypingimportAnnotated,Optional appFastAPI()# 必选查询参数app.get(/search)asyncdefsearch(q:strQuery(...)):return{q:q}# 有默认值的查询参数app.get(/items)asyncdeflist_items(limit:intQuery(10,ge1,le100),offset:intQuery(0,ge0)):return{items:[],limit:limit,offset:offset}# 可选查询参数app.get(/users)asyncdeflist_users(name:Optional[str]Query(None),age:Annotated[int,Query(ge0,le150)]None):filters{}ifname:filters[name]nameifageisnotNone:filters[age]agereturn{filters:filters}4.4 请求体fromfastapiimportFastAPI,BodyfrompydanticimportBaseModelfromtypingimportOptional appFastAPI()classItem(BaseModel):name:strdescription:Optional[str]Noneprice:floatquantity:int1# 单个Body参数app.post(/items)asyncdefcreate_item(item:Item):returnitem# 多个Body参数使用Body显式指定app.post(/items/multiple)asyncdefcreate_item_multiple(item:ItemBody(...),category:strBody(...)):return{item:item,category:category}踩坑记录2当有两个Body参数时FastAPI无法自动识别。解决方案有两种使用Pydantic嵌套模型使用Body(...)显式标记每个参数五、交互式文档5.1 Swagger UI访问 http://localhost:8000/docs你会看到自动生成的API文档界面。这个文档可以直接测试API自动填充请求参数显示所有endpoint支持导出OpenAPI规范5.2 ReDoc访问 http://localhost:8000/redoc你会看到另一种风格的文档更清晰的文档导航适合API规范展示不支持直接测试5.3 自定义文档fromfastapiimportFastAPIfromfastapi.openapi.docsimportget_redoc_html,get_swagger_ui_html appFastAPI()app.get(/docs,include_in_schemaFalse)asyncdefcustom_swagger_ui():自定义Swagger UIreturnget_swagger_ui_html(titleMy API - Swagger UI,openapi_urlapp.openapi_url)app.get(/redoc,include_in_schemaFalse)asyncdefcustom_redoc():自定义ReDocreturnget_redoc_html(titleMy API - ReDoc,openapi_urlapp.openapi_url)六、开发模式配置6.1 环境变量管理安装配置管理依赖uv pipinstallpydantic-settings python-dotenv创建.env文件# .envAPP_NAMEFastAPI-AI-AssistantAPP_VERSION1.0.0DEBUGtrueHOST0.0.0.0PORT8000# 数据库配置DATABASE_URLsqliteaiosqlite:///./data.db# API密钥DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxx创建app/config.py 配置管理 frompydantic_settingsimportBaseSettings,SettingsConfigDictfromtypingimportOptionalclassSettings(BaseSettings):应用配置model_configSettingsConfigDict(env_file.env,env_file_encodingutf-8,case_sensitiveFalse,extraignore# 忽略额外字段)# 应用配置app_name:strFastAPI-AI-Assistantapp_version:str1.0.0debug:boolFalse# 服务器配置host:str0.0.0.0port:int8000# 数据库配置database_url:strsqliteaiosqlite:///./data.db# API配置deepseek_api_key:Optional[str]None# CORS配置cors_origins:list[*]# 全局配置实例settingsSettings()6.2 使用配置fromfastapiimportFastAPIfromapp.configimportsettings appFastAPI(titlesettings.app_name,versionsettings.app_version)app.get(/config)asyncdefshow_config():展示当前配置return{app_name:settings.app_name,debug:settings.debug,port:settings.port}if__name____main__:importuvicorn uvicorn.run(app.main:app,hostsettings.host,portsettings.port,reloadsettings.debug)踩坑记录3在.env文件中尽量避免使用中文因为python-dotenv在Windows下可能有编码问题。建议配置值使用英文或ASCII字符。6.3 生产环境配置# .env.prod生产环境DEBUGfalse HOST0.0.0.0PORT8000LOG_LEVELwarning启动生产模式# 使用生产配置文件uvicorn app.main:app--host0.0.0.0--port8000--workers4# 或指定配置文件uvicorn app.main:app--host0.0.0.0--port8000--env-file .env.prod七、请求/响应模型7.1 响应模型FastAPI 的response_model参数有两个作用自动序列化返回数据为 JSON自动过滤掉不该暴露的字段比如密码。先定义请求和响应的 Pydantic 模型frompydanticimportBaseModelfromdatetimeimportdatetimefromtypingimportOptional,ListclassItem(BaseModel):name:strprice:floatclassUserResponse(BaseModel):响应模型定义返回给客户端的字段id:intname:stremail:strcreated_at:datetime items:Optional[List[Item]]NoneclassUserCreate(BaseModel):请求模型定义客户端需要传的字段name:stremail:strpassword:str注意UserResponse没有password字段——即使数据库存了密码也不会返回给客户端。这就是response_model的价值。然后在路由中使用fromfastapiimportFastAPIfromdatetimeimportdatetime appFastAPI()app.post(/users,response_modelUserResponse)asyncdefcreate_user(user:UserCreate):# 实际项目中这里会插入数据库returnUserResponse(id1,nameuser.name,emailuser.email,created_atdatetime.now(),items[Item(name默认商品,price0.0)])response_modelUserResponse确保返回值自动过滤掉password等敏感字段同时 Swagger 文档也会展示UserResponse的结构。7.2 状态码控制fromfastapiimportFastAPI,HTTPException,status appFastAPI()app.post(/items,status_codestatus.HTTP_201_CREATED)asyncdefcreate_item():创建成功返回201return{id:1}app.delete(/items/{item_id},status_codestatus.HTTP_204_NO_CONTENT)asyncdefdelete_item(item_id:int):删除成功返回204ifitem_id0:raiseHTTPException(status_codestatus.HTTP_404_NOT_FOUND,detailItem not found)# 返回None会产生204状态码returnNone八、踩坑记录8.1 Windows/macOS/Linux差异问题原因解决方案热重载不生效Windows文件系统事件延迟升级uvicorn到最新版本路径斜杠问题Windows与Linux路径分隔符不同使用pathlib.Path处理路径中文乱码Windows CMD默认GBK编码环境变量设置PYTHONIOENCODINGutf-8端口被占用某些服务占用8000端口改用其他端口如80018.2 常见错误错误1端口被占用# 查找占用端口的进程lsof-i:8000# macOS/Linuxnetstat-ano|findstr :8000# Windows# 结束进程kill-9PID# macOS/Linuxtaskkill /F /PIDPID# Windows错误2模块导入失败# 检查是否在虚拟环境中whichpython# 应该指向.venv/bin/python# 重新安装依赖uv pipinstall-rrequirements.txt# 或uv pipinstall-e.错误3CORS跨域问题fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddleware appFastAPI()app.add_middleware(CORSMiddleware,allow_origins[*],allow_credentialsTrue,allow_methods[*],allow_headers[*],)九、总结本文我们完成了✅ 环境搭建Python 3.12 uv虚拟环境 FastAPI安装✅ 第一个API最小可运行应用 健康检查✅ 路由装饰器GET/POST/PUT/DELETE 路径/查询/Body参数✅ 交互式文档Swagger UI ReDoc✅ 开发配置.env pydantic-settingsFastAPI的核心优势在于用最少的代码得到最完整的API。下一篇文章我们将深入学习Pydantic模型掌握请求/响应数据验证的精髓。下篇预告《请求/响应模型Pydantic从入门到实战》自定义验证器嵌套模型高级用法computed_field、model_validator