项目结构

文档版本: 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 添加新功能

在相应模块创建文件
实现功能代码
编写单元测试
更新文档
添加示例

9.2 修改现有功能

找到对应模块文件
修改代码
更新测试
更新文档
检查兼容性

9.3 添加新中间件

在 middleware/ 创建文件
继承 BaseMiddleware
实现 process_request 和 process_response
在 __init__.py 导出
编写测试和文档

10. 相关资源

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

FilesExpand file tree

project-structure.md

Latest commit

History

project-structure.md

File metadata and controls

项目结构

概述

1. 项目根目录

2. 源代码结构

2.1 主包目录 (src/litefs/)

2.2 模块职责

核心模块

服务器模块

路由模块

中间件模块

缓存模块

会话模块

扩展能力模块

3. 测试结构

3.1 测试目录 (tests/)

3.2 测试分类

4. 示例结构

4.1 示例目录 (examples/)

4.2 示例分类

5. 文档结构

5.1 文档目录 (docs/)

5.2 文档分类

6. 配置文件

6.1 项目配置

6.2 工具配置

7. 依赖关系

7.1 模块依赖图

7.2 外部依赖

8. 文件命名规范

8.1 Python 文件

8.2 测试文件

8.3 文档文件

9. 开发建议

9.1 添加新功能

9.2 修改现有功能

9.3 添加新中间件

10. 相关资源

2.1 主包目录 (`src/litefs/`)

3.1 测试目录 (`tests/`)

4.1 示例目录 (`examples/`)

5.1 文档目录 (`docs/`)