| 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)、队列与调度。