用 PHP 构建轻量级 REST API:从路由到鉴权的完整实践

1. 引言

在微服务与前后端分离日益普及的今天,REST API 已成为系统间通信的主流方式。PHP 凭借其部署简单、生态成熟的特点,依然是构建 Web 服务的常用选择。本文不引入 Laravel、Symfony 等重型框架,而是从零开始,用 PHP 原生能力配合轻量组件,搭建一个结构清晰、易于维护的 REST API 服务。

我们将依次覆盖 REST 设计原则、路由定义、请求解析、JSON 响应封装、状态码与错误处理,以及 API Key / Bearer Token 两种简单鉴权方式。整个项目不依赖 Composer 之外的第三方框架,代码可直接运行。

2. REST 设计原则简述

REST(Representational State Transfer)是一种基于 HTTP 协议的架构风格,核心思想是将一切视为资源,通过统一的接口对资源进行操作。理解以下原则,是设计好 API 的第一步。

2.1 资源与 URL 设计

资源是 REST 的核心抽象,URL 只用来定位资源,不包含动词。例如:

  • GET /api/users:获取用户列表
  • POST /api/users:创建用户
  • GET /api/users/42:获取单个用户
  • PUT /api/users/42:整体更新用户
  • DELETE /api/users/42:删除用户

资源名称使用复数名词,层级关系用斜杠表达,如 /api/users/42/orders 表示某个用户的订单列表。

2.2 HTTP 方法与语义

每个 HTTP 方法对应一种标准操作:

方法 语义 幂等
GET 查询资源 是
POST 创建资源 否
PUT 整体替换资源 是
PATCH 局部更新资源 否
DELETE 删除资源 是

幂等意味着多次执行结果一致,这对网络重试场景非常重要。

2.3 无状态与统一接口

服务端不保存客户端会话状态,每个请求都携带完整信息,这便于水平扩展。同时,所有资源通过统一的接口访问,使用标准状态码表达结果,使用标准媒体类型(如 JSON)表达数据。

3. 使用 FastRoute 定义路由

FastRoute 是 PHP 社区广泛使用的轻量路由库,性能优异,支持占位符与分组。首先通过 Composer 安装:

bash 复制代码
composer require nikic/fast-route

3.1 基础路由配置

创建一个 routes.php 文件,集中定义所有路由:

php 复制代码
<?php
// routes.php
use FastRoute\RouteCollector;

return function (RouteCollector $r) {
    // 用户资源
    $r->addRoute('GET', '/api/users', 'UserController@index');
    $r->addRoute('POST', '/api/users', 'UserController@store');
    $r->addRoute('GET', '/api/users/{id:\d+}', 'UserController@show');
    $r->addRoute('PUT', '/api/users/{id:\d+}', 'UserController@update');
    $r->addRoute('DELETE', '/api/users/{id:\d+}', 'UserController@destroy');

    // 订单资源
    $r->addRoute('GET', '/api/users/{id:\d+}/orders', 'OrderController@index');
};

{id:\d+} 是带正则约束的占位符,确保 id 只能是数字,避免非法参数进入业务层。

3.2 前端控制器(入口文件)

在 public/index.php 中统一调度:

php 复制代码
<?php
// public/index.php
require __DIR__ . '/../vendor/autoload.php';

$dispatcher = FastRoute\simpleDispatcher(require __DIR__ . '/../routes.php');

$httpMethod = $_SERVER['REQUEST_METHOD'];
$uri = $_SERVER['REQUEST_URI'];

// 去除查询字符串与末尾斜杠
if (false !== $pos = strpos($uri, '?')) {
    $uri = substr($uri, 0, $pos);
}
$uri = rawurldecode($uri);

$routeInfo = $dispatcher->dispatch($httpMethod, $uri);

switch ($routeInfo[0]) {
    case FastRoute\Dispatcher::NOT_FOUND:
        // 404 处理
        break;
    case FastRoute\Dispatcher::METHOD_NOT_ALLOWED:
        // 405 处理
        break;
    case FastRoute\Dispatcher::FOUND:
        $handler = $routeInfo[1];
        $vars = $routeInfo[2];
        // 调用控制器
        break;
}

4. 请求解析与 JSON 响应封装

4.1 请求体解析

REST API 通常接收 JSON 格式的请求体。我们需要一个统一的请求解析器:

