Coolify 的 Laravel 代码风格与命名规范从 skill 规则到仓库源码的完整实践【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本文以 Coolify 仓库中的 rules/style.md 为核心系统讲解 Laravel 项目的命名约定、更简洁的框架语法、Str/Arr/Number/Uri辅助类用法以及 Blade 模板与注释的书写纪律。读完后你不仅能掌握这套可复制的编码规范还能对照 Coolify 的真实源码看到每条规则在大型项目中的落地形态。规则背景Consistency First 原则下的第 19 条这份 style 规则并非孤立存在它是 laravel-best-practices skill 中 19 个规则章节之一。skill 的索引文件明确将其定位为 Conventions Style 章节摘要为Follow Laravel naming conventions for all entitiesPrefer Laravel helpersStr、Arr、Number、Uri、Str::of()、$request-string()over raw PHP functionsNo JS/CSS in Blade, no HTML in PHP classesCode should be readable; comments only for config files。skill 还强调一个前置原则——Consistency First一致性优先应用任何规则之前先检查应用既有写法。Laravel offers multiple valid approaches — the best choice is the one the codebase already uses, even if another pattern would theoretically better. Inconsistency is worse than a suboptimal pattern. 换句话说这些规则是当代码库尚无既定模式时的默认选择而不是对既有代码的强制覆盖。理解了这一点才能正确地把这套风格规则用于代码评审与重构。命名约定Laravel 全生态的命名对照表文档给出的第一张核心表格是各类实体的命名规范这是 Laravel 社区约定俗成、且 Eloquent/路由系统深度依赖的命名规则。完整继承如下实体约定正确示例错误示例Controller单数ArticleControllerArticlesControllerModel单数UserUsersTable复数、snake_casearticle_commentsarticleCommentsPivot table中间表单数、按字母序article_useruser_articleColumnsnake_case、不带模型名前缀meta_titlearticle_meta_titleForeign key单数模型名 _idarticle_idarticles_idRoute复数articles/1article/1Route namesnake_case 带点分隔users.show_activeusers.show-activeMethodcamelCasegetAllget_allVariablecamelCase$articlesWithAuthor$articles_with_authorCollection描述性、复数$activeUsers$dataObject描述性、单数$activeUser$usersViewkebab-caseshow-filtered.blade.phpshowFiltered.blade.phpConfigsnake_casegoogle_calendar.phpgoogleCalendar.phpEnum单数UserTypeUserTypes在 Coolify 源码中的验证这套约定在 Coolify 这个真实的大型 Laravel 项目中被完整遵循可以直接打开仓库对照Model 单数app/Models 目录下全部是单数命名如User.php、Server.php、Application.php、Service.php、Environment.phpController 单数app/Http/Controllers/Api/GithubController.php 等 API 控制器均为单数表名复数 snake_casedatabase/migrations 中2023_03_27_081716_create_applications_table.phpapplications表、create_environment_variables_table.php等外键列则遵循单数模型名 _id的规则View kebab-caseresources/views/livewire 下的 Livewire 视图文件如activity-monitor.blade.php、settings-backup.blade.php、global-search.blade.php全部是 kebab-case无一例 camelCaseConfig snake_caseconfig 目录中app.php、fortify.php之外的多词配置均为 snake_case如chunk-upload.php、logging.php所在目录下的各文件。值得注意的一个细节app/Enums/下存在ActivityTypes.php这样的复数枚举与Enum 单数的约定相悖。这恰好印证了 Consistency First 原则——规则是默认值而存量代码库的一致性优先于理论最优新增代码时跟随既有模式即可。为什么这些命名被系统依赖这些约定不只是审美问题很多是框架行为的硬性前提Eloquent 通过模型名复数化自动推导表名Article→articles中间表按两侧模型名单数按字母序推导User、Post→user_post列名规则决定了belongsTo等关系自动推断外键article_id路由名用点分隔users.show_active是因为route(a.b)与视图里route、route()助手都按点解析命名空间层级View 的 kebab-case 与 Livewire 组件名livewire:settings-backup的组件解析规则直接对应——Coolify 的 Livewire 类目录结构与视图文件名一一对应正是这一约定在组件化场景下的延伸。偏好更短、更易读的框架语法文档第二张表格列出了冗长写法 → 简洁写法的对照核心思想是框架已经提供了门面Facade、助手函数与查询器语法糖直接用它们。完整表格如下冗长写法简洁写法Session::get(cart)session(cart)$request-session()-get(cart)session(cart)$request-input(name)$request-namereturn Redirect::back()return back()Carbon::now()now()App::make(Class)app(Class)-where(column, , 1)-where(column, 1)-orderBy(created_at, desc)-latest()-orderBy(created_at, asc)-oldest()-first()-name-value(name)几条值得展开的实践要点$request-nameIlluminate\Http\Request实现了__get魔术方法$request-name等价于$request-input(name)在控制器与 Livewire 组件中更贴近读代码的自然语序where(column, 1)查询构建器默认操作符就是省略操作符让条件读起来更像自然语言latest()/oldest()不仅是语法糖还语义明确地表达了按创建时间排序的意图避免orderBy(created_at, desc)在 created_at 字段命名不一致的项目里产生歧义value(name)-first()-name会先实例化整个模型再取属性value(name)则直接在数据库层只取单列单值在只需一个字段时更省开销——这与 skill 中数据库性能章节只 select 需要的列的原则一脉相承。用 Laravel 辅助类替代裸 PHP 函数这是 style 文档中篇幅最大、实操价值最高的部分。文档明确指出Laravel 提供的Str、Arr、Number、Uri辅助类比裸 PHP 函数更可读、可链式调用、且对 UTF-8 安全always prefer them。字符串Str与流式Str::of()文档给出的错误/正确对照// Incorrect $slug strtolower(str_replace( , -, $title)); $short substr($text, 0, 100) . ...; $class substr(strrchr(App\Models\User, \), 1); // Correct $slug Str::slug($title); $short Str::limit($text, 100); $class class_basename(App\Models\User);差异不仅是行数Str::slug()内部做了 Unicode 转写 连字符归一化而strtolower(str_replace(...))对多字节内容会直接截断坏字符Str::limit()处理了省略号的精确拼接。对复杂转换文档推荐流式字符串Fluent strings// Incorrect $result strtolower(trim(str_replace(_, -, $input))); // Correct $result Str::of($input)-trim()-replace(_, -)-lower();文档列出的应优先使用的Str方法清单Str::slug()、Str::limit()、Str::contains()、Str::before()、Str::after()、Str::between()、Str::camel()、Str::snake()、Str::kebab()、Str::headline()、Str::squish()、Str::mask()、Str::uuid()、Str::ulid()、Str::random()、Str::is()。Coolify 中的真实用例在 app/Models/Application.php 中应用创建时为各 Git 平台生成手动 webhook 密钥用的就是Str::random(40)$application-manual_webhook_secret_github ?? Str::random(40); $application-manual_webhook_secret_gitlab ?? Str::random(40); $application-manual_webhook_secret_bitbucket ?? Str::random(40); $application-manual_webhook_secret_gitea ?? Str::random(40);同文件的全局搜索过滤逻辑约 L1174-L1202则是Str::startsWithStr::after组合解析status:、source:、server:这类过滤前缀比裸 PHP 的strpos/substr写法意图更清晰。此外Str::replaceEnd、Str::finish、Str::start被用于规范化 Git 仓库 URL 与 commit 路径Str::lower用于搜索大小写归一化——这个模型文件中Str::调用达到十余处是辅助类优先原则的典型落地样本。数组Arr优先于isset三元式// Incorrect $name isset($array[user][name]) ? $array[user][name] : default; // Correct $name Arr::get($array, user.name, default);Arr::get()用点语法一次穿透任意层级嵌套且统一了缺省值的语义避免了对多层嵌套逐级isset的冗长判断。文档推荐的方法清单Arr::get()、Arr::has()、Arr::only()、Arr::except()、Arr::first()、Arr::flatten()、Arr::pluck()、Arr::where()、Arr::wrap()。Coolify 中 app/Console/Commands/Generate/Services.php 在处理模板解析结果时使用了Arr::pull($parsed, name)把name键取出并移除同时作为数组索引使用——这是取出 删除一步完成的高效用法。数字与 URINumber与Uri文档给出的展示格式示例数字格式化属于展示层Number类统一处理了本地化与单位换算Number::format(1000000); // 1,000,000 Number::currency(1500, USD); // $1,500.00 Number::abbreviate(1000000); // 1M Number::fileSize(1024 * 1024); // 1 MB Number::percentage(75.5); // 75.5%URI 操作用Uri类避免手工拼接字符串$uri Uri::of(https://example.com/search) -withQuery([q laravel, page 1]);文档还补充了两个进阶技巧$request-string(name)直接从请求输入取得流式Stringable便于对入参立即链式处理trim、replace、lower 等文档末尾提示使用search-docs查询完整方法列表——这些辅助类非常庞大即本文档列出的只是高频子集完整 API 以所安装 Laravel 版本的官方文档为准。Blade 中禁止内联 JS/CSS数据通过 data 属性传递文档第四条规则Do not put JS or CSS in Blade templates. Do not put HTML in PHP classes.不要在 Blade 模板里写 JS/CSS也不要在 PHP 类里写 HTML。文档给出的对照示例{{-- 错误在模板中直接注入 JSON 生成 JS 变量 --}} let article {{ json_encode($article) }};{{-- 正确用 json 指令把数据挂到 data 属性上 --}} button classjs-fav-article>// 错误用注释解释一段晦涩的判断 // Check if there are any joins if (count((array) $builder-getQuery()-joins) 0)// 正确提取语义化方法名注释自然消失 if ($this-hasJoins())这个示例的精妙之处在于它展示的不是少写一行注释而是用提取方法Extract Method把注释意图编码进了方法名——hasJoins()本身就是那句注释的可执行版本。而配置文件例外是因为 config 数组的 key 往往是env驱动的行为开关如 config/queue.php 中各队列连接的定义缺少一行说明就难以判断该键在何种环境下生效、为何存在。落地建议把 style 规则变成评审清单结合 SKILL.md 的 How to Apply 流程这套 style 规则的实际使用路径是按文件类型定位规则写/改控制器与模型时style 规则命名、辅助类是必查项再叠加 routing、eloquent、db-performance 等章节先查兄弟文件在 app/Http/Controllers 或 app/Models 中找一个同类既有文件若它已有命名/写法模式跟随它Consistency First评审时按清单核对新类/表/列/路由名是否符合上表 15 条约定是否还有可用助手函数替代的Session::/App::make()/Carbon::now()冗长调用字符串/数组处理是否裸用了substr/str_replace/isset三元式而非Str/ArrBlade 中是否出现了内联script/style或手写 JSON 注入代码注释是否属于解释显而易见逻辑应删除或提取方法名配置文件注释是否充分。这套规则的价值在于它把 Laravel 框架应有的样子压缩成一张可直接执行、可对照源码验证的规范表。以 Coolify 仓库为参照——从单数命名的 Model 与 Controller、kebab-case 的 Livewire 视图到Application.php中密集使用的Str::方法与Generate/Services.php中的Arr::pull——可以看到这些约定在一个真实生产级 Laravel 项目里被系统性遵循这正是文档从应然规范落到实然代码的证据。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考