FastAPI实现角色权限控制与项目重构实践

1. 项目背景与目标

最近在开发一个基于FastAPI的后端服务时，遇到了权限管理的问题。现有的系统只有简单的登录验证，所有用户登录后都能访问所有接口，这显然不符合实际业务需求。于是决定对系统进行升级，主要实现以下几个目标：

1. 在用户模型中添加角色字段(role)，区分普通用户和管理员
2. 实现接口级别的权限控制，确保只有管理员能访问特定接口
3. 重构项目结构，采用标准后端分层架构
4. 将注册功能从主文件中拆解出来，提高代码可维护性

这个改造过程涉及到数据库模型修改、权限中间件开发、项目结构重构等多个环节，下面我会详细记录每个步骤的实现细节和注意事项。

2. 环境准备与基础配置

2.1 开发环境

项目基于以下技术栈：

• Python 3.13
• FastAPI 0.95.2
• SQLAlchemy 2.0
• Pydantic 1.10.7

开发工具使用PyCharm，数据库采用SQLite（适合快速开发和测试）。

2.2 初始状态检查

在开始改造前，确保已有功能正常运行：

• 数据库连接正常
• 用户注册/登录功能可用
• JWT token生成和验证正常
• 基础API接口能正确响应

可以通过以下命令启动服务：

bash复制uvicorn main:app --reload

3. 实现角色管理与权限控制

3.1 修改用户数据模型

首先需要在用户表中添加role字段，用于区分用户角色。修改models.py文件：

python复制from sqlalchemy import Column, Integer, String
from app.db.database import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    phone = Column(String, unique=True, index=True)
    password = Column(String)
    role = Column(String, default="user")  # 新增角色字段

关键点说明：

1. role字段类型为String，默认值为"user"
2. 后续可以通过修改该字段值为"admin"来提升用户权限
3. 由于修改了模型结构，需要重建数据库表

注意：在生产环境中，应该使用数据库迁移工具如Alembic来处理模型变更，而不是直接删除重建数据库。

3.2 重建数据库

由于模型结构发生了变化，最简单的方法是删除旧数据库并让SQLAlchemy重新创建：

1. 删除项目目录下的database.db文件
2. 重启FastAPI服务，会自动创建新表

验证方法：

1. 注册一个新用户
2. 检查数据库，确认role字段已存在且默认值为"user"

3.3 实现管理员专属接口

现在可以创建一个只有管理员能访问的接口。在main.py中添加：

python复制from fastapi import HTTPException, Depends

@app.get("/ad