文档站架构方案

本文保留最初的信息架构规划与问题清单。两条开发路径、API 参考、迁移和设计记录现已落地；部分短主题合并成独立章节，例如配置集中为一页、适配器归入架构与文件参考。具体页面以站点导航为准，维护约定见文档维护。下述“当前问题”描述整理前状态。

1. 定位与组织原则

文档站采用「应用开发、框架开发两条路径，共享 API 参考与版本迁移」的结构。

应用开发者的主线是创建项目、实现接口、处理异常、测试和部署；框架开发者的主线是理解边界、追踪请求生命周期、修改实现、验证行为和发布。顶层导航按这些任务组织，框架源码目录只用于内核章节。

框架开发进一步区分两类读者：通过公开入口编写扩展的开发者，以及修改 Nova 源码的贡献者。使用中间件、Hooks 和子应用的业务开发者不必先学习 HTTP Parser；修改协议和连接协调的贡献者则必须了解消息契约与取消所有权。

同一主题可以有不同深度的页面，但契约只维护一份：指南讲如何使用，API 参考定义行为，内核文档解释实现，设计提案保留决策背景。

2. 当前问题与依据

现状	对读者的影响	调整方向
`docs/.vitepress/config.mts` 中快速开始、路由、中间件、测试入口没有对应页面	首次访问无法完成入门路径	优先补齐入门闭环；只将已有页面加入导航
首页将测试文档作为第二入口，所有页面共用一个侧栏	应用使用与框架贡献缺少明确入口	首页提供两种角色入口，侧栏按栏目切换
根 README 同时包含教程、API、架构、CLI 校验和调优内容	内容难查找，更新容易不同步	将完整内容迁入站点，README 保留概览与最小示例
简介仍把 Parser 等实现统称为 `src/core`	与当前分层不符	依据 `app/core/message/protocol/server/static` 重写架构说明
首页宣称“中间件洋葱模型”	容易误解 `next()` 的等待语义	以 `handler.ts` 中返回 `void` 的 `NextFunction` 和中间件测试解释执行顺序，避免承诺 Koa 式语义
`core-api-migration.md` 混合公开 API 迁移和内部所有权设计	应用开发者被内部细节打断	拆分迁移步骤与内核生命周期说明
流式响应指南与历史提案并存，提案仍引用旧源码位置	读者可能把方案当作当前行为	为提案增加状态、适用版本与当前文档入口
GitHub 链接为 `your-name/nova`，首页性能表述没有附带证据	导航与可信度不足	使用包元数据中的仓库地址，性能结论链接可复现报告

依据主要包括 packages/nova-http/package.json 的 exports、各公开入口、scripts/tests、现有指南和 CI。仓库包版本目前为 0.2.1，不能据此断言工作区中的每项变更都已发布。

3. 顶层导航与阅读路径

目标顶栏：应用开发 · API 参考 · 框架开发 · 版本与迁移。GitHub 使用独立图标入口；提案、性能与贡献指南归入框架开发侧栏。

首页提供「开始构建应用」和「参与框架开发」两个主按钮，以及 API、迁移、示例的快捷入口。概览说明适用场景、支持范围和安装方式，性能描述附测试环境与报告。

读者任务	推荐路径	完成标志
第一次使用 Nova	简介 → 快速开始 → 第一个 API → 应用测试	能创建、启动并验证一个接口
构建业务服务	路由与挂载 → 中间件 → 请求体 → 错误处理 → 部署	能组织服务并处理失败与关闭
实现 SSE 或下载	流式响应 → SSE/文件示例 → Response API	理解等待写入、结束、取消与提交后错误
编写扩展	扩展概览 → 中间件/Hooks → 公开入口与兼容边界	扩展不依赖未导出的内部文件
修改框架	本地开发 → 架构总览 → 请求生命周期 → 对应模块 → 验证与提交	能定位职责并运行相关回归检查
升级版本	版本说明 → 对应迁移 → API 参考	能识别影响并完成代码调整