php 复制代码
<?php
// src/Http/Request.php
namespace App\Http;

class Request
{
    public static function jsonBody(): array
    {
        $raw = file_get_contents('php://input');
        $data = json_decode($raw, true);

        if (json_last_error() !== JSON_ERROR_NONE) {
            return [];
        }

        return is_array($data) ? $data : [];
    }

    public static function queryParams(): array
    {
        return $_GET;
    }

    public static function header(string $name): ?string
    {
        $key = 'HTTP_' . strtoupper(str_replace('-', '_', $name));
        return $_SERVER[$key] ?? null;
    }
}

4.2 JSON 响应封装

统一的响应结构能让客户端解析逻辑保持一致。我们设计一个 Response 类:

php 复制代码
<?php
// src/Http/Response.php
namespace App\Http;

class Response
{
    public static function json(array $data, int $status = 200): void
    {
        http_response_code($status);
        header('Content-Type: application/json; charset=utf-8');
        echo json_encode($data, JSON_UNESCAPED_UNICODE);
        exit;
    }

    public static function success($data = null, string $message = 'ok'): void
    {
        self::json([
            'code' => 0,
            'message' => $message,
            'data' => $data,
        ], 200);
    }

    public static function error(string $message, int $status, int $code = -1): void
    {
        self::json([
            'code' => $code,
            'message' => $message,
            'data' => null,
        ], $status);
    }
}

统一响应格式为 { code, message, data },其中 code 为业务码,HTTP 状态码 表达传输层结果,二者解耦,便于客户端分别处理。

5. 状态码与错误处理规范

5.1 常用状态码语义

状态码 含义 典型场景
200 成功 GET 查询、PUT 更新
201 已创建 POST 新建资源
204 无内容 DELETE 删除成功
400 请求参数错误 JSON 解析失败、校验不通过
401 未认证 缺少或无效的 Token
403 无权限 已认证但无权访问
404 资源不存在 路由未匹配或资源缺失
405 方法不允许 URL 存在但方法不支持
422 语义错误 业务校验失败
500 服务器内部错误 未捕获异常

5.2 全局异常处理

在入口文件中注册异常处理器,避免错误信息直接暴露给客户端:

php 复制代码
<?php
// public/index.php 中追加
set_exception_handler(function (Throwable $e) {
    error_log($e->getMessage() . ' in ' . $e->getFile() . ':' . $e->getLine());

    Response::error('服务器内部错误', 500);
});

生产环境务必隐藏堆栈细节,仅记录到日志;开发环境可选择性输出调试信息。

5.3 路由未匹配处理

完善入口文件中的 404 与 405 分支:

php 复制代码
case FastRoute\Dispatcher::NOT_FOUND:
    Response::error('资源不存在', 404);
    break;

case FastRoute\Dispatcher::METHOD_NOT_ALLOWED:
    Response::error('请求方法不允许', 405);
    break;

6. 简单鉴权:API Key / Bearer Token

6.1 API Key 鉴权

API Key 适合服务端到服务端的调用,客户端在请求头中携带密钥:

php 复制代码
<?php
// src/Auth/ApiKeyAuth.php
namespace App\Auth;

use App\Http\Request;
use App\Http\Response;

class ApiKeyAuth
{
    private const VALID_KEYS = [
        'live_key_abc123',
        'test_key_xyz789',
    ];

    public static function verify(): void
    {
        $key = Request::header('X-API-Key');

        if (!$key || !in_array($key, self::VALID_KEYS, true)) {
            Response::error('无效的 API Key', 401);
        }
    }
}

调用方在请求头中携带:

http 复制代码
GET /api/users HTTP/1.1
Host: api.example.com
X-API-Key: live_key_abc123

6.2 Bearer Token 鉴权

Bearer Token 更常用于用户态场景,客户端在 Authorization 头中携带令牌:

php 复制代码
<?php
// src/Auth/BearerAuth.php
namespace App\Auth;

use App\Http\Request;
use App\Http\Response;

class BearerAuth
{
    public static function verify(): void
    {
        $header = Request::header('Authorization');

        if (!$header || !preg_match('/^Bearer\s+(\S+)$/', $header, $matches)) {
            Response::error('缺少或格式错误的 Token', 401);
        }

        $token = $matches[1];

        // 实际项目中应校验签名与过期时间,这里仅做示例
        if (!self::isValid($token)) {
            Response::error('Token 无效或已过期', 401);
        }
    }

