我用fastapi-scaff搭了个项目，两天工期缩到两小时，老板以为我开挂了

一句话它把 FastAPI 项目的“最佳实践”固化成了代码模板。你不用再去网上搜“FastAPI项目结构推荐”也不用拷贝上一个项目里乱七八糟的配置文件。它能给你直接生成一套包括异步SQLAlchemy数据库连接、Alembic数据库迁移、JWT/API Key认证、Docker部署支持、环境变量管理在内的完整骨架甚至连Celery异步任务都集成好了。本文能帮你解决⚡ 5分钟跑起来一个结构清晰、可直接开发的FastAPI项目。⚡ 理解 fastapi-scaff 的核心目录作用别在里面迷路。⚡ 解决新手最容易碰到的环境变量加载失败、数据库连接不上的问题。️ 上手第一步别怂就是几条命令的事好咱们先来把它装上。这工具用起来和咱们熟悉的 create-react-app 或者 vue-cli 差不多全程无痛。1. 确保你有Python 3.11的环境。然后直接uv虚拟环境下安装它uv add fastapi-scaff2. 装完之后先看看帮助文档确认装对了fastapi-scaff -h3. 接下来重点来了在你想要创建项目的目录下敲入这行命令fastapi-scaff new my_awesome_project看着屏幕上一堆文件刷刷地创建出来是不是有种莫名的舒适感Starting new project... Done. Now run: 1. cd my_awesome_project 2. modify config, eg: db 3. pip install -r requirements.txt 4. python runserver.py 控制台里输出以上内容到这里架子就搭好了。是不是以为这样就完了别急着跑直接 uvicorn main:app --reload 绝对行不通这个脚手架有自己的启动方式。另外再说个好用的脚手架支持四种项目模板按需选择- 标准模板默认不写 -t 就行- 轻量模板 fastapi-scaff new 项目名 -t light- 微型模板 fastapi-scaff new 项目名 -t tiny- 单文件模板 fastapi-scaff new 项目名 -t single如果你需要集成Celery做异步任务创建项目时直接加参数 fastapi-scaff new myproject --celery 。 最容易翻车的三个点我全替你们趟过了你可能会问不就是个脚手架吗能有多坑这里就是我当初头撞南墙的地方。坑一Python版本不对安装直接失败这个脚手架明确要求Python 3.11如果你还在用3.8、3.9建议先升级。我当初在公司的老服务器上部署Python 3.9直接报错查了半天才发现是版本问题。坑二启动命令不是 uvicorn这个脚手架有自己的入口脚本。进入项目目录后先安装依赖uv add -r requirements.txt然后运行项目用的是项目根目录下的 runserver.py uv run runserver.py官方文档虽然说了但很多人都习惯性敲 uvicorn 结果自然是一头雾水。坑三数据库迁移命令也变了这个脚手架内置了Alembic迁移但执行方式不是直接敲 alembic upgrade head 而是通过项目里的脚本# 生成迁移文件 uv run runmigration.py generate init # 执行迁移 uv run runmigration.py upgrade再说个容易翻车的点你需要在运行项目之前先去 config/ 目录下把数据库配置改好默认的数据库URL如果不改启动照样报错。.env 定义了环境变量的类型app_xxx 是不同环境的具体配置信息APP信息、数据库连接等就在这里面修改 实战演示跑起来然后看看里面都有啥填完上面的坑现在进入项目目录用你喜欢的IDE打开。先把数据库迁移跑一下前提是你已经配好了数据库连接uv run runmigration.py generate init uv run runmigration.py upgrade然后启动服务uv run runserver.py访问 http://127.0.0.1:8000/docs 看到那个熟悉的 Swagger UI 界面没恭喜你骨架跑通了使用 create 接口创建一个 admin 角色的用户然后使用 login 接口登录拿到 token 后输入到上面的 Authorize 中然后就可以访问 list 用户列表了否则会报权限错误这一套下来妥妥的用户认证也有了这个脚手架的精髓在于模块化。它把项目比作一个精装房架构是ASMAPI-Services-Models- app/api/ 目录就是你的客厅和卧室所有接口路由都放这里。- app/services/ 目录是工具箱业务逻辑往里塞。- app/models/ 是房子的承重墙数据库表结构。- app/initializer/ 是水电煤气总闸配置、数据库连接、日志都在这里。- config/ 是项目级的配置文件目录。- app_celery/ 如果你加了 --celery 参数这个目录就出现了。这个脚手架还有个很实用的功能——给现有项目添加API# 进入项目根目录 uv run fastapi-scaff add user它会自动生成对应API的CRUD代码骨架连增删改查的路由都给你搭好了。 最后一个忠告