4. 目标目录

保留现有 /guide/ 前缀作为应用开发入口，减少已有链接迁移。以下为内容规划，可分批创建；尚未完成的页面不进入线上导航。

text

docs/
├── index.md
├── guide/                          应用开发：按任务渐进阅读
│   ├── index.md                    学习路线与前置知识
│   ├── introduction.md             定位、适用场景、兼容性边界
│   ├── getting-started.md          安装、TS/JS、启动与验证
│   ├── project-structure.md        CLI 模板、配置与目录组织
│   ├── router.md                   方法、参数、匹配、子应用挂载
│   ├── middleware.md               next、异步处理与执行顺序
│   ├── request.md                  URL、headers、cookies、context
│   ├── request-body.md             IncomingBody、bodyParser、大小限制
│   ├── response.md                 状态、响应头、JSON、响应结束
│   ├── error-handling.md           错误链、404、提交前后错误
│   ├── hooks.md                    观测钩子与中间件职责
│   ├── streaming-response.md       背压、结束与取消
│   ├── static-files.md             sendFile、Range、缓存
│   ├── testing.md                  应用测试：启动、请求断言、清理
│   ├── deployment.md               代理信任、资源限制、超时与关闭
│   └── recipes/                    完整、可运行的任务示例
│       ├── rest-api.md
│       ├── sse.md
│       └── file-download.md
├── api/                            共享参考：行为契约的唯一来源
│   ├── index.md                    导入路径、运行时值与类型、稳定性
│   ├── app.md                      createApp、Nova、NovaConfig
│   ├── routing.md                  use、route、method、all 等
│   ├── request.md                  NovaRequest
│   ├── response.md                 NovaResponse、流式方法与状态
│   ├── hooks.md                    事件、上下文、触发时机
│   ├── middleware.md               处理函数类型、bodyParser、staticFiles
│   ├── static.md                   nova-http/static
│   ├── cli.md                      两个包的命令、选项与模板
│   ├── errors.md                   错误码、触发条件与恢复方式
│   ├── core.md                     nova-http/core 的公开扩展接口
│   ├── message.md                  消息契约及实际可用的导入路径
│   └── http1.md                    nova-http/protocol/http1
├── framework/                      框架扩展与实现
│   ├── index.md                    扩展作者 / 源码贡献者路径
│   ├── extensions.md               中间件、Hooks、子应用组合
│   ├── architecture.md             分层、依赖方向、公共边界
│   ├── request-lifecycle.md         从输入到响应完成的时序
│   ├── internals/
│   │   ├── message.md              body、headers、sink 端口契约
│   │   ├── core.md                 分发、匹配、挂载视图与执行
│   │   ├── http1.md                输入解析、定界与序列化
│   │   ├── server.md               TCP、连接复用、超时与代理
│   │   ├── response-lifecycle.md   状态、背压、失败与取消所有权
│   │   └── adapters.md             app 组合层与 static 适配器
│   ├── contributing/
│   │   ├── setup.md                workspace、本地构建与调试
│   │   ├── testing.md              测试分层、定位与回归矩阵
│   │   └── release.md              Changesets、CLI 与模板同步
│   └── performance/
│       ├── methodology.md          运行环境、场景、指标与复现
│       └── reports.md              带版本和日期的报告索引
├── releases/
│   ├── index.md                    版本状态及 CHANGELOG 入口
│   └── migrations/
│       └── core-api.md             现有 core 迁移内容的目标位置
└── proposals/
    ├── index.md                    提案状态与当前文档映射
    ├── documentation-architecture.md
    ├── streaming-response-prd.md
    └── streaming-response-technical-design.md

应用开发侧栏按「入门、基础能力、生产实践、示例」分组；框架开发按「扩展、内核、贡献、设计记录」分组。API 侧栏先展示应用常用接口，再展示内核扩展参考。页面过长时按职责拆页，避免一开始为每个方法建立独立页面。

