项目结构

文档版本: 1.0
最后更新: 2026-04-14

概述

本文档详细说明 Litefs 项目的目录结构、模块职责和文件组织，帮助开发者快速理解项目架构。

1. 项目根目录

litefs/
├── src/                    # 源代码目录
│   └── litefs/            # 主包目录
├── tests/                  # 测试代码目录
├── examples/               # 示例代码目录
├── docs/                   # 文档目录
├── .trae/                  # Trae AI 配置
├── .scannerwork/           # SonarQube 扫描结果
├── pyproject.toml          # 项目配置文件
├── setup.py                # 安装脚本
├── requirements.txt        # 依赖列表
├── Makefile                # 构建命令
├── README.md               # 项目说明
├── LICENSE                 # 许可证
└── MANIFEST.in             # 打包清单

2. 源代码结构

2.1 主包目录 (src/litefs/)

src/litefs/
├── __init__.py             # 包初始化，导出公共 API
├── __main__.py             # 命令行入口
├── _version.py             # 版本信息
├── cli.py                  # 命令行工具
├── cli_db.py               # 数据库迁移 CLI（litefs db 子命令）
├── config.py               # 配置管理
├── context.py              # 请求上下文（g / 协程上下文）
├── core.py                 # 核心类 Litefs（Mixin 组合入口与装配）
├── forms.py                # 表单定义与校验
├── metrics.py              # 指标注册中心（Prometheus）
├── static_handler.py       # 静态文件处理
├── cache_decorators.py     # 缓存装饰器
│
├── app/                    # 应用组装模块（自 core.py 拆分）
│   ├── __init__.py         # 子包说明
│   ├── helpers.py          # 序列化/配置/套接字/Session 初始化辅助
│   ├── protocol_mixin.py   # WSGI/ASGI 协议适配与错误处理
│   ├── routing_mixin.py    # 路由注册与 WebSocket 入口
│   ├── extension_mixin.py  # 中间件/插件/健康检查/数据库扩展
│   ├── server_mixin.py     # 服务器启动/关闭/热重载
│   └── server_cli.py       # 内置测试服务器 CLI
│
├── auth/                   # 认证与授权
│   ├── __init__.py
│   ├── decorators.py       # 权限装饰器
│   ├── jwt.py              # JWT 签发与校验
│   ├── middleware.py       # 认证中间件
│   ├── models.py           # 用户/角色模型
│   ├── oauth2.py           # OAuth2 流程
│   ├── password.py         # 密码哈希
│   └── providers.py        # 第三方登录提供商
│
├── cache/                  # 缓存模块
│   ├── __init__.py
│   ├── base.py             # 缓存接口定义
│   ├── cache.py            # 内存缓存实现
│   ├── db.py               # 数据库缓存
│   ├── factory.py          # 缓存工厂
│   ├── form_cache.py       # 表单缓存
│   ├── manager.py          # 缓存管理器
│   ├── memcache.py         # Memcache 缓存
│   └── redis.py            # Redis 缓存
│
├── database/               # 数据库模块
│   ├── __init__.py
│   ├── core.py             # 数据库核心
│   ├── migrations.py       # Alembic 迁移管理器
│   └── models.py           # 数据模型
│
├── debug/                  # 调试工具
│   ├── __init__.py
│   └── middleware.py       # 调试工具栏中间件
│
├── error_pages.py          # 错误页面
├── exceptions.py           # 异常定义
├── security.py             # 安全工具
├── validators.py           # 验证器
│
├── handlers/               # 请求处理器
│   ├── __init__.py
│   ├── base.py             # 请求处理器基类
│   ├── wsgi.py             # WSGI 请求处理器
│   ├── asgi.py             # ASGI 请求处理器
│   ├── socket.py           # Socket 请求处理器
│   ├── response.py         # HTTP 响应对象
│   ├── form.py             # 表单数据解析
│   └── enhanced.py         # 增强请求处理
│
├── i18n/                   # 国际化
│   ├── __init__.py
│   ├── locale.py           # locale 解析与协商
│   ├── middleware.py       # 语言协商中间件
│   ├── template.py         # 模板翻译函数注入
│   └── translator.py       # gettext 包装
│
├── mail/                   # 邮件服务
│   ├── __init__.py
│   ├── message.py          # 邮件与附件 MIME 结构
│   ├── smtp.py             # SMTP 客户端（STARTTLS/SSL + 重试）
│   ├── tasks.py            # Celery 异步发送任务
│   └── template.py         # Mako 双模板渲染
│
├── middleware/             # 中间件
│   ├── __init__.py
│   ├── base.py             # 中间件基类
│   ├── cors.py             # CORS 中间件
│   ├── csrf.py             # CSRF 中间件
│   ├── enhanced_logging.py # 增强日志中间件
│   ├── health_check.py     # 健康检查
│   ├── logging.py          # 日志中间件
│   ├── prometheus.py       # Prometheus 监控中间件
│   ├── rate_limit.py       # 限流中间件
│   └── security.py         # 安全中间件
│
├── openapi/                # OpenAPI
│   ├── __init__.py
│   ├── generator.py        # 规范生成
│   └── ui.py               # Swagger UI
│
├── plugins/                # 插件系统
│   ├── __init__.py
│   ├── base.py             # 插件基类
│   └── loader.py           # 插件加载器
│
├── routing/                # 路由系统
│   ├── __init__.py
│   ├── radix_tree.py       # 基数树实现
│   └── router.py           # 路由器
│
├── server/                 # 服务器实现
│   ├── __init__.py
│   ├── asgi.py             # ASGI 服务器
│   ├── asyncio.py          # AsyncIO 服务器
│   └── greenlet.py         # Greenlet 服务器
│
├── session/                # 会话管理
│   ├── __init__.py
│   ├── base.py             # 会话接口定义
│   ├── cache_session.py    # 缓存会话
│   ├── db.py               # 数据库会话
│   ├── factory.py          # 会话工厂
│   ├── manager.py          # 会话管理器
│   ├── memcache.py         # Memcache 会话
│   ├── redis.py            # Redis 会话
│   └── session.py          # 会话基类实现
│
├── tasks/                  # Celery 任务队列集成
│   └── __init__.py         # Celery 封装、任务装饰器、状态查询与健康检查
│
├── templates/              # 模板文件
│   └── scaffold/           # 脚手架模板
│       ├── site/           # 站点模板
│       └── __init__.py
│
├── utils/                  # 工具函数
│   ├── __init__.py
│   └── utils.py            # 工具函数实现
│
└── websocket/              # WebSocket
    ├── __init__.py
    ├── connection.py       # 连接管理
    ├── protocol.py         # 帧编解码
    └── server.py           # WebSocket 服务器

