# NewLife 模块文档标准模板 适用于 `Doc/*.md` 功能模块文档的标准结构，确保格式统一、机器可解析、人类可读。 ## 完整模板 ```markdown --- title: "{中文名}" namespace: "{命名空间}" project: "{NuGet包名}" url: "https://newlifex.com/core/{slug}" updated: "{YYYY-MM-DD}" --- # {中文名} {一段话概述：这是什么、解决什么问题、核心优势} ## 核心概念 {模块的关键设计理念，2-5 个要点} ## 快速开始 ### 安装 ```shell dotnet add package {NuGet包名} ``` ### 基础用法 ```csharp // 最简化的可运行示例 ``` ## API 参考 ### {核心类/接口名} {一句话描述} ```csharp // 关键公共成员签名（从源码提取，不虚构） public interface IXxx { /// <summary>说明</summary> ReturnType Method(ParamType param); } ``` ### {其它核心类} ... ## 常见场景 ### 场景 1：{动词短语} {场景描述} ```csharp // 完整可运行代码 ``` ## 高级用法 {扩展点、自定义实现、配置选项等} ## 注意事项 - {注意点 1} - {注意点 2} ## 与其它模块的关系 | 相关模块 | 关系 | |---------|------| | {模块名} | {如何配合使用} | ``` --- ## Frontmatter 字段说明 | 字段 | 必选 | 说明 | |------|------|------| | `title` | ✅ | 文档标题（中文，如"统一缓存接口ICache"） | | `namespace` | ✅ | .NET 命名空间 | | `project` | ✅ | NuGet 包名 | | `url` | ❌ | 官网对应页面 URL | | `updated` | ✅ | 最后更新日期 | ## 代码示例要求 1. **来自源码**：API 签名必须从实际源码提取，不虚构方法名或参数 2. **可运行**：示例代码应可直接复制使用，包含必要 `using` 3. **NewLife 风格**：使用 `String`/`Int32` 而非 `string`/`int` 4. **简洁**：快速开始用最少代码展示核心功能，完整示例放常见场景 ## 篇幅控制 | 文档类型 | 建议行数 | 说明 | |---------|---------|------| | 核心接口（ICache, ILog 等） | 200–400 行 | 详细覆盖 | | 实现类（MemoryCache 等） | 100–200 行 | 重点差异和扩展 | | 工具类（SecurityHelper 等） | 100–150 行 | API 列表 + 示例 | | 内部组件（Codec 等） | 50–100 行 | 简要说明 | ## 文件命名约定 ``` {中文名}{英文名}.md 缓存系统ICache.md 网络服务端NetServer.md 安全扩展SecurityHelper.md ``` ## 已有文档改进检查清单 - [ ] 添加 YAML frontmatter（title/namespace/project/updated） - [ ] 确保有"快速开始"段落 - [ ] 确保 API 签名与当前源码一致 - [ ] 代码示例使用 NewLife 规范（String/Int32） ## 来源 - `D:\X\NewLife.Core\Doc\文档标准模板.md`