当前版本: v0.9.0
目标版本: v1.0.0（方案见 release-roadmap.md，待评审）
更新日期: 2026-10-21
基线 Commit: cb2988f
阶段进度：P0 ✅ → P1 ✅ → P2 ✅ → P3 ✅（v0.9.0 已发布）→ 0.x.x 路线待评审
路线调整（2026-10-21）：v1.0.0 硬性标准拆分为 6 个 0.x.x 版本逐步交付。
硬性标准未全部达成前，不升级到 v1.0。
Generated by TRAE SOLO at 2026-10-20 16:32
| 指标 |
数值 |
说明 |
| 源码规模 |
约 22,500 行 / 88 个模块 |
src/litefs |
| 测试覆盖率 |
46%（5643 语句，缺失 2817） |
coverage.json |
| 性能基准 |
Hello World 较 FastAPI 快 1.4~2.0 倍 |
8 核 20,976 req/s |
| Python 支持 |
3.8 ~ 3.12 |
setup.py |
- 服务器: 自研 epoll / greenlet / asyncio HTTP 服务器，WSGI 1.0 / ASGI 3.0 兼容
- 路由: RadixTree 路由已集成（
routing/router.py）
- 认证: JWT + OAuth2（GitHub / Google / 微信 / 企业微信 Provider 齐全）
- 中间件: 日志、安全头、CORS、CSRF、限流、健康检查、增强日志
- 数据: SQLAlchemy 连接池、多级缓存（Memory/Tree/Redis/Memcache/DB）、会话多后端
- 生态: WebSocket、Celery、OpenAPI/Swagger、插件系统、调试工具栏、热重载
| 任务 |
内容 |
验收标准 |
状态 |
| core.py 拆分 |
拆分为 app/ 包（helpers + 4 个 Mixin + server_cli），core.py 保留装配与再导出 |
单文件 ≤ 600 行，行为不变 |
✅ 2026-10-20 完成（1216 → 105 行） |
| 覆盖率提升 |
新增 20 个测试模块约 640 用例，修复 5 处源码 bug |
46% → 70%（v0.9.0），85%（v1.0） |
✅ 2026-10-20 完成阶段目标（70%，详见 unit-tests.md） |
| 类型注解完善 |
核心模块 type hints |
mypy 核心目录零错误 |
✅ 2026-10-20 完成（app/ 包 + core.py，81 → 0，详见 type-hints.md） |
| 静态检查流水线 |
flake8 + ruff + mypy 纳入 CI |
全部通过方可合并 |
✅ 2026-10-21 完成（src/ 全量三工具零告警，CI 门禁已上线，详见 static-checks.md） |
| 任务 |
内容 |
状态 |
| Prometheus 监控 |
PrometheusMiddleware、请求计数/延迟直方图/错误率、连接池与缓存命中指标、/metrics 端点、可选依赖懒加载 |
✅ 2026-10-21 完成（指标 7 项、路由模板低基数标签，详见 prometheus-monitoring.md）
2026-10-21 修复原生 Socket 链路指标未采集缺陷 |
| 数据库迁移 |
Alembic 封装（当前 litefs db 仅为提示占位），实现 db init/migrate/upgrade/downgrade/current/history |
✅ 2026-10-21 完成（嵌套子命令 + 保留旧扁平入口，详见 database-migrations.md） |
| 任务 |
内容 |
状态 |
| 邮件发送 |
smtplib 封装、Message 类、Mako 模板邮件、附件、Celery 异步发送 |
✅ 2026-10-21 完成（零新增依赖，MIME 三态结构、TLS/SSL、指数退避重试、Celery 不可用自动降级，详见 mail-service.md） |
| i18n 国际化 |
gettext 封装、请求级 locale 协商、模板翻译函数 |
✅ 2026-10-21 完成（零新增依赖，四级 locale 协商优先级、线程局部隔离、恒等函数保障零行为变化，详见 i18n.md）
2026-10-21 修复原生 Socket 链路 Content-Language 与 locale Cookie 未写入缺陷 |
| 任务 |
内容 |
状态 |
| 性能回归基准 |
以 benchmarks/ 为基础固化阈值，防止发布回退 |
✅ 2026-10-21 完成（16 组场景 / 32 项检查，RPS ≥ 基线 85%、P99 ≤ 基线 130%，零新增依赖，详见 performance-regression.md） |
| 示例与文档同步 |
新功能各配 1 个示例 + 对应 docs 页面，更新 index.rst |
✅ 2026-10-21 完成（新增 4 个可运行示例，重写 examples/README.md，修复 3 处失效交叉引用，详见 project-structure.md） |
| 依赖安全审计 |
pip-audit 定期扫描 |
✅ 2026-10-21 完成（scripts/audit_deps.py + make audit + CI security job，审计面收敛至运行时依赖，详见 dependency-audit.md） |
| 任务 |
内容 |
状态 |
| 版本号统一 |
消除源码版本号硬编码，版本号升至 v0.9.0 |
✅ 2026-10-21 完成（消除 7 处硬编码，_version.py 为唯一权威源；新增 server_software 常量区分 WSGI SERVER_SOFTWARE 语义，两条响应链路输出格式不变） |
| 发布物料 |
CHANGELOG.md + RELEASE_v0.9.0.md |
✅ 2026-10-21 完成（CHANGELOG.md 为 Keep a Changelog 格式，已通过 {include} 引入 Sphinx 文档 changelog.md） |
| 文档告警清零 |
Sphinx 构建告警 |
✅ 2026-10-21 完成（30 → 0，详见 RELEASE_v0.9.0.md 文档章节） |
完整方案见 release-roadmap.md（含行业对标基线、15 条硬性标准、破坏性变更分配、验收门禁）
定位：生产就绪 —— API 稳定承诺 + 质量硬指标达标
对标对象：Starlette（近 8 年唯一真正走完 0.x → 1.0 的同代 ASGI 框架）
原则：硬性标准（H1–H15）全部达成前，不升级到 v1.0.0。
每一版 0.x 均为独立可发布版本（含 CHANGELOG、Release Notes、全量回归、性能基线不回退）。
| 版本 |
主题 |
核心交付 |
绑定硬性标准 |
工作量 |
状态 |
| v0.10.0 |
契约与结构重构 |
API 稳定性与 SemVer 政策、548 符号分级冻结（stable/provisional/internal 三级）、弃用机制与时间表、拆分 5 个超 600 行文件 |
H1 H2 H3 H6 |
≈7d |
✅ 已完成 |
| v0.11.0 |
类型系统与打包契约 |
py.typed 落盘、mypy --strict 全量零豁免（53 个）、公共 API 标注补齐 |
H4 H5 |
≈6d |
⬜ 待启动 |
| v0.12.0 |
测试基础设施与质量基线 |
核心服务器覆盖率 ≥80%、conftest.py + TestClient、整体覆盖率 ≥85%、pytest filterwarnings=error |
H7 H8 H9 H10 |
≈12d |
🔶 进行中（覆盖率专项完成：server_mixin 86%、greenlet_server_base 87%、greenlet 81%、websocket 90%+，整体 76% → 84%，详见 unit-tests.md） |
| v0.13.0 |
ASGI 协议与插件生态 |
ASGI lifespan、原生 streaming、ASGI 中间件签名兼容、entry_points 插件发现 |
H11 H12 |
≈10.5d |
⬜ 待启动 |
| v0.14.0 |
工程化与 Python 基线收敛 |
GitHub PR 级 CI 门禁、删除 setup.py、核心依赖 optional 化、extras 重整、Python 3.10–3.14 |
H13 |
≈8d |
⬜ 待启动 |
| v0.15.0 |
发布基础设施与安全闭环 |
SECURITY.md、SBOM 与签名、版本化文档站、LTS 政策、迁移指南 |
H14 H15 |
≈7d |
⬜ 待启动 |
| v1.0.0 |
稳定性声明发布 |
API 冻结宣告、政策定稿、破坏性变更汇总专章、打标签发布、1.0 稳定分支 |
H1–H15 全达成 |
≈4d |
⬜ 待启动 |
| 指标 |
当前 |
目标 |
交付版本 |
| 测试覆盖率 |
84%（核心服务器 ≥80% 已达成） |
≥85%（核心模块 ≥80%） |
v0.12.0 |
| mypy 豁免模块 |
53 个 |
0 个（--strict） |
v0.11.0 |
py.typed |
❌ 无 |
✅ 随 wheel 分发 |
v0.11.0 |
TestClient / conftest.py |
❌ 无 |
✅ 具备 |
v0.12.0 |
| ASGI lifespan |
❌ 报错 |
✅ 支持 |
v0.13.0 |
| 插件发现 |
仅目录扫描 |
✅ entry_points |
v0.13.0 |
| GitHub PR CI |
❌ 无 |
✅ 三级门禁 |
v0.14.0 |
| 超 600 行文件 |
0 个 |
0 个 |
✅ v0.10.0 已达成 |
| Python 基线 |
3.8–3.12 |
3.10–3.14 |
v0.14.0 |
SECURITY.md / SBOM / 签名 |
❌ 无 |
✅ 就绪 |
v0.15.0 |
| 里程碑 |
内容 |
| v0.9.0-alpha |
P0 完成：core.py 拆分、覆盖率 ≥ 60%、CI 流水线 |
| v0.9.0-beta |
P1 完成：Prometheus + Alembic 迁移 |
| v0.9.0-rc |
P2 完成：邮件 + i18n，回归测试通过 |
| v0.9.0 |
文档补齐、示例更新、正式发布 ✅ 2026-10-21 |
| v0.10.0 – v0.15.0 |
硬性标准分步交付（契约 → 类型 → 质量 → 协议 → 工程 → 发布） |
| v1.0.0 |
稳定性声明发布（H1–H15 全达成后） |
| 风险 |
影响 |
对策 |
| core.py 拆分引入回归 |
高 |
拆分前先补齐对应模块测试，行为快照对照 |
| Prometheus 依赖侵入核心 |
中 |
设计为可选依赖 + 懒加载导入 |
| Alembic 与 SQLAlchemy 版本耦合 |
低 |
现有 SQLAlchemy>=2.0.0 已满足 Alembic 要求 |
- 架构约束：HTTPS 不在框架内实现，生产环境由 Nginx/HAProxy 做 SSL 终止
- 所有新功能需附带单元测试并同步文档，遵循语义化版本与向后兼容
- 每周五评审进度
文档维护: 开发团队