FastAPI 集成 Redis 开发手册

I'm Jie2026-03-31 16:00

Redis 是一款高性能的键值对内存数据库，凭借内存读写、单线程模型、丰富数据结构等特性，被广泛应用于缓存、会话存储、接口限流、消息队列等后端场景。在 FastAPI 项目中集成 Redis，可大幅提升接口响应速度、减轻数据库查询压力，是后端开发的核心必备技能。

本文提供可落地的 FastAPI + Redis 异步集成方案，从环境搭建、配置管理、客户端封装，到接口开发、生命周期管理，全程采用异步编程规范，兼顾代码可维护性与性能，同时补充实操细节和避坑点，带你快速完成集成落地。

一、搭建 Redis 服务（本地 / 远程）

1.1 本地安装（MacOS 推荐）

使用 Homebrew 一键安装，简洁高效，适合开发环境（MacOS 安装 Homebrew）：

Bash 复制代码 
# 安装 Redis
brew install redis

1.2 启动 Redis 服务

推荐后台常驻启动（不占用终端，关闭终端仍运行），也可选择前台临时运行（方便查看日志）：

Bash 复制代码 
# 方式1：后台常驻启动（开发/生产推荐）
brew services start redis

# 方式2：前台临时运行（仅调试，关闭终端即停止）
redis-server

1.3 基础服务信息

  • 默认连接地址：redis://``localhost:6379
  • 默认配置：无密码、使用 0 号数据库
  • 验证启动成功：终端输入 redis-cli，进入客户端后输入 ping，返回 PONG 即启动正常

1.4 远程 Redis 服务说明

若使用云服务器 / 远程 Redis，无需本地安装，只需获取以下信息即可：

  • 远程 Redis 地址（host）、端口（port）
  • 访问密码（password）
  • 分配的数据库编号（db）
  • 确保服务器开放对应端口，且 Redis 配置允许远程连接（需修改 redis.conf 关闭绑定 IP 限制）

二、项目环境与依赖准备

2.1 安装核心依赖

本次集成需安装以下依赖：

Bash 复制代码 
# 核心依赖安装
poetry add fastapi redis pydantic-settings uvicorn

2.2 项目目录结构

目录结构如下（核心文件标注）：

Bash 复制代码 
your_project/
├── .env                # 环境变量配置（敏感信息，不提交仓库）
├── config.py           # Redis 配置类（统一管理连接参数）
├── redis_client.py     # Redis 客户端封装（单例+连接池）
├── redis_api.py        # Redis 操作接口路由
├── main.py             # FastAPI 主程序（生命周期+路由注册）
└── requirements.txt    # 项目依赖清单

三、配置文件管理

采用 Pydantic Settings + .env 环境文件的方式管理配置，支持开发 / 测试 / 生产多环境切换，配置统一管理且易于修改，同时隔离敏感信息（如密码）。

3.1 核心配置文件（config.py）

自动从 .env 文件加载配置，支持类型校验，默认值兜底，避免配置缺失导致的报错：

python 复制代码 
from pydantic_settings import BaseSettings, SettingsConfigDict

