specsfy-specialist-laravel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Laravel

Quando usar

适用场景

Acionar quando o repositório tem
```
artisan
```
,
```
composer.json
```
com
```
laravel/framework
```
, e a tarefa envolve rotas, controllers, models, policies, form requests, jobs, eventos, cache, config ou testes Laravel.
Acionar também para revisão de PR Laravel, diagnóstico de N+1, fila travada, autorização quebrada ou migration arriscada.
Não acionar para decisão pura de schema, índice ou plano de query — usar
```
$specsfy-specialist-postgres
```
e trazer o resultado para o Eloquent.
Combinar com
```
$specsfy-specialist-application-security
```
quando a mudança tocar autenticação, mass assignment, upload ou dado sensível, e com
```
$specsfy-specialist-supabase
```
quando o Postgres for gerenciado por Supabase em vez de instância própria.

当仓库包含
```
artisan
```
、
```
composer.json
```
中存在
```
laravel/framework
```
，且任务涉及Laravel的路由、控制器、模型、策略、表单请求、任务、事件、缓存、配置或测试时触发。
也可用于Laravel PR审查、N+1问题诊断、队列阻塞、授权失效或高风险迁移等场景。
请勿用于单纯的Schema、索引或查询计划决策——应使用
```
$specsfy-specialist-postgres
```
，并将结果应用到Eloquent中。
当变更涉及认证、批量赋值、上传或敏感数据时，需结合
```
$specsfy-specialist-application-security
```
；当Postgres由Supabase托管而非自建实例时，需结合
```
$specsfy-specialist-supabase
```
。

Fluxo

流程

Ler
```
composer.json
```
/
```
composer.lock
```
para confirmar versão do framework, PHP e pacotes relevantes (Sanctum, Horizon, Octane, Scout) antes de supor comportamento por memória.
Mapear a requisição do ponto de entrada até domínio, persistência, efeitos assíncronos e resposta, identificando o boundary onde a regra de negócio já vive no projeto (Action, Service, Model rico).
Localizar convenções irmãs — como o projeto organiza Form Requests, Policies, Resources e Jobs — e seguir o padrão existente em vez de introduzir um novo.
Definir autorização, validação, transação, idempotência e modo de falha antes de escrever código, especialmente para jobs e webhooks.
Escrever o teste focal (Pest ou PHPUnit conforme o projeto), implementar a menor fatia que o torna verde e então refatorar.
Inspecionar as queries geradas (
```
DB::listen
```
, Telescope, Debugbar ou
```
EXPLAIN
```
via
```
$specsfy-specialist-postgres
```
) quando cardinalidade ou latência importarem.
Executar testes, análise estática (Larastan/PHPStan) e formatter (Pint) disponíveis no projeto antes de considerar a tarefa concluída.
Verificar impacto operacional — migration em produção, workers, scheduler, cache de config — e registrar risco quando a ação exigir autorização externa.

在凭记忆假设框架行为前，先读取
```
composer.json
```
/
```
composer.lock
```
确认框架版本、PHP版本及相关包（Sanctum、Horizon、Octane、Scout）。
从入口点到领域层、持久层、异步副作用及响应，梳理请求流程，识别项目中已存在的业务规则边界（Action、Service、富模型）。
查找同类约定——如项目如何组织Form Requests、Policies、Resources和Jobs——遵循现有模式，而非引入新范式。
在编写代码前，先定义授权、验证、事务、幂等性及故障模式，尤其是针对任务和Webhook。
编写聚焦测试（根据项目选择Pest或PHPUnit），实现最小化代码使测试通过，再进行重构。
当涉及基数或延迟问题时，检查生成的查询（
```
DB::listen
```
、Telescope、Debugbar或通过
```
$specsfy-specialist-postgres
```
执行
```
EXPLAIN
```
）。
在任务完成前，执行项目中可用的测试、静态分析（Larastan/PHPStan）及格式化工具（Pint）。
检查运维影响——生产环境迁移、Worker、调度器、配置缓存——当操作需要外部授权时，记录风险。

Padrões

规范

Manter controllers finos: validação em Form Requests, autorização em Policies/Gates, regra de negócio no boundary já adotado pelo projeto.
Tratar Eloquent como acesso a dados: eager load explícito (
```
with
```
,
```
withCount
```
) sempre que uma coleção acessar relação em loop; nunca escrever N+1 e justificar "está rápido o bastante por enquanto".
Selecionar colunas (
```
select
```
) quando a tabela for larga ou a listagem não precisar do model completo; preferir
```
chunkById
```
/
```
lazyById
```
para varreduras grandes em vez de carregar tudo em memória.
Projetar jobs idempotentes:
```
ShouldBeUnique
```
/lock quando duplicidade for possível, timeout e tentativas explícitos,
```
failed()
```
tratando o efeito colateral de falha definitiva.
Migrations compatíveis com o volume real:
```
expand → migrar dado → contract
```
para mudança incompatível em tabela grande; nunca um único
```
ALTER
```
bloqueante sem medir o lock esperado.
Nunca confiar em validação do cliente nem autorizar somente na UI — Policy/Gate roda no servidor em toda ação e em todo objeto, não só na rota de criação.
Proteger mass assignment com
```
$fillable
```
(ou
```
$guarded
```
deliberado) e nunca passar
```
$request->all()
```
direto para
```
create
```
/
```
update
```
sem validação prévia.
Não criar abstração, evento, pacote ou camada extra sem um segundo consumidor real e benefício verificável — três controllers parecidos não justificam um framework interno.

