SuperAPI AI 工具集

bagisto-coding-standards

编程与开发

查看项目

更新于 10-15 17:25

技能介绍

用途:为 Bagisto 全部代码提供统一规范,使 DataGrid、支付类或主题的改动与包改动遵循同一标准。机械性问题交给 Pint,运行 vendor/bin/pint 处理空格、导入顺序、尾逗号等;本技能覆盖 Pint 看不到、评审会退回的部分。

主要能力与规则:每个方法和属性都要有 docblock,描述为以句号结尾的大写句子,最多两行,类型信息放签名,仅原生类型无法表达时才加 @param/@return。类成员顺序为常量→属性→构造函数→public→protected→private,各可见性连续成块。多子句条件换行且布尔运算符置于行首,单子句保持内联。方法体、对象字面量和标记内不写注释,非显然原因放 docblock 或提交信息。类、接口、trait、enum 上方一律不写 docblock。所有数据库访问经 repository,控制器、监听器、任务或服务中不得用 DB:: 和模型查询,唯一例外是 DataGrid 的 prepareQueryBuilder()。事件用点分隔字符串而非类,如 catalog.product.update.after,成对触发 before/after。Blade 中 : 绑定 PHP 值,:: 向 Vue 传递字面 :,且 :: 仅用于 Blade 组件标签。服务端授权、插值处转义;店铺查询按所有者限定范围,请求中的 id 不能单独选行。用户可见字符串经 trans(),键加入全部 22 个语言包并用 php artisan bagisto:translations:check 校验。翻译键用 kebab-case,路由名用 snake_case。修改文件时顺带修复既有违规。

参考文件按需加载:code-style.md、comments.md、laravel.md、data-access.md、security.md、security-authorization.md、blade.md、blade-formatting.md、localization.md。

限制:代码与规范文件冲突时以代码为准,遵循周边代码并在总结中说明、提出偏差;规范文件是快照而非唯一事实来源。未触及类中缺失 docblock 属债务而非约定,应匹配规则而非最差示例。相关技能:bagisto-code-review、bagisto-package-development。