写给愿意动手的 PHP 开发者
PHP学习网 PHP学习网
公告PHP学习网为公益性网站,致力于为广大PHP爱好者服务
首页/ PHP 教程/ 实战项目/ RESTful 接口与 JWT:给前端和 App 写 API
实战项目 APIJWTRESTful

RESTful 接口与 JWT:给前端和 App 写 API

URL 与状态码设计、统一返回结构、JWT 的三段结构、签名与过期、刷新策略、常见错误。

接口和页面的思路不同:页面返回 HTML,接口返回数据;页面重定向,接口用状态码表达结果。

URL 与状态码

  • GET /api/articles:列表
  • GET /api/articles/12:详情
  • POST /api/articles:创建
  • PUT /api/articles/12:整体更新
  • DELETE /api/articles/12:删除

状态码要真的用起来:200 成功、201 已创建、400 参数错误、401 未认证、403 无权限、404 不存在、422 校验失败、429 请求过多、500 服务端错误。全部返回 200 再在 body 里写 code,是偷懒的做法。

统一返回结构

PHP
function json_out($data = null, string $msg = 'ok', int $code = 200): void
{
    http_response_code($code);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode(['code' => $code, 'msg' => $msg, 'data' => $data], JSON_UNESCAPED_UNICODE);
    exit;
}

结构固定,前端只写一次解析逻辑。错误时 data 为 null,msg 给人看,code 给程序判断。

JWT 的结构

JWT 是三段 base64url 用点连接:header.payload.signature。header 声明算法,payload 放数据(用户 ID、过期时间),signature 是对前两段的签名。

PHP
function jwt_encode(array $payload, string $secret): string
{
    $h = base64url(json_encode(['alg' => 'HS256', 'typ' => 'JWT']));
    $p = base64url(json_encode($payload));
    $sig = base64url(hash_hmac('sha256', "$h.$p", $secret, true));
    return "$h.$p.$sig";
}

payload 只是 base64 编码,不是加密,任何人都能解开看。所以里面不要放密码、手机号这类敏感信息。

校验三件事

  1. 签名对不对(用 hash_equals 比较,防时序攻击)。
  2. 过期没有(exp 字段)。
  3. 签发者与受众对不对(iss、aud),防止拿别的系统的 token 来用。
PHP
[$h, $p, $sig] = explode('.', $token) + ['', '', ''];
$expect = base64url(hash_hmac('sha256', "$h.$p", $secret, true));
if (!hash_equals($expect, $sig)) json_out(null, '签名无效', 401);
$claims = json_decode(base64url_decode($p), true);
if (($claims['exp'] ?? 0) < time()) json_out(null, '登录已过期', 401);

过期与刷新

access token 设短一点(15 分钟到 2 小时),配一个长期 refresh token。refresh token 存数据库,可以单独吊销。JWT 本身无法「立即失效」,除非维护一个黑名单。

常见错误:把 JWT 放在 URL 参数里。URL 会进日志、进 Referer。令牌只放 Authorization 头,或者 HttpOnly Cookie。

文中提到的函数

接着读