【免费下载链接】DroppedNeedle项目地址https://gitcode.com/gh_mirrors/mu/DroppedNeedle点击查看免费下载DroppedNeedle 是一款自托管音乐请求与资源发现系统搜索 MusicBrainz 目录、请求整张专辑或单曲由它驱动你自己的下载客户端slskd、SABnzbd完成下载、校验并入库再交给 Jellyfin、Navidrome、Plex 或本地文件播放。本文带你用一条最短路径搭建 DroppedNeedle 本地开发环境读懂它的测试体系并快速上手/api/v1/docsAPI 参考文档。一、本地开发环境搭建1. 先认清技术栈DroppedNeedle 是典型的前后端分离架构两套技术栈都要跑起来| 端 | 技术栈 | 目录 | |-|-|-| | 后端 | Python 3.13 / FastAPI / Pydantic / SQLite |backend/| | 前端 | Node.js 22 / SvelteKit / Svelte 5 / Tailwind CSS / daisyUI |frontend/|完整的前端依赖清单见 package.json后端依赖见 requirements.txtFastAPI 0.118.3、uvicorn、httpx、mutagen 等。2. 获取代码git clone https://gitcode.com/gh_mirrors/mu/DroppedNeedle项目根目录下的 Makefile 是开发的第一入口所有常用命令都封装成了 make 目标跑make help即可列出全部目标及说明。3. 启动后端uvicorn官方开发文档 CONTRIBUTING.md 给出的标准流程只有三步cd backend pip install -r requirements-dev.txt cp env.dev.example .env uvicorn target_main:app --reload --port 8688⚠️ 注意入口必须是target_main:app。旧入口main:app已在 F-NL-03 扫描切换中移除直接启动会抛出明确的报错提示——见 main.py 开头的注释说明。.env从 env.dev.example 复制而来开发态默认只包含两个开关ROOT_APP_DIR./app-dev DEBUGtrue4. 启动前端pnpmcd frontend cp env.development.example .env.development pnpm install pnpm run devenv.development.example 中只配置了一个变量PUBLIC_API_URLhttp://localhost:8688即前端指向本地后端的地址。pnpm run dev会启动 Vite 开发服务器并自动打开浏览器。两个终端并行运行后即可在本地完整体验这套请求 → 下载 → 入库 → 播放的系统。二、Makefile 命令速查日常开发 90% 的操作都在 Makefile 里。下面这几个目标覆盖最高频场景| 命令 | 作用 | |-|-| |make help| 列出全部目标与说明 | |make backend-venv| 创建并刷新后端虚拟环境自动装 requirements-dev.txt pytest | |make backend-lint| 用 Ruff 检查后端代码 | |make frontend-lint/make frontend-check/make frontend-format-check| 前端 ESLint、svelte-check 类型检查、Prettier 格式检查 | |make format| 一键自动格式化后端 Ruff --fix 前端 Prettier | |make rebuild| 重新构建应用 |Makefile 还按功能域拆出了上百个细分测试目标如backend-test-jellyfin、backend-test-subsonic-security、test-events等改哪块模块就跑哪个目标比全量测试快得多。三、测试体系全解析1. 后端pytest 分批全量 功能域细分make backend-test跑全部后端测试。实现上按每批 24 个测试文件分组执行避免单进程长时运行适合本地全量回归。细分目标按功能域精确运行例如make test-compatConnect Apps 兼容层全套Subsonic / Jellyfin 序列化、端点、流式、映射、错误处理见backend/tests/compat/目录make security-tests安全套件含日志不落密钥、认证矩阵、API key 掩码make e2e/make e2e-fast端到端套件mock 可选真实 slskd 容器fast 版本跳过真实容器测试目录组织清晰tests/routes/91 个路由测试、tests/services/259 个服务测试、tests/repositories/仓储层、tests/security/、tests/e2e/fixtures 集中在backend/tests/fixtures/含 musicbrainz、navidrome、lrclib 等 API 响应快照与 library/ 下的真实音频样本。2. 前端Vitest 双项目 Playwright前端测试用 Vitest 分为两个 projectmake frontend-test-server数据层SvelteKit server 项目无需浏览器make frontend-test-client组件与页面测试Chromium基于 Playwright vitest browser mode需先执行make frontend-browser-install安装浏览器make test后端全量 前端 server 套件是日常提交前最实用的组合3. CI 流水线完整 CI 由一个目标触发make ci等价于依次执行backend-lint→frontend-lint→frontend-check类型检查→frontend-format-check→backend-test→frontend-test-server→security-tests→e2e-fast→docs-check。提 PR 前本地跑通make ci基本可以确保远端 CI 绿灯。四、/api/v1/docs API 参考速览1. 三个文档地址DroppedNeedle 在启动时直接暴露完整的 Swagger UI见 target_application.py 中的 FastAPI 实例配置| 地址 | 内容 | |-|-| |/api/v1/docs| Swagger UI交互式可在线 Try it out | |/api/v1/redoc| ReDoc 风格的只读文档 | |/api/v1/openapi.json| OpenAPI 规范原始 JSON |2. 认证与权限模型所有/api/v1/*路由接受Bearer token 或会话 Cookie两种凭据其中/api/v1/settings/*额外要求 Admin 角色/health保持公开供容器健康检查。登录、OIDC / Jellyfin / Plex / Spotify 回调与 OpenAPI 规范属于少数公开路径见 middleware.py 中的_PUBLIC_PATHS与_PUBLIC_PREFIXES。3. 路由模块地图全部 55 个路由模块按功能域组织在 backend/api/v1/routes/ 下在 Swagger UI 中对应的分组| 功能域 | 主要模块 | |-|-| | 认证与账户 |auth、profile、me_connections、plex_auth| | 目录与搜索 |search、albums、artists、tracks、discover、home| | 请求与下载 |requests、downloads、download、download_clients、indexers、quarantine、free_music| | 库管理 |library_target、library_management、library_operations_target、library_contributions、import_drop| | 播放与播放列表 |stream、playlists、now_playing、covers、jellyfin_library、navidrome_library、plex_library| | 社交与个性化 |following、scrobble、lastfm、spotify、youtube、wrapped| | 系统与设置 |settings、status、system、version、cache、plugins、connect_apps_routes|五、核心模块导航| 内容 | 路径 | |-|-| | 开发规范与本地运行说明 | CONTRIBUTING.md | | 全部开发命令 | Makefile | | 应用入口生产 target | backend/target_main.py | | FastAPI 装配与中间件栈 | backend/target_application.py | | 速率限制 / 认证公开路径 | backend/middleware.py | | API v1 路由 | backend/api/v1/routes/ | | API v1 请求/响应模型 | backend/api/v1/schemas/ | | 依赖注入装配 | backend/core/dependencies/ | | 后端测试 | backend/tests/ | | 开发态 Docker 编排 | docker-compose.dev.yml | | 前端环境变量示例 | frontend/env.development.example | | 插件契约 | PLUGINS.md | | 插件开发教程 | docs/PLUGIN-CREATION.md |六、代码风格与 PR 流程后端强类型、async/await异步上下文中禁止阻塞 I/O用 Ruff 做检查与格式化。前端严格 TypeScript禁用any统一具名导出只使用 async/await颜色一律用既有设计 tokenprimary、secondary等不要硬编码。PR 流程从main切出描述性分支如fix-scrobble-timing修 Bug 时在描述里带上 issue 号提交前确保测试通过一个 PR 只解决一件事如使用了 AI 工具辅助写码请在 PR 中注明。规则原文见 CONTRIBUTING.md。七、上手清单git clone后先make help熟悉全部命令起两个终端uvicorn target_main:app --reload --port 8688pnpm run dev提交前跑make testCI 前跑make ci打开http://localhost:8688/api/v1/docs用 Swagger UI 边调试边写代码祝编码愉快欢迎向 DroppedNeedle 提交你的第一个 PR赞分享【免费下载链接】DroppedNeedle项目地址https://gitcode.com/gh_mirrors/mu/DroppedNeedle点击查看免费下载相关推荐Tianshou 开发者指南从环境搭建、测试体系到 High-Level API 扩展与版本发布Tianshou 开发者指南从环境搭建、测试体系到 High Level API 扩展与版本发布 导读 本文面向希望参与 Tianshou 开发的贡献者与维护人工智能机器学习深度学习强化学习WeKnora 开发指南本地开发环境搭建、构建测试体系与调试实战WeKnora 开发指南本地开发环境搭建、构建测试体系与调试实战 WeKnora 是一个由 Go 后端、Python docreader 文档解析服务与 Vu人工智能大模型RAGAI Agent后端前端MCP 服务知识库dsh-plugin工具调用Dify 后端 API 开发指南从 uv 环境搭建、本地联调到 Celery 任务与测试体系Dify 后端 API 开发指南从 uv 环境搭建、本地联调到 Celery 任务与测试体系 本文基于 Dify 仓库中 api/README.md http人工智能大模型LLMOpsAI 应用RAGAI Agent低代码创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考