FastAPI 实战项目：从 0 到 1 搭一个类似 Netflix Dispatch 的事件管理后端

前言最近在做一个偏工程化的后端练手项目我没有再去写“用户管理 文章管理”这种常规 CRUD而是选择实现一个Netflix Dispatch的精简版后端。这个项目更接近真实业务场景它有 Incident 的创建、搜索、指派、状态流转也有团队权限、任务拆分、通知系统、WebSocket 实时推送以及 Alembic 迁移、Docker Compose、测试和 CI。我觉得这类项目特别适合写进简历或者做技术总结因为它体现的不是“会不会写接口”而是“有没有把后端当成一个完整系统来设计”。一、项目背景为什么选择做 Dispatch 类项目Dispatch这类系统本质上是在解决“事件协同处理”问题。一个 Incident 从创建开始通常会经历谁提交的谁能看见谁来接手当前处于什么状态中间发生了哪些操作相关人员如何收到通知所以相比传统 CRUD这类项目天然更适合练习后端里的几个关键能力权限控制、状态机设计、事件记录、异步通知、实时通信和系统分层。而我的这个项目就是围绕这些核心点展开的。README 中也明确写了这个项目目标不是完整复刻 Dispatch而是聚焦 Incident 核心流程并强调后端工程化实践比如权限、状态流转、通知、迁移、容器化、测试和 CI二、技术栈选型这个项目的技术栈如下FastAPI负责 API 层开发接口定义清晰文档友好SQLAlchemy 2.xasync asyncpg做异步数据库访问Alembic管理数据库迁移PostgreSQL作为主数据库Redis缓存和消息相关能力Celery处理异步任务WebSocket实现实时通知订阅Docker Compose本地一键启动Pytest GitHub Actions做测试和 CI 验证这套组合很典型也很实用。尤其是FastAPI PostgreSQL Redis Celery基本已经覆盖了很多中小型后端系统的核心基础设施。三、整体架构设计我怎么拆这个项目从目录结构上看这个项目不是把所有逻辑都塞进 router而是按职责拆成了几层models数据库模型schemas请求/响应模型crud数据库读写services业务编排routers接口路由utils鉴权、缓存、WebSocket、邮件等公共能力conf配置与数据库会话alembic迁移脚本这种拆法的好处很明显router 不直接承担全部业务逻辑crud 层聚焦数据存取service 层负责更复杂的业务编排公共能力沉淀到 utils避免重复造轮子在main.py中应用通过 FastAPI 的lifespan管理资源退出时机关闭数据库引擎和 Redis 连接同时统一挂载/api/v1路由。根路由还保留了简单的健康接口方便基础验证。四、核心模块设计1认证与权限用户模块支持注册、登录、JWT 鉴权以及管理员权限校验。/users/register和/users/login完成身份入口/users/me用于获取当前用户信息而管理员接口则通过require_superuser做权限收口。这一层虽然不复杂但它是后续一切业务的基础。因为 Incident、Team、Task、Notification 几乎都离不开“当前用户是谁”“有没有权限”的判断。真实后端项目里权限系统做不好业务边界就会很混乱。2Incident 模块项目的核心Incident 是这个系统最关键的业务实体。项目里已经支持Incident 列表Incident 搜索Incident 详情Incident 指派Incident 状态流转评论与事件记录能力其中我觉得最值得展开写的是两个点。第一列表与搜索不是“全量返回”而是有可见性规则。在list_incidents里管理员可以看到全部 Incident普通用户只能看到“我创建的”或者“指派给我的” Incident。搜索接口也沿用了用户身份和筛选条件支持q / status / team_id / assignee_id / reporter_id / limit / offset等参数。这个设计说明项目开始考虑“业务可见性”了而不是停留在最基础的查库返回。第二指派与状态流转不是简单改字段而是会联动事件和通知。在指派逻辑中如果 assignee 发生变化系统会写入ASSIGNED事件同时给新负责人创建通知如果 Incident 原本是OPEN在被指派后还会自动变成TRIAGED并记录状态变更事件。这个链路设计非常像真实业务系统。3状态机设计限制非法流转很多练手项目在状态字段上只是放一个字符串但这个项目已经开始做“状态机约束”了。代码里明确限制了状态流转规则OPEN - TRIAGEDTRIAGED - CLOSEDCLOSED之后不能再继续流转如果出现非法状态切换会直接返回 400。这个设计的意义在于业务规则不再依赖前端自觉而是在后端被强约束下来。这也是一个项目从“能跑”走向“靠谱”的重要一步。4Task 模块把 Incident 拆成可执行动作除了 Incident 主流程项目还设计了 Task 模块用于为某个 Incident 创建任务并支持按 Incident 查看相关任务。也就是说系统不是停在“记录一条故障单”而是开始往“协同处理”演进。这类设计的价值在于一个 Incident 往往不会被一个接口解决而是会分解成若干工作项。Task 的存在让系统更像一个真实的团队协作后端而不是单表管理。5通知系统REST WebSocket 双通道这个项目里通知能力做了两层一层是 REST 接口。用户可以查询自己的通知列表还可以将单条通知标记为已读。这个设计适合页面首次加载、历史通知回看等场景。另一层是 WebSocket 实时订阅。项目提供了/api/v1/ws/notifications?tokenJWT这样的 WebSocket 入口客户端携带 JWT 即可建立实时通知连接。这意味着它不只是“把通知存到数据库里”而是已经考虑到消息实时到达的用户体验。从练手项目角度说这一点很加分。因为很多人会写通知表但不会真正把“实时推送链路”打通。五、异步任务设计为什么还要引入 Celery项目里单独定义了celery_app.py使用 Redis 作为 broker 和 result backend并把任务包含到utils.mail中。Docker Compose 里也单独起了worker服务命令为celery -A celery_app.celery worker -l info。这说明这个项目不是把所有动作都同步执行而是已经有意识地区分哪些请求应该快速返回哪些任务适合异步处理哪些通知/邮件逻辑应该交给后台 worker这类设计在生产环境里非常重要。比如发邮件、批量通知、耗时任务编排如果全部放在接口线程里接口延迟和稳定性都会受到影响。引入 Celery 后系统在架构层面会更合理。六、工程化能力Docker、迁移、测试、CI1Docker Compose 一键启动仓库已经提供了docker-compose.yml里面包含dbPostgreSQL 16redisRedis 7apiFastAPI 服务workerCelery Worker并且api容器启动时会先执行alembic upgrade head再启动 Uvicorn。也就是说数据库迁移和服务启动链路已经串起来了。这一点非常实用因为它让项目的“启动方式”不再依赖本地手工操作别人拉下代码后更容易复现环境。对简历项目来说这也是很重要的工程化信号。2测试不是空白README 里说明当前已经提供最小可运行测试而tests目录下至少有test_health.py和test_security.py两个测试文件。虽然规模还不算大但至少已经把“可验证性”这件事考虑进来了。我个人觉得这是很多练手项目最容易忽略的一点接口能写出来不算结束能不能被稳定验证决定了这个项目到底像不像“工程项目”。3GitHub Actions 做基础 CI仓库中已经配置了 GitHub Actions 的CI工作流在push到master/main或发起pull_request时会使用 Python 3.11 安装依赖并执行pytest -q。这一步虽然基础但意义很大。因为它说明这个项目已经从“本地自己跑通”进入到“每次提交都能自动验证”的阶段。对后端项目来说这是非常标准且必要的工程实践。七、这个项目里我最满意的几个点如果让我总结这个项目最有价值的地方不是“功能多”而是下面这几个思路做对了1. 不是只做表结构而是做业务流Incident 不是单表增删改查而是包含创建、可见性、指派、状态流转、事件记录和通知联动。2. 有明确的权限边界管理员和普通用户能看到什么、能操作什么已经开始分层处理。3. 开始考虑系统拆分crud / services / routers / utils的分层让代码不会很快失控。4. 有异步和实时能力Celery 负责异步任务WebSocket 负责实时通知这已经明显超出了普通练手项目的深度。5. 有基本工程保障Alembic、Docker Compose、测试、CI这些能力让项目更接近真实协作开发。八、后续还能怎么继续完善当然这个项目还有不少可以继续提升的空间。比如补充更完整的单元测试和集成测试增加更细粒度的 RBAC 权限模型给通知系统增加重试和失败补偿优化 Incident 搜索能力比如全文检索或更丰富的筛选条件增加更完整的审计日志和操作追踪对 WebSocket 连接管理做更完善的异常处理和横向扩展设计这些能力一旦补上项目的“工程感”会更强也更适合作为面试中的项目讲解案例。现有仓库已经有不错的基础用户认证、Incident 主流程、Team、Task、Notification、WebSocket、容器化、测试和 CI 都已经搭起来了。九、总结这个fastapi_netflix_dispatch项目让我最大的收获是一个好的后端练手项目重点不在于页面有多花而在于后端有没有真正体现业务流和工程化能力。如果只是做 CRUD项目很容易显得薄但当你开始处理权限、状态流转、事件记录、异步通知、实时推送、测试和 CI 时项目的含金量就完全不一样了。这个项目虽然是精简版但它已经具备了一个事件管理系统的关键骨架。如果你也在学 FastAPI我很建议尝试做一个类似这种“有业务流”的项目。它比单纯做几个接口更累但成长也会更快。项目地址https://github.com/juemimgcd项目名称fastapi_netflix_dispatch