    private static function isValid(string $token): bool
    {
        // 可对接 Redis / 数据库 / JWT 验签
        return $token === 'demo_token_2024';
    }
}

请求示例:

http 复制代码
GET /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer demo_token_2024

6.3 在控制器中组合使用

php 复制代码
<?php
// src/Controller/UserController.php
namespace App\Controller;

use App\Auth\ApiKeyAuth;
use App\Auth\BearerAuth;
use App\Http\Response;

class UserController
{
    public function index(array $params): void
    {
        ApiKeyAuth::verify(); // 服务端调用场景
        // 业务逻辑...
        Response::success([['id' => 1, 'name' => 'Alice']]);
    }

    public function show(array $params): void
    {
        BearerAuth::verify(); // 用户态场景
        $id = (int) $params['id'];
        // 业务逻辑...
        Response::success(['id' => $id, 'name' => 'Alice']);
    }
}

7. 完整请求流程串联

将以上模块在入口文件中串联起来,形成完整的请求生命周期:

php 复制代码
<?php
// public/index.php 完整版
require __DIR__ . '/../vendor/autoload.php';

use App\Auth\ApiKeyAuth;
use App\Auth\BearerAuth;
use App\Http\Response;
use FastRoute\Dispatcher;

$dispatcher = FastRoute\simpleDispatcher(require __DIR__ . '/../routes.php');

$httpMethod = $_SERVER['REQUEST_METHOD'];
$uri = $_SERVER['REQUEST_URI'];

if (false !== $pos = strpos($uri, '?')) {
    $uri = substr($uri, 0, $pos);
}
$uri = rawurldecode($uri);

$routeInfo = $dispatcher->dispatch($httpMethod, $uri);

switch ($routeInfo[0]) {
    case Dispatcher::NOT_FOUND:
        Response::error('资源不存在', 404);
        break;

    case Dispatcher::METHOD_NOT_ALLOWED:
        Response::error('请求方法不允许', 405);
        break;

    case Dispatcher::FOUND:
        [$controller, $method] = explode('@', $routeInfo[1]);
        $vars = $routeInfo[2];

        $instance = new ("App\\Controller\\{$controller}")();
        $instance->{$method}($vars);
        break;
}

8. 总结

本文用 PHP 原生能力配合 FastRoute,搭建了一个轻量级 REST API 骨架,覆盖了从路由、请求解析、响应封装到鉴权的完整链路。核心要点如下:

  • REST 设计:资源化 URL、语义化 HTTP 方法、无状态通信。
  • 路由:FastRoute 提供高性能匹配与参数约束。
  • 响应封装 :统一 { code, message, data } 结构,业务码与状态码解耦。
  • 错误处理:全局异常捕获,生产环境隐藏堆栈。
  • 鉴权:API Key 适合机器间调用,Bearer Token 适合用户态场景。

这套骨架足够支撑中小型项目的起步,后续可按需扩展中间件、参数校验、数据库访问层与日志系统。保持轻量、保持清晰,是构建可维护 API 的长久之道。

相关推荐
代码丰5 小时前
从重复点击到多实例并发:异步报表导出的五层幂等与防重设计
后端
斯维赤5 小时前
三级缓存为什么是三级?二级缓存不够吗
前端·后端·面试
Rain的Java大神之路6 小时前
把数组本身变成哈希表:原地哈希搞定 LeetCode 41「缺失的第一个正数」
java·后端·leetcode
卷无止境6 小时前
FDE全解析:把软件真正落地到客户现场的那类工程师
后端
锋行天下6 小时前
LangGraph 对接 MCP 实战指南:从本地开发到线上部署与模型防坑
前端·人工智能·后端
山楂树の6 小时前
Java 泛型:泛型类、泛型方法、泛型接口与通配符
java·开发语言·笔记
利威尔xu6 小时前
2026-11-18-Go接口幂等设计实战
开发语言·后端·golang
喵个咪7 小时前
RushWind Admin — update_mask 写面:字段级白名单、显式清除与点路径合并
后端·rust
喵个咪7 小时前
RushWind Admin — 多租户行级隔离与租户回收站:Viewer 三态、repo_shell! 与全域级联清除
后端·rust
喵个咪7 小时前
RushWind CMS — 三服务拓扑:core 领域层、双 BFF 薄代理与一份契约的双面输出
后端·rust