选 rebing/graphql-laravel，因其“laravel 优先”，复用 eloquent、中间件、验证等生态；需手动配置 schema、路由前缀和错误处理器，并严格对齐 graphqltype 与模型类型、关系加载及可空字段声明。
直接用 Laravel 开发 GraphQL API 是可行的，但别指望框架原生支持——php artisan make:graphql 不存在。你得靠第三方包，目前最稳定、维护最勤的是 rebing/graphql-laravel。
为什么选 rebing/graphql-laravel 而不是 nuwave/lighthouse
两者都能跑通，但定位不同：nuwave/lighthouse 更像“GraphQL 优先”的全栈方案（强依赖 schema-first、自动生成 resolver），而 rebing/graphql-laravel 是“Laravel 优先”：复用 Eloquent、中间件、请求验证、服务容器，schema 和 resolver 都能写在 PHP 里，调试更直观。
- 如果你已有 Laravel 项目，模型/策略/Policy/Resource 已写好，选
rebing/graphql-laravel - 如果你团队熟悉 SDL（Schema Definition Language）且倾向前端驱动 schema，再考虑
lighthouse -
rebing的GraphQLController默认走POST /graphql，和 Laravel 路由完全兼容，不用额外配 nginx 重写
安装后必须改的三处配置
装完 composer require rebing/graphql-laravel 后，光 php artisan vendor:publish 不够，有三个地方不手动改就会 500 或返回空数据：
- 在
config/graphql.php中确认'schemas' => ['default' => [...]]里的'query' => [...]指向了你定义的 query class，比如App\GraphQL\Queries\UserQuery::class - 确保
'routes' => ['prefix' => 'graphql']和你实际注册的路由一致；如果想挂到/api/graphql，就得同步改 prefix 并在routes/api.php里显式调用GraphQL::routes() - 把
'error_handler' => [...]里的DebugFlag::MASKED改成DebugFlag::INCLUDE_DEBUG_INFO（仅开发环境），否则字段报错只显示 “Internal server error”，看不到具体哪行 resolver 抛了异常
GraphQLType 和 Eloquent Model 怎么对齐才不翻车
很多人把 GraphQLType 当作 Model 镜像，结果字段类型错位、关系查 N+1、null 值崩掉前端解析。关键不是“映射”，而是“声明契约”：
- 字段类型必须严格对应：Eloquent 的
$casts = ['is_active' => 'boolean']，GraphQL type 就得用Type::boolean()，不能用Type::string()然后靠resolve强转 - 关系字段（如
posts）不要直接 return$user->posts，要用$user->posts()->get()或更优的$user->load('posts')，否则在 batch query 场景下会触发多次查询 - 可空字段（如
avatar_url允许为 null）必须显式声明：用Type::string()->nullable()，否则 GraphQL 执行器遇到 null 会直接中断整个响应 - 避免在
fields()里写业务逻辑，比如'full_name' => ['type' => Type::string(), 'resolve' => fn() => $user->first_name . ' ' . $user->last_name]—— 这种拼接应该放在 Accessor 里，保持 type 定义纯粹
调试时看不清请求体？加个日志中间件比 dump 更准
GraphQL 请求体是 JSON，dd(request()->all()) 只能看到解码后的数组，丢失原始结构；用 Chrome Network 面板又难复现变量变化。最稳的方式是加一个临时日志中间件：
class LogGraphQLRequest
{
public function handle($request, Closure $next)
{
if ($request->is('graphql') && $request->isMethod('POST')) {
\Log::info('GraphQL raw', [
'query' => $request->input('query'),
'variables' => $request->input('variables'),
'operationName' => $request->input('operationName'),
]);
}
return $next($request);
}
}
注册到 app/Http/Kernel.php 的 $middlewareGroups['api'] 里，就能在 storage/logs/laravel.log 里看到每次请求的原始 query 字符串和变量，比反复切 Postman 方便得多。
真正麻烦的从来不是写完第一个 query，而是当多个 client（Web、iOS、Android）开始传不同 shape 的 variables，或者前端突然要求加一个带复杂嵌套过滤的 users(where: { status: ACTIVE, tags_contains: ["vip"] }) —— 那时候你得回过头去修 UserQuery@resolve 里的 Builder，而不是重写 schema。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
