| name | laravel |
| description | Laravel 路由、Eloquent、Blade、Artisan 与部署。在开发或维护 Laravel 项目时使用。 |
Laravel
开发规范
以下规范与框架版本无关，适用于 Laravel 项目日常开发与代码审查。能愿动词：必须/禁止表示强制，应/宜表示建议。
项目规范
- 环境与配置：敏感及环境相关配置必须放在
.env，代码中通过 config() 读取；禁止在代码中硬编码密钥、数据库连接等。
- Composer：依赖通过 Composer 管理；禁止提交
vendor/；开发专用包放入 require-dev。
- 工具统一：团队内 PHP、Node、Composer、代码风格工具等版本与用法应统一，并在项目文档中说明。
- 静态资源：前端资源放置与编译方式应统一（如 Laravel Mix/Vite 等），构建产物不提交仓库。
- 文档：项目应具备 README（运行方式、环境要求、常用命令），接口变更宜更新文档。
路由
- 路由应使用命名（便于
route() 生成 URL）并合理分组（前缀、中间件、域名等）。
- 对资源的 CRUD 应优先使用资源路由（resource），保持路由文件简洁可读。
控制器
- 控制器应保持精简，只做请求分发与响应组织；复杂业务逻辑应放入 Service 或领域层。
- 表单验证应使用框架提供的 Form Request 类，不在控制器内写大量
validate() 或 if 判断。
- 单一职责：一个控制器方法对应一个用户操作，避免臃肿方法。
模型
- 表名遵循框架约定（通常为复数形式）；使用 Eloquent 进行查询与关联，避免手写原生 SQL（除非确有性能或复杂度需求）。
- 敏感字段（如密码、令牌）必须在模型中使用隐藏（如
$hidden），禁止在 JSON 或数组序列化中输出。
配置与环境变量
- 所有可因环境变化的配置必须通过
.env 与 config/ 管理；代码中只读取 config()，不直接读 env()（除 config 文件内）。
- 新增配置项时，应在配置文件中提供默认值并注明含义。
日期与时间
- 日期时间统一使用框架提供的日期 API（如 Carbon）；存储与比较时明确时区，展示时按用户或业务时区转换。
API 设计
- API 应使用统一的响应结构（如
data、message、code）与合适的 HTTP 状态码。
- 列表与详情输出应使用 API 资源类（Resource）做转换，避免在控制器中手写数组；便于统一字段与隐藏敏感信息。
辅助函数与代码风格
- 通用逻辑应抽取为辅助函数或工具类，放在约定位置（如
app/Helpers），避免在控制器或模型中重复书写。
- 代码风格必须遵循 PSR-12；项目内宜使用 PHP CS Fixer 等工具统一格式。
中间件、授权与验证
- 跨请求的通用逻辑（认证、跨域、日志等）应放在中间件中；中间件命名与职责应清晰。
- 权限判断应使用框架提供的策略（Policy）或授权门面，避免在控制器或视图中散落权限判断。
- 表单验证规则应集中在 Form Request 或验证类中，便于复用与测试。
视图与前端
- 视图应避免复杂逻辑；需要的数据由控制器或 View Composer 提供，视图只负责展示。
- 前端资源与后端接口分离清晰；接口契约（字段、状态码）应稳定并文档化。
测试、Artisan 与数据
- 重要业务逻辑应有单元或功能测试；测试应可重复运行，不依赖外部状态。
- 自定义 Artisan 命令应放在约定命名空间下，命名清晰；可复用的数据准备逻辑宜放在 Seeder 中，通过 Artisan 调用。
Service 与扩展
- 复杂业务宜采用 Service 层封装，控制器调用 Service，Service 再调用模型与外部服务。
- 使用权限/角色等扩展包时，应遵循包的最佳实践并与项目路由、策略统一。
安全与性能
- 遵循框架安全实践：CSRF、XSS、SQL 注入防护；敏感操作需授权与日志。
- 生产环境应开启配置与路由缓存；按需使用队列、缓存与数据库索引，避免 N+1 查询。
详细条目与示例见 LearnKu《Laravel 项目开发规范》（文档按版本组织，规范原则通用）。
常用能力速览
- 路由：命名、分组、资源路由、中间件。
- 控制器：精简、Form Request 验证、单一职责。
- 模型：Eloquent、关联、隐藏字段、迁移与填充。
- Blade：布局、组件、指令；少写逻辑。
- Artisan：迁移、填充、队列、缓存、自定义命令。
- 部署：环境配置、优化命令（config/route cache）、队列与调度。