class RedisConfig(BaseSettings):
    """Redis 连接配置类，自动从 .env 加载，支持类型校验"""
    redis_host: str = "localhost"       # Redis 地址
    redis_port: int = 6379              # Redis 端口
    redis_password: str = ""            # Redis 密码（无则空）
    redis_db: int = 0                   # 使用的数据库编号
    redis_decode_responses: bool = True # 自动解码响应为字符串（无需手动转码）
    redis_max_connections: int = 50     # 连接池最大连接数（避免连接溢出）# 配置 .env 文件加载规则
    model_config = SettingsConfigDict(
        env_file=".env",        # 指定环境文件路径
        env_file_encoding="utf-8", # 文件编码
        case_sensitive=False    # 忽略环境变量大小写)# 创建全局配置实例，项目中统一引用
redis_config = RedisConfig()

3.2 环境变量文件（.env）

存储具体配置值，该文件需添加到 .gitignore 中，禁止提交到代码仓库，避免敏感信息泄露：

Plain 复制代码 
# Redis 基础连接配置（与 RedisConfig 字段对应）
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
# 自动解码响应为字符串，建议开启
REDIS_DECODE_RESPONSES=True
# 连接池最大连接数，根据项目并发量调整
REDIS_MAX_CONNECTIONS=50

3.3 多环境配置扩展（可选）

若需要区分开发 / 测试 / 生产环境，可创建多个环境文件（.env.dev、.env.test、.env.prod），并在启动服务时指定：

Plain 复制代码 
# 启动时指定环境文件（开发环境）ENV_FILE=.env.dev uvicorn main:app --reload

同时修改 config.py 中 env_file 为动态读取：

python 复制代码 
import os
model_config = SettingsConfigDict(
    env_file=os.getenv("ENV_FILE", ".env"), # 优先读取环境变量指定的文件
    env_file_encoding="utf-8")

四、Redis 客户端封装

采用连接池 + 单例模式 封装 Redis 客户端，避免重复创建连接导致的资源泄漏，同时统一管理连接，适配 FastAPI 异步特性。核心使用 redis.asyncio 提供的异步 API，所有操作均为协程。

4.1 客户端封装（redis_client.py）

python 复制代码 
from redis.asyncio import Redis, ConnectionPool
from config import redis_config

# 创建 Redis 连接池（核心：复用连接，提升性能）
redis_connection_pool = ConnectionPool(
    host=redis_config.redis_host,
    port=redis_config.redis_port,
    password=redis_config.redis_password,
    db=redis_config.redis_db,
    decode_responses=redis_config.redis_decode_responses,
    max_connections=redis_config.redis_max_connections,
    socket_timeout=5,  # 补充：socket 超时时间（秒），避免连接阻塞
    socket_connect_timeout=3  # 补充：连接超时时间（秒）
)

# 从连接池创建 Redis 客户端实例（单例，项目中统一引用）
redis_client = Redis.from_pool(redis_connection_pool)

# 可选：添加连通性测试函数（用于服务启动时校验 Redis 连接）
async def check_redis_connect() -> bool:
    """校验 Redis 连通性，返回 True 表示连接正常"""
    try:
        await redis_client.ping()
        return True
    except Exception as e:
        print(f"Redis 连接失败：{str(e)}")
        return False

4.2 基础使用

项目中任意异步代码中，直接导入 redis_client 即可使用，所有操作需加 await（异步协程）：

python 复制代码 
from redis_client import redis_client

# 1. 设置键值对（永久有效）
await redis_client.set("name", "fastapi-redis")

# 2. 设置带过期时间的键值对（10 秒后过期）
await redis_client.setex("code", 10, "123456")

# 3. 获取值
value = await redis_client.get("name")

# 4. 删除键
await redis_client.delete("code")

# 5. 判断键是否存在
exists = await redis_client.exists("name")

五、开发 Redis 操作接口

创建 api_router.py，直接基于封装的客户端开发 Redis 基础操作接口：

python 复制代码 
from fastapi import APIRouter, HTTPException
from redis_client import redis_client
from typing import Optional

# 创建路由
router = APIRouter(
    prefix="/redis",
    tags=["Redis 操作接口"]
)

# 1. 设置缓存（支持过期时间）
@router.post("/set")
async def set_redis_cache(key: str, value: str, expire: Optional[int] = None):
    """
    设置 Redis 缓存
    - key: 缓存键
    - value: 缓存值
    - expire: 过期时间（秒），可选
    """
    try:
        if expire:
            await redis_client.setex(key, expire, value)
        else:
            await redis_client.set(key, value)
        return {"status": "success", "msg": f"键 {key} 设置成功"}
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"设置缓存失败：{str(e)}")

