Feat 文档写作指南
写作标准速查（写作时优先看本节）
Section titled “写作标准速查（写作时优先看本节）”按类型选择 → 结构模板 → 人称与代码规范执行，即可产出符合 Feat 文档体系的高质量内容。
类型选择与结构（必须遵守）
Section titled “类型选择与结构（必须遵守）”| 写作目的 | 文档类型 | 必选结构顺序 | 人称 |
|---|---|---|---|
| 新手入门、第一次做某事 | 教程 | 学习目标 → 前置条件 → 实践步骤 → 验证结果 → 总结回顾 | 多用「你」，适当「我们」 |
| 解决一个具体任务 | 操作指南 | 任务描述 → 解决方案 → 替代方案 → 注意事项 → 相关链接 | 主要「你」，少用「我们」 |
| 解释为什么、设计思路 | 概念解释 | 背景介绍 → 设计理念 → 架构解析 → 权衡分析 → 扩展思考 | 多用「我们」，少用「你」 |
| API/参数/返回值说明 | 参考文档 | API 概览 → 参数详解 → 使用示例 → 异常处理 → 版本差异 | 第三人称，客观中立 |
按类型写作模板（可直接复制为大纲）
Section titled “按类型写作模板（可直接复制为大纲）”| 类型 | 二级标题顺序 |
|---|---|
| 教程 | 学习目标 → 前置条件 → 实践步骤（第一步/第二步…）→ 验证结果 → 总结回顾 |
| 操作指南 | 任务描述 → 解决方案 → 替代方案 → 注意事项 → 相关链接 |
| 概念解释 | 背景介绍 → 设计理念 → 架构解析 → 权衡分析 → 扩展思考 |
| 参考文档 | API 概览 → 参数详解 → 使用示例 → 异常处理 → 版本差异 |
代码与格式硬性要求
Section titled “代码与格式硬性要求”- 示例来源：优先基于
feat-test、feat-ai等项目内真实可运行示例（含main或可执行测试）。 - JDK 8：禁止文本块、
var、Record、增强 switch、Optional.isEmpty()等 JDK 9+ 特性；允许 Lambda、Stream、方法引用。 - 强调：加粗表重要概念；
代码表行内代码、类名、文件名。 - 补充说明：用
<Aside type="tip">/type="caution"/type="danger">；页面顶部import { Aside } from '@astrojs/starlight/components';。 - 复杂流程：优先用 Mermaid（泳道图、流程图、状态图）。
高质量文档判定（达标后再发布）
Section titled “高质量文档判定（达标后再发布）”- 类型明确：一眼能看出类型，且结构顺序符合上表。
- 可执行：教程与操作指南中的代码读者可复制即跑（或明确写出「需先完成 X」）；参考文档示例简短正确。
- 术语与人称：术语首次出现有简短解释；人称符合上表。
- 代码合规：所有 Java 示例符合 JDK 8，且来源于或可对应到
feat-test/feat-ai等。 - 链接有效：文档内链接（含 Gitee、站内）有效且指向正确。
- 无类型混淆：教程带人做、操作指南解任务、概念讲原理、参考列 API。
核心理念与原则
Section titled “核心理念与原则”基于 Diataxis：教程带人做、操作指南解任务、概念解释讲原理、参考文档列 API。写作原则：实用至上、结构清晰、真实可靠（基于可运行代码）、用户导向。
动笔前确认：① 已选类型并对应结构模板；② 已明确目标读者（入门/中级/高级）；③ 已划内容边界（必备详写、扩展链接、避免重复）；④ 已找到可运行示例（feat-test、feat-ai 等）并确认可跑。
| 写作目的 | 推荐类型 | 典型标题示例 |
|---|---|---|
| 新手入门 | 教程 | 「构建你的第一个 HTTP 服务器」 |
| 解决具体问题 | 操作指南 | 「如何配置 HTTPS 支持」 |
| 解释设计原理 | 概念解释 | 「Feat 的异步处理机制」 |
| API 说明 | 参考文档 | 「HttpServer API 参考」 |
按类型侧重：教程—前 50% 内宜有完整可运行示例，每步有验证；操作指南—至少一种推荐方案 + 替代 + 注意事项；概念—讲原理与架构，代码服务于理解；参考—完整参数与返回值，示例简短准确。
人称：与速查表一致（教程/指南用「你」，概念用「我们」，参考用第三人称）。
表达：避免堆砌参数；术语首次出现通俗解释；适度用类比（如 NIO 类比餐厅服务、路由类比交通管制）。生硬 → 自然：如「处理 HTTP 请求的功能」→「几行代码搭建高性能 HTTP 服务器」。
代码示例规范
Section titled “代码示例规范”通用：示例优先来自 feat-test、feat-ai；教程与操作指南须完整可运行（含 main 或可执行入口），读者可复制即跑；关键步骤有注释；指明预期结果与验证方式。类型侧重：教程—步骤清晰、注释到位；操作指南—推荐方案 + 常见错误/注意；概念—可与原理对应即可；参考—突出 API 与参数。
JDK 8：✅ Lambda、Stream、方法引用、接口默认方法、传统字符串。❌ 文本块、var、增强 switch、Record、Optional.isEmpty() 等 JDK 9+。
| 格式 | 用途 |
|---|---|
| 加粗 | 重要概念、关键词 |
代码 | 行内代码、类名、文件名 |
<Aside type="tip/caution/danger"> | 技巧/注意/警告 |
复杂流程优先用 Mermaid（泳道图、流程图、状态图）；简单情况用文字。
常见问题与自检
Section titled “常见问题与自检”| 问题表现 | 改进 |
|---|---|
| 先原理后代码 | 教程/操作指南先展示代码再解释 |
| 示例缺 main 或不完整 | 提供可直接运行的完整代码 |
| 堆砌参数 | 结合场景讲参数用法 |
| 术语无解释 | 首次出现时通俗解释 |
| 混淆文档类型 | 教程带人做、指南解任务、概念讲原理、参考列 API |
发布前统一检查：类型与结构符合速查表；示例可运行且 JDK 8；人称与术语符合要求；链接有效；Aside/代码高亮/图表使用恰当。
- 随版本更新 API 参考；根据反馈优化教程与操作指南；定期验证示例可运行性。
- 写新文档时：以「写作标准速查」+ 对应类型模板为纲 → 按结构填内容 → 用「高质量文档判定」自检 → 达标后发布。