# @closeio/best-practices-documentation 中文文档 规范地址：https://npmcn.com/package/%40closeio/best-practices-documentation/ 版本：0\.6\.0 npm 元数据更新时间：2026-10-20T16:07:50.196Z 中文译文更新时间：2026-11-10T02:14:15.443Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40closeio/best-practices-documentation 原文对照：https://npmcn.com/package/%40closeio/best-practices-documentation/?lang=original 项目主页：https://github.com/closeio/best-practices-documentation#readme 源码仓库：https://github.com/closeio/best-practices-documentation ## 关键信息（来自 npm 元数据） - 包体积（解压后）：94.4 kB，75 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：2 个 - 首次发布：2023-08-25T15:10:26.891Z - 最新版本发布：2025-05-14T19:50:19.865Z - 近 30 天下载量：47385（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：8（近 12 个月 0 个） ## 中文简介 用于记录代码库中的最佳做法的工具. ## 安装 ```sh npm install @closeio/best-practices-documentation ``` 也可以使用：`pnpm add @closeio/best-practices-documentation`、`yarn add @closeio/best-practices-documentation`、`bun add @closeio/best-practices-documentation` ## README # 关闭最佳做法文档 `close-best-practices` 是一个库和一个帮助团队记录其 编码最佳做法. (有兴趣在这样的项目上工作吗? [关闭](https://www.close.com/) 实值 寻找 [伟大的工程师](https://jobs.close.com/) 加入我们的队伍!) ## 哲学 该图书馆的建设体现了以下原则: 1. 文件应尽量贴近编码(最好在 代码) 2. 文档应当可以发现 3. 文档应在相关代码更改时自动更新 4. 你不必仔细看密码才能读到我们最好的 实践 ## 安装 您可以通过 npm 安装此软件包 : ``` npm i --save-dev @closeio/best-practices-documentation yarn add -D @closeio/best-practices-documentation ``` ## 将守则作为最佳做法 您可以用特殊格式的注释标记代码块为最佳做法 : ```tsx // @BestPractice React Components // @BestPractice.subtitle State Updates // @BestPractice.description // If you need to update state based on the current value, use // the functional version of the state setter rather than using // the `value`. This keeps `useCallback` from creating a new function // every time the value changes. const [value, setValue] = useState(0); const incrementValue = useCallback( () => setValue((currentValue) => currentValue + 1), [], ); // @BestPractice.end ``` 您也可以在 JSX 块中用 `{/* ... */}` 注释 格式. 检查作为代码一部分的样本项目以看到更多实例. ### 限制 - 我们目前不支持多行评论. - 此工具只查看文件 `.js`, (中文(简体) ), `.jsx`, (中文(简体) ), `.ts`,以及 `.tsx` 扩展 ## 摘录最佳做法文件 为了提取你的最佳做法文档,您可以引用我们的CLI工具: ``` npx best-practices write -s src/ -g docs/best-practices -u "https://github.com///tree/main" ``` 这将扫描您的代码 `src` 建立最佳做法 从您标记的代码中获取文件。 报告的内容 `-g` 目录将会是 完全覆盖,所以要确定您指向一个目录,而不是 包含任何手工编写的文档. 这还将写出 `digest.txt` 用于跟踪更改的文件 您生成的文档 . ## 检查 Docs 新鲜度 您可以检查您的生成的文档是否已经过时 页:1 `check` 子命令 : ``` npx best-practices check -s src/ -g docs/best-practices ``` 这将从您的代码中收集您的最佳做法文档并生成 文摘,并将这些文摘与上次编写的文摘相比较 已生成。 这个 `check` 命令将以状态代码退出 `1` 若为 文档已过时, 这使得它成为一个很好的指令 用于前承诺钩或 a CI步骤. ## 插入块入静态文档 请将一些最佳做法插入(并不断更新)静态 文档,指您自己输入的文档,而不是完全 您可以使用特殊格式的注释和 元标记 . ### 在您的代码中 在代码中,添加 `id` 元字段到文档块: ``` // @BestPractice.id insertIntoStaticDocs ``` 这个ID应该在整个代码库都是独一无二的, 但这个没有检查,或者 由工具执行。 如果您有多个相同标识的最佳做法块 然后工具拾取的最后一个 当解析您的代码时. ### 在静态文档中 在您的静态标记下文档文件中, 添加这样的评论 喜欢插入最佳做法: ``` ``` 如果你的文件是一个 `.mdx` 标记下的文件, 使用 `JSX` 样式注释代替 : ``` {/* @BestPractice.insert insertIntoStaticDocs */} {/* @BestPractice.end */} ``` 必须有始发线和终发线,因为它们将作为 边框以知道在哪里替换代码. ### 从命令行 要写给静态文件, 你必须将工具指向您的文件 根带有 `-d` 命令行参数. 举个例子. ``` `npx best-practices write -s src/ -g docs/best-practices -d docs/ ...` ``` ### 旧身份证 如果将最佳做法插入静态文档,则不会 插入到生成的文档中。 但是,它仍将包括在 检查医生新鲜度的文摘. ## 不断更新文档 您的文档有几种最新策略: 1. 创建将运行的预承诺钩 `best-practices write` 2. 创建将运行的预承诺钩 `best-practices check` 3. 创建将运行的 CI 步骤 `best-practices check` 4. 如果您拥有自动创建静态的文档系统 文档站点,您可能可以在 `best-practices` 命令作为其中的一部分. ## 自定义文档生成 如果默认使用 CLI 工具不符合您的需要, 您可以使用 用于自定义您的最佳做法生成。 我们出口所有的初级 函数 `write` 财务报告和审定财务报表 `check` CLI 子命令使用, 您可以 编一些你需要的 ## 常见问题 ### @closeio/best-practices-documentation 是什么？ 用于记录代码库中的最佳做法的工具\. ### 如何安装 @closeio/best-practices-documentation？ 在项目目录运行 npm install @closeio/best-practices-documentation，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 best-practices，可以用 npx best-practices 直接运行。 ### @closeio/best-practices-documentation 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @closeio/best-practices-documentation 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @closeio/best-practices-documentation 可以商用吗？ @closeio/best-practices-documentation 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @closeio/best-practices-documentation 的下载量有多少？ 根据 npm 官方下载统计，@closeio/best-practices-documentation 在 2026/10/10 – 2026/11/08 这 30 天内被下载 47,385 次，日均约 1,580 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @closeio/best-practices-documentation 还在维护吗？ 最新版本 0\.6\.0 发布于 2025/05/15（1\.5 年前）；至今共发布 8 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/08/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。