README

为 ThinkPHP 6.0+ 或 8.0+ 提供的 API 快速开发工具包——开箱即用的限流、签名、JWT 鉴权、统一响应、字段过滤与分页包装、Debug 模式调试面板。

特性

安装

composer require wiseadmin/wise-api

包通过 composer.json 的 extra.think.services 自动注册服务提供者，无需手动配置。

配置

将 vendor/wiseadmin/wise-api/config/wise-api.php 复制到项目 config/ 目录后按需修改：

// config/wise-api.php
return [
    'jwt' => [
        'algorithm'   => 'HS256',
        'secret'      => env('JWT_SECRET', 'change-me'),
        'ttl'         => 7200,
        'refresh_ttl' => 1800,
    ],
    'sign' => [
        'enable'        => true,
        'secret'        => env('SIGN_SECRET', 'change-me'),
        'timestamp_ttl' => 300,
        'enable_nonce'  => true,
    ],
    'rate_limit' => [
        'enable'    => true,
        'algorithm' => 'token_bucket',
        'key_by'    => 'combine',
        'default'   => ['algorithm' => 'token_bucket', 'capacity' => 60, 'rate' => 1.0],
        'groups'    => [
            // 'api/v1/login' => ['algorithm' => 'sliding_window', 'limit' => 10, 'window' => 60],
        ],
    ],
    // ...
];

基础用法

1. 控制器继承 ApiController

namespace app\api\controller\v1;

use think\model\User;
use wise\api\ApiController;
use wise\api\middleware\RateLimitMiddleware;
use wise\api\middleware\SignVerifyMiddleware;
use wise\api\middleware\JwtAuthMiddleware;

class UserController extends ApiController
{
    /**
     * 中间件栈
     * - 限流：60 个令牌，1 个/秒
     * - 签名验证
     * - JWT 鉴权
     */
    protected $middleware = [
        RateLimitMiddleware::class . ':60,1',
        SignVerifyMiddleware::class,
        JwtAuthMiddleware::class,
    ];

    /**
     * GET /api/v1/users
     */
    public function index()
    {
        $params = $this->validateRequest([
            'page'      => 'integer|egt:1',
            'page_size' => 'integer|between:1,100',
            'keyword'   => 'chs',
        ]);
        $query = User::order('id desc');
        if (!empty($params['keyword'])) {
            $query->where('name', 'like', "%{$params['keyword']}%");
        }
        return $this->paginate($query, (int) ($params['page_size'] ?? 15));
    }

    /**
     * GET /api/v1/users/5?fields=id,name,email
     */
    public function read($id)
    {
        $user = User::find($id);
        if (!$user) {
            return $this->error(4001, '用户不存在');
        }
        $fields = $this->resolveFields(['id', 'name', 'email', 'create_time']);
        return $this->success($this->allowFields($fields, $user));
    }

    /**
     * POST /api/v1/users
     */
    public function save()
    {
        $params = $this->validateRequest([
            'name'  => 'require|chs|length:2,20',
            'email' => 'require|email',
        ]);
        $user = User::create($params);
        return $this->success(['id' => $user->id], '创建成功');
    }
}

2. 路由（API 版本管理）

// app/api/route/v1.php
use think\Route;

Route::group('v1', function () {
    Route::resource('users', 'v1.User');
});

业务请求 /api/v1/users 自动路由到 app\api\controller\v1\UserController。 增加 /api/v2/users 只需新建 app\api\controller\v2\UserController + app/api/route/v2.php。

3. JWT 签发与解析

use wise\api\facade\Jwt;

// 签发
$token = Jwt::issue($userId, ['role' => 'admin', 'custom_claims' => ['role' => 'admin']]);
// → eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.xxx.yyy

// 解析（带完整校验）
$payload = Jwt::parse($token);
echo $payload['sub']; // 用户 ID
echo $payload['role']; // 业务自定义字段

// 安全解析（失败返回 null）
$payload = Jwt::tryParse($token);

4. 在控制器获取当前登录用户

$user = $this->currentUser();
// ['id' => '123', 'payload' => [...]]

5. 手动签名（供业务方主动签名时复用）

use wise\api\sign\SignVerifier;

$verifier = new SignVerifier();
$params = ['app_key' => 'demo', 'timestamp' => time(), 'nonce' => 'xyz', 'foo' => 'bar'];
$sign = $verifier->sign($params, 'your-secret');
// 客户端将 sign 追加到 params 后发起请求即可

6. 限流分组

// config/wise-api.php
'rate_limit' => [
    'groups' => [
        'api/v1/login' => ['algorithm' => 'sliding_window', 'limit' => 10, 'window' => 60],
        'api/v1/sms'   => ['algorithm' => 'token_bucket',   'capacity' => 5, 'rate' => 0.1],
    ],
],

匹配到分组时，相应 API 自动使用分组配置；未匹配时使用 default。

7. 自动续签

JwtAuthMiddleware 在剩余有效期 < refresh_ttl 时，会在响应头自动添加：

X-New-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.xxx.yyy

客户端在 axios/fetch 拦截器中替换本地 token 即可。

调试面板（仅 Debug 模式）

启动应用时调用 app()->isDebug() 必须为 true。启用后：

• 每次请求的 Header 中附带 X-Debug-Info（base64 编码的 JSON）
• 访问 GET /__debug_api 返回最近一次请求的完整调试快照
• 包含：耗时、内存、限流状态、JWT payload、签名原始串与本地计算结果、SQL 日志

{
  "code": 0,
  "msg": "ok",
  "data": {
    "elapsed_ms": 42,
    "memory": { "start": 2097152, "current": 3145728, "peak": 4194304 },
    "context": {
      "rate_limit": { "key": "...", "algorithm": "token_bucket", "allowed": true, "info": {...} },
      "sign":       { "raw_string": "...", "local_sign": "..." },
      "jwt":        { "sub": "123", "exp": 1718256000, "ttl": 1700, "should_refresh": true }
    },
    "sql": ["[ SQL ] SELECT * FROM ..."]
  }
}

生产环境 app()->isDebug() 为 false 时，/__debug_api 路由自动不注册。

架构概览

src/
├── ApiController.php          控制器基类
├── Service.php                服务注册
├── helper.php                 助手函数
├── middleware/                限流 / 签名 / JWT 中间件
├── jwt/                       JWT 核心 + HS256 / RS256
├── rate/                      令牌桶 / 滑动窗口 / 协调者
├── sign/                      签名验证器
├── response/                  统一响应 + 错误码枚举
├── debug/                     调试面板
├── exception/                 JWT 异常
└── facade/                    JwtFacade
config/wise-api.php             配置文件
route/wise.php                 默认路由（debug 模式）

错误码

License

MIT