day03(搭建项目框架)

一、前言今天我们将学习了如何搭建一个标准化 FastAPI 项目框架包含环境配置、数据库连接、全局异常处理、接口与服务分层等核心内容二、项目目录结构先看一下最终的项目目录这是典型的分层架构职责清晰plaintextboss_api/ ├── app/ │ ├── __init__.py │ ├── config/ # 配置模块 │ │ ├── __init__.py │ │ └── settings.py # 环境配置、Pydantic Settings │ ├── core/ # 核心功能模块 │ │ ├── __init__.py │ │ ├── database.py # 数据库连接、Tortoise-ORM 配置 │ │ ├── exception_handler.py # 全局异常处理 │ │ └── logging.py # 日志配置 │ ├── models/ # ORM 模型层 │ │ └── __init__.py │ ├── schemas/ # Pydantic 请求/响应模型 │ │ └── __init__.py │ └── services/ # 业务逻辑服务层 │ └── __init__.py ├── logs/ # 日志文件目录 ├── .env # 通用环境变量 ├── .env.dev # 开发环境配置 ├── .env.prod # 生产环境配置 ├── .env.test # 测试环境配置 ├── main.py # 应用入口 └── test_main.http # 接口测试文件分层职责说明config统一管理应用配置支持多环境切换。core存放核心基础设施如数据库、异常处理、日志等。models定义数据库表结构Tortoise-ORM 模型。schemas定义请求体、响应体的 Pydantic 模型做数据校验。services封装业务逻辑实现接口与业务解耦。main.py应用启动入口注册路由、中间件、生命周期等。三、核心配置与环境管理1. 环境变量与 Pydantic Settings使用pydantic-settings管理配置支持从.env文件加载实现多环境隔离。python运行# app/config/settings.py from pydantic_settings import BaseSettings, SettingsConfigDict class BaseAppSettings(BaseSettings): 基础配置类所有环境共享 model_config SettingsConfigDict( env_file_encodingutf-8, case_sensitiveFalse, extraignore, # 让子类继承 env 配置不会被覆盖掉这是核心修复 env_file.env, ) # 通用配置 app_title: str p4boss开发文档 app_version: str 1.0.0 api_prefix: str /api/v1 app_description: str Boss项目的接口文档,包含求职者端,企业端,管理端 # 可根据环境继承基础配置 class DevSettings(BaseAppSettings): model_config SettingsConfigDict(env_file.env.dev) debug: bool True class ProdSettings(BaseAppSettings): model_config SettingsConfigDict(env_file.env.prod) debug: bool False # 根据环境变量选择配置 settings DevSettings() # 开发环境 # settings ProdSettings() # 生产环境2. 数据库配置Tortoise-ORM在core/database.py中定义 Tortoise-ORM 配置通过lifespan管理数据库连接生命周期。python运行# app/core/database.py from tortoise import Tortoise TORTOISE_ORM { connections: { default: { engine: tortoise.backends.mysql, credentials: { host: 127.0.0.1, port: 3306, user: root, password: 123456, database: boss_api, charset: utf8mb4, } } }, apps: { models: { models: [app.models, aerich.models], default_connection: default, } } }四、全局异常处理为了统一 API 错误响应格式我们实现全局异常捕获所有未处理的异常都会被封装成标准 JSON 格式返回。python运行# app/core/exception_handler.py from starlette.requests import Request from starlette.responses import JSONResponse def global_exception_handler(request: Request, exc: Exception) - JSONResponse: 全局异常处理 return JSONResponse( status_code500, content{ code: 400, msg: str(exc) or 服务器错误 } )在main.py中注册异常处理器python运行from app.core.exception_handler import global_exception_handler app.add_exception_handler(Exception, global_exception_handler)五、应用启动与中间件配置1. 生命周期管理Lifespan使用asynccontextmanager管理应用启动 / 关闭时的资源比如数据库连接的初始化与释放。python运行# main.py from contextlib import asynccontextmanager from fastapi import FastAPI from tortoise import Tortoise from app.config.settings import settings from app.core.exception_handler import global_exception_handler from fastapi.middleware.cors import CORSMiddleware from fastapi.middleware.trustedhost import TrustedHostMiddleware asynccontextmanager async def lifespan(app: FastAPI): # 项目启动时执行初始化 Tortoise-ORM await Tortoise.init(configTORTOISE_ORM, _enable_global_fallbackTrue) yield # 应用运行期间 # 项目关闭时执行关闭数据库连接 await Tortoise.close_connections() # 创建 FastAPI 实例 app FastAPI( titlesettings.app_title, versionsettings.app_version, descriptionsettings.app_description, lifespanlifespan # 注册生命周期 )2. 中间件配置CORS 中间件解决跨域问题允许所有来源访问。TrustedHost 中间件限制可访问的主机头防止主机头攻击。python运行# 解决跨域 app.add_middleware( CORSMiddleware, allow_origins[*], allow_credentialsTrue, allow_methods[*], allow_headers[*], ) # 解决主机头信任问题 app.add_middleware(TrustedHostMiddleware, allowed_hosts[*])六、接口层与服务层分离1. 分层思想接口层API Layer负责接收请求、参数校验、调用服务层、返回响应。服务层Service Layer封装核心业务逻辑与数据库交互不关心 HTTP 细节。2. 代码示例接口层路由python运行# app/api/user.py from fastapi import APIRouter from app.services.user_service import get_user_service user_router APIRouter(prefix/users, tags[用户管理]) user_router.get(/{user_id}) async def get_user(user_id: int): # 只做参数传递和结果返回业务逻辑交给服务层 user await get_user_service(user_id) return {code: 200, data: user}服务层业务逻辑python运行# app/services/user_service.py from app.models import User async def get_user_service(user_id: int): 获取用户信息的业务逻辑 user await User.get_or_none(iduser_id) if not user: raise ValueError(用户不存在) return user分层优势解耦接口层专注于 HTTP 交互服务层专注于业务逻辑。可测试服务层可独立测试无需启动 Web 服务。可复用业务逻辑可被多个接口复用。易维护修改业务逻辑不影响接口定义。七、今日学习总结项目结构掌握了标准 FastAPI 分层架构清晰划分 config、core、models、schemas、services 等模块。环境管理使用 Pydantic Settings .env文件实现多环境配置隔离。生命周期通过lifespan管理应用启动 / 关闭时的资源如数据库连接。异常处理实现全局异常捕获统一 API 错误响应格式。中间件配置 CORS 和 TrustedHost 中间件解决跨域和安全问题。分层开发理解接口层与服务层的分离思想提升代码可维护性和可测试性。