goletter/hyperf-resource

API Resource helpers for Hyperf (includes, response envelope, ApiResponse).

v1.0.3 2026-08-30 10:43 UTC

Requires

• php: >=8.1
• goletter/hyperf-utils: ^1.0
• hyperf/collection: ^3.1
• hyperf/context: ^3.1
• hyperf/contract: ^3.1
• hyperf/db-connection: ^3.1
• hyperf/resource: ^3.1
• hyperf/server: ^3.1
• hyperf/stringable: ^3.1

MIT

• goletter

• php
• api
• resource
• hyperf

Published on Packagist.org on 2026-08-30 10:43 UTC

README

基于 hyperf/resource 的 API 资源层：统一响应信封、?include= 关联预加载、ApiResponse 辅助方法。

安装

composer require goletter/hyperf-resource

发布配置（可选，用于自定义 Resource 命名空间）：

php bin/hyperf.php vendor:publish goletter/hyperf-resource

响应信封

成功响应会附带：

{
  "data": {},
  "success": true,
  "status": "success",
  "code": 200,
  "message": ""
}

code / message 可通过 success() / collection() 第三个、第四个参数传入。

快速使用

在 Service / Controller 中使用 ApiResponse（goletter/hyperf-server 的 Service 已默认引入）：

use Goletter\Resource\ApiResponse;

class UserService
{
    use ApiResponse;

    public function show(int $id)
    {
        $user = User::query()->findOrFail($id);

        // 自动解析 App\Resource\User 或 App\Resource\UserResource
        return $this->success($user);

        // 或显式指定
        // return $this->success($user, UserResource::class, 200, 'ok');
    }

    public function index()
    {
        $users = User::query()->paginate();

        return $this->collection($users, UserResource::class);
    }

    public function store()
    {
        // 业务失败：抛出 BusinessException（需在项目中注册异常处理器）
        $this->fail(422, '邮箱已被占用');
    }
}

自动解析命名空间默认 App\Resource，可在 .env 或 config/autoload/resource.php 修改：

RESOURCE_NAMESPACE=App\Resource

编写 Resource

namespace App\Resource;

use Goletter\Resource\Resource;

class UserResource extends Resource
{
    /** 单资源允许通过 ?include= 加载的关联 */
    protected static array $availableIncludes = [
        'profile',
        'roles',
    ];

    /** 列表允许的 include（可与单资源不同） */
    protected static array $collectionAvailableIncludes = [
        'profile',
    ];

    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'profile' => $this->whenLoaded('profile'),
            'roles' => $this->whenLoaded('roles'),
        ];
    }

    /** 可选：约束 include 查询，方法名为 {relation}Query */
    public static function rolesQuery($query): void
    {
        $query->where('status', 1);
    }
}

请求示例：

GET /users/1?include=profile,roles
GET /users?include=profile

未出现在白名单中的 include 会被忽略，避免随意加载关联。

分页

传入分页器时，会输出精简后的 meta（含 total 等）。若项目使用 goletter/hyperf-server 的 ResponseFormatMiddleware，会将 meta.total 提升为顶层 total。

说明

• 集合会先统一 loadMissing，再实例化子 Resource，避免 N 次重复预加载。
• fail() / BusinessException 支持 int 或 BackedEnum（若 Enum 有 label() / getMessage() 会用作默认文案）。
• 请在应用内注册 BusinessException 的异常处理器，以返回与成功响应一致的 JSON 信封。