# @azure/avocado 中文文档

规范地址：https://npmcn.com/package/%40azure/avocado/

版本：0\.12\.1
npm 元数据更新时间：2026-09-03T02:29:08.417Z
中文译文更新时间：2026-11-07T13:55:49.428Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azure/avocado
原文对照：https://npmcn.com/package/%40azure/avocado/?lang=original
项目主页：https://github.com/Azure/avocado#readme
源码仓库：https://github.com/Azure/avocado

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：202 kB，59 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：18 个
- 首次发布：2019-03-06T00:26:08.157Z
- 最新版本发布：2026-09-03T02:29:08.259Z
- 近 30 天下载量：47466（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 5 个）

## 中文简介

OpenAPI 配置验证器

## 安装

```sh
npm install @azure/avocado
```

也可以使用：`pnpm add @azure/avocado`、`yarn add @azure/avocado`、`bun add @azure/avocado`

## README

# 阿沃卡多语Name

OpenAPI spec寄存器配置和目录的又一验证器.

[![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/public.avocado?branchName=master)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=120&branchName=master)

国家预防机制:https://www.npmjs.com/package/@azure/vocado

## 概览

Avocado验证文件夹结构和配置.

Avocado可以被集成到Azure管道来验证OpenAPI spec寄存器. 例如,Avocado被使用为 `Azure/azure-rest-api-specs` 当新的拉动请求被创建时, 它会自动被 Azure DevOps 管道触发 .

阿沃卡多主要功能如下:

-   对于给定的目录验证是否存在 `specification` 过滤器 `readme.md` 下划线 `specification` 文件夹.
-   验证是否 `readme.md` 是自定义的特定文件,必须包含 `see https://aka.ms/autorest`
-   验证是否 `swagger file` 是有效的json文件,并检查所有引用 `json` 文件( 编号`referenced json` 以 json 对象标记的文件有密钥名称 `"$ref"`) (中文(简体) ).
-   校验文件夹是否有未引用的文件 . `swagger file` 必须引用 `readme.md` 或其他类型 `swagger file`。 。 。 .
-   验证是否 `swagger file` 有个通知和警告 详见: [民事裁判所](https://npmcn.com/package/%40azure/avocado/#readme-circular-reference)
-   验证每个 RP 文件夹是否包含 SDK 生成的 readme 文件 .

## 如何使用

### 安装

`npm install -g @azure/avocado`

### 使用量

-   `avocado -h` 显示帮助消息
-   `avocado` 验证当前目录
-   `avocado -d <my-folder-path>` 验证 `<my-folder-path>` 目录
-   `avocado -d <my-folder-path> --excludePaths 'common-types'` 校验文件夹并排除“ 常见类型” 的错误

### 示例

-   运行全部规格 : 清除还原 `azure/azure-rest-api-specs` 在文件夹中运行“ vocado ” `azure/azure-rest-api-specs`。 。 。 .
-   运行单个服务规格: 创建文件夹 `specification`并移动您的服务规格文件夹 `specification`运行"vocado"

## 如何解决错误

### JSON 平面

级别: 错误

要解决 json 解析错误, 您需要确保 json 格式是有效的 .

### 否 JSON FILE FOUND

级别: 错误

Readme 文件引用了一个不存在的json文件. 要解决错误, 您需要检查 json 文件是否存在 .

### (原始内容存档于2017-10-21) (英语). UNREFERENCE JSON FILE

级别: 错误

Json文件必须被readme输入文件部分或其他json文件所引用. Eg,实例 swagger 文件应该被主 swagger json 引用,对于 SDK 生成主 swagger ,应该被 readme 输入文件部分引用. 要解决错误, 您需要将非引用文件放置到合适的位置 .

### 失忆了

级别: 错误

每个资源提供者文件夹必须有一个下游SDK生成所需的readme文件. 要解决错误,需要创建包含SDK生成配置的readme文件.

### 不为人知

级别: 错误

资源提供者文件夹中的每个读取器都应遵循自动降标格式。 要解决错误, 请检查 readme 块引用是否包含 `see https://aka.ms/autorest` 从字面上说.

### 密码:

级别: 错误

Swagger json 文件 api 版本必须与其文件路径一致 。 斯瓦格可以定义 [swagger 2.0 基本结构](https://swagger.io/docs/specification/2-0/basic-structure/) 包含 api 版本。 要解决错误, 您需要修改您的 swagger 文件位置或 swagger 文件 api 版本, 以使两者一致 .

### 中心-资源

级别: 警告

要解决循环参考问题,应当打破循环链.

示例 `a.json` - > (中文) `b.json`\- > (中文)`c.json`

```json
// a.json
{ "$ref": "b.json" }
```

```json
// b.json
{ "$ref": "c.json" }
```

```json
// c.json
{ "$ref": "a.json" }
```

```mermaid
graph TD

A((a.json))-->B((b.json))
B-->C((c.json))
C-->A

```

### 模拟 API VERSION

级别: 错误

默认标记只应包含一个API版本.

要解决这个错误, 您应该为您服务中的所有资源类型添加一个新的一致的版本, 并将字段复制到当前版本文件夹中 .

### 评分( F)

级别: 警告

管理平面 swagger JSON 文件与其文件夹路径不符 。 确保位于资源管理文件夹中的管理平面 swagger

要解决此警告, 您应该确保位于资源管理文件夹中的管理器平面 swagger .

### 错过 APIS IN DEFAULT TAG

级别: 错误

这个 [默认](https://azure.github.io/autorest/generate/#adding-tags-when-generating) API 版本标签( 可见于 `Basic information` 节次 [自动Rest 配置文件](http://azure.github.io/autorest/user/configuration.html) (README文件)应当包含所有API路径. API 路径 : ${0} 在任何 OpenAPI 中都没有 `.json` 包含在默认标签中的路径列表中列出的文件,如 [相关 `Tag:` 节](https://azure.github.io/autorest/generate/#adding-tags-when-generating) 在自动恢复配置文件(README文件)中.

修复此错误包括 OpenAPI `.json` 默认 API 版本标签路径列表中的文件路径( 在 [相关 `Tag:` 节](https://azure.github.io/autorest/generate/#adding-tags-when-generating)包括缺失的 API 路径.

**重要性**:错误可能指向之前的API版本. **这并不意味着这是假阳性**来啊! 这意味着之前的API版本有一个API路径在默认API版本中缺失.

**Avocado 正常公关失败的常见情况**数字 :

-   由于外壳不匹配, API 路径往往从默认 API 版本中缺失; 例如, 新 API 版本中的路径 `resourceGroups` 在其中,而前一个有 `resourcegroups`. 见下文实例.
-   如果阿沃卡多报告你错过了一条路 **故意贬值** 或者说 **故意删除** 但API版本是公开发布的(GA,通用可用,不预览中),您需要先获得 突破变更委员会审批. 跟踪步骤1的突破性改变过程 [此图](https://aka.ms/pr-diagram)如果您在先前的公关中已经获得这种批准,请遵循 [压制指南](https://aka.ms/azsdk/pr-suppressions)提到你确定的情况.

**已知的阿沃卡多报告虚假阳性的情况**: Avocado可能错误地报告以下两种情景中的失败:

-   您的API 已贬值/ 过时 [6627号](https://github.com/Azure/azure-sdk-tools/issues/6627) (实例 [24771卢比](https://github.com/Azure/azure-rest-api-specs/pull/24771#issuecomment-1660776189)(中文(简体) )
-   您的 API 正在使用服务组文件夹 [6201号](https://github.com/Azure/azure-sdk-tools/issues/6201)

如果你正在处理其中一种情况 [压制指南](https://aka.ms/azsdk/pr-suppressions)提到你确定的情况.

**当此错误可以被压制时**: 如果缺失的 API 路径被贬值, 您可以压制这个错误 。 循此\[先入后入导\].

例如,详细分析这类错误的发生,见这些GitHub评论:

-   [PR 23941 评论](https://github.com/Azure/azure-rest-api-specs/pull/23941#issuecomment-1585095669)
-   [PR 24939 评论](https://github.com/Azure/azure-rest-api-specs/pull/24939#issuecomment-1656434544)

### (简体中文)

级别: 错误

这个 [默认](https://azure.github.io/autorest/generate/#adding-tags-when-generating) API 版本标签( 可见于 `Basic information` 节次 [自动Rest 配置文件](http://azure.github.io/autorest/user/configuration.html) (README文件)不包含给定的OpenAPI的最新API版本 `.json` 文档.

要纠正这个错误,请确保 `.json` 最晚API版本路径的文件包含在默认标签路径列表中,在 [相关 `Tag:` 节](https://azure.github.io/autorest/generate/#adding-tags-when-generating) 在自动恢复配置文件(README文件)中. 或者,通过编辑 API 版本标签,将默认的 API 版本标签改为有效的标签 `Basic information` 节.

例如,详细分析这种错误的发生,见 [此 GitHub 注释](https://github.com/Azure/azure-rest-api-specs/pull/23941#issuecomment-1585085436)。 。 。 .

### (原始内容存档于2013-10-12). MULTIPLE DEFAULT TAGS

级别: 错误

Readme 文件有多个默认标签.

期望是只有一个默认标记,这会导致一个SDK包. 在同一RP的不同服务资源上发布单独的SDK软件包,不妨考虑采用 [服务组的文件夹结构](https://github.com/Azure/azure-rest-api-specs/blob/main/README.md#folder-structure-for-service-group),它支持每个子文件夹下的 readme 配置文件.

### 评分( T)

级别: 错误

Typec 文件在资源管理或数据平面文件夹中不允许使用.

以修此错. 您应该将 TypeSpec 文件移动到 TypeSpec 文件夹 .

## 捐款

该项目欢迎各方的贡献和建议。 大多数捐款要求您同意 撰稿人许可协议(CLA)宣布,你有权并且实际上确实给了我们 有权使用您的贡献。 详情请访问 [https://cla.microsoft.com (中文(简体) )](https://cla.microsoft.com/)。 。 。 .

当您提交拉动请求时, CLA 机器人会自动确定您是否需要提供 a CLA并适当装饰公关(例如标签、评论)。 只要听从指示 由机器人提供。 你只需要用我们的CLA 一次就能完成.

该项目通过了 [Microsoft 开源行为守则](https://opensource.microsoft.com/codeofconduct/)。 。 。 . 更多信息见 [《行为守则》](https://opensource.microsoft.com/codeofconduct/faq/) 或者说 联系人 [打开码@ microsoft.com](mailto:opencode@microsoft.com) 并附上任何其他问题或评论.

## 常见问题

### @azure/avocado 是什么？

OpenAPI 配置验证器

### 如何安装 @azure/avocado？

在项目目录运行 npm install @azure/avocado，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 avocado，可以用 npx avocado 直接运行。

### @azure/avocado 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @azure/avocado 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @azure/avocado 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @azure/avocado 可以商用吗？

@azure/avocado 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @azure/avocado 的下载量有多少？

根据 npm 官方下载统计，@azure/avocado 在 2026/10/08 – 2026/11/06 这 30 天内被下载 47,466 次，日均约 1,582 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @azure/avocado 还在维护吗？

最新版本 0\.12\.1 发布于 2026/09/03（2 个月前）；至今共发布 59 个版本，其中过去 12 个月发布了 5 个；首次发布于 2019/03/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。