# 2. 获取缓存
@router.get("/get")
async def get_redis_cache(key: str):
    """根据 key 获取 Redis 缓存"""
    try:
        value = await redis_client.get(key)
        if not value:
            raise HTTPException(status_code=404, detail=f"键 {key} 不存在")
        return {"status": "success", "key": key, "value": value}
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"获取缓存失败：{str(e)}")

六、FastAPI 生命周期管理

使用 FastAPI 内置的 lifespan 上下文管理器，统一管理服务启动前初始化 和关闭后资源释放，确保 Redis 连接池优雅关闭，避免进程退出时的资源泄漏。

6.1 主程序开发（main.py）

python 复制代码 
from contextlib import asynccontextmanager
from fastapi import FastAPI
import uvicorn
from api_router import router
from redis_client import redis_client, check_redis_connect

# 定义服务生命周期
@asynccontextmanager
async def lifespan(app: FastAPI):
    # 服务启动前：执行初始化操作
    print("FastAPI 服务启动中，开始校验 Redis 连接...")
    redis_connect_status = await check_redis_connect()
    if not redis_connect_status:
        print("Redis 连接失败，服务启动异常！")
    else:
        print("Redis 连接成功，服务启动完成！")
    yield  # 服务运行中
    # 服务关闭后：释放资源（优雅关闭 Redis 客户端和连接池）
    await redis_client.close()
    print("FastAPI 服务已关闭，Redis 客户端及连接池已释放！")

# 创建 FastAPI 实例
app = FastAPI(
    title="FastAPI 集成 Redis 项目",
    lifespan=lifespan  # 绑定生命周期
)

# 注册全局总路由
app.include_router(router)

# 主函数运行服务
if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",  # 允许外部访问
        port=8000,       # 服务端口
        reload=True      # 开发环境自动重载（生产环境关闭）
    )

6.2 启动并测试服务

终端运行主程序，启动 FastAPI 服务：

Bash 复制代码 
python main.py

服务启动后，可通过以下地址访问：

在 Swagger 文档中，找到「Redis 操作接口」，即可直接测试 set/get 等接口。

七、Redis 可视化管理工具推荐

命令行操作 Redis 效率较低，推荐以下可视化工具，支持图形化操作、连接管理、数据查看，适配不同使用场景和系统：

工具名称 授权方式 核心优势
Redis Insight 免费官方 官方出品、支持集群/哨兵、监控面板、慢查询分析
Another Redis Desktop Manager 开源免费 中文友好、轻量流畅、支持 SSH 隧道
Tiny RDM 开源免费 极简小巧、启动快、无多余功能
Medis 免费（Mac） 界面美观、操作顺滑、Mac 原生体验
相关推荐
keyborad pianist2 小时前
一篇文章学会Redis
数据库·redis·缓存
ok_hahaha2 小时前
java从头开始-黑马点评-分布式锁-redis实现基础版
java·redis·分布式
敢敢のwings3 小时前
智元 D1 强化学习sim-to-real系列 | Robot Lab 基于 Isaac Lab 的机器人强化学习使用（四）
数据库·redis·机器人
samson_www4 小时前
用nssm部署FASTAPI服务
数据库·python·fastapi
小李云雾4 小时前
零基础-从ESS6基础到前后端联通实战
前端·python·okhttp·中间件·eclipse·html·fastapi
dovens4 小时前
GO 快速升级Go版本
开发语言·redis·golang
XDHCOM5 小时前
TP5框架Redis分布式缓存实战，解决高并发场景下的数据一致性问题
redis·分布式·缓存
手握风云-5 小时前
Redis：不只是缓存那么简单（一）
redis·缓存
yuweiade5 小时前
docker desktop安装redis
redis·docker·容器
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03围棋-html版本04纯 HTML/CSS/JS 实现的高颜值登录页，还会眨眼睛！少女心爆棚！05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06OpenClaw 使用和管理 MCP 完全指南07Mac 本地部署 OMLX + 通义千问 Qwen3.5-27B 保姆级教程08“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）09班级宠物园部署指南10Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services