音视频后端前端【免费下载链接】koelMusic streaming solution that works.项目地址https://gitcode.com/gh_mirrors/ko/koel点击查看免费下载本文以仓库 .junie/guidelines.mdLaravel Boost Guidelines为骨架逐条解读这份由 Laravel 维护者为本仓库定制的 AI 辅助开发规范并结合 Koel 的实际源码、配置与测试用例composer.json、bootstrap/app.php、app/Models/Artist.php、tests/ 等验证其落地情况。读完本文你将掌握Koel 的技术栈基线、遵循的 Laravel 12/13 应用结构约定、PHP 与测试的强制编码规范、Tailwind CSS v4 的前端样式约定以及 Boost 工具与测试命令的正确用法。一、指南是什么Laravel Boost Guidelines 的定位.junie/guidelines.md是一份被设计为 AI 编码助手Agent在 Koel 仓库内写代码时必须遵守的项目级开发规范全称为 Laravel Boost Guidelines。文件顶部明确说明这份指南由Laravel 维护者专门为本应用挑选curated并强调应该被严格遵守以提升用户构建 Laravel 应用的满意度。整份指南采用laravel-boost-guidelines包裹内部按foundation rules、boost rules、php rules、tests rules、laravel/core rules、laravel/v12 rules、phpunit/core rules、tailwindcss/core rules、tailwindcss/v4 rules九个区块组织。它不是一篇零散笔记而是一份层次分明、可直接执行的技术约束清单既有版本基线也有命令、代码示例和可替换的工具类名映射表。与之配套的是 .junie/mcp/mcp.json 中声明的 MCP 配置——Laravel Boost 以一个 MCP 服务器形态存在为 Agent 提供list-artisan-commands、tinker、database-query、browser-logs、search-docs等专用工具。换言之这份规范不仅是给人看的代码风格文档更是给 LLM/AI 工具驱动这个 Laravel 应用的操作手册。二、技术栈基线指南声明与仓库实际的版本对照指南在 Foundational Context 一节列出了本应用依赖的 PHP 与 Laravel 生态版本清单并声明必须以这些具体包与版本为准组件指南声明版本仓库实际约束composer.json / package.jsonPHP8.4.208.3composer 平台锁定8.3.0laravel/frameworkv12^13.0laravel/nightwatchv1^1.13laravel/promptsv0^0.3.6laravel/sanctumv4^4.0laravel/scoutv10^11.0laravel/socialitev5^5.12larastan/larastanv3^3.7phpunit/phpunitv11^11.0vuev3^3.5.29laravel-echov2^2.1.6laravel/echo-vue亦为^2.1.6tailwindcssv4^4.3.0含tailwindcss/vite^4.3.0需要说明的是指南中 Laravel 框架标注为 v12而当前仓库的 composer.json 已将laravel/framework提升至^13.0、laravel/scout提升至^11.0。指南中关于Laravel 12 结构的说明中间件声明式注册、bootstrap/app.php为注册中枢等在 Laravel 13 下依然成立且被仓库严格遵循因此本文以当前仓库实际内容为准展开版本差异仅作为对照信息呈现。其余组件版本与指南基本吻合Sanctum v4、Socialite v5、PHPUnit v11、Vue 3、Tailwind CSS v4 均与声明一致。三、通用约定命名、复用与验证Conventions 一节给出了四条适用于所有代码改动的基础规则遵循既有代码约定创建或编辑文件时先查看同级文件以确定正确的结构、写法和命名。Koel 的 app/Http/Requests/ 目录即典型例子——所有表单请求按 API / Download / Subsonic 分组存放新增校验类时应遵循该分组模式。描述性命名使用描述性的变量与方法名例如isRegisteredForDiscounts而非discount。优先复用动手写新组件前先检查是否已有可复用组件。验证脚本纪律不要为了验证而创建一次性脚本或使用 tinker 去验证已有测试覆盖的功能单元测试与功能测试的优先级更高。此外还有三条治理性规则目录结构坚持既有目录结构未经批准不得新建顶层基础目录。依赖变更未经批准不得改动应用依赖。回复风格解释保持简洁聚焦重点不赘述显而易见的内容。文档文件仅在用户明确要求时才创建文档文件。这些规则共同塑造了可审计、可测试、最小改动的工程约束与 Koel 庞大的 tests/ 测试树Feature、Integration、Unit 三层所体现的测试优先文化一致。四、应用结构与架构Laravel 12/13 的声明式组织方式指南的laravel/v12 rules区块专门说明了新版 Laravel 的精简目录结构Koel 仓库是这一结构的忠实体现4.1 中间件不再注册在app/Http/Kernel.php自 Laravel 11 起app/Http/Kernel.php已被移除中间件改为在 bootstrap/app.php 中通过Application::configure()-withMiddleware()声明式注册。Koel 的实际写法印证了这一点return Application::configure(basePath: dirname(__DIR__)) -withRouting( using: static function (): void { RouteServiceProvider::loadVersionAwareRoutes(web); RouteServiceProvider::loadVersionAwareRoutes(api); Route::middleware(api)-group(base_path(routes/subsonic.php)); }, commands: __DIR__ . /../routes/console.php, channels: __DIR__ . /../routes/channels.php, health: /up, ) -withMiddleware(static function (Middleware $middleware): void { $middleware-api(prepend: [AddRequestContextForLogging::class]); $middleware-web(prepend: [AddRequestContextForLogging::class]); $middleware-api(append: [ RestrictPlusFeatures::class, HandleDemoMode::class, ForceHttps::class, ]); $middleware-web(append: [ RestrictPlusFeatures::class, HandleDemoMode::class, ForceHttps::class, ]); $middleware-alias([ audio.auth AuthenticateAudioRequests::class, os.auth ObjectStorageAuthenticate::class, embeds.enabled EnsureEmbedsEnabled::class, ]); // Koel is an SPA without a login route, so the Authenticate middleware would // otherwise throw RouteNotFoundException when resolving route(login) on guests. $middleware-redirectGuestsTo(/); }) -withExceptions(/* ... */) -create();可以看到 bootstrap/app.php 同时承担了路由注册、中间件注册、异常渲染三件事路由通过RouteServiceProvider::loadVersionAwareRoutes()加载web/api两个版本化路由文件并挂载routes/subsonic.phpwithMiddleware中既按组api/web前后追加中间件也通过alias注册audio.auth、os.auth、embeds.enabled等具名中间件withExceptions则自定义了AuthenticationException的 JSON/重定向响应并接入SubsonicAwareErrorRenderer。4.2 服务提供者集中登记在bootstrap/providers.php指南指出bootstrap/providers.php存放应用特有的服务提供者。仓库中的 bootstrap/providers.php 列出了一串 Koel 特有的提供者AppServiceProvider、AuthServiceProvider、SongStorageServiceProvider、StreamerServiceProvider、ObjectStorageServiceProvider、LicenseServiceProvider、SocialiteServiceProvider等并前置注册了第三方提供者ImageServiceProvider、ScoutServiceProvider、AuditingServiceProvider、TNTSearchScoutServiceProvider。4.3 控制台配置的迁移指南明确app/Console/Kernel.php已不存在控制台配置改用bootstrap/app.php或routes/console.php且 app/Console/Commands/ 下的命令自动被发现、无需手动注册。Koel 的routes/console.php正是被withRouting(commands: ...)显式挂载的而ScanCommand、InitCommand、DoctorCommand、CollectTagsCommand、FetchArtworkCommand等二十余个命令均放在命令目录中自动生效。4.4 数据库与模型指南在laravel/v12 rules中还强调了两条模型层规则迁移必须保留列的既有属性修改列时迁移需包含该列此前定义的全部属性否则这些属性会被丢弃。Koel 的迁移历史如 database/migrations/2024_01_16_215642_use_uuids_for_playlists.php、2025_07_20_165224_migrate_foreign_keys_to_ulid.php展示了这种逐步改写列定义、保留语义的谨慎迁移风格。Casts 用casts()方法而非$casts属性指南建议在模型上通过casts()方法定义类型转换并遵循既有模型的惯例。这一约定在 Koel 中执行得非常彻底——app/Models/ 下全部 16 个模型都采用casts()方法。例如 app/Models/Artist.php/** inheritDoc */ protected function casts(): array { return [ favorite boolean, favorited_at datetime, ]; }五、Laravel Boost面向本应用的 MCP 工具集指南的boost rules区块介绍了 Boost MCP 服务器为 Agent 提供的专属工具并要求优先使用它们list-artisan-commands需要调用 Artisan 命令前先用它核对可用参数指南要求所有 Artisan 调用都带--no-interaction并补全正确的--options确保无人值守可运行。get-absolute-url向用户分享项目 URL 时用它确认 scheme、域名/IP 与端口正确。tinker需要执行 PHP 调试代码或直接查询 Eloquent 模型时使用如果只是读取数据库则改用database-query工具。browser-logs读取浏览器日志、错误与异常但只有最近的日志有价值应忽略旧日志。search-docs重点处理任何 Laravel 或 Laravel 生态包Laravel、Inertia、Livewire、Filament、Tailwind、Pest、Nova、Nightwatch 等时必须先于其他途径使用它。该工具会把已安装的包列表与版本自动传给远端 Boost API从而只返回与当前环境匹配的版本化文档可传入包名数组做过滤。search-docs的搜索语法支持多种形式简单词搜索自动词干authentication可命中authenticate与auth。多词 AND 逻辑rate limit要求同时包含rate与limit。精确短语infinite scroll要求词相邻且顺序一致。混合查询middleware rate limit表示middleware与精确短语rate limit。多查询[authentication, middleware]任一命中即可。指南建议以宽泛、简单、主题化的多个查询起步如[rate limiting, routing rate limiting, routing]且不要在查询中加入包名包信息已自动共享例如应写test resource table而非filament 4 test resource table。这与 Koel 使用大量 Laravel 生态包Scout 全文搜索、Sanctum API 认证、Socialite SSO、laravel-echo 实时广播、Auditing 审计日志等的现实高度匹配——正确查询版本化文档是安全改动的第一步。六、PHP 编码规则类型、注释与枚举php rules区块给出了强制性的 PHP 风格约束Koel 源码中处处可见其落实6.1 控制结构与构造器所有控制结构必须使用花括号即使只有一行。构造函数使用PHP 8 构造器属性提升constructor property promotion且不允许出现零参数的空__construct()除非构造器是 privatepublic function __construct(public GitHub $github) { }6.2 显式类型声明方法与函数必须显式声明返回类型参数要使用恰当的类型提示。指南给出的范例protected function isAccessible(User $user, ?string $path null): bool { ... }Koel 的模型、Builder、Repository 几乎全部遵循此风格如 app/Models/Artist.php 中的public static function getOrCreate(User $user, ?string $name null): self以及每个 Eloquent 关系方法都带返回类型albums(): HasMany、songs(): HasMany、user(): BelongsTo。6.3 注释与 PHPDoc优先使用 PHPDoc 块而非行内注释除非逻辑非常复杂否则不要在代码内部写注释数组场景下应添加有用的 array shape 类型定义。Koel 的模型注释即典型如property Collectionarray-key, Song $songs。6.4 枚举命名枚举的键case 名一般使用 TitleCase例如FavoritePerson、BestLake、Monthly。Koel 的 app/Enums/ 下如SongStorageType、ScanResultType、SmartPlaylistModel等枚举均遵循该命名法。七、测试规则PHPUnit 与最小化运行7.1 强制测试tests rules区块的硬性要求每次改动都必须有程序化测试——写新测试或更新既有测试并运行确认通过。Koel 的测试体系完全按此组织tests/Feature/HTTP 层、命令、KoelPlus 等、tests/Integration/服务、迁移、观察者、tests/Unit/AI、模型、管道、值对象。指南同时给出成本控制手段运行保证代码质量所需的最少测试并推荐php artisan test --compact配合指定文件名或过滤器。7.2 PHPUnit 专属规则phpunit/core rules本应用使用PHPUnit所有测试必须以 PHPUnit 类编写用php artisan make:test --phpunit {name}创建若遇到 Pest 风格测试需转换为 PHPUnit。每次更新测试后运行该单一测试相关功能测试全部通过后询问用户是否需要运行整个测试套件。测试须覆盖 happy path、failure path 与 edge/weird path 三类路径。未经批准不得删除 tests 目录中的任何测试文件——这些是应用的核心资产而非临时文件。Faker 使用遵循既有惯例$this-faker-word()或fake()-randomDigit()。创建测试模型时优先使用工厂database/factories/ 提供 AlbumFactory、SongFactory、PlaylistFactory 等 20 余个工厂并先检查工厂是否有可用的自定义状态。7.3 测试运行命令场景命令运行全部测试php artisan test --compact运行单个文件php artisan test --compact tests/Feature/ExampleTest.php按名称过滤php artisan test --compact --filtertestName改动相关文件后的推荐方式八、Laravel Core 规则以 Eloquent 为中心的开发方式laravel/core rules是覆盖面最广的区块定义了Laravel 之道数据库与模型始终使用带返回类型提示的 Eloquent 关系方法优先于原生查询或手写 join用Model::query()而非DB::不绕过 ORM。用 eager loading 预防 N1 查询问题仅对非常复杂的数据库操作使用查询构造器。创建新模型时同时创建有用的工厂与 seeder并用list-artisan-commands核对php artisan make:model的可用选项。API 与资源默认使用 Eloquent API Resources 与 API 版本化除非既有 API 路由未采用——此时遵循应用既有约定。Koel 的RouteServiceProvider::loadVersionAwareRoutes(api)正是版本化路由的落地实现。控制器与校验校验必须放在Form Request类中而非控制器内联并同时包含校验规则与自定义错误消息。写新 Form Request 前检查同级请求app/Http/Requests/确认应用采用数组式还是字符串式规则。Koel 的 104 个请求类API/、Download/、Subsonic/ 分组均遵循此约定。队列、认证与授权耗时操作使用实现ShouldQueue接口的队列任务如 app/Jobs/ 下的HandleSongUploadJob、ScrobbleJob、GenerateAlbumThumbnailJob。使用 Laravel 内置的认证与授权能力gates、policies、Sanctum 等。Koel 在 app/Policies/ 下为 12 个实体各建了 Policy并用 Sanctum 做 API 认证。URL 与配置页面链接优先使用命名路由与route()函数。环境变量只允许出现在配置文件里禁止在配置文件之外调用env()一律使用config(app.name)而非env(APP_NAME)。测试用php artisan make:test [options] {name}创建功能测试大多数测试应为功能测试加--unit创建单元测试。九、前端构建与调试Tailwind v4 与 Vite9.1 前端打包指南在 Frontend Bundling 中指出用户看不到前端变更时通常需要运行pnpm run build、pnpm run dev或composer run dev。结合仓库实际package.json、composer.jsonpnpm run build实际执行vp build pnpm run build:sw构建应用 通过vite.config.sw.js生成 Service Worker。pnpm run dev在 package.json 中已被移除运行它会得到提示Usecomposer devinstead.。composer run dev才是本地开发命令它用 concurrently 同时启动php artisan serve、php artisan queue:listen --tries1与vp devVite 开发服务器并关闭进程超时限制。9.2 Vite manifest 错误遇到Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest时先运行pnpm run build或请用户运行pnpm run dev/composer run dev生成/刷新 manifest。9.3 Tailwind CSS v4 规则tailwindcss/core rulestailwindcss/v4 rules样式一律使用 Tailwind 类并先检查项目内既有约定再自行书写重复模式可抽取为符合项目惯例的组件Blade、JSX、Vue 等。注意类名放置、顺序、优先级与默认值去掉冗余类谨慎地把类加到父/子元素以控制重复并按逻辑分组元素。间距列表项间距用gap工具类而非 margindiv classflex gap-8 divSuperior/div divMichigan/div divErie/div /div暗色模式既有页面支持暗色模式时新页面必须用同样的方式通常为dark:支持。Tailwind CSS v4 的专属约束包括始终使用 v4不使用已废弃的工具类。corePlugins在 v4 中不受支持。v4 配置是CSS-first的用theme指令无需独立的tailwind.config.jstheme { --color-brand: oklch(0.72 0.11 178); }v4 通过普通 CSSimport引入 Tailwind而非 v3 的tailwind指令- tailwind base; - tailwind components; - tailwind utilities; import tailwindcss;从 Koel 的实际配置看package.json 已采用tailwindcss ^4.3.0与tailwindcss/vite ^4.3.0仓库仍保留的 tailwind.config.js 内容被显著精简——主要声明content扫描路径resources/assets/js/**/*.{vue,js,ts,jsx,tsx}并将颜色、间距、动画等映射到CSS 变量如k-fg: var(--color-fg)、k-header-height: var(--header-height)。从源码结构可以推断Koel 的主题系统由 CSS 变量驱动配合 app/Values/Theme/ 与 themes 迁移v4 的 CSS-first 配置方式与其自洽。9.4 已废弃工具类的替换表v4Tailwind v4 移除了大量废弃工具类指南给出了完整的替换映射改动样式时必须使用替代品不透明度数值仍为数字已废弃替代bg-opacity-*bg-black/*text-opacity-*text-black/*border-opacity-*border-black/*divide-opacity-*divide-black/*ring-opacity-*ring-black/*placeholder-opacity-*placeholder-black/*flex-shrink-*shrink-*flex-grow-*grow-*overflow-ellipsistext-ellipsisdecoration-slicebox-decoration-slicedecoration-clonebox-decoration-clone十、规范在仓库中的落地核查与注意事项将指南逐条与 Koel 源码对照可以得到一份规范执行度清单规范条目仓库证据执行情况中间件声明式注册于bootstrap/app.phpbootstrap/app.php 中withMiddleware/withExceptions/withRouting链式配置完全一致服务提供者登记于bootstrap/providers.phpbootstrap/providers.php 列出 16 个应用提供者完全一致控制台命令自动发现app/Console/Commands/ 下 20 命令无 Kernel 注册完全一致模型使用casts()方法app/Models/ 全部 16 个模型均采用casts()完全一致校验放入 Form Requestapp/Http/Requests/ 104 个请求类完全一致关系方法带返回类型app/Models/Artist.php 等完全一致用 Policy / Sanctum 做授权认证app/Policies/、app/Http/Middleware/完全一致配置用config()而非env()config/ 下 25 个配置文件一致Tailwind v4package.jsontailwindcss ^4.3.0一致指南版本基线composer.jsonLaravel 框架实际已升至^13.0、Scout^11.0其余吻合使用这份规范时有两点需特别注意版本基线以仓库为准指南头部声明的 Laravel v12 / Scout v10 是编写指南时的基线当前 composer.json 已升级到 Laravel 13 / Scout 11。指南中关于结构、命名、测试的所有规则在 Laravel 13 下依然有效但涉及具体版本特性时应依据composer.json、package.json与composer.lock的实际锁定版本行事。开发命令以仓库为准pnpm run dev已被移除统一使用composer run dev构建仍用pnpm run build含 Service Worker 生成。结语.junie/guidelines.md的价值不在于罗列教条而在于它把 Koel 这一大型 Laravel 音乐流媒体项目数百个模型、控制器、请求类与测试背后可复制的工程纪律沉淀成了显式规则从 Eloquent 优先的数据库哲学到bootstrap/app.php的声明式结构再到 PHPUnit 最小化测试与 Tailwind v4 的 CSS-first 配置。对希望在 Koel 之上做二次开发、或想借鉴其 Laravel 工程规范的开发者而言这份指南加上仓库源码的相互印证就是最可靠的学习与执行依据。赞分享音视频后端前端【免费下载链接】koelMusic streaming solution that works.项目地址https://gitcode.com/gh_mirrors/ko/koel点击查看免费下载相关推荐Koel 前端工程实践指南Vue 3 TypeScript 下的组件、表单与测试开发约定Koel 前端工程实践指南Vue 3 TypeScript 下的组件、表单与测试开发约定 Koel 是一个采用 Laravel 后端 Vue 3 前端音视频后端前端Process Hacker项目开发指南构建规范与编码约定详解Process Hacker项目开发指南构建规范与编码约定详解 项目概述 Process Hacker是一个功能强大的系统监控工具它提供了对进程、线程、服务桌面应用调试器应用安全驱动开发rclone AGENTS.md 精读AI 编码代理协作开发规范、构建测试流程与核心架构约定rclone AGENTS.md 精读AI 编码代理协作开发规范、构建测试流程与核心架构约定 rclone 仓库根目录下的 AGENTS.md 是专门写给 ACLI数据同步对象存储上一篇karma-coverage高级技巧自定义报告器与in-memory模式应用下一篇XSS Hunter Express安全实践最小化攻击面与防护策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Koel 的 Laravel 开发规范指南：解读 Laravel Boost 下的编码、测试与前端构建约定
音视频后端前端【免费下载链接】koelMusic streaming solution that works.项目地址https://gitcode.com/gh_mirrors/ko/koel点击查看免费下载本文以仓库 .junie/guidelines.mdLaravel Boost Guidelines为骨架逐条解读这份由 Laravel 维护者为本仓库定制的 AI 辅助开发规范并结合 Koel 的实际源码、配置与测试用例composer.json、bootstrap/app.php、app/Models/Artist.php、tests/ 等验证其落地情况。读完本文你将掌握Koel 的技术栈基线、遵循的 Laravel 12/13 应用结构约定、PHP 与测试的强制编码规范、Tailwind CSS v4 的前端样式约定以及 Boost 工具与测试命令的正确用法。一、指南是什么Laravel Boost Guidelines 的定位.junie/guidelines.md是一份被设计为 AI 编码助手Agent在 Koel 仓库内写代码时必须遵守的项目级开发规范全称为 Laravel Boost Guidelines。文件顶部明确说明这份指南由Laravel 维护者专门为本应用挑选curated并强调应该被严格遵守以提升用户构建 Laravel 应用的满意度。整份指南采用laravel-boost-guidelines包裹内部按foundation rules、boost rules、php rules、tests rules、laravel/core rules、laravel/v12 rules、phpunit/core rules、tailwindcss/core rules、tailwindcss/v4 rules九个区块组织。它不是一篇零散笔记而是一份层次分明、可直接执行的技术约束清单既有版本基线也有命令、代码示例和可替换的工具类名映射表。与之配套的是 .junie/mcp/mcp.json 中声明的 MCP 配置——Laravel Boost 以一个 MCP 服务器形态存在为 Agent 提供list-artisan-commands、tinker、database-query、browser-logs、search-docs等专用工具。换言之这份规范不仅是给人看的代码风格文档更是给 LLM/AI 工具驱动这个 Laravel 应用的操作手册。二、技术栈基线指南声明与仓库实际的版本对照指南在 Foundational Context 一节列出了本应用依赖的 PHP 与 Laravel 生态版本清单并声明必须以这些具体包与版本为准组件指南声明版本仓库实际约束composer.json / package.jsonPHP8.4.208.3composer 平台锁定8.3.0laravel/frameworkv12^13.0laravel/nightwatchv1^1.13laravel/promptsv0^0.3.6laravel/sanctumv4^4.0laravel/scoutv10^11.0laravel/socialitev5^5.12larastan/larastanv3^3.7phpunit/phpunitv11^11.0vuev3^3.5.29laravel-echov2^2.1.6laravel/echo-vue亦为^2.1.6tailwindcssv4^4.3.0含tailwindcss/vite^4.3.0需要说明的是指南中 Laravel 框架标注为 v12而当前仓库的 composer.json 已将laravel/framework提升至^13.0、laravel/scout提升至^11.0。指南中关于Laravel 12 结构的说明中间件声明式注册、bootstrap/app.php为注册中枢等在 Laravel 13 下依然成立且被仓库严格遵循因此本文以当前仓库实际内容为准展开版本差异仅作为对照信息呈现。其余组件版本与指南基本吻合Sanctum v4、Socialite v5、PHPUnit v11、Vue 3、Tailwind CSS v4 均与声明一致。三、通用约定命名、复用与验证Conventions 一节给出了四条适用于所有代码改动的基础规则遵循既有代码约定创建或编辑文件时先查看同级文件以确定正确的结构、写法和命名。Koel 的 app/Http/Requests/ 目录即典型例子——所有表单请求按 API / Download / Subsonic 分组存放新增校验类时应遵循该分组模式。描述性命名使用描述性的变量与方法名例如isRegisteredForDiscounts而非discount。优先复用动手写新组件前先检查是否已有可复用组件。验证脚本纪律不要为了验证而创建一次性脚本或使用 tinker 去验证已有测试覆盖的功能单元测试与功能测试的优先级更高。此外还有三条治理性规则目录结构坚持既有目录结构未经批准不得新建顶层基础目录。依赖变更未经批准不得改动应用依赖。回复风格解释保持简洁聚焦重点不赘述显而易见的内容。文档文件仅在用户明确要求时才创建文档文件。这些规则共同塑造了可审计、可测试、最小改动的工程约束与 Koel 庞大的 tests/ 测试树Feature、Integration、Unit 三层所体现的测试优先文化一致。四、应用结构与架构Laravel 12/13 的声明式组织方式指南的laravel/v12 rules区块专门说明了新版 Laravel 的精简目录结构Koel 仓库是这一结构的忠实体现4.1 中间件不再注册在app/Http/Kernel.php自 Laravel 11 起app/Http/Kernel.php已被移除中间件改为在 bootstrap/app.php 中通过Application::configure()-withMiddleware()声明式注册。Koel 的实际写法印证了这一点return Application::configure(basePath: dirname(__DIR__)) -withRouting( using: static function (): void { RouteServiceProvider::loadVersionAwareRoutes(web); RouteServiceProvider::loadVersionAwareRoutes(api); Route::middleware(api)-group(base_path(routes/subsonic.php)); }, commands: __DIR__ . /../routes/console.php, channels: __DIR__ . /../routes/channels.php, health: /up, ) -withMiddleware(static function (Middleware $middleware): void { $middleware-api(prepend: [AddRequestContextForLogging::class]); $middleware-web(prepend: [AddRequestContextForLogging::class]); $middleware-api(append: [ RestrictPlusFeatures::class, HandleDemoMode::class, ForceHttps::class, ]); $middleware-web(append: [ RestrictPlusFeatures::class, HandleDemoMode::class, ForceHttps::class, ]); $middleware-alias([ audio.auth AuthenticateAudioRequests::class, os.auth ObjectStorageAuthenticate::class, embeds.enabled EnsureEmbedsEnabled::class, ]); // Koel is an SPA without a login route, so the Authenticate middleware would // otherwise throw RouteNotFoundException when resolving route(login) on guests. $middleware-redirectGuestsTo(/); }) -withExceptions(/* ... */) -create();可以看到 bootstrap/app.php 同时承担了路由注册、中间件注册、异常渲染三件事路由通过RouteServiceProvider::loadVersionAwareRoutes()加载web/api两个版本化路由文件并挂载routes/subsonic.phpwithMiddleware中既按组api/web前后追加中间件也通过alias注册audio.auth、os.auth、embeds.enabled等具名中间件withExceptions则自定义了AuthenticationException的 JSON/重定向响应并接入SubsonicAwareErrorRenderer。4.2 服务提供者集中登记在bootstrap/providers.php指南指出bootstrap/providers.php存放应用特有的服务提供者。仓库中的 bootstrap/providers.php 列出了一串 Koel 特有的提供者AppServiceProvider、AuthServiceProvider、SongStorageServiceProvider、StreamerServiceProvider、ObjectStorageServiceProvider、LicenseServiceProvider、SocialiteServiceProvider等并前置注册了第三方提供者ImageServiceProvider、ScoutServiceProvider、AuditingServiceProvider、TNTSearchScoutServiceProvider。4.3 控制台配置的迁移指南明确app/Console/Kernel.php已不存在控制台配置改用bootstrap/app.php或routes/console.php且 app/Console/Commands/ 下的命令自动被发现、无需手动注册。Koel 的routes/console.php正是被withRouting(commands: ...)显式挂载的而ScanCommand、InitCommand、DoctorCommand、CollectTagsCommand、FetchArtworkCommand等二十余个命令均放在命令目录中自动生效。4.4 数据库与模型指南在laravel/v12 rules中还强调了两条模型层规则迁移必须保留列的既有属性修改列时迁移需包含该列此前定义的全部属性否则这些属性会被丢弃。Koel 的迁移历史如 database/migrations/2024_01_16_215642_use_uuids_for_playlists.php、2025_07_20_165224_migrate_foreign_keys_to_ulid.php展示了这种逐步改写列定义、保留语义的谨慎迁移风格。Casts 用casts()方法而非$casts属性指南建议在模型上通过casts()方法定义类型转换并遵循既有模型的惯例。这一约定在 Koel 中执行得非常彻底——app/Models/ 下全部 16 个模型都采用casts()方法。例如 app/Models/Artist.php/** inheritDoc */ protected function casts(): array { return [ favorite boolean, favorited_at datetime, ]; }五、Laravel Boost面向本应用的 MCP 工具集指南的boost rules区块介绍了 Boost MCP 服务器为 Agent 提供的专属工具并要求优先使用它们list-artisan-commands需要调用 Artisan 命令前先用它核对可用参数指南要求所有 Artisan 调用都带--no-interaction并补全正确的--options确保无人值守可运行。get-absolute-url向用户分享项目 URL 时用它确认 scheme、域名/IP 与端口正确。tinker需要执行 PHP 调试代码或直接查询 Eloquent 模型时使用如果只是读取数据库则改用database-query工具。browser-logs读取浏览器日志、错误与异常但只有最近的日志有价值应忽略旧日志。search-docs重点处理任何 Laravel 或 Laravel 生态包Laravel、Inertia、Livewire、Filament、Tailwind、Pest、Nova、Nightwatch 等时必须先于其他途径使用它。该工具会把已安装的包列表与版本自动传给远端 Boost API从而只返回与当前环境匹配的版本化文档可传入包名数组做过滤。search-docs的搜索语法支持多种形式简单词搜索自动词干authentication可命中authenticate与auth。多词 AND 逻辑rate limit要求同时包含rate与limit。精确短语infinite scroll要求词相邻且顺序一致。混合查询middleware rate limit表示middleware与精确短语rate limit。多查询[authentication, middleware]任一命中即可。指南建议以宽泛、简单、主题化的多个查询起步如[rate limiting, routing rate limiting, routing]且不要在查询中加入包名包信息已自动共享例如应写test resource table而非filament 4 test resource table。这与 Koel 使用大量 Laravel 生态包Scout 全文搜索、Sanctum API 认证、Socialite SSO、laravel-echo 实时广播、Auditing 审计日志等的现实高度匹配——正确查询版本化文档是安全改动的第一步。六、PHP 编码规则类型、注释与枚举php rules区块给出了强制性的 PHP 风格约束Koel 源码中处处可见其落实6.1 控制结构与构造器所有控制结构必须使用花括号即使只有一行。构造函数使用PHP 8 构造器属性提升constructor property promotion且不允许出现零参数的空__construct()除非构造器是 privatepublic function __construct(public GitHub $github) { }6.2 显式类型声明方法与函数必须显式声明返回类型参数要使用恰当的类型提示。指南给出的范例protected function isAccessible(User $user, ?string $path null): bool { ... }Koel 的模型、Builder、Repository 几乎全部遵循此风格如 app/Models/Artist.php 中的public static function getOrCreate(User $user, ?string $name null): self以及每个 Eloquent 关系方法都带返回类型albums(): HasMany、songs(): HasMany、user(): BelongsTo。6.3 注释与 PHPDoc优先使用 PHPDoc 块而非行内注释除非逻辑非常复杂否则不要在代码内部写注释数组场景下应添加有用的 array shape 类型定义。Koel 的模型注释即典型如property Collectionarray-key, Song $songs。6.4 枚举命名枚举的键case 名一般使用 TitleCase例如FavoritePerson、BestLake、Monthly。Koel 的 app/Enums/ 下如SongStorageType、ScanResultType、SmartPlaylistModel等枚举均遵循该命名法。七、测试规则PHPUnit 与最小化运行7.1 强制测试tests rules区块的硬性要求每次改动都必须有程序化测试——写新测试或更新既有测试并运行确认通过。Koel 的测试体系完全按此组织tests/Feature/HTTP 层、命令、KoelPlus 等、tests/Integration/服务、迁移、观察者、tests/Unit/AI、模型、管道、值对象。指南同时给出成本控制手段运行保证代码质量所需的最少测试并推荐php artisan test --compact配合指定文件名或过滤器。7.2 PHPUnit 专属规则phpunit/core rules本应用使用PHPUnit所有测试必须以 PHPUnit 类编写用php artisan make:test --phpunit {name}创建若遇到 Pest 风格测试需转换为 PHPUnit。每次更新测试后运行该单一测试相关功能测试全部通过后询问用户是否需要运行整个测试套件。测试须覆盖 happy path、failure path 与 edge/weird path 三类路径。未经批准不得删除 tests 目录中的任何测试文件——这些是应用的核心资产而非临时文件。Faker 使用遵循既有惯例$this-faker-word()或fake()-randomDigit()。创建测试模型时优先使用工厂database/factories/ 提供 AlbumFactory、SongFactory、PlaylistFactory 等 20 余个工厂并先检查工厂是否有可用的自定义状态。7.3 测试运行命令场景命令运行全部测试php artisan test --compact运行单个文件php artisan test --compact tests/Feature/ExampleTest.php按名称过滤php artisan test --compact --filtertestName改动相关文件后的推荐方式八、Laravel Core 规则以 Eloquent 为中心的开发方式laravel/core rules是覆盖面最广的区块定义了Laravel 之道数据库与模型始终使用带返回类型提示的 Eloquent 关系方法优先于原生查询或手写 join用Model::query()而非DB::不绕过 ORM。用 eager loading 预防 N1 查询问题仅对非常复杂的数据库操作使用查询构造器。创建新模型时同时创建有用的工厂与 seeder并用list-artisan-commands核对php artisan make:model的可用选项。API 与资源默认使用 Eloquent API Resources 与 API 版本化除非既有 API 路由未采用——此时遵循应用既有约定。Koel 的RouteServiceProvider::loadVersionAwareRoutes(api)正是版本化路由的落地实现。控制器与校验校验必须放在Form Request类中而非控制器内联并同时包含校验规则与自定义错误消息。写新 Form Request 前检查同级请求app/Http/Requests/确认应用采用数组式还是字符串式规则。Koel 的 104 个请求类API/、Download/、Subsonic/ 分组均遵循此约定。队列、认证与授权耗时操作使用实现ShouldQueue接口的队列任务如 app/Jobs/ 下的HandleSongUploadJob、ScrobbleJob、GenerateAlbumThumbnailJob。使用 Laravel 内置的认证与授权能力gates、policies、Sanctum 等。Koel 在 app/Policies/ 下为 12 个实体各建了 Policy并用 Sanctum 做 API 认证。URL 与配置页面链接优先使用命名路由与route()函数。环境变量只允许出现在配置文件里禁止在配置文件之外调用env()一律使用config(app.name)而非env(APP_NAME)。测试用php artisan make:test [options] {name}创建功能测试大多数测试应为功能测试加--unit创建单元测试。九、前端构建与调试Tailwind v4 与 Vite9.1 前端打包指南在 Frontend Bundling 中指出用户看不到前端变更时通常需要运行pnpm run build、pnpm run dev或composer run dev。结合仓库实际package.json、composer.jsonpnpm run build实际执行vp build pnpm run build:sw构建应用 通过vite.config.sw.js生成 Service Worker。pnpm run dev在 package.json 中已被移除运行它会得到提示Usecomposer devinstead.。composer run dev才是本地开发命令它用 concurrently 同时启动php artisan serve、php artisan queue:listen --tries1与vp devVite 开发服务器并关闭进程超时限制。9.2 Vite manifest 错误遇到Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest时先运行pnpm run build或请用户运行pnpm run dev/composer run dev生成/刷新 manifest。9.3 Tailwind CSS v4 规则tailwindcss/core rulestailwindcss/v4 rules样式一律使用 Tailwind 类并先检查项目内既有约定再自行书写重复模式可抽取为符合项目惯例的组件Blade、JSX、Vue 等。注意类名放置、顺序、优先级与默认值去掉冗余类谨慎地把类加到父/子元素以控制重复并按逻辑分组元素。间距列表项间距用gap工具类而非 margindiv classflex gap-8 divSuperior/div divMichigan/div divErie/div /div暗色模式既有页面支持暗色模式时新页面必须用同样的方式通常为dark:支持。Tailwind CSS v4 的专属约束包括始终使用 v4不使用已废弃的工具类。corePlugins在 v4 中不受支持。v4 配置是CSS-first的用theme指令无需独立的tailwind.config.jstheme { --color-brand: oklch(0.72 0.11 178); }v4 通过普通 CSSimport引入 Tailwind而非 v3 的tailwind指令- tailwind base; - tailwind components; - tailwind utilities; import tailwindcss;从 Koel 的实际配置看package.json 已采用tailwindcss ^4.3.0与tailwindcss/vite ^4.3.0仓库仍保留的 tailwind.config.js 内容被显著精简——主要声明content扫描路径resources/assets/js/**/*.{vue,js,ts,jsx,tsx}并将颜色、间距、动画等映射到CSS 变量如k-fg: var(--color-fg)、k-header-height: var(--header-height)。从源码结构可以推断Koel 的主题系统由 CSS 变量驱动配合 app/Values/Theme/ 与 themes 迁移v4 的 CSS-first 配置方式与其自洽。9.4 已废弃工具类的替换表v4Tailwind v4 移除了大量废弃工具类指南给出了完整的替换映射改动样式时必须使用替代品不透明度数值仍为数字已废弃替代bg-opacity-*bg-black/*text-opacity-*text-black/*border-opacity-*border-black/*divide-opacity-*divide-black/*ring-opacity-*ring-black/*placeholder-opacity-*placeholder-black/*flex-shrink-*shrink-*flex-grow-*grow-*overflow-ellipsistext-ellipsisdecoration-slicebox-decoration-slicedecoration-clonebox-decoration-clone十、规范在仓库中的落地核查与注意事项将指南逐条与 Koel 源码对照可以得到一份规范执行度清单规范条目仓库证据执行情况中间件声明式注册于bootstrap/app.phpbootstrap/app.php 中withMiddleware/withExceptions/withRouting链式配置完全一致服务提供者登记于bootstrap/providers.phpbootstrap/providers.php 列出 16 个应用提供者完全一致控制台命令自动发现app/Console/Commands/ 下 20 命令无 Kernel 注册完全一致模型使用casts()方法app/Models/ 全部 16 个模型均采用casts()完全一致校验放入 Form Requestapp/Http/Requests/ 104 个请求类完全一致关系方法带返回类型app/Models/Artist.php 等完全一致用 Policy / Sanctum 做授权认证app/Policies/、app/Http/Middleware/完全一致配置用config()而非env()config/ 下 25 个配置文件一致Tailwind v4package.jsontailwindcss ^4.3.0一致指南版本基线composer.jsonLaravel 框架实际已升至^13.0、Scout^11.0其余吻合使用这份规范时有两点需特别注意版本基线以仓库为准指南头部声明的 Laravel v12 / Scout v10 是编写指南时的基线当前 composer.json 已升级到 Laravel 13 / Scout 11。指南中关于结构、命名、测试的所有规则在 Laravel 13 下依然有效但涉及具体版本特性时应依据composer.json、package.json与composer.lock的实际锁定版本行事。开发命令以仓库为准pnpm run dev已被移除统一使用composer run dev构建仍用pnpm run build含 Service Worker 生成。结语.junie/guidelines.md的价值不在于罗列教条而在于它把 Koel 这一大型 Laravel 音乐流媒体项目数百个模型、控制器、请求类与测试背后可复制的工程纪律沉淀成了显式规则从 Eloquent 优先的数据库哲学到bootstrap/app.php的声明式结构再到 PHPUnit 最小化测试与 Tailwind v4 的 CSS-first 配置。对希望在 Koel 之上做二次开发、或想借鉴其 Laravel 工程规范的开发者而言这份指南加上仓库源码的相互印证就是最可靠的学习与执行依据。赞分享音视频后端前端【免费下载链接】koelMusic streaming solution that works.项目地址https://gitcode.com/gh_mirrors/ko/koel点击查看免费下载相关推荐Koel 前端工程实践指南Vue 3 TypeScript 下的组件、表单与测试开发约定Koel 前端工程实践指南Vue 3 TypeScript 下的组件、表单与测试开发约定 Koel 是一个采用 Laravel 后端 Vue 3 前端音视频后端前端Process Hacker项目开发指南构建规范与编码约定详解Process Hacker项目开发指南构建规范与编码约定详解 项目概述 Process Hacker是一个功能强大的系统监控工具它提供了对进程、线程、服务桌面应用调试器应用安全驱动开发rclone AGENTS.md 精读AI 编码代理协作开发规范、构建测试流程与核心架构约定rclone AGENTS.md 精读AI 编码代理协作开发规范、构建测试流程与核心架构约定 rclone 仓库根目录下的 AGENTS.md 是专门写给 ACLI数据同步对象存储上一篇karma-coverage高级技巧自定义报告器与in-memory模式应用下一篇XSS Hunter Express安全实践最小化攻击面与防护策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RELATED READING
延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
代码包深度解析与实践指南)