保持控制器轻量化：验证逻辑放在Form Requests中，授权逻辑放在Policies/Gates中，业务规则放在项目已采用的边界层。
将Eloquent视为数据访问层：当集合在循环中访问关联时，显式使用预加载（
```
with
```
、
```
withCount
```
）；绝不编写N+1查询并以“目前速度足够”为借口。
当表数据量大或列表无需完整模型时，选择指定列（
```
select
```
）；对于大数据遍历，优先使用
```
chunkById
```
/
```
lazyById
```
而非一次性加载到内存。
设计幂等性任务：当可能出现重复时，使用
```
ShouldBeUnique
```
/锁，设置显式超时和重试次数，通过
```
failed()
```
处理最终失败的副作用。
迁移需适配真实数据量：对于大表的不兼容变更，采用“扩容→迁移数据→收缩”的流程；绝不直接执行阻塞性的
```
ALTER
```
语句而不评估预期锁时间。
绝不依赖客户端验证或仅在UI层做授权——Policy/Gate需在服务器端对所有操作及所有对象生效，而非仅在创建路由中。
通过
```
$fillable
```
（或刻意使用
```
$guarded
```
）保护批量赋值，绝不未经预先验证就将
```
$request->all()
```
直接传入
```
create
```
/
```
update
```
。
若无真实的第二个使用者和可验证的收益，请勿创建额外的抽象层、事件、包或层级——三个相似的控制器不足以证明需要内部框架。

Antipadrões

反模式

Model "gordo" que mistura regra de negócio, efeito colateral externo e apresentação no mesmo método — sintoma de que o boundary do projeto não foi seguido.
Policy que autoriza pela presença do usuário autenticado, sem checar ownership do objeto — abre acesso cross-tenant mesmo com
```
auth
```
middleware presente.
Job que reprocessa efeito não idempotente (enviar e-mail, cobrar cartão) sem chave de deduplicação — reentrega do worker duplica o efeito.
Migration com
```
Schema::table
```
renomeando ou removendo coluna usada em produção no mesmo deploy que o código que a lê — quebra a janela de deploy misto.
Teste que usa
```
RefreshDatabase
```
mas não recria os dados mínimos de autorização, mascarando policy ausente com um usuário "admin" fixo.

“臃肿”模型：在同一方法中混合业务规则、外部副作用和展示逻辑——这是未遵循项目边界层的征兆。
仅通过认证用户存在性进行授权的Policy，未检查对象所有权——即使存在
```
auth
```
中间件，也会导致跨租户访问漏洞。
处理非幂等副作用（发送邮件、扣款）的任务无去重键——Worker重试会重复触发副作用。
在同一部署中，迁移使用
```
Schema::table
```
重命名或删除生产环境中仍在被代码读取的列——破坏混合部署窗口。
使用
```
RefreshDatabase
```
但未重新创建最小授权数据的测试，用固定的“管理员”用户掩盖缺失的Policy。

Validação

验证

Cobrir caminho feliz, autorização negada, validação, efeitos colaterais e falhas relevantes (job falho, dependência externa indisponível).
Rodar a suíte com
```
RefreshDatabase
```
/factories e confirmar que o teste falha sem a mudança (RED) antes de implementar.
Inspecionar queries geradas quando a tela lista uma coleção com relação — contar queries antes/depois (
```
assertQueryCountLessThan
```
, Debugbar, log de queries) para provar ausência de N+1.
Verificar queues, scheduler, cache de config/rotas e variáveis de ambiente no ambiente alvo antes de declarar a tarefa pronta para deploy.
Não declarar "seguro" ou "idempotente" sem teste que exercite o cenário adversarial correspondente (replay do job, payload malformado, usuário sem permissão).

覆盖正常流程、授权失败、验证、副作用及相关故障场景（任务失败、外部依赖不可用）。
使用
```
RefreshDatabase
```
/工厂运行测试套件，确认在未做变更前测试失败（RED），再进行实现。
当页面列出带关联的集合时，检查生成的查询——对比前后查询数量（
```
assertQueryCountLessThan
```
、Debugbar、查询日志）以证明无N+1问题。
在宣布任务可部署前，检查目标环境的队列、调度器、配置/路由缓存及环境变量。
若无对应对抗场景的测试（任务重放、格式错误的 payload、无权限用户），请勿宣称“安全”或“幂等”。

specsfy-specialist-laravel

Original

Translation

Laravel

Laravel

Quando usar

适用场景

Fluxo

流程

Padrões

规范

Antipadrões

反模式

Validação

验证

Skills relacionadas

相关技能