来源：https://framework.docs.xihanfun.com/appendix/roadmap

# 路线图

XiHan Framework 5 的路线图按门槛推进，不按日期。每个阶段列出退出条件，满足才进入下一阶段；没有「预计某月发布」这种承诺，因为我宁可晚一点，也不想为了赶日期把没通过门禁的东西放出去。这一页列出各阶段的内容、退出条件与当前状态。

## 阶段总览

```text
P0 定边界 → P1 内核 → P2 子系统 → P3 协议与宿主 → P4 插件与跨语言 → P5 GA → 后续版本
```

| 阶段 | 内容 | 退出条件 | 状态 |
| --- | --- | --- | --- |
| P0 定边界 | 总体方案拍板；目录骨架；规范草案（原语、清单、上下文、管道阶段、术语表）；CI 门禁 | 架构决策通过；原语层公开 API 进入冻结候选；空解决方案过全部门禁 | 完成 |
| P1 内核 | 原语层；内核的清单解析、阶段化管道、调用上下文、生命周期状态机、诊断桥、安全原语；进程内插件；测试基座 | 零 Provider 的示例应用可运行；Native AOT 发布通过；内核预算达标 | 完成 |
| P2 子系统 | Domain 与持久化、缓存、消息、安全、多租户五个子系统的抽象、默认实现、一致性套件与首批 Provider；Minimal 与 Standard 组合包；本地化 | Standard 组合应用在零外部设施下运行；换成 EF Core、Redis、RabbitMQ 只改配置与包引用；所有默认实现与 Provider 通过套件 | 完成 |
| P3 协议与宿主 | 操作契约与源生成器；HTTP、gRPC、MCP、CloudEvents 适配器；命令行宿主；对象存储、调度、远程配置、审计；OpenTelemetry；`xihan pack`；Full 组合包 | 一份契约同时在三种协议上服务，共用一份 Schema；Kubernetes 示例通过探针与停机宽限对齐测试 | 完成 |
| P4 插件与跨语言 | 进程外插件协议；Wasm 实验实现；Go SDK；规范独立仓库 | Go 写的插件在 .NET 宿主中服务一个操作，崩溃时宿主降级不退出；Go SDK 通过全部一致性向量；规范仓库公开 | 完成 |
| P5 GA | 批量优先审查、SqlSugar Provider、能力补齐、工作流与 AI 子系统、BasicApp 接入、API 审查、包验证基线、性能基准、文档站 | BasicApp 核心模块全量跑在框架上；全部门禁通过；性能目标达标 | 进行中 |

## P5 的进度

P5 的任务按执行顺序排列，前面的已经完成：

| 任务 | 状态 |
| --- | --- |
| 批量优先：抽象层所有对集合的操作都有一次调用完成的批量方法，逐项结果，Provider 原生批量；架构测试禁止在循环里调单条方法 | 完成 |
| `Persistence.SqlSugar`：依赖 `SqlSugarCore`，协议约定映射，SQLite 通过全部一致性用例 | 完成 |
| 能力补齐：租户分片、`IDistributedCache` 适配、S3 对象存储 | 完成 |
| `Messaging.Kafka`、`Caching.Hybrid`、`Configuration.Nacos` | 完成 |
| 调度子系统重做（引擎进抽象包，Provider 只实现存储与领导选举）与 `Scheduling.Database`、`Workflow.Database` | 完成 |
| 工作流与 AI 子系统：原计划放到后续版本，提前进入 5.0 | 完成 |
| 十项能力补齐：SqlSugar 多库与分表、Validate 阶段契约校验、领域事件派发、三个数据库 Provider、Resilience 阶段、Provider 健康项、OpenAPI 权限扩展 | 完成 |
| 雪花标识、OpenAPI 文案与分组、调用来源、条件引擎、IP 归属地、对象存储进阶能力、绕过管道的端点认证、运行信息、作业重试与执行时限、出站地址策略 | 完成 |
| 第一个与第二个预览版发布到 nuget.org | 完成 |
| BasicApp 接入：核心模块以能力包与操作契约重写在框架上 | 进行中 |
| API 审查：所有公开 API 带稳定性标记，公开面从 `Unshipped` 转入 `Shipped` | 待做 |
| 包验证基线、性能基准回归、安全审查、SBOM | 待做 |
| 文档站：教程、逐包参考、规范链接 | 进行中，就是你正在读的这一站 |
| 发布 5.0.0，声明 LTS | 待做 |

## 后续版本

5.0 正式版之后的内容，按优先级：

| 优先级 | 内容 |
| --- | --- |
| 高 | `Search.*` 子系统（索引与查询的抽象、内存实现与 Elasticsearch 等 Provider） |
| 高 | `Plugins.Wasm` 从 Experimental 到正式；TypeScript SDK |
| 中 | 实时通信与网关的专门包（当前实时通信直接用 ASP.NET Core SignalR，见[实时通信](/web/realtime)） |
| 中 | `Actors.*` 子系统；Kubernetes Operator |
| 中 | 管道阶段内的并行分支（计算图形态） |
| 低 | `Persistence.MongoDB`、`Messaging.Nats`、`Scheduling.Quartz` 等更多 Provider |

有两件事在 5.0 里明确不做：把 4.x 的模块迁移到 5.0 的自动化工具，以及 4.x 到 5.0 的兼容层。4.x 单独维护，5.0 是一条新的线；自动迁移机制保留给 5.x 到 6.x。

## 版本策略

| 项 | 规则 |
| --- | --- |
| 版本线 | 所有包共享一条版本线，从 5.0.0 起；SemVer 2.0 |
| 大版本 | 每三年一次，对齐一个 .NET LTS；LTS 大版本三年活跃支持加一年安全修复 |
| 小版本 | 约每六个月；补丁随时 |
| 目标框架 | 当前 LTS；上一个 LTS 保留 12 个月过渡期 |
| 预览版 | `X.Y.Z-preview.N`，安装时带 `--prerelease` |
| 破坏性变更 | 大版本内为零；原语层永远为零，必须破坏时发布新包 ID 并存 |

## 性能目标

| 指标 | 目标 |
| --- | --- |
| 冷启动额外开销 | 在 ASP.NET Core 基线之上小于 50 毫秒 |
| 管道执行，单个中间件 | 小于 0.1 毫秒 |
| 管道执行，五个中间件 | 小于 0.5 毫秒 |
| 空应用常驻内存 | 小于 30 MB |
| 原语层加内核的包大小 | 小于 500 KB |
| 基准回归阈值 | 5% |

基准项目在仓库的 `framework/benchmarks` 下，本地运行，不进 CI。

## 风险

我把最大的几个风险也写在这里，免得读者只看到好的一面：

| 风险 | 缓解 |
| --- | --- |
| 抽象过度，只剩一堆接口 | 每个抽象必须有能用的默认实现；每个阶段的退出条件都是「跑起来」 |
| 规范成为没人实现的文档 | 第二语言 SDK 是 P4 的退出条件，不是愿景；现在已经有了 |
| 单人维护带宽不足 | 当前范围只含内核与 Standard、Full 两组子系统，其余进孵化区 |
| 源生成器与 AOT 成本 | 允许手写替代；生成器只覆盖操作登记、契约 Schema 与仓储登记 |
| 命名漂移 | 术语表走规范流程，包 ID 文法由架构测试强制 |

## 下一步

- [发展大事记](/appendix/milestones)：各阶段实际发生的事
- [更新日志](/changelog)：每个版本的变更
- [贡献指南](/appendix/contributing)：想参与某个后续版本的任务，从这里开始