# @baloise/spectral-rules 中文文档

规范地址：https://npmcn.com/package/%40baloise/spectral-rules/

版本：1\.5\.3
npm 元数据更新时间：2026-09-07T09:07:31.000Z
中文译文更新时间：2026-11-07T16:00:55.873Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40baloise/spectral-rules
原文对照：https://npmcn.com/package/%40baloise/spectral-rules/?lang=original

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

- 包体积（解压后）：78.6 kB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2021-09-16T06:16:28.785Z
- 最新版本发布：2026-09-07T09:07:30.787Z
- 近 30 天下载量：5845（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 1 个）

## 中文简介

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

## 安装

```sh
npm install @baloise/spectral-rules
```

也可以使用：`pnpm add @baloise/spectral-rules`、`yarn add @baloise/spectral-rules`、`bun add @baloise/spectral-rules`

## README

[![Gitpod](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/baloise-incubator/spectral-ruleset)

# 光谱规则集

**\* 参与发展\***

自定义 [光谱 API Linter](https://github.com/stoplightio/spectral) 规则 [Zalando RESTFul API 准则](https://opensource.zalando.com/restful-api-guidelines/)。 。 。 .

规则有两种口味:

-   `zalando`: 坚持 [Zalando RESTFul API 准则](https://opensource.zalando.com/restful-api-guidelines/)
-   `baloise`: 使一些规则适应 [乌龟](https://github.com/baloise)

详见下表.

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

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

## 用这个

### 可能性A:通过 Github URL 引用

```bash
# 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` 扩展它

```bash
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` 环境变量 :

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

### B: 通过 npm 安装

```bash
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` 扩展它

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

## 发展

### 添加新规则

1.  从下表中选择一个新的、不支持的规则 。 举个例子 [#151 MUST 指定成功和错误反应](https://opensource.zalando.com/restful-api-guidelines/#151)。 。 。 .
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](https://meta.stoplight.io/docs/spectral/docs/guides/4-custom-rulesets.md) 关于如何定义自定义规则.
5.  添加: havy check mark: 到下表.
6.  创建 PR

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

## 设置

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

## 目前得到支持的规则 [扎兰多休息-api-指针](https://opensource.zalando.com/restful-api-guidelines/)

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

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

## 常见问题

### @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 和提交记录判断。