Pin

外观

HTTP 与响应 ​

Pin 的 HTTP 层围绕统一 JSON 响应、请求宏和常用中间件展开。

ApiResponse ​

Pin\Http\ApiResponse 实现 Responsable，可以直接从控制器返回。

php
use Pin\Http\ApiResponse;

return ApiResponse::success([
    'id' => 1,
    'name' => 'Pin',
]);

默认响应结构：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "name": "Pin"
  }
}

创建错误响应：

php
return ApiResponse::make(10001, '用户名不存在')
    ->withStatusCode(404)
    ->withHeaders('X-Request-Source', 'api');

meta 为空时会自动移除。app.debug 为真时会额外输出 debug，包含 request id、环境、耗时、SQL 数量、SQL 耗时、SQL 列表和内存信息。

基础控制器 ​

Pin\Http\Controller 提供两个快捷方法：

php
use Pin\Http\Controller;

class UserController extends Controller
{
    public function show(int $id)
    {
        return $this->success(['id' => $id]);
    }

    public function destroy(int $id)
    {
        return $this->error(10001, '删除失败');
    }
}

success($data, $message = '', $meta = null) 将数据放在第一位，适合 API 常见场景。

Request 宏 ​

Pin\Providers\PinServiceProvider 会调用 Pin\Http\Request::registerMacros()，给 Laravel Request 注册以下宏：

宏说明
getReferer()优先读取 x-referer，其次读取 referer
isFromApiDocument()根据 X-Api-Document 或 Referer 判断是否来自接口文档
isFromFrontend()根据 Referer 或 Origin 判断是否来自受信任前端
isReading()判断是否为 HEAD、GET、OPTIONS
isRequest($values)同时支持 URI 规则和路由名匹配

示例：

php
if ($request->isFromFrontend()) {
    // 允许前端来源逻辑
}

if ($request->isRequest(['api/users/*', 'users.index'])) {
    // 匹配 URI 或路由名称
}

HTTP 中间件 ​

Pin\Http\Request::GLOBAL_MIDDLEWARES 定义了建议加入全局中间件栈的中间件：

php
[
    Pin\Http\Middleware\LogApiResponse::class,
    Pin\Http\Middleware\RequestHeaders::class,
]

常用中间件包括：

中间件用途
LogApiResponse记录 API 响应、耗时和可选 SQL 信息
RequestHeaders标准化请求头处理
ThrottleRequests请求限流
ValidateCsrfTokenCSRF 校验增强
EnsureFrontendRequestsAreStateful与前端来源、Sanctum 状态请求配合
Debug调试场景辅助

是否记录日志由 config/logging.php 的 logging.response 与 logging.sql_logging 控制。