164 lines
5.2 KiB
Markdown
164 lines
5.2 KiB
Markdown
---
|
|
sidebarDepth: 2
|
|
---
|
|
|
|
# 路由规范
|
|
|
|
## 代码规范
|
|
|
|
### 通用准则
|
|
|
|
- **保持一致！**
|
|
- 避免使用已经被废弃的特性。
|
|
- 避免修改 `yarn.lock` 和 `package.json`，除非您添加了新的依赖。
|
|
- 将重复的代码合并为函数。
|
|
- 优先使用更高版本的 ECMAScript 标准特性，而不是使用低版本特性。
|
|
- 按字母顺序排序（大写字母优先），以便更容易找到条目。
|
|
- 尽量使用 HTTPS 而非 HTTP 传输数据。
|
|
- 尽量使用 WebP 格式而非 JPG 格式，因为前者支持更好的压缩。
|
|
|
|
### 代码格式
|
|
|
|
#### 缩进
|
|
|
|
- 使用 4 个空格缩进。
|
|
|
|
#### 分号
|
|
|
|
- 在每条语句结尾添加分号。
|
|
|
|
#### 字符串
|
|
|
|
- 使用单引号而不是双引号。
|
|
- 使用 [模板字符串](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Template_literals) 而非复杂的字符串拼接。
|
|
- 对于 GraphQL 查询，使用 [模板字符串](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Template_literals)。
|
|
|
|
#### 空格
|
|
|
|
- 在每个文件末尾添加一个空行。
|
|
- 避免尾随空格，代码应整洁易读。
|
|
|
|
### 语言特性
|
|
|
|
#### 类型转换
|
|
|
|
- 避免重复转换同一类型。
|
|
|
|
#### 函数
|
|
|
|
- 优先使用 [箭头函数](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Functions/Arrow_functions)，而不是使用 `function` 关键字定义函数。
|
|
|
|
#### 循环
|
|
|
|
- 对于数组，使用 `for-of`，而不是使用 `for`。([javascript:S4138](https://rules.sonarsource.com/javascript/RSPEC-4138))
|
|
|
|
#### 变量
|
|
|
|
- 使用 `const` 和 `let` 而不是 `var`。
|
|
- 每次声明一个变量。
|
|
|
|
### 命名
|
|
|
|
- 使用 `lowerCamelCase` 命名变量和函数
|
|
- 使用 `kebab-case` 命名文件和文件夹，也可以使用 `snake_case`。
|
|
- 使用 `CONSTANT_CASE` 命名常量。
|
|
|
|
## v2 路由规范
|
|
|
|
当在 RSSHub 中编写新的路由时，需要按特定方式组织文件。命名空间文件夹应该存储在 `lib/v2` 目录下，并且应包括三个必需文件：
|
|
|
|
- `router.js` 注册路由
|
|
- `maintainer.js` 提供路由维护者信息
|
|
- `radar.js` 为每个路由提供对应 [RSSHub Radar](https://github.com/DIYgod/RSSHub-Radar) 规则
|
|
|
|
命名空间文件夹结构应该像这样：
|
|
|
|
├───lib/v2
|
|
│ ├───furstar
|
|
│ ├─── templates
|
|
│ ├─── description.art
|
|
│ ├─── router.js
|
|
│ ├─── maintainer.js
|
|
│ ├─── radar.js
|
|
│ ├─── someOtherJs.js
|
|
│ └───test
|
|
│ └───someOtherNamespaces
|
|
...
|
|
|
|
**所有符合条件的，在 `lib/v2` 路径下的路由将会被自动载入，无需更新 `lib/router.js`**
|
|
|
|
### 命名空间
|
|
|
|
RSSHub 会将所有路由命名空间的文件夹名附加到路由前面。路由维护者可命名空间视为根目录。
|
|
|
|
#### 命名规范
|
|
|
|
- 使用二级域名 (second-level domain, SLD) 作为命名空间。有关 URL 结构的更多信息，请参阅 [此页面](/joinus/new-radar.html#ding-ceng-dui-xiang-jian)。
|
|
- 不要创建相同命名空间的变体。有关更多信息，请参阅 [此页面](/joinus/new-rss/before-start.html#chuang-jian-ming-ming-kong-jian)
|
|
|
|
### 注册路由
|
|
|
|
`router.js` 文件应导出一个方法，提供在初始化路由时使用的 `@koa/router` 对象。
|
|
|
|
### 维护者列表
|
|
|
|
`maintainer.js` 文件应导出一个对象，提供与路由相关的维护者信息，包括：
|
|
|
|
- 键: `@koa/router` 对象中对应的路由
|
|
- 值：一个字符串数组，包括所有维护者的 GitHub ID。
|
|
|
|
要生成维护者列表，可使用以下命令：`pnpm run build:maintainer`，它将在 `assets/build/` 目录下一份维护者列表。
|
|
|
|
::: danger 警告
|
|
在 `@koa/router` 对象中的路由应该与相应的文档中添加命名空间前的 `path` 一致。
|
|
:::
|
|
|
|
### Radar 规则
|
|
|
|
所有路由都需要包含 `radar.js` 文件，其中包括相应的域名。最低要求是规则出现在相应的站点上，即需要填写 `title` 和 `docs` 字段。
|
|
|
|
要生成完整的 `radar-rules.js` 文件，可使用以下命令：`yarn build:radar`，它将在 `assets/build/` 目录下创建文件。
|
|
|
|
::: tip 提示
|
|
在提交代码之前，请记得删除所有在 `assets/build/` 中的生成的资源。
|
|
:::
|
|
|
|
### 渲染模板
|
|
|
|
当渲染自定义 HTML 内容（例如 `item.description`）时，**必须**使用 [art-template](https://aui.github.io/art-template/) 进行排版。
|
|
|
|
所有模板都应放置在路由命名空间下的 `templates` 文件夹中，并使用 `.art` 文件扩展名命名。
|
|
|
|
#### 示例
|
|
|
|
下面是在 [furstar](https://github.com/DIYgod/RSSHub/blob/master/lib/v2/furstar) 命名空间中示例：
|
|
|
|
<!-- markdownlint-disable MD046 -->
|
|
|
|
```html
|
|
<div>
|
|
<img src="{{ avatar }}" />
|
|
{{ if link !== null }}
|
|
<a href="{{ link }}">{{name}}</a>
|
|
{{ else }}
|
|
<a href="#">{{name}}</a>
|
|
{{ /if }}
|
|
</div>
|
|
```
|
|
|
|
```js
|
|
const path = require('path');
|
|
const { art } = require('@/utils/render');
|
|
const renderAuthor = (author) => art(path.join(__dirname, 'templates/author.art'), author);
|
|
```
|
|
|
|
<!-- markdownlint-enable MD046 -->
|
|
|
|
### v1 路由规范
|
|
|
|
::: danger 警告
|
|
|
|
v1 路由规范已被弃用。所有新路由都应遵循 [v2 路由规范](#v2-lu-you-gui-fan)。
|
|
|
|
:::
|