feat(core): 增加 sorted 参数来控制结果排序 (#10744)

* feat: 增加 `sorted` 参数来控制结果排序

* feat: 添加 `sorted` 参数的测试

重用了 `sort` 的代码和数据：是不是可以考虑将两者结合？

docs/en/parameter.md

@@ -80,6 +80,12 @@ Set `limit` to limit the number of articles in the feed.
 
 E.g. Dribbble Popular Top 10 [https://rsshub.app/dribbble/popular?limit=10](https://rsshub.app/dribbble/popular?limit=10)
 
+## Sorted
+
+Set `sorted` to control whether to sort the output by the publish date (`pubDate`). This is useful for some feeds that pin some entries at the top. Default to `true` i.e. the output is sorted.
+
+E.g. NJU Undergraduate Bulletin Board <https://rsshub.app/nju/jw/ggtz?sorted=false>
+
 ## Fulltext
 
 Enable fulltext via `mode` parameter.

docs/parameter.md

@@ -79,6 +79,12 @@ filter 支持正则表达式。由于正则部分特性可被利用于 DoS (ReDO
 
 举例: bilibili 排行榜前 10 <https://rsshub.app/bilibili/ranking/0/3?limit=10>
 
+## 排序结果
+
+通过 `sorted` 参数控制是否对输出的条目按照发布时间进行排序，这对一些会把部分新闻等置顶的源比较有用（如信息发布网）。默认为 `true` 即进行排序。
+
+举例：不重新排序南京大学本科生院教学信息网的公告通知：<https://rsshub.app/nju/jw/ggtz?sorted=false>
+
 ## 全文输出
 
 可以使用 `mode` 参数来开启自动提取全文内容功能

lib/middleware/parameter.js

@@ -54,7 +54,9 @@ module.exports = async (ctx, next) => {
         ctx.state.data.description && (ctx.state.data.description = entities.decodeXML(ctx.state.data.description + ''));
 
         // sort items
+        if (ctx.query.sorted !== 'false') {
             ctx.state.data.item = ctx.state.data.item.sort((a, b) => +new Date(b.pubDate || 0) - +new Date(a.pubDate || 0));
+        }
 
         const handleItem = (item) => {
             item.title && (item.title = entities.decodeXML(item.title + ''));

test/middleware/parameter.js

@@ -260,6 +260,18 @@ describe('limit', () => {
     });
 });
 
+describe('sorted', () => {
+    it('sorted', async () => {
+        const response = await request.get('/test/sort?sorted=false');
+        expect(response.status).toBe(200);
+        const parsed = await parser.parseString(response.text);
+        expect(parsed.items[0].title).toBe('Sort Title 0');
+        expect(parsed.items[1].title).toBe('Sort Title 1');
+        expect(parsed.items[2].title).toBe('Sort Title 2');
+        expect(parsed.items[3].title).toBe('Sort Title 3');
+    });
+});
+
 describe('tgiv', () => {
     it(`tgiv`, async () => {
         const response = await request.get('/test/1?tgiv=test');