之前看过一篇报告（文章），一句话结论就是：FastAPI几乎已经是Python生态下的第一流Web框架，参考FastAPI简介。
最佳实践
实际上指代开源（GitHub，16.8K Star，1.2K Fork）仓库，用Markdown形式记录的最佳实践文档。居然能收到近17K星星，值得一看。
| 痛点 | 结果 | 推荐做法 |
|---|---|---|
| 路由、模型混乱 | 难维护 | 按领域划分包，src/router.py等 |
| 异步阻塞 | 整个应用卡住 | async做非阻塞I/O，sync放线程池或外部进程 |
| Pydantic重复创建 | 性能浪费 | 自定义BaseModel、控制序列化 |
| 依赖散落 | 重复校验 | 小颗粒依赖、链式复用（依赖缓存） |
| 迁移不可逆 | 危险 | 明确命名、静态迁移脚本 |
实战小贴士
- 路径参数命名靠一致性：能复用依赖就别换名字；
- CPU密集任务别用
async或线程池，丢给worker（进程）去做； - docs默认隐藏，只有
dev/staging可见； - 把复杂聚合留给DB（SQL-first），Pydantic只做验证/序列化；
- 测试从一开始就用异步TestClient。
FastAPI-MCP
官网，开源（GitHub，11.7K Star，924 Fork）项目，零配置自动将FastAPI端点公开MCP工具，极大简化API的接入和管理。
优势
- 零配置开箱即用：通过几行代码即可将现有FastAPI路由暴露为标准MCP工具，极大缩短开发周期；
- 灵活路由隔离：支持多组MCP工具挂载在不同路径，便于按业务线、角色或权限隔离管理，满足多样化需求；
- 自动化文档与Schema支持：结合Pydantic能力，可自动生成响应/入参描述，提升工具的可发现性和可维护性；
- 易于扩展与集成：适用于内部辅助、知识库问答、流程自动化等一系列智能应用场景，助力快速将传统后端服务能力赋能LLM智能生态；
- 高效协同：多人团队协作时，前端/智能体/业务方无需关心底层接口细节，无缝实现智能助手对后端服务的能力调用。
安装：pip install uvicorn fastapi-mcp
示例：
py
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
import uvicorn
app = FastAPI()
@app.get("/text", operation_id="text")
async def hello():
return "Hello"
mcp = FastApiMCP(
app, name="测试MCP",
description="测试",
)
mcp.mount(mount_path='/test-mcp')
if __name__ == '__main__':
uvicorn.run(app, host="0.0.0.0", port=8000)通过路由区分多个MCP工具：FastAPI-MCP支持一个FastAPI应用公开多个MCP接口，每个接口根据不同业务场景和权限独立管理。
FastApiAdmin
开源（GitHub，523 Star，151 Fork）高度模块化、先进的现代化快速开发平台，旨在帮助开发者高效搭建高质量的企业级中后台系统。采用前后端分离架构，融合FastAPI和Vue3实现多端统一开发，提供一站式开箱即用的开发体验。代码同步托管于Gitee，560 Star，269 Fork。
演示环境
- 网页端：https://service.fastapiadmin.com/web
- 移动端：https://service.fastapiadmin.com/app
- 登录账号：admin，密码：123456
| 优势 | 描述 |
|---|---|
| 现代化技术栈 | 基于FastAPI+Vue3+TypeScript等前沿技术构建 |
| 高性能异步 | 利用FastAPI异步特性和Redis缓存优化响应速度 |
| 安全可靠 | JWT+OAuth2认证机制，RBAC权限控制模型 |
| 模块化设计 | 高度解耦的系统架构，便于扩展和维护 |
| 全栈支持 | Web端+移动端(H5)+后端一体化解决方案 |
| 快速部署 | Docker一键部署，支持生产环境快速上线 |
| 完善文档 | 详细的开发文档和教程，降低学习成本 |
| 智能体框架 | 基于Langchain和Langgraph的开发智能体 |
技术栈
| 类型 | 技术选型 | 描述 |
|---|---|---|
| 后端框架 | FastAPI、Uvicorn、Pydantic2.0、Alembic | 现代、高性能的异步框架，强制类型约束，数据迁移 |
| ORM | SQLAlchemy2.0 | 强大的ORM库 |
| 定时任务 | AP Scheduler | 轻松实现定时任务 |
| 权限认证 | PyJWT | 实现JWT认证 |
| 前端框架 | Vue3/Vite5/Pinia/TypeScript | 快速开发Vue3应用 |
| WebUI | Element Plus | 企业级UI组件库 |
| 移动端 | UniApp、WotDesign Uni | 跨端移动应用框架 |
| 数据库 | MySQL、PG、Sqlite | 关系型和文档型数据库支持 |
| 缓存 | Redis | 高性能缓存数据库 |
| 文档 | Swagger/Redoc | 自动生成API文档 |
| 部署 | Docker/Nginx/Docker Compose | 容器化部署方案 |
| 智能体框架 | Langchain/Langgraph | 基于Langchain和Langgraph的智能体框架 |
插件化架构特性
- 自动路由发现：系统会自动扫描
backend/app/plugin/目录下所有controller.py文件 - 自动路由注册：所有路由会被自动注册到对应的前缀路径
- 模块化管理：按功能模块组织代码，便于维护和扩展
- 支持多层级嵌套：支持模块内部多层级嵌套结构
自动路由注册机制
- 控制器文件必须命名为
controller.py - 路由会自动映射：
module_xxx->/xxx - 支持多个API Router实例
- 自动处理路由去重
功能模块
| 模块 | 功能 | 描述 |
|---|---|---|
| 仪表盘 | 工作台、分析页 | 系统概览和数据分析 |
| 系统管理 | 用户、角色、菜单、部门、岗位、字典、配置、公告 | 核心系统管理功能 |
| 监控管理 | 在线用户、服务器监控、缓存监控 | 系统运行状态监控 |
| 任务管理 | 定时任务 | 异步任务调度管理 |
| 日志管理 | 操作日志 | 用户行为审计 |
| 开发工具 | 代码生成、表单构建、接口文档 | 提升开发效率的工具 |
| 文件管理 | 文件存储 | 统一文件管理 |
| 智能助手 | 类GPT聊天 | RAG检索 |
开发工具
- 代码生成器：自动生成前后端CRUD代码
- API文档：自动生成Swagger/Redoc API文档
- 数据库迁移：支持Alembic数据库迁移
- 日志系统：内置日志记录和查询功能
- 监控系统：内置服务器监控和缓存监控功能
开发流程
- 需求分析：明确功能需求和业务逻辑
- 数据库设计：设计数据库表结构
- 代码生成：使用代码生成器生成基础代码
- 业务逻辑开发：完善业务逻辑和接口
- 前端开发：开发前端页面和交互
- 测试：进行单元测试和集成测试
- 部署：部署到生产环境
注意事项
- 权限控制：所有API接口必须添加权限控制
- 数据验证：所有输入数据必须进行验证
- 异常处理：统一处理API异常
- 日志记录：关键操作必须记录日志
- 性能优化：注意API性能优化，避免慢查询
- 代码规范：遵循PEP8和项目代码规范
项目内置代码生成器，可根据数据库表结构自动生成前后端代码，大幅提升开发效率。生成步骤
- 登录系统：使用管理员账号登录系统
- 进入代码生成模块：在左侧菜单中点击"代码生成"
- 导入表结构：选择要生成代码的数据库表
- 配置生成参数：填写模块名称、功能名称等
- 生成代码：点击"生成代码"按钮
- 下载或写入：选择下载代码包或直接写入项目目录
实战
基于源码部署：
bash
git clone https://github.com/fastapiadmin/FastapiAdmin.git
cd backend
uv add -r requirements.txt
uv run main.py run
uv run main.py run --env=dev or --env=prod
cd frontend
pnpm install
pnpm run dev
pnpm run build
# Docker部署
./deploy.sh or ./deploy.sh --start
./deploy.sh --stop
./deploy.sh --logs以下图片来自官方GitHub仓库，非常适合企业级平台，支持二次开发。
项目采用插件化架构设计，二次开发建议在backend/app/plugin目录下进行，系统会自动发现并注册所有符合规范的路由，便于模块管理和升级维护。
二次开发步骤
- 创建插件模块：在
backend/app/plugin/目录下创建新的模块目录 - 编写数据模型：在
model.py中定义数据库模型 - 编写数据验证：在
schema.py中定义数据验证模型 - 编写数据访问层：在
crud.py中编写数据库操作逻辑 - 编写业务逻辑层：在
service.py中编写业务逻辑 - 编写控制器：在
controller.py中定义路由和处理函数 - 自动注册：系统会自动扫描并注册所有路由，无需手动配置
开发规范
- 命名规范：模块名必须采用
module_xxx格式，控制器名采用驼峰命名法 - 权限控制：所有API接口必须添加权限控制装饰器
- 日志记录：使用OperationLogRoute类自动记录操作日志
- 返回格式：统一使用SuccessResponse或ErrorResponse返回响应
- 代码注释：为所有API接口添加详细的文档字符串
注意事项
- 控制器文件必须命名为
controller.py - 路由会自动映射到对应的前缀路径
- 无需手动注册路由，系统会自动发现并注册
前端部分
- 配置前端API：在
frontend/src/api/目录下创建对应的API文件 - 编写页面组件：在
frontend/src/views/目录下创建页面组件 - 注册路由：在
frontend/src/router/index.ts中注册路由
Aegis Stack
高度模块化、生产就绪的基于FastAPI的开源（GitHub，96 Star，6 Fork）开发平台，目标：使开发者只需花15分钟从创意跨越到可扩展的后端原型。官方文档。
亮点
- 模块化：进化式架构，一行代码增加插件，支持一键移除，Git冲突风险低
- 内置Overseer：无需配置Datadog或New Relic等昂贵的第三方工具，即可实时查看Worker队列状态、数据库健康度、定时任务进度以及AI消耗情况
- CLI：不是简单的脚手架生成器，而是系统运行时的接口。你可以直接在终端查询任务队列积压、管理服务配置
- AI-Native：内置PydanticAI、LangChain等服务组件，开箱即用；通过对话即可理解你的代码逻辑或查看实时遥测数据。
优势
- 工程化上限极高：预置Python 3.11+、Docker、Pydantic V2等主流技术栈，逻辑闭环
- 迁移成本极低：不发明复杂的私有抽象，只是把已有的成熟工具（APScheduler、Redis、PG）优雅地组合在一起
- 维护省心：支持
aegis update同步模板改进
劣势
- 学习曲线：要搞透模块化CLI和Overseer监控，仍需一定上手时间
- 依赖偏好：如果你的团队习惯使用非主流组件（如想用MongoDB替代PG，或用Celery替代其内置Worker），手动定制的成本会抵消其带来的便利
- 环境要求：强依赖Docker和make工作流，在非类Unix环境下可能需要额外配置
实战
bash
# 创建一个带用户鉴权的项目
uvx aegis-stack init my-api --services auth
# 添加异步处理能力
aegis add worker --project-path ./my-api
# 启动开发环境，基于Docker
cd my-api && make serve