@sansenjian/qq-music-api 2.0.5 → 2.1.1

package/.github/workflows/deploy-docs.yml

@@ -0,0 +1,54 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build with VitePress
+        run: npm run docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/release.yml

@@ -10,26 +10,27 @@ jobs:
       contents: read
       packages: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v4
 
-      # 发布到 NPM Registry
       - name: Setup Node.js for NPM
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v4
         with:
           node-version: 20
           registry-url: 'https://registry.npmjs.org/'
+
       - run: npm install
+
       - name: Publish to NPM
         run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      # 发布到 GitHub Packages
       - name: Setup Node.js for GitHub Packages
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v4
         with:
           node-version: 20
           registry-url: 'https://npm.pkg.github.com'
+
       - name: Publish to GitHub Packages
         run: npm publish --access public
         env:

package/.github/workflows/test.yml

@@ -0,0 +1,70 @@
+name: Test
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20.x, 22.x, 24.x]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run linter
+        run: npm run eslint
+        continue-on-error: true
+
+      - name: Run tests
+        run: npm test
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/lcov.info
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build application
+        run: npm run docs:build
+
+      - name: Check build
+        run: |
+          if [ -d "docs/.vitepress/dist" ]; then
+            echo "Build successful"
+          else
+            echo "Build failed"
+            exit 1
+          fi

package/README.md

