aa24615/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）、队列与调度。