2.2 模块职责

核心模块

模块

文件

职责

主入口

__init__.py

导出公共 API，版本信息

核心类

core.py + app/

Litefs 主类（Mixin 组合），应用初始化与能力模块

配置

config.py

配置加载和管理

CLI

cli.py

命令行工具实现

迁移 CLI

cli_db.py

litefs db 数据库迁移子命令

服务器模块

模块

文件

职责

ASGI

server/asgi.py

ASGI 服务器实现

AsyncIO

server/asyncio.py

AsyncIO 服务器实现

Greenlet

server/greenlet.py

Greenlet 服务器实现

路由模块

模块

文件

职责

路由器

routing/router.py

路由注册和匹配

基数树

routing/radix_tree.py

高效路由匹配算法

中间件模块

模块

文件

职责

基类

middleware/base.py

中间件基类和接口

CORS

middleware/cors.py

跨域资源共享

CSRF

middleware/csrf.py

CSRF 保护

健康检查

middleware/health_check.py

健康检查端点

日志

middleware/logging.py

请求日志记录

增强日志

middleware/enhanced_logging.py

请求追踪、结构化日志、敏感信息过滤

监控

middleware/prometheus.py

Prometheus 指标采集与 /metrics 端点

限流

middleware/rate_limit.py

请求限流

安全

middleware/security.py

安全头部和防护

调试

debug/middleware.py

调试工具栏

国际化

i18n/middleware.py

语言协商与 locale 回写

缓存模块

模块

文件

职责

基类

cache/cache.py

缓存接口定义

内存缓存

cache/cache.py

内存缓存实现

数据库缓存

cache/db.py

数据库缓存实现

Redis

cache/redis.py

Redis 缓存实现

Memcache

cache/memcache.py

Memcache 缓存实现

管理器

cache/manager.py

缓存管理器

会话模块

模块

文件

职责

基类

session/session.py

会话接口定义

缓存会话

session/cache_session.py

基于缓存的会话

数据库会话

session/db.py

数据库会话存储

Redis 会话

session/redis.py

Redis 会话存储

Memcache 会话

session/memcache.py