@@ -13,17 +13,17 @@
 </div>
 
 > 🍴 本项目 Fork 自 [Rain120/qq-music-api](https://github.com/Rain120/qq-music-api)，原项目已停止维护，此版本持续更新中
-
-> QQ音乐API koa2 版本, 通过Web网页版请求QQ音乐接口数据, 有问题请提 [issue](https://github.com/sansenjian/qq-music-api/issues)
-
+> QQ 音乐 API koa2 版本，通过 Web 网页版请求 QQ 音乐接口数据，有问题请提 [issue](https://github.com/sansenjian/qq-music-api/issues)
 > 当前代码仅供学习，不可做商业用途
 
-### API结构图
+### API 结构图
 
-> 目前暂时没有时间做登录模块的接口，欢迎各位大佬给我`PR`, 阿里嘎多
+> 目前暂时没有时间做登录模块的接口，欢迎各位大佬给我 `PR`, 阿里嘎多
 
 ![qq-music](./screenshot/qq-music.png)
 
+📖 **详细 API 文档**: [查看完整 API 文档](https://sansenjian.github.io/qq-music-api/)
+
 ### 环境要求
 
 > 本项目采用 `koa2`，需要 Node.js 18.0.0+
@@ -79,9 +79,9 @@ node app.js
 | axios | ^1.6.0 | 修复安全漏洞 CVE-2021-3749 |
 | koa | ^2.15.0 | 框架更新 |
 | koa-bodyparser | ^4.4.0 | 解析器更新 |
-| @koa/router | ^12.0.0 | 替代 koa-router |
+| @koa/router | ^15.3.1 | 替代 koa-router |
 | koa-static | ^5.0.0 | 静态文件服务 |
-| dayjs | ^1.11.10 | 替代 moment.js (更轻量) |
+| date-fns | ^4.1.0 | 日期处理库 (轻量级) |
 
 **开发依赖**
 | 依赖 | 版本 | 说明 |
@@ -94,83 +94,68 @@ node app.js
 | @commitlint/* | ^18.0.0 | 提交信息规范 |
 | @babel/* | ^7.23.0 | 编译工具 |
 | nodemon | ^3.0.0 | 开发热重载 |
+| vitepress | ^1.6.4 | 文档工具 (基于 Vite) |
+| vue | ^3.5.29 | 渐进式 JS 框架 |
 
 **已移除的依赖**
 - `colors` - 存在安全问题，已用 chalk 替代
-- `moment` - 已用 dayjs 替代
+- `moment` - 已用 date-fns 替代
+- `dayjs` - 已用 date-fns 替代 (更小的打包体积)
+- `docsify-cli` - 已用 vitepress 替代 (更好的性能和功能)
 - `lodash.get` - 已用原生可选链 `?.` 替代
 - `eslint-plugin-node` - 已用 eslint-plugin-n 替代
 - `eslint-plugin-standard` - 已集成到 eslint-config-standard
 
 ### 功能特性
 
-- [x] 获取歌曲播放链接 **2021-01-24**
-
-- [x] 支持自定义设置 `cookie` **2021-01-23**
-
-- [x] 获取歌曲 + 专辑图片 **2020-05-24**
-
-- [x] 获取歌手热门歌曲 **2020-07-04**
-
-- [x] 获取QQ音乐产品的下载地址
-
-- [x] 获取歌单分类
-
-- [x] 获取歌单列表
-
-- [x] 获取歌单详情
-
-- [x] 获取MV标签
-
-- [x] 获取MV播放信息
-
-- [x] 获取歌手MV
-
-- [x] 获取相似歌手
-
-- [x] 获取歌手信息
-
-- [x] 获取歌手被关注数量信息
-
-- [x] 获取电台列表
-
-- [x] 获取专辑
-
-- [x] 获取数字专辑
-
-- [x] 获取歌曲歌词
-
-- [x] 获取MV
-
-- [x] 获取新碟信息
-
-- [x] 获取歌手专辑
-
-- [x] ~~获取歌曲VKey~~ **2021-01-24**
-
-- [x] 获取搜索热词
-
-- [x] 获取关键字搜索提示
-
-- [x] 获取搜索结果
-
-- [x] 获取首页推荐
-
-- [x] 获取排行榜单列表
-
-- [x] 获取排行榜单详情
-
-- [x] 获取评论信息(cmd代表的意思没太弄明白)
-
-- [x] 获取票务信息
-
-- [x] 获取歌单详情
-
-- [x] 获取歌手列表
+#### 🎵 音乐播放
+- ✅ **歌曲播放链接** - 获取 QQ 音乐歌曲的播放地址
+- ✅ **歌曲与专辑图片** - 获取歌曲封面和专辑 artwork 图片
+- ✅ **歌曲歌词** - 获取歌曲的歌词信息（含翻译）
+- ✅ **MV 播放信息** - 获取 MV 的播放地址和相关信息
+
+#### 🎤 歌手相关
+- ✅ **歌手热门歌曲** - 获取歌手的热门歌曲列表
+- ✅ **歌手信息** - 获取歌手的基本资料信息
+- ✅ **相似歌手** - 获取与指定歌手风格相似的其他歌手
+- ✅ **歌手关注数** - 获取歌手的被关注数量信息
+- ✅ **歌手 MV** - 获取歌手的 MV 作品列表
+- ✅ **歌手专辑** - 获取歌手的专辑作品列表
+
+#### 📋 歌单相关
+- ✅ **歌单分类** - 获取 QQ 音乐的歌单分类标签
+- ✅ **歌单列表** - 获取指定分类下的歌单列表
+- ✅ **歌单详情** - 获取歌单的详细信息和歌曲列表
+
+#### 🔍 搜索功能
+- ✅ **搜索热词** - 获取当前热门搜索关键词
+- ✅ **搜索提示** - 根据关键字获取搜索建议
+- ✅ **搜索结果** - 获取歌曲、歌手、专辑等搜索结果
+
+#### 📊 排行榜
+- ✅ **排行榜单** - 获取所有音乐排行榜列表
+- ✅ **榜单详情** - 获取指定排行榜的歌曲列表
+
+#### 💿 专辑相关
+- ✅ **专辑信息** - 获取专辑的详细信息
+- ✅ **数字专辑** - 获取数字专辑的售卖信息
+- ✅ **新碟上架** - 获取最新发布的专辑信息
+
+#### 🎬 MV 视频
+- ✅ **MV 标签** - 获取 MV 的分类标签
+- ✅ **MV 列表** - 获取 MV 视频列表
+
+#### 🔧 其他功能
+- ✅ **自定义 Cookie** - 支持配置自定义 Cookie 信息
+- ✅ **产品下载** - 获取 QQ 音乐数字产品的下载地址
+- ✅ **电台列表** - 获取网络电台节目列表
+- ✅ **票务信息** - 获取音乐演出票务信息
+- ✅ **评论信息** - 获取歌曲、专辑等评论数据
+- ✅ **首页推荐** - 获取 APP 首页推荐内容
 
 ### 使用文档
 
-使用`apis`详见[文档](https://rain120.github.io/qq-music-api/#/)
+使用 `apis` 详见 [文档](https://sansenjian.github.io/qq-music-api/)
 
 ### 关于项目
 
@@ -178,7 +163,7 @@ node app.js
 
 [Binaryify/NeteaseCloudMusicApi](https://github.com/Binaryify/NeteaseCloudMusicApi)
 
-[Vue2.0开发企业级移动端音乐Web App](https://coding.imooc.com/class/107.html)
+[Vue2.0 开发企业级移动端音乐 Web App](https://coding.imooc.com/class/107.html)
 
 **参考内容**
 
@@ -190,7 +175,7 @@ node app.js
 
 ### 项目不足
 
-1. 因为本人没写过`unit test`, 所以本项目尚未添加`unit test`, 等有时间再添加;
+1. 因为本人没写过 `unit test`, 所以本项目尚未添加 `unit test`, 等有时间再添加;
 
 2. 登录获取个人信息等接口都没做
 

package/jest.config.js

@@ -0,0 +1,29 @@
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.js'],
+  collectCoverageFrom: [
+    'module/**/*.js',
+    'routers/**/*.js',
+    'util/**/*.js',
+    '!**/node_modules/**',
+    '!**/tests/**'
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  coverageThreshold: {
+    global: {
+      branches: 50,
+      functions: 50,
+      lines: 50,
+      statements: 50
+    }
+  },
+  setupFilesAfterEnv: ['<rootDir>/tests/setup/jest.setup.js'],
+  testTimeout: 10000,
+  verbose: true,
+  moduleNameMapper: {
+    '^@module/(.*)$': '<rootDir>/module/$1',
+    '^@routers/(.*)$': '<rootDir>/routers/$1',
+    '^@util/(.*)$': '<rootDir>/util/$1'
+  }
+};

package/module/apis/music/getLyric.js

@@ -1,12 +1,11 @@
 const { lyricParse } = require('../../../util/lyricParse');
-const dayjs = require('dayjs');
 const y_common = require('../y_common');
 
 module.exports = ({ method = 'get', params = {}, option = {}, isFormat = false }) => {
 	const data = Object.assign(params, {
 		format: 'json',
 		outCharset: 'utf-8',
-		pcachetime: dayjs().valueOf(),
+		pcachetime: Date.now(),
 	});
 	const options = Object.assign(option, {
 		params: data,

package/module/apis/search/getSearchByKey.js

@@ -6,7 +6,7 @@ module.exports = ({ method = 'get', params = {}, option = {} }) => {
 		outCharset: 'utf-8',
 		ct: 24,
 		qqmusic_ver: 1298,
-		// https://github.com/Rain120/qq-music-api/issues/68
+		// https://github.com/sansenjian/qq-music-api/issues/68
 		// new_json: 1,
 		remoteplace: 'txt.yqq.song',
 		// searchid: 58932895599763136,

package/module/apis/singers/getSingerDesc.js

@@ -1,4 +1,3 @@
-const dayjs = require('dayjs');
 const y_common = require('../y_common');
 
 module.exports = ({ method = 'get', params = {}, option = {} }) => {
@@ -7,7 +6,7 @@ module.exports = ({ method = 'get', params = {}, option = {} }) => {
 		format: 'xml',
 		outCharset: 'utf-8',
 		utf8: 1,
-		r: dayjs().valueOf(),
+		r: Date.now(),
 	});
 	const options = Object.assign(option, {
 		params: data,

package/module/apis/singers/getSingerStarNum.js

@@ -1,4 +1,3 @@
-const dayjs = require('dayjs');
 const y_common = require('../y_common');
 
 module.exports = ({ method = 'get', params = {}, option = {} }) => {
@@ -6,7 +5,7 @@ module.exports = ({ method = 'get', params = {}, option = {} }) => {
 		format: 'json',
 		outCharset: 'utf-8',
 		utf8: 1,
-		rnd: dayjs().valueOf(),
+		rnd: Date.now(),
 	});
 	const options = Object.assign(option, {
 		params: data,

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@sansenjian/qq-music-api",
-  "version": "2.0.5",
+  "version": "2.1.1",
   "publishConfig": {
     "access": "public"
   },
   "description": "QQ Music API - QQ音乐API koa2实现",
   "main": "index.js",
   "scripts": {
-    "dev": "nodemon app.js & npm run docs",
+    "dev": "nodemon app.js & npm run docs:dev",
     "start": "node app.js",
-    "docs": "docsify serve docs -p 9611",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:verbose": "jest --verbose",
+    "docs:dev": "vitepress dev docs --port 9611",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
     "commit-push": "./scripts/commit-push.sh",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
     "eslint": "eslint --fix --color module/**/** routers/**/** util/**/**",
@@ -43,11 +49,11 @@
     ]
   },
   "dependencies": {
-    "@koa/router": "^12.0.0",
-    "axios": "^1.6.0",
-    "dayjs": "^1.11.10",
+    "@koa/router": "^15.3.1",
+    "axios": "^1.13.6",
+    "date-fns": "^4.1.0",
     "koa": "^2.15.0",
-    "koa-bodyparser": "^4.4.0",
+    "koa-bodyparser": "^4.4.1",
     "koa-static": "^5.0.0"
   },
   "devDependencies": {
@@ -56,20 +62,26 @@
     "@babel/register": "^7.23.0",
     "@commitlint/cli": "^18.0.0",
     "@commitlint/config-conventional": "^18.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/supertest": "^7.2.0",
     "chalk": "^4.1.0",
     "conventional-changelog-cli": "^4.0.0",
-    "docsify-cli": "^4.4.4",
-    "eslint": "^8.56.0",
+    "eslint": "^8.57.0",
     "eslint-config-standard": "^17.0.0",
     "eslint-plugin-import": "^2.29.0",
     "eslint-plugin-n": "^16.0.0",
     "eslint-plugin-promise": "^6.0.0",
     "husky": "^9.0.0",
+    "jest": "^30.2.0",
     "lint-staged": "^15.0.0",
-    "nodemon": "^3.0.0",
-    "prettier": "^3.0.0"
+    "nodemon": "^3.1.14",
+    "prettier": "^3.8.1",
+    "sinon": "^21.0.1",
+    "supertest": "^7.2.2",
+    "vitepress": "^1.6.4",
+    "vue": "^3.5.29"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   }
 }

package/routers/context/getMv.js

@@ -2,7 +2,7 @@ const { UCommon } = require('../../module');
 
 // area_id=15&version_id=7
 module.exports = async (ctx, next) => {
-	// BUGFIX: https://github.com/Rain120/qq-music-api/issues/16#issuecomment-638230301
+	// BUGFIX: https://github.com/sansenjian/qq-music-api/issues/16#issuecomment-638230301
 	const { area_id = 15, version_id = 7, limit = 20, page = 0 } = ctx.query;
 	const start = (+page ? +page - 1 : 0) * +limit;
 	const data = {

package/routers/context/getRanks.js

@@ -1,21 +1,34 @@
 const { UCommon } = require('../../module');
 const { commonParams } = require('../../module/config');
-const dayjs = require('dayjs');
-const isoWeek = require('dayjs/plugin/isoWeek');
-const isoWeekYear = require('dayjs/plugin/isoWeekYear');
-dayjs.extend(isoWeek);
-dayjs.extend(isoWeekYear);
+
+// 缓存 date-fns 模块（避免每次请求都导入）
+let dateFnsCache = null;
+async function getDateFns() {
+	if (!dateFnsCache) {
+		dateFnsCache = await import('date-fns');
+	}
+	return dateFnsCache;
+}
 
 module.exports = async (ctx, next) => {
-	// Desc: https://github.com/Rain120/qq-music-api/issues/14
+	// 异步加载 date-fns (ESM 模块，带缓存)
+	const { getISOWeekYear, getISOWeek, parseISO } = await getDateFns();
+	
+	// Desc: https://github.com/sansenjian/qq-music-api/issues/14
 	// 1. topId is useless
 	// 2. qq api period is change not YYYY-MM-DD
 	const topId = +ctx.query.topId || 4;
 	const num = +ctx.query.limit || 20;
 	const offset = +ctx.query.page || 0;
-	const date = ctx.query.period || dayjs();
-	const week = dayjs(date).isoWeek();
-	const isoWeekYearVal = dayjs(date).isoWeekYear();
+	// 支持日期格式：YYYY-MM-DD 或 ISO 8601 格式，无效时自动使用当前日期
+	// 使用 parseISO 确保日期字符串被解析为本地时间，避免 UTC 偏移问题
+	let date = ctx.query.period ? parseISO(ctx.query.period) : new Date();
+	// 验证日期是否有效，无效则使用当前日期
+	if (Number.isNaN(date.getTime())) {
+		date = new Date();
+	}
+	const week = getISOWeek(date);
+	const isoWeekYearVal = getISOWeekYear(date);
 	const period = `${isoWeekYearVal}_${week}`;
 
 	const data = {

package/routers/context/getSearchByKey.js

@@ -5,7 +5,8 @@ const { getSearchByKey } = require('../../module');
 // n：每页歌曲数量
 // catZhida: 0表示歌曲, 2表示歌手, 3表示专辑, 4, 5
 module.exports = async (ctx, next) => {
-	const { key: w, limit: n, page: p, catZhida, remoteplace = 'song' } = ctx.query;
+	const w = ctx.query.key || ctx.params.key;
+	const { limit: n, page: p, catZhida, remoteplace = 'song' } = ctx.query;
 	const props = {
 		method: 'get',
 		params: {

package/routers/context/getSongLists.js

@@ -10,7 +10,7 @@ const { songLists } = require('../../module');
  */
 module.exports = async (ctx, next) => {
 	const { limit = 20, page = 0, sortId = 5, categoryId = 10000000 } = ctx.query;
-	// BUGFIX: https://github.com/Rain120/qq-music-api/issues/16
+	// BUGFIX: https://github.com/sansenjian/qq-music-api/issues/16
 	const sin = +page * +limit;
 	const ein = +limit * (+page + 1) - 1;
 	const params = Object.assign({

package/routers/router.js

@@ -11,58 +11,72 @@ router.get('/downloadQQMusic', context.getDownloadQQMusic);
 
 router.get('/getHotkey', context.getHotKey);
 
-router.get('/getSearchByKey/:key?/:limit?/:page?/:catZhida?', context.getSearchByKey);
+// @deprecated Use query params instead: /getSearchByKey?key=xxx
+// Backward compatible: path param route
+router.get('/getSearchByKey/:key', context.getSearchByKey);
+router.get('/getSearchByKey', context.getSearchByKey);
 
 // search smartbox
-router.get('/getSmartbox/:key?', context.getSmartbox);
+// @deprecated Use query params instead: /getSmartbox?key=xxx
+// Backward compatible: path param route
+router.get('/getSmartbox/:key', context.getSmartbox);
+router.get('/getSmartbox', context.getSmartbox);
 
 // 1
 router.get('/getSongListCategories', context.getSongListCategories);
 
-router.get('/getSongLists/:page?/:limit?/:categoryId?/:sortId?', context.getSongLists);
+// @deprecated Use query params instead: /getSongLists?page=1&limit=20&categoryId=10000000&sortId=5
+// Backward compatible: positional params route
+router.get('/getSongLists/:page/:limit/:categoryId/:sortId', context.getSongLists);
+router.get('/getSongLists', context.getSongLists);
 
 router.post('/batchGetSongLists', context.batchGetSongLists);
 
 // getSongInfo
-router.get('/getSongInfo/:songmid?/:songid?', context.getSongInfo);
+// @deprecated Use query params instead: /getSongInfo?songmid=xxx
+// Backward compatible: path param route
+router.get('/getSongInfo/:songmid', context.getSongInfo);
+router.get('/getSongInfo', context.getSongInfo);
 router.post('/batchGetSongInfo', context.batchGetSongInfo);
 
 // 4
 // disstid=7011264340
-router.get('/getSongListDetail/:disstid?', context.getSongListDetail);
+// @deprecated Use query params instead: /getSongListDetail?disstid=xxx
+router.get('/getSongListDetail/:disstid', context.getSongListDetail);
+router.get('/getSongListDetail', context.getSongListDetail);
 
 // newDisk
-router.get('/getNewDisks/:page?/:limit?', context.getNewDisks);
+router.get('/getNewDisks', context.getNewDisks);
 
 // getMvByTag
 router.get('/getMvByTag', context.getMvByTag);
 
 // MV
 // area_id=15&version_id=7
-router.get('/getMv/:area_id?/:version_id?/:limit?/:page?', context.getMv);
+router.get('/getMv', context.getMv);
 
 // getSingerList
-router.get('/getSingerList/:area?/:sex?/:genre?/:index?/:page?', context.getSingerList);
+router.get('/getSingerList', context.getSingerList);
 
 // getSimilarSinger
 // singermid=0025NhlN2yWrP4
-router.get('/getSimilarSinger/:singermid?', context.getSimilarSinger);
+router.get('/getSimilarSinger', context.getSimilarSinger);
 
 // getSingerAlbum
 // singermid=0025NhlN2yWrP4
-router.get('/getSingerAlbum/:singermid?/:limit?/:page?', context.getSingerAlbum);
+router.get('/getSingerAlbum', context.getSingerAlbum);
 
-router.get('/getSingerHotsong/:singermid?/:limit?/:page?', context.getSingerHotsong);
+router.get('/getSingerHotsong', context.getSingerHotsong);
 
 /**
  * @description: getSingerMv
  * @param order: time(fan upload) || listen(singer all)
  */
-router.get('/getSingerMv/:singermid?/:limit?/:order?', context.getSingerMv);
+router.get('/getSingerMv', context.getSingerMv);
 
-router.get('/getSingerDesc/:singermid?', context.getSingerDesc);
+router.get('/getSingerDesc', context.getSingerDesc);
 
-router.get('/getSingerStarNum/:singermid?', context.getSingerStarNum);
+router.get('/getSingerStarNum', context.getSingerStarNum);
 
 // radio
 router.get('/getRadioLists', context.getRadioLists);
@@ -73,31 +87,37 @@ router.get('/getDigitalAlbumLists', context.getDigitalAlbumLists);
 // music
 // getLyric
 // songmid=003rJSwm3TechU
-router.get('/getLyric/:songmid?/:isFormat?', context.getLyric);
+// @deprecated Use query params instead: /getLyric?songmid=xxx
+// Backward compatible: path param route
+router.get('/getLyric/:songmid', context.getLyric);
+router.get('/getLyric', context.getLyric);
 
 // songmid=003rJSwm3TechU
-router.get('/getMusicPlay/:songmid?', context.getMusicPlay);
+// @deprecated Use query params instead: /getMusicPlay?songmid=xxx
+// Backward compatible: path param route
+router.get('/getMusicPlay/:songmid', context.getMusicPlay);
+router.get('/getMusicPlay', context.getMusicPlay);
 
 // album
 // albummid=0016l2F430zMux
-router.get('/getAlbumInfo/:albummid?', context.getAlbumInfo);
+// @deprecated Use query params instead: /getAlbumInfo?albummid=xxx
+// Backward compatible: path param route
+router.get('/getAlbumInfo/:albummid', context.getAlbumInfo);
+router.get('/getAlbumInfo', context.getAlbumInfo);
 
-router.get(
-	'/getComments/:id?/:rootcommentid?/:cid?/:pagesize?/:pagenum?/:cmd?/:reqtype?/:biztype?',
-	context.getComments,
-);
+router.get('/getComments', context.getComments);
 
 // recommend
 router.get('/getRecommend', context.getRecommend);
 
 // mv play
-router.get('/getMvPlay/:vid?', context.getMvPlay);
+router.get('/getMvPlay', context.getMvPlay);
 
 // rankList: getTopLists
 router.get('/getTopLists', context.getTopLists);
 
 // ranks
-router.get('/getRanks/:topId?/:limit?/:page?', context.getRanks);
+router.get('/getRanks', context.getRanks);
 
 // ticket
 router.get('/getTicketInfo', context.getTicketInfo);

package/tests/integration/api/api.test.js

@@ -0,0 +1,116 @@
+const request = require('supertest');
+const Koa = require('koa');
+const bodyParser = require('koa-bodyparser');
+const router = require('../../../routers/router');
+const cors = require('../../../middlewares/koa-cors');
+
+jest.mock('axios', () => {
+	const mockFn = jest.fn().mockResolvedValue({ data: { code: 0, data: {} } });
+	return {
+		get: mockFn,
+		post: mockFn,
+		GET: mockFn,
+		POST: mockFn,
+		defaults: {
+			withCredentials: true,
+			timeout: 10000,
+			headers: { post: {} },
+			responseType: 'json',
+		},
+	};
+});
+
+const axios = require('axios');
+
+function createTestApp() {
+	const app = new Koa();
+	app.use(cors());
+	app.use(bodyParser());
+	app.use(router.routes());
+	app.use(router.allowedMethods());
+	return app;
+}
+
+describe('API Integration Tests', () => {
+	let app;
+	let callback;
+
+	beforeAll(() => {
+		app = createTestApp();
+		callback = app.callback();
+	});
+
+	beforeEach(() => {
+		jest.clearAllMocks();
+		axios.get.mockResolvedValue({ data: { code: 0, data: {} } });
+		axios.post.mockResolvedValue({ data: { code: 0, data: {} } });
+		global.userInfo = { cookie: 'test_cookie=123' };
+	});
+
+	describe('GET /getHotkey', () => {
+		test('should return hot search keywords', async () => {
+			const response = await request(callback).get('/getHotkey').expect(200);
+			expect(response.body).toBeDefined();
+		}, 10000);
+	});
+
+	describe('GET /getTopLists', () => {
+		test('should return top lists', async () => {
+			const response = await request(callback).get('/getTopLists').expect(200);
+			expect(response.body).toBeDefined();
+		}, 10000);
+	});
+
+	describe('GET /getSearchByKey', () => {
+		test('should search with query param', async () => {
+			const response = await request(callback)
+				.get('/getSearchByKey')
+				.query({ key: 'test' })
+				.expect(200);
+			expect(response.body).toBeDefined();
+		}, 10000);
+
+		test('should search with path param (backward compatibility)', async () => {
+			const response = await request(callback).get('/getSearchByKey/test').expect(200);
+			expect(response.body).toBeDefined();
+		}, 10000);
+	});
+
+	describe('GET /getLyric', () => {
+		test('should return lyric with query param', async () => {
+			const response = await request(callback)
+				.get('/getLyric')
+				.query({ songmid: 'test123' })
+				.expect(200);
+			expect(response.body).toBeDefined();
+		}, 10000);
+	});
+
+	describe('POST /batchGetSongInfo', () => {
+		test('should batch get song info', async () => {
+			const response = await request(callback)
+				.post('/batchGetSongInfo')
+				.send({ songmids: 'test1,test2' })
+				.expect(200);
+			expect(response.body).toBeDefined();
+		}, 10000);
+	});
+
+	describe('Error handling', () => {
+		test('should return 404 for unknown route', async () => {
+			await request(callback).get('/unknown-route').expect(404);
+		});
+
+		test('should return 400 for missing search key', async () => {
+			const response = await request(callback).get('/getSearchByKey').expect(400);
+			expect(response.body.response).toBe('search key is null');
+		});
+	});
+
+	describe('CORS middleware', () => {
+		test('should set CORS headers', async () => {
+			const response = await request(callback).get('/getHotkey').expect(200);
+			expect(response.headers['access-control-allow-origin']).toBeDefined();
+		});
+	});
+});

package/tests/integration/middleware/cors.test.js

@@ -0,0 +1,37 @@
+const cors = require('../../../middlewares/koa-cors');
+
+describe('CORS Middleware', () => {
+  test('should set CORS headers', async () => {
+    const ctx = {
+      method: 'GET',
+      set: jest.fn(),
+      get: jest.fn().mockReturnValue('http://localhost:3000'),
+      vary: jest.fn(),
+      status: 200,
+      body: {}
+    };
+    const next = jest.fn().mockResolvedValue(undefined);
+
+    await cors()(ctx, next);
+
+    expect(ctx.set).toHaveBeenCalled();
+    expect(ctx.vary).toHaveBeenCalledWith('Origin');
+    expect(next).toHaveBeenCalled();
+  });
+
+  test('should handle preflight request', async () => {
+    const ctx = {
+      method: 'OPTIONS',
+      set: jest.fn(),
+      get: jest.fn().mockReturnValue('GET'),
+      vary: jest.fn(),
+      status: 200
+    };
+    const next = jest.fn().mockResolvedValue(undefined);
+
+    await cors()(ctx, next);
+
+    expect(ctx.status).toBe(204);
+    expect(ctx.set).toHaveBeenCalledWith('Access-Control-Allow-Methods', expect.any(String));
+  });
+});

package/tests/setup/jest.setup.js

@@ -0,0 +1,46 @@
+// Jest setup file
+// Global setup for all tests
+
+// Increase timeout for async operations
+jest.setTimeout(10000);
+
+// Mock console methods in tests to reduce noise
+global.console = {
+  ...console,
+  log: jest.fn(),
+  debug: jest.fn(),
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn()
+};
+
+// Global test utilities
+global.testUtils = {
+  // Generate random string
+  randomString: (length = 10) => {
+    return Math.random().toString(36).substring(2, length + 2);
+  },
+
+  // Wait for specified milliseconds
+  sleep: (ms) => new Promise(resolve => setTimeout(resolve, ms)),
+
+  // Create mock response
+  mockResponse: (data = {}) => ({
+    status: 200,
+    data: data,
+    json: jest.fn().mockReturnValue(data)
+  }),
+
+  // Create mock request
+  mockRequest: (params = {}, query = {}, body = {}) => ({
+    params: params,
+    query: query,
+    body: body,
+    headers: {}
+  })
+};
+
+// Clean up after each test
+afterEach(() => {
+  jest.clearAllMocks();
+});

package/tests/setup/testUtils.js

@@ -0,0 +1,106 @@
+/**
+ * Test utilities for QQ Music API tests
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Load test fixture from file
+ * @param {string} fixtureName - Name of the fixture file
+ * @returns {any} Parsed fixture data
+ */
+function loadFixture(fixtureName) {
+  const fixturePath = path.join(__dirname, 'fixtures', fixtureName);
+  const data = fs.readFileSync(fixturePath, 'utf8');
+  return JSON.parse(data);
+}
+
+/**
+ * Create a mock Koa context
+ * @param {Object} options - Context options
+ * @returns {Object} Mock context
+ */
+function createMockContext(options = {}) {
+  const {
+    params = {},
+    query = {},
+    body = {},
+    headers = {},
+    method = 'GET'
+  } = options;
+
+  return {
+    params,
+    query,
+    request: {
+      body,
+      headers,
+      method
+    },
+    body: null,
+    status: 200,
+    set: jest.fn(),
+    get: jest.fn()
+  };
+}
+
+/**
+ * Create a mock next function
+ * @returns {Function} Mock next function
+ */
+function createMockNext() {
+  return jest.fn().mockResolvedValue(undefined);
+}
+
+/**
+ * Wait for async operations
+ * @param {number} ms - Milliseconds to wait
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Generate random string
+ * @param {number} length - Length of string
+ * @returns {string} Random string
+ */
+function randomString(length = 10) {
+  return Math.random().toString(36).substring(2, length + 2);
+}
+
+/**
+ * Generate random integer
+ * @param {number} min - Minimum value
+ * @param {number} max - Maximum value
+ * @returns {number} Random integer
+ */
+function randomInt(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Assert that response has correct structure
+ * @param {Object} response - Response object
+ * @param {number} expectedStatus - Expected status code
+ */
+function assertResponseStructure(response, expectedStatus = 200) {
+  expect(response).toBeDefined();
+  expect(response.status).toBe(expectedStatus);
+  if (expectedStatus === 200) {
+    expect(response.body).toBeDefined();
+    expect(response.body.code).toBeDefined();
+  }
+}
+
+module.exports = {
+  loadFixture,
+  createMockContext,
+  createMockNext,
+  sleep,
+  randomString,
+  randomInt,
+  assertResponseStructure
+};

package/tests/unit/util/lyricParse.test.js

@@ -0,0 +1,97 @@
+const { lyricParse, Lyric } = require('../../../util/lyricParse');
+
+describe('lyricParse', () => {
+	describe('Lyric class', () => {
+		test('should parse simple lyric', () => {
+			const lyricString = `[ti:Song Title]
+[ar:Artist Name]
+[al:Album Name]
+[00:01.00]First line
+[00:05.00]Second line
+[00:10.00]Third line`;
+
+			const result = lyricParse(lyricString);
+
+			expect(result).toBeInstanceOf(Lyric);
+			expect(result.tags.title).toBe('Song Title');
+			expect(result.tags.artist).toBe('Artist Name');
+			expect(result.tags.album).toBe('Album Name');
+			expect(result.lines).toHaveLength(3);
+		});
+
+		test('should parse time correctly', () => {
+			const lyricString = `[00:01.50]Test line`;
+			const result = lyricParse(lyricString);
+
+			expect(result.lines[0].time).toBe(1500);
+			expect(result.lines[0].txt).toBe('Test line');
+		});
+
+		test('should parse time with milliseconds', () => {
+			const lyricString = `[01:23.45]Test line`;
+			const result = lyricParse(lyricString);
+
+			expect(result.lines[0].time).toBe(83450);
+		});
+
+		test('should handle empty lyric', () => {
+			const result = lyricParse('');
+
+			expect(result.lines).toHaveLength(0);
+			expect(result.tags.title).toBe('');
+			expect(result.tags.artist).toBe('');
+		});
+
+		test('should sort lines by time', () => {
+			const lyricString = `[00:10.00]Third
+[00:01.00]First
+[00:05.00]Second`;
+			const result = lyricParse(lyricString);
+
+			expect(result.lines[0].txt).toBe('First');
+			expect(result.lines[1].txt).toBe('Second');
+			expect(result.lines[2].txt).toBe('Third');
+		});
+
+		test('should ignore empty lines', () => {
+			const lyricString = `[00:01.00]Line 1
+[00:05.00]
+[00:10.00]Line 2`;
+			const result = lyricParse(lyricString);
+
+			expect(result.lines).toHaveLength(2);
+		});
+
+		test('should handle special characters', () => {
+			const lyricString = `[00:01.00]测试中文 🎵 Special!@#$%`;
+			const result = lyricParse(lyricString);
+
+			expect(result.lines[0].txt).toBe('测试中文 🎵 Special!@#$%');
+		});
+
+		test('should parse offset tag', () => {
+			const lyricString = `[offset:500]
+[00:01.00]Test`;
+			const result = lyricParse(lyricString);
+
+			expect(result.tags.offset).toBe('500');
+		});
+
+		test('should parse by tag', () => {
+			const lyricString = `[by:Lyric Creator]
+[00:01.00]Test`;
+			const result = lyricParse(lyricString);
+
+			expect(result.tags.by).toBe('Lyric Creator');
+		});
+
+		test('should handle multiple time stamps in one line', () => {
+			const lyricString = `[00:01.00][00:05.00]Repeated line`;
+			const result = lyricParse(lyricString);
+
+			expect(result.lines).toHaveLength(2);
+			expect(result.lines[0].time).toBe(1000);
+			expect(result.lines[1].time).toBe(5000);
+		});
+	});
+});

package/tests/unit/util/request.test.js

@@ -0,0 +1,66 @@
+const request = require('../../../util/request');
+
+jest.mock('axios', () => {
+	const mockAxios = {
+		GET: jest.fn(),
+		POST: jest.fn(),
+		get: jest.fn(),
+		post: jest.fn(),
+		defaults: {
+			withCredentials: true,
+			timeout: 10000,
+			headers: {
+				post: {},
+			},
+			responseType: 'json',
+		},
+	};
+	return mockAxios;
+});
+
+const axios = require('axios');
+
+describe('request util', () => {
+	beforeEach(() => {
+		jest.clearAllMocks();
+		global.userInfo = { cookie: 'test_cookie=123' };
+	});
+
+	afterEach(() => {
+		delete global.userInfo;
+	});
+
+	test('should make GET request', async () => {
+		const mockData = { code: 0, data: {} };
+		axios.GET.mockResolvedValue({ data: mockData });
+
+		const result = await request('/api/test', 'GET');
+
+		expect(axios.GET).toHaveBeenCalled();
+	});
+
+	test('should handle request error', async () => {
+		const error = new Error('Network Error');
+		axios.GET.mockRejectedValue(error);
+
+		await expect(request('/api/test', 'GET')).rejects.toThrow();
+	});
+
+	test('should set correct headers', async () => {
+		axios.GET.mockResolvedValue({ data: {} });
+
+		await request('/api/test', 'GET', { headers: { 'Custom-Header': 'value' } });
+
+		const call = axios.GET.mock.calls[0][1];
+		expect(call.headers).toBeDefined();
+		expect(call.headers.cookies).toBe('test_cookie=123');
+	});
+
+	test('should handle timeout', async () => {
+		const error = new Error('Timeout');
+		error.code = 'ECONNABORTED';
+		axios.GET.mockRejectedValue(error);
+
+		await expect(request('/api/test', 'GET', { timeout: 5000 })).rejects.toThrow();
+	});
+});

package/util/lyricParse.js

@@ -34,16 +34,19 @@ class Lyric {
 	_initLines() {
 		const lines = this.lyric.split('\n');
 		for (let i = 0; i < lines.length; i++) {
-			const line = lines[i];
-			const result = timeExp.exec(line);
-			if (result) {
+			const line = lines[i].trim();
+			timeExp.lastIndex = 0;
+			const matches = [...line.matchAll(timeExp)];
+			if (matches.length > 0) {
 				const txt = line.replace(timeExp, '').trim();
-				const time = result[1] * 60 * 1000 + result[2] * 1000 + (result[3] || 0) * 10;
 				if (txt) {
-					this.lines.push({
-						time,
-						txt,
-					});
+					for (const result of matches) {
+						const time = result[1] * 60 * 1000 + result[2] * 1000 + (result[3] || 0) * 10;
+						this.lines.push({
+							time,
+							txt,
+						});
+					}
 				}
 			}
 		}