问题背景
使用fastapi-scaff脚手架创建项目后，发现三个常见问题：
- 时区配置缺失 默认的user导入的时区类有的python版本不支持 好像至于哦3.9才有 ？我是3.11也是报错的
- ORM Base类不一致 统一使用 DeclBase
- 数据库迁移工具alembic 配置文件
完整解决方案
第一步：创建项目
# 1. 安装脚手架pipinstallfastapi-scaff==0.5.7# 2. 创建项目fastapi-scaff create my_fastapi --database sqlite# 3. 进入项目目录cdmy_fastapifastapi-scaff 常见参数 -h可以直接看
-e, --edition`new`时可指定项目结构版本(默认标准版)这个用的多一些 -d, --db`new`时可指定项目数据库(默认sqlite)-v, --vn`add`时可指定版本(默认v1)-s, --subdir`add`时可指定子目录(默认空)-t, --target`add`时可指定目标(默认asm)--celery`new`|`add`时可指定是否集成celery(默认不集成)examples:`new`:fastapi-scaff new<myproj>`add`:fastapi-scaffadd<myapi>第二步：添加缺失依赖
# 添加时区和迁移工具依赖echo"tzdata>=2021.5">>requirements.txtecho"alembic>=1.11.0">>requirements.txt# 安装所有依赖pipinstall-r requirements.txt第三步：创建时区工具文件
# 创建统一时区工具cat>app/utils/mytime.py<<'EOF' from datetime import datetime from zoneinfo import ZoneInfo SHANGHAI_TZ = ZoneInfo("Asia/Shanghai") def now() -> datetime: """返回上海时区的当前时间""" return datetime.now(SHANGHAI_TZ) def now_timestamp() -> int: """返回当前时间戳（秒）""" return int(now().timestamp()) def now_ms() -> int: """返回当前时间戳（毫秒）""" return int(now().timestamp() * 1000) EOF第四步：修改用户模型
# 备份原文件cpapp/models/user.py app/models/user.py.backup# 使用sed修改文件sed-i'/from toollib.utils import now2timestamp/d'app/models/user.pysed-i'/from app.initializer import g/a\from app.utils import mytime'app/models/user.pysed-i's/default=now2timestamp/default=mytime.now_timestamp/g'app/models/user.py修改后的关键部分：
fromsqlalchemyimportColumn,BigInteger,Integer,Stringfromapp.initializerimportgfromapp.modelsimportDeclBasefromapp.utilsimportmytime# 新增导入classUser(DeclBase):__tablename__="user"# ... 其他字段保持不变created_at=Column(BigInteger,default=mytime.now_timestamp,comment="创建时间")updated_at=Column(BigInteger,default=mytime.now_timestamp,onupdate=mytime.now_timestamp,comment="更新时间")第五步：初始化Alembic迁移
# 初始化Alembicalembic init alembic# 配置env.py使用项目Base类cat>>alembic/env.py<<'EOF' # 添加项目路径 import sys import os sys.path.append(os.path.dirname(os.path.dirname(__file__))) # 导入Base类 from app.models import DeclBase target_metadata = DeclBase.metadata # 设置数据库URL（根据配置文件） config.set_main_option("sqlalchemy.url", "sqlite:///app_dev.sqlite") EOF使用sqlite的完整env.py配置文件：
fromlogging.configimportfileConfigfromsqlalchemyimportengine_from_configfromsqlalchemyimportpoolfromalembicimportcontextimportosimportsys config=context.config# Set database URL directlyconfig.set_main_option("sqlalchemy.url","sqlite:///app_dev.sqlite")# Add project root to Python pathproject_root=os.path.dirname(os.path.dirname(__file__))sys.path.append(project_root)# Import Base classtry:fromapp.modelsimportDeclBase target_metadata=DeclBase.metadataexceptImportError:try:fromapp.initializer._dbimportDeclBase target_metadata=DeclBase.metadataexceptImportError:fromsqlalchemy.ext.declarativeimportdeclarative_base DeclBase=declarative_base()target_metadata=DeclBase.metadataifconfig.config_file_nameisnotNone:fileConfig(config.config_file_name)defrun_migrations_offline():url=config.get_main_option("sqlalchemy.url")context.configure(url=url,target_metadata=target_metadata,literal_binds=True,dialect_opts={"paramstyle":"named"},)withcontext.begin_transaction():context.run_migrations()defrun_migrations_online():connectable=engine_from_config(config.get_section(config.config_ini_section,{}),prefix="sqlalchemy.",poolclass=pool.NullPool,)withconnectable.connect()asconnection:context.configure(connection=connection,target_metadata=target_metadata)withcontext.begin_transaction():context.run_migrations()ifcontext.is_offline_mode():run_migrations_offline()else:run_migrations_online()第六步：执行数据库迁移
# 生成迁移文件alembic revision --autogenerate -m"init"# 应用迁移alembic upgradehead# 验证表结构sqlite3 app_dev.sqlite".tables"API测试流程
1. 启动服务
uvicorn app.main:app --host0.0.0.0 --port8000--reload2. 创建用户
curl-X POST"http://127.0.0.1:8000/api/v1/user"\-H"Content-Type: application/json"\-d'{ "phone": "13634759152", "password": "passwd", "name": "admin", "age": 0, "gender": 1 }'3. 登录获取Token
curl-X POST"http://127.0.0.1:8000/api/v1/user/login"\-H"Content-Type: application/json"\-d'{ "phone": "13634759152", "password": "passwd" }'4. 使用Token查询用户
# 使用上一步返回的tokenTOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjIwMDA5MDc1NjI2MjY1ODg2NzIiLCJwaG9uZSI6IjEzNjM0NzU5MTUyIiwibmFtZSI6ImFkbWluIiwiYWdlIjowLCJnZW5kZXIiOjEsImV4cCI6MTc2ODQ4MTIyOX0.yS_pyuHfR0FuctSsb86zebYVlk8CFK2-ErsQMBvRqaA"curl-X GET"http://127.0.0.1:8000/api/v1/user/2000907562626588672"\-H"accept: application/json"\-H"Authorization: Bearer$TOKEN"5. 查询用户列表
curl-X GET"http://127.0.0.1:8000/api/v1/user?page=1&size=10"\-H"accept: application/json"\-H"Authorization: Bearer$TOKEN"验证命令
# 验证时区配置python -c"from app.utils.mytime import now_timestamp; print('当前时间戳:', now_timestamp())"# 验证数据库迁移alembic current# 验证表结构sqlite3 app_dev.sqlite"SELECT name FROM sqlite_master WHERE type='table';"问题排查清单
| 问题 | 检查命令 | 解决方案 |
|---|---|---|
| 时区错误 | python -c "from zoneinfo import ZoneInfo; print(ZoneInfo('Asia/Shanghai'))" | pip install tzdata |
| Alembic找不到Base | grep -r "DeclBase" app/ | 修改env.py导入路径 |
| 迁移文件不生成 | sqlite3 app_dev.sqlite ".tables" | 检查env.py中的target_metadata |
| Token认证失败 | 检查用户表的jwt_key字段 | 确保jwt_key不为空 |
总结
fastapi-scaff脚手架创建的项目需要手动补充三个核心配置：
- 时区统一：创建
app/utils/mytime.py，替换所有时间相关函数 - 数据库迁移：初始化Alembic，配置正确的Base类和数据库连接
- 模型一致：确保所有模型继承同一个Base类
完成上述配置后，项目即可正常运行完整的JWT认证流程和数据库迁移功能。
欢迎焦虑 沟通 有错误 指正留言~