Memcache 会话存储

管理器

session/manager.py

会话管理器

扩展能力模块

模块

文件

职责

认证

auth/

JWT、OAuth2、密码哈希、权限装饰器

数据库迁移

database/migrations.py

Alembic 迁移环境与版本管理

国际化

i18n/

locale 协商、gettext 翻译、模板翻译注入

邮件

mail/

邮件结构、SMTP 客户端、模板渲染、异步任务

指标

metrics.py

指标注册中心与 Prometheus 文本渲染

OpenAPI

openapi/

规范生成与 Swagger UI

任务队列

tasks/__init__.py

Celery 封装与任务状态查询

WebSocket

websocket/

连接管理、帧编解码、WebSocket 服务器

3. 测试结构

3.1 测试目录 (tests/)

tests/
├── __init__.py             # 测试包初始化
├── run_tests.py            # 测试运行脚本
├── README.md               # 测试说明
│
├── unit/                   # 单元测试
│   ├── __init__.py
│   ├── test_basic.py       # 基础功能测试
│   ├── test_cache.py       # 缓存测试
│   ├── test_cache_manager.py
│   ├── test_cache_backends_web.py
│   ├── test_config.py      # 配置测试
│   ├── test_core.py        # 核心类测试
│   ├── test_database_cache.py
│   ├── test_database_session.py
│   ├── test_default_page.py
│   ├── test_environ.py
│   ├── test_error_pages.py
│   ├── test_examples_basic.py
│   ├── test_form.py
│   ├── test_health_check.py
│   ├── test_max_request_size.py
│   ├── test_memorycache.py
│   ├── test_middleware.py
│   ├── test_middleware_params.py
│   ├── test_rate_limit_*.py
│   ├── test_routing.py     # 路由测试
│   ├── test_scaffold.py
│   ├── test_session.py
│   ├── test_streaming.py
│   ├── test_treecache.py
│   ├── test_validators.py
│   ├── test_wsgi*.py       # WSGI 测试
│   └── ...
│
├── integration/            # 集成测试
│   └── test_starlette_integration.py
│
├── performance/            # 性能测试
│   ├── test_deployment_modes.py
│   ├── test_greenlet_vs_asyncio.py
│   ├── test_performance.py
│   ├── test_worker_performance.py
│   └── run_test.sh
│
├── stress/                 # 压力测试
│   └── test_stress.py
│
├── test_asyncio_server.py
├── test_form_cache.py
├── test_hot_reload.py
├── test_keepalive.py
├── test_process_server.py
├── test_security.py
└── test_session_optimization.py

3.2 测试分类

类型

目录

说明

单元测试

unit/

测试单个函数和类

集成测试

integration/

测试模块间交互

性能测试

performance/

测试性能指标

压力测试

stress/

测试高并发场景

4. 示例结构

4.1 示例目录 (examples/)

examples/
├── README.md               # 示例索引
│
├── 01-quickstart/          # 快速入门示例
│   ├── app.py
│   ├── templates/
│   └── static/
│
├── 02-rest-api/            # REST API 示例
│   ├── app.py
│   ├── templates/
│   └── static/
│
├── 03-web-app/             # 博客系统示例
│   ├── app.py
│   ├── models.py
│   ├── data/
│   ├── templates/
│   └── static/
│
├── 04-realtime/            # 实时通信示例
│   ├── app.py
│   ├── templates/
│   └── static/
│
├── 05-production/          # 生产部署示例
│   ├── app.py
│   ├── celery_tasks.py
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── nginx.conf
│   └── requirements.txt
│
├── 06-prometheus-monitoring/   # Prometheus 监控示例
│   ├── app.py
│   ├── templates/
│   └── static/
│
├── 07-database-migrations/    # 数据库迁移示例
│   ├── app.py
│   ├── models.py
│   ├── templates/
│   └── static/
│
├── 08-mail-service/            # 邮件服务示例
│   ├── app.py
│   ├── templates/
│   │   └── email/              # 邮件双模板（txt / html）
│   └── static/
│
└── 09-i18n/                   # 国际化示例
    ├── app.py
    ├── compile_messages.py     # .po -> .mo 编译器
    ├── locales/
    │   └── zh_CN/LC_MESSAGES/
    │       ├── messages.po
    │       └── messages.mo
    ├── templates/
    └── static/

4.2 示例分类

示例

说明

难度

01-quickstart

路由、中间件、模板、静态文件入门

⭐