5. 公开契约与内部实现边界

公开 API 以包的 exports 和入口实际导出为准，不能将 src 下的目录直接转换为用户可导入的模块。

层次	文档表达	当前项目中的例子
应用公共 API	提供直接可用的导入和完整示例	`nova-http`、`nova-http/middlewares`、`nova-http/static`
公开扩展接口	说明构造条件、所有权与兼容范围	`nova-http/core`、`nova-http/protocol/http1`
内部实现	解释实现和测试约束，明确不属于公开入口	`server`、`message` 源码目录、middleware-chain 等

特别注意：message 下的一部分契约由主入口或 core 重新导出，但当前没有 nova-http/message 子路径；server 也没有独立公开子路径。NovaRequest 和 NovaResponse 在主入口是类型导出，在 core 入口才是运行时类导出。API 页应分别标明这些区别。

架构页以当前依赖方向为骨架：core → message、protocol/http1 → message；server 组合内核、协议和消息契约，app 组装服务器与可选适配器。用请求时序串联模块，避免只罗列源码文件。

6. 每类页面的内容契约

页面类型	必须回答的问题	应包含的材料
入门教程	怎样从零得到可验证结果？	环境要求、完整导入、步骤、预期输出、下一步
使用指南	什么时候用，怎样用，失败时怎么办？	场景、最小示例、边界、常见错误、API 链接
API 参考	精确行为是什么？	导入路径、签名、参数与默认值、返回值、错误、生命周期、版本信息
内核说明	为什么这样实现，改动会影响哪里？	职责、依赖、状态/时序、不变量、源码与测试入口
贡献指南	怎样复现、验证并提交？	前置条件、准确命令、变更对应的检查、提交与发布流程
设计提案	当时解决什么问题，最终采纳什么？	状态、背景、取舍、关联实现、取代关系、当前文档入口

以流式响应为例：指南负责 await res.write() 与结束/取消用法；API 负责方法返回值和错误契约；内核页负责写队列、sink、取消协调与连接复用；PRD 保留需求背景。后续行为变更先更新指南和 API，再补充内核说明及提案状态。

应用测试页讲如何验证业务服务；框架测试页讲 parser、路由、响应、连接、交互生命周期和架构测试。性能测试放入独立的框架性能分组，不作为应用新手入口。

7. 现有内容迁移表

当前内容	目标归属	迁移方式
根 `README.md` / `README_EN.md`	概览、安装、最小示例、站点入口	详细内容迁入对应栏目后再精简，保留双语入口
包内 README	npm 用户入口	保留安装、快速开始、CLI 和文档链接
`guide/introduction.md`	应用开发简介	重写过时分层描述，补充适用范围
README 安装与 CLI 用法	快速开始、项目结构、CLI API	教程讲操作，参考页列全部选项
README 核心概念与 API	guide 与 api	按主题拆分，默认值与语义回查源码和测试
README 架构与扩展点	framework	将公开扩展用法和源码内部实现分开
README 性能调优	应用部署、框架性能方法	配置实践与框架基准分开
`guide/streaming-response.md`	保留原 URL	补 API、SSE 示例和内核说明的交叉链接
`guide/core-api-migration.md`	releases/migrations/core-api 与内核生命周期	迁移页提供旧/新用法，所有权细节进入内核页
两份 streaming 提案	proposals	保留历史 URL，标记哪些设计已落地、已被替代或待核实
`/testing/index`	framework/contributing/testing	当前页面缺失；先移除失效入口，目标页完成后可增加兼容入口
性能脚本 README 与报告	framework/performance 的索引与方法页	运行命令仍靠近脚本维护，站点摘要并链接原报告，避免复制多份

对于已存在的页面，移动时保留原路径的迁移说明与目标链接；不要先删除旧文件。迁移时检查深层链接及章节锚点，不只检查顶层导航。

8. 站点与内容维护规则

