尧图网页设计 
厌倦了重复搭建 FastAPI 后端我写了个 CLI 工具一键生成项目骨架在快速迭代的业务开发中你是否也经历过这样的场景每次启动一个新项目都要重复搭建 FastAPI 后端环境——创建项目目录、安装依赖、配置数据库连接、编写基础的路由和模型、设置 CORS、配置日志……这些重复性工作不仅耗时还容易因疏忽导致配置不一致为后续的开发和维护埋下隐患。为了彻底解决这个问题我开发了一个命令行工具CLI它能够根据预设的模板和配置一键生成一个功能完整、结构清晰的 FastAPI 项目骨架。本文将详细介绍这个工具的设计思路、实现过程、使用方法以及如何根据自身需求进行定制。无论你是想快速启动新项目还是希望学习如何构建自己的 CLI 工具这篇文章都将为你提供一套完整的实战方案。1. 背景与核心概念为什么需要项目生成 CLI在深入代码之前我们有必要厘清几个核心概念以及这个工具要解决的根本问题。1.1 FastAPI 与项目脚手架FastAPI是一个现代、快速高性能的 Web 框架用于基于标准 Python 类型提示构建 API。它以其简洁的语法、自动化的交互式 API 文档Swagger UI 和 ReDoc以及出色的性能而广受欢迎。项目脚手架是指为一个新项目创建初始文件结构、基础配置和样板代码的过程。一个良好的脚手架应该包含标准化的目录结构如app/核心应用、core/配置和工具、models/数据模型、routers/路由、tests/测试等。基础依赖管理如requirements.txt或pyproject.toml。预配置数据库连接、日志、中间件如 CORS、异常处理等。示例代码一个简单的 “Hello World” API 或 CRUD 示例作为开发起点。手动搭建脚手架不仅重复而且容易出错。不同的开发者或团队可能有不同的习惯导致项目结构五花八门不利于代码审查和新人上手。1.2 CLI 工具的价值CLICommand Line Interface工具允许用户通过命令行与程序交互。一个项目生成 CLI 工具的核心价值在于提升效率将数十分钟甚至数小时的手动配置过程压缩到几秒钟。保证一致性确保团队内所有项目都遵循相同的结构和规范。降低门槛新成员无需了解所有最佳实践细节即可获得一个高质量的项目起点。可定制化可以根据不同项目类型如纯 API 服务、包含 WebSocket、包含任务队列生成不同的模板。市面上已有一些优秀的项目生成工具如cookiecutter但它们通常需要用户寻找和配置模板。本文的目标是打造一个更轻量、更聚焦于 FastAPI 特定场景、且完全由自己掌控的 CLI 工具。2. 环境准备与工具设计在开始构建 CLI 之前我们需要明确技术选型和环境要求。2.1 所需环境与工具Python 3.8FastAPI 和多数现代库的支持版本。pipPython 包管理器。Git可选用于初始化版本控制。文本编辑器或 IDE如 VS Code, PyCharm。我们的 CLI 工具本身也将是一个 Python 包主要利用 Python 标准库的argparse用于解析命令行参数和pathlib/shutil用于文件操作以及Jinja2用于模板渲染。这样依赖极少易于分发和安装。2.2 CLI 工具功能设计我们期望的 CLI 工具姑且命名为fastapi-scaffold-cli应具备以下基本功能fastapi-scaffold create project_name [options]create命令核心命令用于创建新项目。project_name必选参数指定要创建的项目目录名称。[options]可选参数例如--db database_type指定数据库类型如sqlite,postgresql。--auth是否包含基础的 JWT 认证模块。--docker是否生成 Dockerfile 和 docker-compose.yml。--git是否初始化 Git 仓库。工具执行后应在当前目录下创建名为project_name的文件夹其中包含完整的 FastAPI 项目文件。3. 核心实现构建 CLI 与模板引擎接下来我们分步实现这个 CLI 工具。我们将创建一个名为fastapi_scaffold的 Python 包。3.1 项目结构规划首先规划 CLI 工具自身的项目结构fastapi-scaffold-cli/ ├── fastapi_scaffold/ │ ├── __init__.py │ ├── cli.py # CLI 入口和命令定义 │ ├── generator.py # 核心生成逻辑 │ └── templates/ # Jinja2 模板目录 │ ├── {{project_name}}/ │ │ ├── app/ │ │ ├── core/ │ │ ├── ... │ │ └── requirements.txt.j2 │ └── ... (其他模板文件) ├── pyproject.toml # 项目元数据和依赖声明 ├── README.md └── setup.py (或使用 pyproject.toml 替代)3.2 定义 CLI 入口 (cli.py)我们使用argparse库来解析命令行参数。# fastapi_scaffold/cli.py import argparse import sys from pathlib import Path from .generator import ProjectGenerator def main(): parser argparse.ArgumentParser( descriptionA CLI tool to generate FastAPI project scaffolding. ) subparsers parser.add_subparsers(destcommand, helpAvailable commands) # create 命令 create_parser subparsers.add_parser(create, helpCreate a new FastAPI project) create_parser.add_argument(project_name, typestr, helpName of the project to create) create_parser.add_argument(--db, typestr, choices[sqlite, postgresql], defaultsqlite, helpDatabase type (default: sqlite)) create_parser.add_argument(--auth, actionstore_true, helpInclude JWT authentication boilerplate) create_parser.add_argument(--docker, actionstore_true, helpGenerate Dockerfile and docker-compose.yml) create_parser.add_argument(--git, actionstore_true, helpInitialize a git repository) args parser.parse_args() if args.command create: generator ProjectGenerator( project_nameargs.project_name, db_typeargs.db, with_authargs.auth, with_dockerargs.docker, init_gitargs.git ) try: generator.generate() print(f\n✅ Project {args.project_name} created successfully!) print(f Navigate to: {Path.cwd() / args.project_name}) print( Next steps:) print(f cd {args.project_name}) print( pip install -r requirements.txt) print( uvicorn app.main:app --reload) if args.git: print( git add . git commit -m Initial commit) except Exception as e: print(f\n❌ Failed to create project: {e}, filesys.stderr) sys.exit(1) else: parser.print_help() if __name__ __main__: main()3.3 实现项目生成器 (generator.py)这是工具的核心负责读取模板、渲染内容并写入目标目录。# fastapi_scaffold/generator.py import shutil from pathlib import Path import subprocess import sys from jinja2 import Environment, FileSystemLoader, select_autoescape class ProjectGenerator: def __init__(self, project_name, db_typesqlite, with_authFalse, with_dockerFalse, init_gitFalse): self.project_name project_name self.db_type db_type self.with_auth with_auth self.with_docker with_docker self.init_git init_git self.target_dir Path.cwd() / project_name # 获取模板目录的绝对路径 self.template_dir Path(__file__).parent / templates self.env Environment( loaderFileSystemLoader(self.template_dir), autoescapeselect_autoescape(), trim_blocksTrue, lstrip_blocksTrue ) def generate(self): 执行项目生成的主流程 self._validate_project_name() self._create_project_directory() self._render_and_copy_templates() if self.init_git: self._init_git_repo() print(f\n Project context: DB{self.db_type}, Auth{self.with_auth}, Docker{self.with_docker}) def _validate_project_name(self): 验证项目名是否合法且目录不存在 if not self.project_name.isidentifier(): raise ValueError(fProject name {self.project_name} is not a valid Python identifier.) if self.target_dir.exists(): raise FileExistsError(fDirectory {self.target_dir} already exists.) def _create_project_directory(self): 创建项目根目录及子目录结构 self.target_dir.mkdir(parentsTrue) print(f Created project directory: {self.target_dir}) def _render_and_copy_templates(self): 遍历模板目录渲染 Jinja2 模板并复制文件 # 定义传递给模板的上下文变量 context { project_name: self.project_name, db_type: self.db_type, with_auth: self.with_auth, with_docker: self.with_docker, } # 遍历模板目录中的所有文件 for template_path in self.template_dir.rglob(*): if template_path.is_file(): # 计算相对于模板目录的路径并作为模板名 relative_path template_path.relative_to(self.template_dir) template_name str(relative_path) # 处理目标文件路径将模板路径中的变量部分如项目名目录替换为实际值 # 例如templates/{{project_name}}/app/main.py.j2 - my_project/app/main.py dest_path self.target_dir / relative_path # 移除 .j2 后缀如果是模板文件 if dest_path.suffix .j2: dest_path dest_path.with_suffix() # 移除 .j2 # 确保目标目录存在 dest_path.parent.mkdir(parentsTrue, exist_okTrue) # 渲染模板或直接复制文件 if template_path.suffix .j2: # 是 Jinja2 模板需要渲染 template self.env.get_template(template_name) content template.render(**context) dest_path.write_text(content, encodingutf-8) print(f ✨ Rendered: {dest_path.relative_to(self.target_dir)}) else: # 是普通文件直接复制 shutil.copy2(template_path, dest_path) print(f Copied: {dest_path.relative_to(self.target_dir)}) def _init_git_repo(self): 在项目目录中初始化 Git 仓库 try: subprocess.run([git, init], cwdself.target_dir, checkTrue, capture_outputTrue) print( Initialized Git repository.) except subprocess.CalledProcessError as e: print(f ⚠️ Git initialization failed: {e.stderr.decode()}, filesys.stderr) except FileNotFoundError: print( ⚠️ Git not found. Skipping Git initialization., filesys.stderr)3.4 创建 Jinja2 模板 (templates/)模板是项目的蓝图。我们在templates/{{project_name}}/目录下存放所有模板文件。.j2后缀表示这是一个 Jinja2 模板文件。1. 项目根目录模板 (templates/{{project_name}}/requirements.txt.j2):# requirements.txt fastapi0.104.1 uvicorn[standard]0.24.0 {% if db_type sqlite %} sqlalchemy2.0.23 {% elif db_type postgresql %} sqlalchemy2.0.23 psycopg2-binary2.9.9 {% endif %} {% if with_auth %} python-jose[cryptography]3.3.0 passlib[bcrypt]1.7.4 python-multipart0.0.6 {% endif %} pydantic-settings2.1.0 python-dotenv1.0.02. 核心应用文件 (templates/{{project_name}}/app/main.py.j2):# app/main.py from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from .core.config import settings from .api import api_router app FastAPI( title{{ project_name }} API, descriptionA FastAPI application generated by fastapi-scaffold-cli, version0.1.0, ) # 设置 CORS app.add_middleware( CORSMiddleware, allow_originssettings.BACKEND_CORS_ORIGINS, allow_credentialsTrue, allow_methods[*], allow_headers[*], ) # 包含所有路由 app.include_router(api_router, prefix/api) app.get(/) async def root(): return {message: Welcome to {{ project_name }} API, docs: /docs}3. 配置文件 (templates/{{project_name}}/app/core/config.py.j2):# app/core/config.py from pydantic_settings import BaseSettings from typing import List class Settings(BaseSettings): PROJECT_NAME: str {{ project_name }} API_V1_STR: str /api/v1 {% if db_type sqlite %} DATABASE_URL: str sqlite:///./app.db {% elif db_type postgresql %} DATABASE_URL: str postgresql://user:passwordlocalhost/{{ project_name }}_db {% endif %} SECRET_KEY: str your-secret-key-change-in-production ALGORITHM: str HS256 ACCESS_TOKEN_EXPIRE_MINUTES: int 30 BACKEND_CORS_ORIGINS: List[str] [http://localhost:3000, http://localhost:8000] class Config: env_file .env case_sensitive True settings Settings()4. 数据库连接与模型示例 (templates/{{project_name}}/app/core/database.py.j2):# app/core/database.py from sqlalchemy import create_engine from sqlalchemy.ext.declarative import declarative_base from sqlalchemy.orm import sessionmaker from .config import settings {% if db_type sqlite %} # SQLite 需要 check_same_threadFalse engine create_engine( settings.DATABASE_URL, connect_args{check_same_thread: False} ) {% elif db_type postgresql %} engine create_engine(settings.DATABASE_URL) {% endif %} SessionLocal sessionmaker(autocommitFalse, autoflushFalse, bindengine) Base declarative_base() # 依赖注入用于获取数据库会话 def get_db(): db SessionLocal() try: yield db finally: db.close()5. 路由聚合文件 (templates/{{project_name}}/app/api/__init__.py.j2):# app/api/__init__.py from fastapi import APIRouter from app.api.endpoints import items, users # 根据模板条件导入 api_router APIRouter() api_router.include_router(items.router, prefix/items, tags[items]) {% if with_auth %} api_router.include_router(users.router, prefix/users, tags[users]) {% endif %}6. 一个示例 CRUD 路由 (templates/{{project_name}}/app/api/endpoints/items.py.j2):# app/api/endpoints/items.py from fastapi import APIRouter, Depends, HTTPException from sqlalchemy.orm import Session from typing import List from app import schemas, crud from app.core.database import get_db router APIRouter() router.get(/, response_modelList[schemas.Item]) def read_items(skip: int 0, limit: int 100, db: Session Depends(get_db)): 检索项目列表 items crud.item.get_multi(db, skipskip, limitlimit) return items router.post(/, response_modelschemas.Item) def create_item(item: schemas.ItemCreate, db: Session Depends(get_db)): 创建新项目 return crud.item.create(db, obj_initem)7. Docker 相关模板 (条件生成):templates/{{project_name}}/Dockerfile.j2templates/{{project_name}}/docker-compose.yml.j2templates/{{project_name}}/.dockerignore.j28. 其他必要文件:templates/{{project_name}}/.gitignore.j2templates/{{project_name}}/README.md.j2templates/{{project_name}}/app/__init__.py(空文件)templates/{{project_name}}/app/schemas/,app/crud/,app/models/目录及示例文件。由于篇幅限制这里不展开所有模板文件内容但上述示例已经勾勒出了核心结构。完整的模板仓库可以独立维护。3.5 打包与安装 CLI 工具为了让工具可以通过pip安装我们需要配置pyproject.toml。# pyproject.toml [build-system] requires [setuptools61.0, wheel] build-backend setuptools.build_meta [project] name fastapi-scaffold-cli version 0.1.0 description A CLI tool to generate FastAPI project scaffolding. readme README.md authors [{name Your Name, email youexample.com}] license {text MIT} classifiers [ Programming Language :: Python :: 3, License :: OSI Approved :: MIT License, Operating System :: OS Independent, ] requires-python 3.8 dependencies [ Jinja23.1.2, ] [project.scripts] fastapi-scaffold fastapi_scaffold.cli:main [project.urls] Homepage https://github.com/yourusername/fastapi-scaffold-cli Bug Tracker https://github.com/yourusername/fastapi-scaffold-cli/issues然后在项目根目录下可以使用以下命令进行本地安装测试# 在开发模式下安装可编辑模式修改代码无需重装 pip install -e . # 安装后即可全局使用 fastapi-scaffold 命令 fastapi-scaffold --help4. 完整实战使用 CLI 工具生成项目现在让我们从头到尾演示如何使用这个工具。4.1 安装 CLI 工具假设你已经将工具打包并发布到了 PyPI或使用本地开发安装# 从 PyPI 安装发布后 pip install fastapi-scaffold-cli # 验证安装 fastapi-scaffold --help输出应显示create命令的帮助信息。4.2 生成一个基础项目创建一个名为my_fastapi_app的基础项目使用 SQLite不包含认证和 Dockerfastapi-scaffold create my_fastapi_app工具会快速执行输出类似 Created project directory: /path/to/current/dir/my_fastapi_app ✨ Rendered: requirements.txt Copied: .gitignore ✨ Rendered: app/main.py ✨ Rendered: app/core/config.py ... ✅ Project my_fastapi_app created successfully! Navigate to: /path/to/current/dir/my_fastapi_app Next steps: cd my_fastapi_app pip install -r requirements.txt uvicorn app.main:app --reload4.3 生成一个功能更全的项目创建一个包含 PostgreSQL 数据库、JWT 认证和 Docker 支持的项目fastapi-scaffold create my_fullstack_api --db postgresql --auth --docker --git输出会显示生成了更多文件包括Dockerfile,docker-compose.yml以及认证相关的路由和模型。4.4 运行生成的项目进入项目目录并启动服务cd my_fastapi_app # 创建虚拟环境推荐 python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows # 安装依赖 pip install -r requirements.txt # 启动开发服务器 uvicorn app.main:app --reload访问http://127.0.0.1:8000/docs即可看到自动生成的 Swagger UI 文档并且/api/items/等端点已经可用。4.5 项目结构回顾生成的项目结构清晰遵循了常见的 FastAPI 项目组织方式my_fastapi_app/ ├── .env.example # 环境变量示例 ├── .gitignore ├── requirements.txt ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 应用实例 │ ├── core/ # 核心配置、数据库连接等 │ │ ├── __init__.py │ │ ├── config.py │ │ └── database.py │ ├── api/ # 路由聚合 │ │ ├── __init__.py │ │ └── endpoints/ # 具体路由文件 │ ├── crud/ # 数据库操作层 │ ├── models/ # SQLAlchemy 模型 │ ├── schemas/ # Pydantic 模型 │ └── tests/ # 测试文件 └── README.md5. 常见问题与排查思路在使用或开发此类 CLI 工具时你可能会遇到以下问题问题现象常见原因解决思路命令fastapi-scaffold未找到1. 工具未正确安装。2. Python 脚本目录未加入系统 PATH。1. 使用pip install -e .在开发模式下重装。2. 检查虚拟环境是否激活或使用python -m fastapi_scaffold.cli create ...直接运行模块。生成项目时提示目录已存在目标目录project_name在当前路径下已存在。1. 删除或重命名已存在的目录。2. 换一个项目名或在其他路径下执行命令。模板渲染错误变量未定义Jinja2 模板中引用了未传递给上下文的变量。检查generator.py中的context字典确保包含了模板中所有用到的变量如{{ db_type }}。生成的项目运行时报ModuleNotFoundError1. 依赖未安装。2. 项目结构或导入路径错误。1. 确保在项目根目录下执行pip install -r requirements.txt。2. 检查app/main.py中的导入语句确保路径与生成的结构一致。使用相对导入如from .core.config import settings。使用--db postgresql选项后数据库连接失败1. PostgreSQL 服务未运行。2.DATABASE_URL中的连接信息用户名、密码、数据库名不正确。1. 启动 PostgreSQL 服务如sudo service postgresql start。2. 修改app/core/config.py或.env文件中的DATABASE_URL确保其指向正确的数据库实例。--auth选项生成的认证端点返回 4011. 未正确传递 JWT Token。2. Token 已过期或密钥不匹配。1. 在 Swagger UI 中点击 “Authorize” 按钮输入Bearer your_token。2. 检查SECRET_KEY和ALGORITHM配置确保生成和验证 Token 时使用相同的密钥。Docker 构建失败1. Dockerfile 中基础镜像不存在。2. 依赖安装超时或网络问题。1. 检查 Dockerfile 中的FROM python:3.11-slim等基础镜像标签是否有效。2. 尝试使用国内镜像源或在 Dockerfile 的pip install命令后添加--default-timeout100。6. 最佳实践与工程建议将这个 CLI 工具用于生产或团队协作时考虑以下最佳实践6.1 模板设计原则保持简洁与可扩展性初始模板应提供最必要的功能骨架避免过度设计。复杂的业务逻辑应由开发者后续添加。清晰的目录结构遵循 FastAPI 官方文档推荐或社区共识的结构如app/内部按功能分层使项目易于导航和理解。配置外部化所有配置数据库 URL、密钥、CORS 源都应通过环境变量或.env文件管理切勿将敏感信息硬编码在模板中。包含测试骨架即使在模板中只放一个空的tests/目录和__init__.py也能鼓励开发者编写测试。6.2 CLI 工具开发建议完善的错误处理如我们代码所示对目录存在、权限不足、模板缺失等情况进行友好提示并返回非零退出码。提供丰富的选项除了基础的--db,--auth可以考虑添加--celery任务队列、--redis缓存、--frontend生成前端模板等选项满足不同场景。支持自定义模板路径允许用户通过--template-path指定自己的模板目录实现高度定制化。版本管理对 CLI 工具和模板进行版本控制。当模板有重大更新时可以通过 CLI 版本号来管理兼容性。6.3 生成项目的后续开发指南立即进行版本控制生成项目后第一时间执行git init git add . git commit -m Initial scaffold。更新依赖版本生成器中的依赖版本如requirements.txt.j2可能不是最新的。创建项目后应检查并更新到安全、稳定的版本。修改默认配置必须修改默认的SECRET_KEY、数据库密码等敏感信息。为生产环境创建独立的配置文件如config/production.py。编写文档生成的README.md是一个起点应根据实际项目补充部署步骤、API 说明、环境变量列表等。逐步添加功能不要试图在模板中一次性包含所有功能。鼓励开发者根据需求逐步引入像 Alembic数据库迁移、Pytest、Loguru 等库。6.4 安全注意事项密钥管理强调在生成的项目中必须将SECRET_KEY、数据库凭证等替换为安全值并纳入.gitignore。依赖安全定期审计生成项目中的依赖requirements.txt使用工具如safety或pip-audit检查已知漏洞。CORS 配置提醒开发者根据实际前端地址严格配置BACKEND_CORS_ORIGINS在生产环境中避免使用[*]。输入验证虽然 FastAPI 和 Pydantic 提供了良好的验证但仍需在业务逻辑层对关键操作进行额外的校验和授权检查。通过构建这样一个 CLI 工具你不仅为自己和团队节省了大量重复劳动还深入理解了 FastAPI 的项目组织、配置管理和模板渲染技术。你可以以此为基础不断迭代模板加入更多最佳实践甚至为不同的技术栈如 FastAPI React, FastAPI Vue生成全栈项目骨架将开发效率提升到一个新的水平。 FastAPI项目脚手架CLI工具：一键生成标准化后端项目结构
厌倦了重复搭建 FastAPI 后端我写了个 CLI 工具一键生成项目骨架在快速迭代的业务开发中你是否也经历过这样的场景每次启动一个新项目都要重复搭建 FastAPI 后端环境——创建项目目录、安装依赖、配置数据库连接、编写基础的路由和模型、设置 CORS、配置日志……这些重复性工作不仅耗时还容易因疏忽导致配置不一致为后续的开发和维护埋下隐患。为了彻底解决这个问题我开发了一个命令行工具CLI它能够根据预设的模板和配置一键生成一个功能完整、结构清晰的 FastAPI 项目骨架。本文将详细介绍这个工具的设计思路、实现过程、使用方法以及如何根据自身需求进行定制。无论你是想快速启动新项目还是希望学习如何构建自己的 CLI 工具这篇文章都将为你提供一套完整的实战方案。1. 背景与核心概念为什么需要项目生成 CLI在深入代码之前我们有必要厘清几个核心概念以及这个工具要解决的根本问题。1.1 FastAPI 与项目脚手架FastAPI是一个现代、快速高性能的 Web 框架用于基于标准 Python 类型提示构建 API。它以其简洁的语法、自动化的交互式 API 文档Swagger UI 和 ReDoc以及出色的性能而广受欢迎。项目脚手架是指为一个新项目创建初始文件结构、基础配置和样板代码的过程。一个良好的脚手架应该包含标准化的目录结构如app/核心应用、core/配置和工具、models/数据模型、routers/路由、tests/测试等。基础依赖管理如requirements.txt或pyproject.toml。预配置数据库连接、日志、中间件如 CORS、异常处理等。示例代码一个简单的 “Hello World” API 或 CRUD 示例作为开发起点。手动搭建脚手架不仅重复而且容易出错。不同的开发者或团队可能有不同的习惯导致项目结构五花八门不利于代码审查和新人上手。1.2 CLI 工具的价值CLICommand Line Interface工具允许用户通过命令行与程序交互。一个项目生成 CLI 工具的核心价值在于提升效率将数十分钟甚至数小时的手动配置过程压缩到几秒钟。保证一致性确保团队内所有项目都遵循相同的结构和规范。降低门槛新成员无需了解所有最佳实践细节即可获得一个高质量的项目起点。可定制化可以根据不同项目类型如纯 API 服务、包含 WebSocket、包含任务队列生成不同的模板。市面上已有一些优秀的项目生成工具如cookiecutter但它们通常需要用户寻找和配置模板。本文的目标是打造一个更轻量、更聚焦于 FastAPI 特定场景、且完全由自己掌控的 CLI 工具。2. 环境准备与工具设计在开始构建 CLI 之前我们需要明确技术选型和环境要求。2.1 所需环境与工具Python 3.8FastAPI 和多数现代库的支持版本。pipPython 包管理器。Git可选用于初始化版本控制。文本编辑器或 IDE如 VS Code, PyCharm。我们的 CLI 工具本身也将是一个 Python 包主要利用 Python 标准库的argparse用于解析命令行参数和pathlib/shutil用于文件操作以及Jinja2用于模板渲染。这样依赖极少易于分发和安装。2.2 CLI 工具功能设计我们期望的 CLI 工具姑且命名为fastapi-scaffold-cli应具备以下基本功能fastapi-scaffold create project_name [options]create命令核心命令用于创建新项目。project_name必选参数指定要创建的项目目录名称。[options]可选参数例如--db database_type指定数据库类型如sqlite,postgresql。--auth是否包含基础的 JWT 认证模块。--docker是否生成 Dockerfile 和 docker-compose.yml。--git是否初始化 Git 仓库。工具执行后应在当前目录下创建名为project_name的文件夹其中包含完整的 FastAPI 项目文件。3. 核心实现构建 CLI 与模板引擎接下来我们分步实现这个 CLI 工具。我们将创建一个名为fastapi_scaffold的 Python 包。3.1 项目结构规划首先规划 CLI 工具自身的项目结构fastapi-scaffold-cli/ ├── fastapi_scaffold/ │ ├── __init__.py │ ├── cli.py # CLI 入口和命令定义 │ ├── generator.py # 核心生成逻辑 │ └── templates/ # Jinja2 模板目录 │ ├── {{project_name}}/ │ │ ├── app/ │ │ ├── core/ │ │ ├── ... │ │ └── requirements.txt.j2 │ └── ... (其他模板文件) ├── pyproject.toml # 项目元数据和依赖声明 ├── README.md └── setup.py (或使用 pyproject.toml 替代)3.2 定义 CLI 入口 (cli.py)我们使用argparse库来解析命令行参数。# fastapi_scaffold/cli.py import argparse import sys from pathlib import Path from .generator import ProjectGenerator def main(): parser argparse.ArgumentParser( descriptionA CLI tool to generate FastAPI project scaffolding. ) subparsers parser.add_subparsers(destcommand, helpAvailable commands) # create 命令 create_parser subparsers.add_parser(create, helpCreate a new FastAPI project) create_parser.add_argument(project_name, typestr, helpName of the project to create) create_parser.add_argument(--db, typestr, choices[sqlite, postgresql], defaultsqlite, helpDatabase type (default: sqlite)) create_parser.add_argument(--auth, actionstore_true, helpInclude JWT authentication boilerplate) create_parser.add_argument(--docker, actionstore_true, helpGenerate Dockerfile and docker-compose.yml) create_parser.add_argument(--git, actionstore_true, helpInitialize a git repository) args parser.parse_args() if args.command create: generator ProjectGenerator( project_nameargs.project_name, db_typeargs.db, with_authargs.auth, with_dockerargs.docker, init_gitargs.git ) try: generator.generate() print(f\n✅ Project {args.project_name} created successfully!) print(f Navigate to: {Path.cwd() / args.project_name}) print( Next steps:) print(f cd {args.project_name}) print( pip install -r requirements.txt) print( uvicorn app.main:app --reload) if args.git: print( git add . git commit -m Initial commit) except Exception as e: print(f\n❌ Failed to create project: {e}, filesys.stderr) sys.exit(1) else: parser.print_help() if __name__ __main__: main()3.3 实现项目生成器 (generator.py)这是工具的核心负责读取模板、渲染内容并写入目标目录。# fastapi_scaffold/generator.py import shutil from pathlib import Path import subprocess import sys from jinja2 import Environment, FileSystemLoader, select_autoescape class ProjectGenerator: def __init__(self, project_name, db_typesqlite, with_authFalse, with_dockerFalse, init_gitFalse): self.project_name project_name self.db_type db_type self.with_auth with_auth self.with_docker with_docker self.init_git init_git self.target_dir Path.cwd() / project_name # 获取模板目录的绝对路径 self.template_dir Path(__file__).parent / templates self.env Environment( loaderFileSystemLoader(self.template_dir), autoescapeselect_autoescape(), trim_blocksTrue, lstrip_blocksTrue ) def generate(self): 执行项目生成的主流程 self._validate_project_name() self._create_project_directory() self._render_and_copy_templates() if self.init_git: self._init_git_repo() print(f\n Project context: DB{self.db_type}, Auth{self.with_auth}, Docker{self.with_docker}) def _validate_project_name(self): 验证项目名是否合法且目录不存在 if not self.project_name.isidentifier(): raise ValueError(fProject name {self.project_name} is not a valid Python identifier.) if self.target_dir.exists(): raise FileExistsError(fDirectory {self.target_dir} already exists.) def _create_project_directory(self): 创建项目根目录及子目录结构 self.target_dir.mkdir(parentsTrue) print(f Created project directory: {self.target_dir}) def _render_and_copy_templates(self): 遍历模板目录渲染 Jinja2 模板并复制文件 # 定义传递给模板的上下文变量 context { project_name: self.project_name, db_type: self.db_type, with_auth: self.with_auth, with_docker: self.with_docker, } # 遍历模板目录中的所有文件 for template_path in self.template_dir.rglob(*): if template_path.is_file(): # 计算相对于模板目录的路径并作为模板名 relative_path template_path.relative_to(self.template_dir) template_name str(relative_path) # 处理目标文件路径将模板路径中的变量部分如项目名目录替换为实际值 # 例如templates/{{project_name}}/app/main.py.j2 - my_project/app/main.py dest_path self.target_dir / relative_path # 移除 .j2 后缀如果是模板文件 if dest_path.suffix .j2: dest_path dest_path.with_suffix() # 移除 .j2 # 确保目标目录存在 dest_path.parent.mkdir(parentsTrue, exist_okTrue) # 渲染模板或直接复制文件 if template_path.suffix .j2: # 是 Jinja2 模板需要渲染 template self.env.get_template(template_name) content template.render(**context) dest_path.write_text(content, encodingutf-8) print(f ✨ Rendered: {dest_path.relative_to(self.target_dir)}) else: # 是普通文件直接复制 shutil.copy2(template_path, dest_path) print(f Copied: {dest_path.relative_to(self.target_dir)}) def _init_git_repo(self): 在项目目录中初始化 Git 仓库 try: subprocess.run([git, init], cwdself.target_dir, checkTrue, capture_outputTrue) print( Initialized Git repository.) except subprocess.CalledProcessError as e: print(f ⚠️ Git initialization failed: {e.stderr.decode()}, filesys.stderr) except FileNotFoundError: print( ⚠️ Git not found. Skipping Git initialization., filesys.stderr)3.4 创建 Jinja2 模板 (templates/)模板是项目的蓝图。我们在templates/{{project_name}}/目录下存放所有模板文件。.j2后缀表示这是一个 Jinja2 模板文件。1. 项目根目录模板 (templates/{{project_name}}/requirements.txt.j2):# requirements.txt fastapi0.104.1 uvicorn[standard]0.24.0 {% if db_type sqlite %} sqlalchemy2.0.23 {% elif db_type postgresql %} sqlalchemy2.0.23 psycopg2-binary2.9.9 {% endif %} {% if with_auth %} python-jose[cryptography]3.3.0 passlib[bcrypt]1.7.4 python-multipart0.0.6 {% endif %} pydantic-settings2.1.0 python-dotenv1.0.02. 核心应用文件 (templates/{{project_name}}/app/main.py.j2):# app/main.py from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from .core.config import settings from .api import api_router app FastAPI( title{{ project_name }} API, descriptionA FastAPI application generated by fastapi-scaffold-cli, version0.1.0, ) # 设置 CORS app.add_middleware( CORSMiddleware, allow_originssettings.BACKEND_CORS_ORIGINS, allow_credentialsTrue, allow_methods[*], allow_headers[*], ) # 包含所有路由 app.include_router(api_router, prefix/api) app.get(/) async def root(): return {message: Welcome to {{ project_name }} API, docs: /docs}3. 配置文件 (templates/{{project_name}}/app/core/config.py.j2):# app/core/config.py from pydantic_settings import BaseSettings from typing import List class Settings(BaseSettings): PROJECT_NAME: str {{ project_name }} API_V1_STR: str /api/v1 {% if db_type sqlite %} DATABASE_URL: str sqlite:///./app.db {% elif db_type postgresql %} DATABASE_URL: str postgresql://user:passwordlocalhost/{{ project_name }}_db {% endif %} SECRET_KEY: str your-secret-key-change-in-production ALGORITHM: str HS256 ACCESS_TOKEN_EXPIRE_MINUTES: int 30 BACKEND_CORS_ORIGINS: List[str] [http://localhost:3000, http://localhost:8000] class Config: env_file .env case_sensitive True settings Settings()4. 数据库连接与模型示例 (templates/{{project_name}}/app/core/database.py.j2):# app/core/database.py from sqlalchemy import create_engine from sqlalchemy.ext.declarative import declarative_base from sqlalchemy.orm import sessionmaker from .config import settings {% if db_type sqlite %} # SQLite 需要 check_same_threadFalse engine create_engine( settings.DATABASE_URL, connect_args{check_same_thread: False} ) {% elif db_type postgresql %} engine create_engine(settings.DATABASE_URL) {% endif %} SessionLocal sessionmaker(autocommitFalse, autoflushFalse, bindengine) Base declarative_base() # 依赖注入用于获取数据库会话 def get_db(): db SessionLocal() try: yield db finally: db.close()5. 路由聚合文件 (templates/{{project_name}}/app/api/__init__.py.j2):# app/api/__init__.py from fastapi import APIRouter from app.api.endpoints import items, users # 根据模板条件导入 api_router APIRouter() api_router.include_router(items.router, prefix/items, tags[items]) {% if with_auth %} api_router.include_router(users.router, prefix/users, tags[users]) {% endif %}6. 一个示例 CRUD 路由 (templates/{{project_name}}/app/api/endpoints/items.py.j2):# app/api/endpoints/items.py from fastapi import APIRouter, Depends, HTTPException from sqlalchemy.orm import Session from typing import List from app import schemas, crud from app.core.database import get_db router APIRouter() router.get(/, response_modelList[schemas.Item]) def read_items(skip: int 0, limit: int 100, db: Session Depends(get_db)): 检索项目列表 items crud.item.get_multi(db, skipskip, limitlimit) return items router.post(/, response_modelschemas.Item) def create_item(item: schemas.ItemCreate, db: Session Depends(get_db)): 创建新项目 return crud.item.create(db, obj_initem)7. Docker 相关模板 (条件生成):templates/{{project_name}}/Dockerfile.j2templates/{{project_name}}/docker-compose.yml.j2templates/{{project_name}}/.dockerignore.j28. 其他必要文件:templates/{{project_name}}/.gitignore.j2templates/{{project_name}}/README.md.j2templates/{{project_name}}/app/__init__.py(空文件)templates/{{project_name}}/app/schemas/,app/crud/,app/models/目录及示例文件。由于篇幅限制这里不展开所有模板文件内容但上述示例已经勾勒出了核心结构。完整的模板仓库可以独立维护。3.5 打包与安装 CLI 工具为了让工具可以通过pip安装我们需要配置pyproject.toml。# pyproject.toml [build-system] requires [setuptools61.0, wheel] build-backend setuptools.build_meta [project] name fastapi-scaffold-cli version 0.1.0 description A CLI tool to generate FastAPI project scaffolding. readme README.md authors [{name Your Name, email youexample.com}] license {text MIT} classifiers [ Programming Language :: Python :: 3, License :: OSI Approved :: MIT License, Operating System :: OS Independent, ] requires-python 3.8 dependencies [ Jinja23.1.2, ] [project.scripts] fastapi-scaffold fastapi_scaffold.cli:main [project.urls] Homepage https://github.com/yourusername/fastapi-scaffold-cli Bug Tracker https://github.com/yourusername/fastapi-scaffold-cli/issues然后在项目根目录下可以使用以下命令进行本地安装测试# 在开发模式下安装可编辑模式修改代码无需重装 pip install -e . # 安装后即可全局使用 fastapi-scaffold 命令 fastapi-scaffold --help4. 完整实战使用 CLI 工具生成项目现在让我们从头到尾演示如何使用这个工具。4.1 安装 CLI 工具假设你已经将工具打包并发布到了 PyPI或使用本地开发安装# 从 PyPI 安装发布后 pip install fastapi-scaffold-cli # 验证安装 fastapi-scaffold --help输出应显示create命令的帮助信息。4.2 生成一个基础项目创建一个名为my_fastapi_app的基础项目使用 SQLite不包含认证和 Dockerfastapi-scaffold create my_fastapi_app工具会快速执行输出类似 Created project directory: /path/to/current/dir/my_fastapi_app ✨ Rendered: requirements.txt Copied: .gitignore ✨ Rendered: app/main.py ✨ Rendered: app/core/config.py ... ✅ Project my_fastapi_app created successfully! Navigate to: /path/to/current/dir/my_fastapi_app Next steps: cd my_fastapi_app pip install -r requirements.txt uvicorn app.main:app --reload4.3 生成一个功能更全的项目创建一个包含 PostgreSQL 数据库、JWT 认证和 Docker 支持的项目fastapi-scaffold create my_fullstack_api --db postgresql --auth --docker --git输出会显示生成了更多文件包括Dockerfile,docker-compose.yml以及认证相关的路由和模型。4.4 运行生成的项目进入项目目录并启动服务cd my_fastapi_app # 创建虚拟环境推荐 python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows # 安装依赖 pip install -r requirements.txt # 启动开发服务器 uvicorn app.main:app --reload访问http://127.0.0.1:8000/docs即可看到自动生成的 Swagger UI 文档并且/api/items/等端点已经可用。4.5 项目结构回顾生成的项目结构清晰遵循了常见的 FastAPI 项目组织方式my_fastapi_app/ ├── .env.example # 环境变量示例 ├── .gitignore ├── requirements.txt ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 应用实例 │ ├── core/ # 核心配置、数据库连接等 │ │ ├── __init__.py │ │ ├── config.py │ │ └── database.py │ ├── api/ # 路由聚合 │ │ ├── __init__.py │ │ └── endpoints/ # 具体路由文件 │ ├── crud/ # 数据库操作层 │ ├── models/ # SQLAlchemy 模型 │ ├── schemas/ # Pydantic 模型 │ └── tests/ # 测试文件 └── README.md5. 常见问题与排查思路在使用或开发此类 CLI 工具时你可能会遇到以下问题问题现象常见原因解决思路命令fastapi-scaffold未找到1. 工具未正确安装。2. Python 脚本目录未加入系统 PATH。1. 使用pip install -e .在开发模式下重装。2. 检查虚拟环境是否激活或使用python -m fastapi_scaffold.cli create ...直接运行模块。生成项目时提示目录已存在目标目录project_name在当前路径下已存在。1. 删除或重命名已存在的目录。2. 换一个项目名或在其他路径下执行命令。模板渲染错误变量未定义Jinja2 模板中引用了未传递给上下文的变量。检查generator.py中的context字典确保包含了模板中所有用到的变量如{{ db_type }}。生成的项目运行时报ModuleNotFoundError1. 依赖未安装。2. 项目结构或导入路径错误。1. 确保在项目根目录下执行pip install -r requirements.txt。2. 检查app/main.py中的导入语句确保路径与生成的结构一致。使用相对导入如from .core.config import settings。使用--db postgresql选项后数据库连接失败1. PostgreSQL 服务未运行。2.DATABASE_URL中的连接信息用户名、密码、数据库名不正确。1. 启动 PostgreSQL 服务如sudo service postgresql start。2. 修改app/core/config.py或.env文件中的DATABASE_URL确保其指向正确的数据库实例。--auth选项生成的认证端点返回 4011. 未正确传递 JWT Token。2. Token 已过期或密钥不匹配。1. 在 Swagger UI 中点击 “Authorize” 按钮输入Bearer your_token。2. 检查SECRET_KEY和ALGORITHM配置确保生成和验证 Token 时使用相同的密钥。Docker 构建失败1. Dockerfile 中基础镜像不存在。2. 依赖安装超时或网络问题。1. 检查 Dockerfile 中的FROM python:3.11-slim等基础镜像标签是否有效。2. 尝试使用国内镜像源或在 Dockerfile 的pip install命令后添加--default-timeout100。6. 最佳实践与工程建议将这个 CLI 工具用于生产或团队协作时考虑以下最佳实践6.1 模板设计原则保持简洁与可扩展性初始模板应提供最必要的功能骨架避免过度设计。复杂的业务逻辑应由开发者后续添加。清晰的目录结构遵循 FastAPI 官方文档推荐或社区共识的结构如app/内部按功能分层使项目易于导航和理解。配置外部化所有配置数据库 URL、密钥、CORS 源都应通过环境变量或.env文件管理切勿将敏感信息硬编码在模板中。包含测试骨架即使在模板中只放一个空的tests/目录和__init__.py也能鼓励开发者编写测试。6.2 CLI 工具开发建议完善的错误处理如我们代码所示对目录存在、权限不足、模板缺失等情况进行友好提示并返回非零退出码。提供丰富的选项除了基础的--db,--auth可以考虑添加--celery任务队列、--redis缓存、--frontend生成前端模板等选项满足不同场景。支持自定义模板路径允许用户通过--template-path指定自己的模板目录实现高度定制化。版本管理对 CLI 工具和模板进行版本控制。当模板有重大更新时可以通过 CLI 版本号来管理兼容性。6.3 生成项目的后续开发指南立即进行版本控制生成项目后第一时间执行git init git add . git commit -m Initial scaffold。更新依赖版本生成器中的依赖版本如requirements.txt.j2可能不是最新的。创建项目后应检查并更新到安全、稳定的版本。修改默认配置必须修改默认的SECRET_KEY、数据库密码等敏感信息。为生产环境创建独立的配置文件如config/production.py。编写文档生成的README.md是一个起点应根据实际项目补充部署步骤、API 说明、环境变量列表等。逐步添加功能不要试图在模板中一次性包含所有功能。鼓励开发者根据需求逐步引入像 Alembic数据库迁移、Pytest、Loguru 等库。6.4 安全注意事项密钥管理强调在生成的项目中必须将SECRET_KEY、数据库凭证等替换为安全值并纳入.gitignore。依赖安全定期审计生成项目中的依赖requirements.txt使用工具如safety或pip-audit检查已知漏洞。CORS 配置提醒开发者根据实际前端地址严格配置BACKEND_CORS_ORIGINS在生产环境中避免使用[*]。输入验证虽然 FastAPI 和 Pydantic 提供了良好的验证但仍需在业务逻辑层对关键操作进行额外的校验和授权检查。通过构建这样一个 CLI 工具你不仅为自己和团队节省了大量重复劳动还深入理解了 FastAPI 的项目组织、配置管理和模板渲染技术。你可以以此为基础不断迭代模板加入更多最佳实践甚至为不同的技术栈如 FastAPI React, FastAPI Vue生成全栈项目骨架将开发效率提升到一个新的水平。