FastAPI 写一个 demo 很快但项目要像样不能所有代码都堆在 main.py。工程化的 FastAPI 项目要考虑分层、依赖注入、配置管理、异常处理、中间件、日志、数据库连接和测试。【一、什么叫工程化】工程化不是把项目写复杂而是让项目在多人协作、需求变化、出错排查、上线部署时仍然可维护。一个 demo 默认一切顺利参数一定正确数据库一定能连上外部 API 一定返回成功用户不会乱传数据工程化项目正好相反参数可能错数据库可能断模型 API 可能超时用户可能没权限任务可能失败日志必须能查【二、推荐项目结构】小型 FastAPI 项目可以这样拆app/main.pyapi/users.pytasks.pyschemas/user.pyservices/user_service.pyrepositories/user_repo.pycore/config.pysecurity.pydb/session.py大概职责- api接收请求返回响应。- schemasPydantic 请求和响应模型。- services业务逻辑。- repositories数据库访问。- core配置、安全、工具。- db数据库连接。【三、依赖注入是什么】FastAPI 的 Depends 可以把公共逻辑抽出来。比如获取当前用户from fastapi import Depends, HTTPExceptiondef get_current_user(token: str):user parse_token(token)if not user:raise HTTPException(status_code401, detail未登录)return userapp.get(/me)def me(current_userDepends(get_current_user)):return current_user这样每个需要登录的接口都可以复用 get_current_user。依赖注入常用于- 获取数据库连接。- 获取当前用户。- 校验权限。- 注入配置。- 注入第三方客户端。【四、Pydantic 模型怎么分】不要一个模型到处用。例如用户相关可以拆成class UserCreate(BaseModel):username: strpassword: strclass UserLogin(BaseModel):username: strpassword: strclass UserOut(BaseModel):id: intusername: str注意 UserOut 不应该包含 password 或 password_hash。请求模型和响应模型分开是后端安全和维护的基本习惯。【五、统一异常处理】项目里不要到处返回杂乱错误。可以统一异常结构{code: USER_NOT_FOUND,message: 用户不存在}FastAPI 可以注册异常处理器from fastapi import Requestfrom fastapi.responses import JSONResponseclass BizError(Exception):def __init__(self, code: str, message: str):self.code codeself.message messageapp.exception_handler(BizError)async def biz_error_handler(request: Request, exc: BizError):return JSONResponse(status_code400,content{code: exc.code, message: exc.message},)这样业务层可以直接抛 BizError。【六、中间件是什么】中间件是在请求进入接口前、响应返回客户端前执行的一层逻辑。常见用途- 记录请求日志。- 统计接口耗时。- 处理跨域 CORS。- 统一添加响应头。- 追踪 request_id。示例import timefrom fastapi import Requestapp.middleware(http)async def log_requests(request: Request, call_next):start time.time()response await call_next(request)cost time.time() - startprint(request.method, request.url.path, cost)return response生产项目里建议用 logging不要直接 print。【七、配置管理】不要把数据库密码、JWT 密钥写死在代码里。推荐用环境变量from pydantic_settings import BaseSettingsclass Settings(BaseSettings):database_url: strjwt_secret: strclass Config:env_file .envsettings Settings().env 不要上传 GitHub.env.example 可以上传示例。【八、测试怎么写】FastAPI 可以用 TestClient 测接口。from fastapi.testclient import TestClientfrom app.main import appclient TestClient(app)def test_health():resp client.get(/health)assert resp.status_code 200有测试的项目比只有截图的项目更有工程化说服力。【九、常见坑】- 所有代码堆在一个文件。- 数据库连接在每个接口里重复创建。- 配置写死密钥上传 GitHub。- 只写 happy path不处理异常。- 没有日志出问题只能猜。- 请求模型和响应模型混用泄漏敏感字段。【十、面试常问】1. FastAPI 的 Depends 有什么用Depends 用于依赖注入可以复用公共逻辑例如数据库连接、当前用户、权限校验、配置对象等减少重复代码。2. 中间件适合做什么适合处理请求级别的通用逻辑比如日志、耗时统计、CORS、request_id、鉴权前置处理等。不适合把复杂业务逻辑都塞进中间件。3. FastAPI 项目如何分层常见分层是 API 层处理请求响应Schema 层定义数据结构Service 层写业务逻辑Repository 层访问数据库Core 层管理配置和安全工具。
