本文深入介绍了如何在 FastAPI 中零依赖实现轻量、灵活且生产就绪的 RBAC（基于角色的权限控制）系统：通过 Pydantic 定义清晰的角色与权限模型，利用 FastAPI 原生依赖注入机制完成用户认证后的角色提取与自动注入，并封装可复用的 `require_permission` 依赖项实现声明式权限校验；同时支持通配符授权、多权限组合、前缀匹配及角色继承等进阶能力，全程无需引入 fastapi-users 等第三方库，代码简洁、逻辑透明、易于测试与扩展，为中小型项目提供了高性价比的权限治理方案。

FastAPI 本身不内置 RBAC（基于角色的权限控制），但可以完全不用第三方库（如 fastapi-users、authlib 等），仅靠其依赖注入、依赖项（Depends）、Pydantic 模型和中间件机制，实现轻量、清晰、可扩展的角色权限控制。

1. 定义用户、角色与权限模型

先用 Pydantic 和 Python 原生数据结构描述核心概念，避免过早耦合数据库：

• 角色（Role）：如 "admin"、"editor"、"viewer"
• 权限（Permission）：字符串标识，如 "user:read"、"post:write"、"config:delete"
• 角色-权限映射：用字典静态定义或从配置/DB 加载，例如：

ROLE_PERMISSIONS = {
    "admin": ["*"],  # 通配符表示全部权限（需后端校验时特殊处理）
    "editor": ["post:read", "post:write", "user:read"],
    "viewer": ["post:read", "user:read"]
}

注意："*" 是语义约定，不是通配符匹配逻辑，后续校验需显式判断。

2. 用户身份认证与角色注入

假设你已通过 JWT 或 Session 完成基础认证，并从中提取出当前用户 ID 和角色（例如从 token payload 或数据库查得）。关键是在每个需要鉴权的路由中，把 role 作为依赖项注入：

• 写一个依赖函数，负责解析凭证 → 获取用户 → 提取角色 → 返回角色名（str）或完整用户对象
• 该函数抛出 HTTPException(status_code=401) 或 403，FastAPI 会自动终止请求

from fastapi import Depends, HTTPException, status
from typing import Annotated
async def get_current_role() -> str:
示例：从 Authorization header 解析 Bearer Token 并验证（省略 JWT 验证细节）
# 实际中应调用你的 auth 工具函数，返回 role 字符串，如 "editor"
token = "fake-token"  # ← 替换为真实逻辑
# ... 解码、校验、查 DB 得到 role
role = "editor"
if not role:
    raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid or missing credentials")
return role

这样，所有需要鉴权的接口都能通过 role: str = Depends(get_current_role) 获得当前角色。

3. 权限检查依赖项（核心）

封装一个可复用的依赖项，接收所需权限字符串，自动比对当前角色是否具备：

from fastapi import Depends, HTTPException, status
def require_permission(required_perm: str):
async def _check(role: str = Depends(get_current_role)) -> None:
perms = ROLE_PERMISSIONS.get(role, [])
if "*" in perms or required_perm in perms:
return
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail=f"Role '{role}' lacks permission '{required_perm}'"
)
return _check

使用方式非常简洁：

@app.get("/api/posts")
async def list_posts(_=Depends(require_permission("post:read"))):
    return [{"id": 1, "title": "Hello"}]

支持多权限校验（如同时要读+写）可稍作增强，例如传入列表并全量检查；也可扩展为支持 "post:*" 模式匹配（需自行实现前缀匹配逻辑）。

4. 角色继承与动态权限（进阶可选）

若需角色继承（如 editor 自动拥有 viewer 权限），可改用有向图或层级字典：

ROLE_HIERARCHY = {
    "admin": [],
    "editor": ["viewer"],
    "viewer": []
}
def get_all_permissions_for_role(role: str) -> set:
perms = set(ROLE_PERMISSIONS.get(role, []))
for parent in ROLE_HIERARCHY.get(role, []):
perms.update(get_all_permissions_for_role(parent))
return perms

然后在 require_permission 中调用它替代直查 ROLE_PERMISSIONS。无需 ORM 或外部库，纯逻辑即可支撑常见业务需求。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~