让开源，少一点语言距离。
npm包中文文档

@baloise/spectral-rules

中文文档
1.5.3发布于 2026/09/07Apache-2.0CommonJS零依赖近 30 天下载 5845

自定义光谱 API 以Zalando API准则为基础的Baloise API准则的通则.

中文使用文档
中文原文
文档目录7 节
  1. 用这个
  2. 可能性A:通过 Github URL 引用
  3. B: 通过 npm 安装
  4. 发展
  5. 添加新规则
  6. 设置
  7. 目前得到支持的规则 扎兰多休息-api-指针

Gitpod

光谱规则集

* 参与发展*

自定义 光谱 API Linter 规则 Zalando RESTFul API 准则。 。 。 .

规则有两种口味:

详见下表.

规则 spectral:oas 默认已禁用。 如果您想要再次启用这些规则

echo "extends: [https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/zalando.yml, spectral:oas]" \
    > .spectral.yml

用这个

可能性A:通过 Github URL 引用

# zalando flavor:
npx @stoplight/spectral-cli lint \
    --ruleset https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/zalando.yml \
    example/example-openapi.yml

# baloise flavor:
npx @stoplight/spectral-cli lint \
    --ruleset https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/baloise.yml \
    example/example-openapi.yml

或者创造出一个 .spectral.yml 扩展它

echo "extends: [https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/baloise.yml]" \
    > .spectral.yml
npx @stoplight/spectral-cli lint example/example-openapi.yml

如果你在代理后 你可以通过 PROXY 环境变量 :

PROXY=<PROXY URL> npx @stoplight/spectral lint <...>

B: 通过 npm 安装

npm i @baloise/spectral-rules

# zalando flavor:
npx @stoplight/spectral-cli lint \
    --ruleset ./node_modules/@baloise/spectral-rules/zalando.yml \
    example/example-openapi.yml

# baloise flavor:
npx @stoplight/spectral-cli lint \
    --ruleset ./node_modules/@baloise/spectral-rules/baloise.yml \
    example/example-openapi.yml

或者创造出一个 .spectral.yml 扩展它

echo "extends: [./node_modules/@baloise/spectral-rules/baloise.yml]" > .spectral.yml
npx @stoplight/spectral-cli lint example/example-openapi.yml

发展

添加新规则

  1. 从下表中选择一个新的、不支持的规则 。 举个例子 #151 MUST 指定成功和错误反应。 。 。 .
  2. 确保 tests/fixtures/base-openapi.yml 满足规则.
  3. 添加测试 tests/151-MUST-specify-success-and-error-responses.test.ts 那个
    1. 拿着 base-openapi.yaml 作为投入
    2. 修改它以打破新规则
    3. 期待光谱找到错误( 暂时失效)
  4. 扩展 zalando.yml 与新规则相配合,从而使之前添加的测试成功. 见 https://meta.stoplight.io/docs/光谱/docs/guides/4-海关规则集.md 关于如何定义自定义规则.
  5. 添加: havy check mark: 到下表.
  6. 创建 PR

替代的贝卢斯规则的标志是附加规则编号,加上 a例如,扎兰多规则 #115 对白鲸规则 #115a扎兰多规则 #115 定义于 zalando.yml. 白鲸规则 #115a 定义于 baloise.yml 解除原扎兰多规则 #115a。 。 。 .

设置

npm install
npm run test
npm run lint
npm run lint-fix # format source files

目前得到支持的规则 扎兰多休息-api-指针

: havy check mark:=规则已执行
: grey 感叹:=规则执行不可能或复杂

