接口和页面的思路不同:页面返回 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,是偷懒的做法。
统一返回结构
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 是对前两段的签名。
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 编码,不是加密,任何人都能解开看。所以里面不要放密码、手机号这类敏感信息。
校验三件事
- 签名对不对(用 hash_equals 比较,防时序攻击)。
- 过期没有(exp 字段)。
- 签发者与受众对不对(iss、aud),防止拿别的系统的 token 来用。
[$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。