继续使用仓库现有 VitePress。导航、栏目侧栏、搜索与页面信息均围绕上述内容结构配置，不为本次整理引入另一套站点技术。

导航：按路径提供栏目侧栏；未落地内容只出现在本方案的待办中，不设置空页面或失效链接。关键内容从首页经两到三次导航可达。
检索：规划站内搜索，API 标题保留符号名；术语采用固定中文名并附英文，便于搜索 ResponseSink、背压、取消等关键词。
版本：页面标注已发布版本或未发布状态。升级说明关联 Changeset/CHANGELOG，未经核实不把当前工作区行为写成 0.2.1 已发布能力。初期维护一套主文档，有并行维护需求时再建立版本快照。
语言：先形成完整中文站；英文 README 继续保留。后续按相同栏目与 URL 层级补英文内容，语言入口只链接实际存在的翻译。
内容归属：API 行为变更同步更新参考、相关指南和迁移记录；内部重构更新架构、源码路径和设计记录；CLI 变更同步更新模板与快速开始。
示例：包含必要导入、启动与验证方式，标明省略部分。完整应用示例优先复用 CLI 模板或可执行示例源，避免多份代码独立漂移。
环境：区分包声明的运行要求与贡献者工具链要求。目前包声明 Node >=18，CI 测试矩阵为 20/22/24，不能将二者写成同一项已验证支持范围。
验证：运行 pnpm docs:build，另行检查 nav/sidebar 的目标文件和锚点；不要假定构建能覆盖所有导航错误。现有 CI 的递归 build 已包含 docs，后续增加导航检查与关键示例验证即可。
性能证据：报告带提交/版本、环境、命令、场景、吞吐与延迟等指标，首页摘要链接报告，避免脱离场景的绝对性能宣传。

9. 实施顺序与验收

P0：修复入口，形成最小阅读闭环

完成首页双入口、简介、快速开始、路由、中间件、基础请求/响应与错误处理；补框架入口、架构总览、本地开发和测试入口。修正仓库链接与中间件描述，保留现有流式指南，导航只展示完成页面。

验收：新用户能从首页启动服务并验证接口；贡献者能找到源码分层与测试命令；站点构建通过且导航无缺失目标。

P1：建立契约参考，迁移已有知识

从 README 提取 API 与生产实践；覆盖所有公开代码入口中的符号，区分运行时值与类型导出；补请求体、挂载、流式响应、Hooks、静态文件和 CLI 文档。拆分 core 迁移内容，完成旧 URL 兼容，并在对应站点内容齐全后精简 README。

验收：每项公开 API 有参考归属；指南与源码、类型和行为测试一致；每项破坏性变化有迁移入口；重复的完整参考已收敛。

P2：完善框架贡献闭环

补请求/响应时序、取消所有权、协议与连接协调、架构约束、回归矩阵、基准方法和发布流程，整理历史提案状态。回归说明链接现有 architecture.spec.ts、exchange-lifecycle.spec.ts、connection-lifecycle.spec.ts、stream-timeout-lifecycle.spec.ts 等实际测试。

验收：贡献者可以从一个模块的说明找到依赖、不变量、相关测试和提交前检查；性能结论可追溯并复现；提案不会被误读为当前 API。

优先让两类读者各有一条可走通的路径，再扩大覆盖面。本方案完成后可按 P0、P1、P2 分批实施，各批次独立构建和验收。

文档站架构方案 ​

1. 定位与组织原则 ​

2. 当前问题与依据 ​

3. 顶层导航与阅读路径 ​

4. 目标目录 ​

5. 公开契约与内部实现边界 ​

6. 每类页面的内容契约 ​

7. 现有内容迁移表 ​

8. 站点与内容维护规则 ​

9. 实施顺序与验收 ​

P0：修复入口，形成最小阅读闭环 ​

P1：建立契约参考，迁移已有知识 ​

P2：完善框架贡献闭环 ​