编号标题扎兰多.yml乌龟. ymlprio (A, B, C) (中文(简体) )
一百块MUST 遵循 API 第一原则: grey 感叹:: grey 感叹:页:1
101号MUST 使用 OpenAPI 提供 API 规格: grey 感叹:: grey 感叹:A 类
102号应提供 API 用户手册- 说吧- 说吧C级
103号MUST 使用美国英语编写 API: grey 感叹:: grey 感叹:A 类
104号带有 OAuth 2. 0 的安全端点- 说吧- 说吧页:1
105号MUST 定义和指定权限( 镜片)- 说吧- 说吧页:1
106号不得打破后向兼容性- 说吧- 说吧页:1
107号应选择兼容的扩展: grey 感叹:: grey 感叹:- 说吧
108号MUST 准备客户端接受相容的 API 扩展: grey 感叹:: grey 感叹:C级
109号应保守地设计 API: grey 感叹:: grey 感叹:- 说吧
110号MUST 总是返回 JSON 对象作为顶级数据结构: 重度 检查 标记 :: 重度 检查 标记 :A 类
111号MUST 默认将 Open API 规格作为可扩展的打开: grey 感叹:: grey 感叹:- 说吧
112号应使用不限成员名额的数值清单(x-extensible-enum用于查点: 重度 检查 标记 :: 重度 检查 标记 :- 说吧
113号应避免版本: grey 感叹:: grey 感叹:页:1
114号MUST 使用媒体类型版本: grey 感叹:: grey 感叹:- 说吧
115号不得使用 URI 版本: 重度 检查 标记 :- 说吧A 类
#115a (英语)可以使用正确的 URI 版本 : ^((?!.*\/v\d+(\/.*)?\/v\d+)\/.*)$- 说吧: 重度 检查 标记 :A 类
116号MUST 使用语义化版本: 重度 检查 标记 :: 重度 检查 标记 :页:1
118号MUSST 属性名称必须是 ASCII 蛇案( 绝不是骆驼案) : ^[a-z_][a-z_0-9]*$: 重度 检查 标记 :- 说吧A 类
#118a (韩语)必需的属性名称必须是 ASCII 骆驼Case : ^[a-z]+((\d)([A-Z0-9][a-z0-9]+))*([A-Z])?$- 说吧: 重度 检查 标记 :A 类
#120号应当复数阵列名称- 说吧- 说吧页:1
122号绝对不能使用 null 布尔属性: grey 感叹:: grey 感叹:- 说吧
123号MUST 使用相同的语义 null 和缺席财产: grey 感叹:: grey 感叹:- 说吧
124号不应使用 null 用于空数组: grey 感叹:: grey 感叹:- 说吧
125号应当将点数作为字符串- 说吧- 说吧? 吗?
126号应当按照 RFC 3339 定义日期属性- 说吧- 说吧? 吗?
#127号应当定义时间长度和间隔属性符合ISO 8601: grey 感叹:: grey 感叹:- 说吧
128号应使用国家、语言和货币编码标准- 说吧- 说吧? 吗?
129号MUST 路径段使用带连字符的小写分出单词: 重度 检查 标记 :: 重度 检查 标记 :A 类
130号MUST 在查询参数时使用蛇 case( 从未使用驼峰Case): 重度 检查 标记 :- 说吧页:1
#130a 时间轴:MUST 使用骆驼Case( 绝不是蛇 case) 查询参数- 说吧: 重度 检查 标记 :页:1
132号HTTP 信头字段更喜欢连字符- 帕斯卡大小写: 重度 检查 标记 :: 重度 检查 标记 :页:1
133号可能使用标准化标题- 说吧- 说吧- 说吧
134号需要复数资源名称- 说吧- 说吧A 类
135号不应使用 /api 作为基础路径: 重度 检查 标记 :: 重度 检查 标记 :A 类
136号MUST 使用不带空路段的正态路径并跟踪斜线: 重度 检查 标记 :: 重度 检查 标记 :页:1
137号MUST 坚持常规查询参数: grey 感叹:: grey 感叹:- 说吧
138号必须避免行动——考虑资源: grey 感叹:: grey 感叹:A 类
139号应建立完整的业务流程模型: grey 感叹:: grey 感叹:- 说吧
140号应定义 实用 资源: grey 感叹:: grey 感叹:- 说吧
141号MUST 保持无动词的 URL: grey 感叹:: grey 感叹:A 类
142号MUST 使用特定域的资源名称: grey 感叹:: grey 感叹:- 说吧
143号MUST 通过路径段确定资源和子资源- 说吧- 说吧- 说吧
144号必要时只应使用UUID: grey 感叹:: grey 感叹:- 说吧
145号可能考虑使用( 未) 已确认的 URL: grey 感叹:: grey 感叹:- 说吧
146号应限制资源类型的数目: 重度 检查 标记 :: 重度 检查 标记 :页:1
147号应限制次资源水平的数量: 重度 检查 标记 :: 重度 检查 标记 :页:1
148号必须正确使用 HTTP 方法: grey 感叹:: grey 感叹:A 类
149号MUST 实现通用方法属性: grey 感叹:: grey 感叹:- 说吧
150号MUST 使用标准的 HTTP 状态代码: 重度 检查 标记 :- 说吧
150a号MUST 使用额外的标准 HTTP 状态代码- 说吧: 重度 检查 标记 :- 说吧
151号MUST 指定成功和错误反应: 重度 检查 标记 :: 重度 检查 标记 :页:1
152号批量或批量请求使用编号207: grey 感叹:: grey 感叹:C级
153号MUST 使用代码 429 并带有页眉的费率限制: grey 感叹:: grey 感叹:C级
154号MUST 定义信头和查询参数的收集格式: grey 感叹:: grey 感叹:- 说吧
155号应减少带宽需要并改进反应能力: grey 感叹:: grey 感叹:- 说吧
156号应使用 gzip 压缩: grey 感叹:: grey 感叹:- 说吧
157号应当通过过滤支持部分响应: grey 感叹:: grey 感叹:- 说吧
158号应允许可选嵌入子资源: grey 感叹:: grey 感叹:- 说吧
159号MUST 支持页- 说吧- 说吧- 说吧
#160号偏好基于光标的页码, 避免基于相抵的页码- 说吧- 说吧- 说吧
161号应酌情使用页码链接- 说吧- 说吧- 说吧
162号MUST 使用 REST 成熟度二级- 说吧- 说吧- 说吧
163号可能使用 REST 第3级 -- -- HATEOAS- 说吧- 说吧- 说吧
164号MUST 使用通用的超文本控制器- 说吧- 说吧- 说吧
165号应使用简单的超文本控件进行页码和自引用- 说吧- 说吧- 说吧
166号不得使用 JSON 实体的链接头- 说吧- 说吧- 说吧
167号使用 JSON 编码结构化数据- 说吧- 说吧- 说吧
#168 (英语)可使用非 JSON 介质类型进行二进制数据或替代内容表达: grey 感叹:: grey 感叹:- 说吧
169号使用标准日期和时间格式: 重度 检查 标记 :- 说吧A 类
170号应使用国家、语言和货币编码标准- 说吧- 说吧页:1
#171号MUSST 定义数字和整数类型的格式: 重度 检查 标记 :- 说吧- 说吧
172号应选择标准媒体类型名称 application/json: 重度 检查 标记 :: 重度 检查 标记 :页:1
173号使用普通货币对象: grey 感叹:: grey 感叹:- 说吧
174号MUST 使用常见的字段名和语义: grey 感叹:: grey 感叹:- 说吧
176号必需支持问题 JSON: 重度 检查 标记 :: 重度 检查 标记 :- 说吧
#177 (中文(简体) )不可显示堆栈痕迹: grey 感叹:: grey 感叹:- 说吧
178号必须使用 Content-* 标题正确: grey 感叹:: grey 感叹:- 说吧
179号可用 Content-Location 标题: grey 感叹:: grey 感叹:- 说吧
#180 (英语)应使用 Location 页眉代替 Content-Location 标题- 说吧- 说吧- 说吧
181号可能考虑支持 Prefer 处理处理首选项的页眉: grey 感叹:: grey 感叹:- 说吧
182号可能考虑支持 ETag 合并 If-Match编号 :If-None-Match 标题: grey 感叹:: grey 感叹:- 说吧
183号应只使用指定的专有 Zalando 信头- 说吧- 说吧- 说吧
184号MUST 推广专有信头- 说吧- 说吧- 说吧
185号API 关闭前获得客户批准: grey 感叹:: grey 感叹:- 说吧
186号MUST 获取外部伙伴对折旧时间跨度的同意: grey 感叹:: grey 感叹:- 说吧
187号MUST 在API 规格中反映折旧: grey 感叹:: grey 感叹:- 说吧
188号MUST 监测预定在日出时使用的已贬值的API的使用情况: grey 感叹:: grey 感叹:- 说吧
#189 (英语)应添加 Deprecation 财务报告和审定财务报表 Sunset 答复标题: grey 感叹:: grey 感叹:- 说吧
190号应该添加监视器 Deprecation 财务报告和审定财务报表 Sunset 标题: grey 感叹:: grey 感叹:- 说吧
191号不得开始使用已贬值的API: grey 感叹:: grey 感叹:页:1
192号MUST 发布开放 API 规格: grey 感叹:: grey 感叹:A 类
#193号应监视 API 使用情况: grey 感叹:: grey 感叹:- 说吧
194号MUST 将事件作为服务接口的一部分- 说吧- 说吧- 说吧
195号MUST 提供活动计划供审查- 说吧- 说吧- 说吧
196号MUST 确保事件计划符合 Open API 计划对象- 说吧- 说吧- 说吧
197号MUSST 确保事件登记为事件类型- 说吧- 说吧- 说吧
198号MUST 确保事件符合众所周知的事件类别- 说吧- 说吧- 说吧
199号MUSST 确保事件定义有用的商业资源- 说吧- 说吧- 说吧
200块MUSST 确保事件不提供敏感数据- 说吧- 说吧- 说吧
#201号MUSST 使用一般事件类别来指示业务流程中的步骤和到达点- 说吧- 说吧- 说吧
202号MUST 使用数据变化事件来信号突变- 说吧- 说吧- 说吧
#203号应当为明确事件排序提供手段- 说吧- 说吧- 说吧
#204号对数据变化事件使用散列分区策略- 说吧- 说吧- 说吧
205号应确保数据更改事件与API资源相匹配- 说吧- 说吧- 说吧
207号显示事件类型的所有权- 说吧- 说吧- 说吧
208号MUST 定义符合总体API准则的事件有效载荷- 说吧- 说吧- 说吧
209号事件必须保持后向兼容性- 说吧- 说吧- 说吧
#210号应避免 additionalProperties 在事件类型定义中- 说吧- 说吧- 说吧
211号MUST 使用独特的事件标识符- 说吧- 说吧- 说吧
212号应对单电源外处理进行设计- 说吧- 说吧- 说吧
213号活动类型名称遵循命名惯例- 说吧- 说吧- 说吧
214号MUST 为重复事件准备事件消费者- 说吧- 说吧- 说吧
215号MUST 提供 API 标识符: 重度 检查 标记 :: 重度 检查 标记 :- 说吧
#216号应使用 additionalProperties- 说吧- 说吧- 说吧
217号绝对 URI 完全使用- 说吧- 说吧- 说吧
218号MUST 包含 API 元信息: 重度 检查 标记 :: 重度 检查 标记 :- 说吧
219号MUST提供API观众: 重度 检查 标记 :- 说吧- 说吧
#219a (英语)MUST提供baloise API观众- 说吧: 重度 检查 标记 :- 说吧
#220号MUST 使用最具体的 HTTP 状态代码: grey 感叹:: grey 感叹:- 说吧
#223号MUST-SHOULD 使用功能命名方案: grey 感叹:: grey 感叹:- 说吧
224号MUST 遵循主机名命名惯例: grey 感叹:: grey 感叹:- 说吧
225号MUST 遵循权限命名惯例( 范围): grey 感叹:: grey 感叹:- 说吧
226号MUST 文档隐含过滤: grey 感叹:: grey 感叹:- 说吧
227号MUST 文档卡通 GET, (中文(简体) ), HEAD,以及 POST 结束点: grey 感叹:: grey 感叹:- 说吧
228号MUST使用方便URL的资源标识符: [a-zA-Z0-9:. -/]*: grey 感叹:: grey 感叹:A 类
#229号应当考虑设计 POST 财务报告和审定财务报表 PATCH 专有: grey 感叹:: grey 感叹:- 说吧
230号可能考虑支持 Idempotency-Key 标题: grey 感叹:: grey 感叹:- 说吧
231号应使用二键来配音 POST 设计: grey 感叹:: grey 感叹:- 说吧
233a号MUST 请求必须使用追踪信头- 说吧: 重度 检查 标记 :- 说吧
#234号仅使用持久和不可改变的远程引用: grey 感叹:: grey 感叹:- 说吧
235号应使用名称日期/时间属性 _at 后缀- 说吧- 说吧- 说吧
236号应使用查询参数设计简单的查询语言: grey 感叹:: grey 感叹:- 说吧
237号应使用 JSON 设计复杂查询语言: grey 感叹:: grey 感叹:- 说吧
238号应使用标准化属性格式: grey 感叹:: grey 感叹:- 说吧
239号应编码嵌入式二进制数据 base64url: grey 感叹:: grey 感叹:- 说吧
#240号应使用 UPPER SNAKE CASE 格式声明 enum 值: 重度 检查 标记 :: 重度 检查 标记 :- 说吧
#241号可能显示复合密钥为资源标识符: grey 感叹:: grey 感叹:- 说吧

版本与发布记录

@baloise/spectral-rules 共发布 29 个版本，首次发布于 2021/09/16；过去 12 个月发布了 1 个版本。

版本发布日期距今
1.5.3latest2026/09/072 个月前
1.5.02025/04/291.5 年前
1.4.12024/05/272 年前
1.4.02024/05/272 年前
1.3.02024/05/272 年前
1.2.02024/05/272 年前

关于 @baloise/spectral-rules 的常见问题

@baloise/spectral-rules 是什么？

自定义光谱 API 以Zalando API准则为基础的Baloise API准则的通则.

如何安装 @baloise/spectral-rules？

在项目目录运行 npm install @baloise/spectral-rules，或使用 pnpm add / yarn add / bun add。

@baloise/spectral-rules 支持 TypeScript 吗？

该包的 package.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/baloise__spectral-rules 是否存在。

@baloise/spectral-rules 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@baloise/spectral-rules 可以商用吗？

@baloise/spectral-rules 使用 Apache-2.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

@baloise/spectral-rules 的下载量有多少？

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

@baloise/spectral-rules 还在维护吗？

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