02-rest-api

JWT 认证与完整 REST API

⭐⭐⭐

03-web-app

完整博客系统与 OAuth2

⭐⭐⭐⭐

04-realtime

WebSocket 实时通信

⭐⭐

05-production

生产部署与容器化

⭐⭐⭐

06-prometheus-monitoring

监控指标采集与暴露

⭐⭐

07-database-migrations

Alembic 版本化迁移

⭐⭐

08-mail-service

邮件模板与异步发送

⭐⭐

09-i18n

国际化与语言协商

⭐⭐

5. 文档结构

5.1 文档目录 (docs/)

docs/
├── source/                 # Sphinx 源文件
│   ├── index.rst           # 文档首页
│   ├── conf.py             # Sphinx 配置
│   │
│   ├── getting-started.md  # 快速开始
│   ├── routing-guide.md    # 路由指南
│   ├── static-files-guide.md
│   ├── configuration.md    # 配置管理
│   ├── middleware-guide.md # 中间件指南
│   ├── cache-system.md     # 缓存系统
│   ├── session-management.md
│   ├── wsgi-deployment.md  # WSGI 部署
│   ├── asgi-deployment.md  # ASGI 部署
│   ├── unit-tests.md       # 单元测试
│   ├── performance-stress-tests.md
│   ├── improvement-analysis.md
│   ├── bug-fixes.md
│   ├── linux-server-guide.md
│   ├── development.md
│   └── project-structure.md
│
├── build/                  # 构建输出
│   └── html/              # HTML 文档
│
├── Makefile                # 文档构建命令
└── make.bat                # Windows 构建命令

5.2 文档分类

类型

文件

说明

快速开始

getting-started.md

入门教程

核心功能

routing-guide.md 等

功能指南

部署运维

wsgi-deployment.md 等

部署指南

开发文档

development.md 等

开发指南

API 文档

api/

API 参考

6. 配置文件

6.1 项目配置

文件

说明

pyproject.toml

项目配置、依赖、工具配置

setup.py

安装脚本

requirements.txt

依赖列表

Makefile

构建命令

MANIFEST.in

打包清单

6.2 工具配置

文件

说明

.gitignore

Git 忽略规则

.editorconfig

编辑器配置

pyproject.toml

Black/isort/mypy 配置

7. 依赖关系

7.1 模块依赖图

litefs (core)
    ├── cache (缓存)
    ├── session (会话)
    ├── routing (路由)
    ├── middleware (中间件)
    ├── handlers (处理器)
    ├── server (服务器)
    └── utils (工具)

7.2 外部依赖

依赖

版本

用途

argh

>=0.26.2

CLI 参数解析

greenlet

>=0.4.13

协程支持

Mako

>=1.0.6

模板引擎

MarkupSafe

>=1.1.1

HTML 转义

PyYAML

>=5.1

YAML 解析

watchdog

>=0.8.3

文件监控

SQLAlchemy

>=2.0.0

ORM 支持

pathtools 已于 v0.9.0 移除：源码从未直接引用，且它是 watchdog 的子依赖； 显式声明会导致其在 Python 3.12 上构建失败（No module named 'imp'）。

8. 文件命名规范

8.1 Python 文件

  • 模块: 小写字母，下划线分隔 (cache_manager.py)

  • 类: PascalCase (MemoryCache)

  • 函数: snake_case (get_cache)

  • 常量: UPPER_SNAKE_CASE (MAX_SIZE)

8.2 测试文件

  • 单元测试: test_<module>.py (test_cache.py)

  • 集成测试: test_<feature>_integration.py

  • 性能测试: test_<feature>_performance.py

8.3 文档文件

  • Markdown: 小写字母，连字符分隔 (getting-started.md)

  • Sphinx: 小写字母，连字符分隔 (api-guide.rst)

9. 开发建议

9.1 添加新功能

  1. 在相应模块创建文件

  2. 实现功能代码

  3. 编写单元测试

  4. 更新文档

  5. 添加示例

9.2 修改现有功能

  1. 找到对应模块文件

  2. 修改代码

  3. 更新测试

  4. 更新文档

  5. 检查兼容性

9.3 添加新中间件

  1. 在 middleware/ 创建文件

  2. 继承 BaseMiddleware

  3. 实现 process_request 和 process_response

  4. 在 __init__.py 导出

  5. 编写测试和文档

10. 相关资源

文档维护: 开发团队
最后更新: 2026-04-14