PHP RESTful（快速上手）

什么是 PHP RESTful？从零开始理解现代 API 设计

在当今的 Web 开发中，前后端分离已经成为主流架构。你可能已经听说过“API”这个词，也见过各种接口文档，比如 https://api.example.com/users。这些接口背后，其实都遵循了一种叫 RESTful 的设计规范。而 PHP 作为一门历史悠久又极其灵活的语言，正是构建这类接口的绝佳选择。

简单来说，PHP RESTful 就是使用 PHP 语言，按照 REST 架构风格来设计和实现 Web 接口。它强调资源的统一访问方式，让客户端通过标准的 HTTP 方法（GET、POST、PUT、DELETE）来操作服务器上的数据资源。

想象一下，你去一家餐厅吃饭。菜单上的每道菜就是一个“资源”，而你点餐、加菜、退菜的动作，就对应着不同的 HTTP 方法。点菜用 GET（获取信息），加菜用 POST（创建资源），修改订单用 PUT，取消订单用 DELETE。整个过程清晰、高效，这就是 RESTful 的核心思想。

RESTful 的核心原则：资源与状态转移

REST 不是某个框架，而是一种设计理念。它的核心原则可以概括为以下几点：

• 一切皆资源：无论是用户、文章、订单还是图片，都可以看作一个“资源”。每个资源都有唯一的标识，通常是 URL。
• 统一接口：使用标准的 HTTP 方法来操作资源，避免自定义逻辑。
• 无状态通信：每次请求都独立，服务器不保存客户端的状态。这提升了系统的可扩展性。
• 可缓存性：响应可以被客户端或代理缓存，提升性能。

比如一个用户资源，我们可以这样设计：

GET    /users           # 获取所有用户列表
GET    /users/1         # 获取 ID 为 1 的用户
POST   /users           # 创建新用户
PUT    /users/1         # 更新 ID 为 1 的用户
DELETE /users/1         # 删除 ID 为 1 的用户

这些 URL 和方法的组合，就是典型的 PHP RESTful 接口设计。它让接口的用途一目了然，无需额外文档也能理解。

用 PHP 实现一个简单的 RESTful 接口

接下来我们来动手实现一个最基础的 PHP RESTful 接口。我们将创建一个“待办事项”系统，支持增删改查。

首先，创建一个 index.php 文件，作为入口：

<?php
// index.php
// 设置响应头，告诉客户端返回的是 JSON 数据
header('Content-Type: application/json');
header('Access-Control-Allow-Origin: *'); // 允许跨域访问，开发时使用
header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE'); // 支持的方法
header('Access-Control-Allow-Headers: Content-Type'); // 允许的请求头

// 模拟数据库：使用数组存储数据
$tasks = [
    ['id' => 1, 'title' => '学习 PHP RESTful', 'completed' => false],
    ['id' => 2, 'title' => '写博客文章', 'completed' => true]
];

// 获取请求方法
$method = $_SERVER['REQUEST_METHOD'];
// 获取请求路径，去除前缀
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

// 根据路径和方法分发请求
if ($path === '/tasks' && $method === 'GET') {
    // 获取所有任务
    echo json_encode(['status' => 'success', 'data' => $tasks]);
} elseif ($path === '/tasks' && $method === 'POST') {
    // 创建新任务
    $input = json_decode(file_get_contents('php://input'), true);
    $newTask = [
        'id' => count($tasks) + 1,
        'title' => $input['title'] ?? '',
        'completed' => false
    ];
    $tasks[] = $newTask;
    echo json_encode(['status' => 'success', 'message' => '任务创建成功', 'data' => $newTask]);
} elseif (preg_match('/^\/tasks\/(\d+)$/', $path, $matches) && $method === 'GET') {
    // 根据 ID 获取单个任务
    $id = (int)$matches[1];
    $task = array_filter($tasks, fn($t) => $t['id'] === $id);
    if (!empty($task)) {
        echo json_encode(['status' => 'success', 'data' => array_values($task)[0]]);
    } else {
        http_response_code(404);
        echo json_encode(['status' => 'error', 'message' => '任务未找到']);
    }
} elseif (preg_match('/^\/tasks\/(\d+)$/', $path, $matches) && $method === 'PUT') {
    // 更新任务
    $id = (int)$matches[1];
    $input = json_decode(file_get_contents('php://input'), true);
    $updated = false;
    foreach ($tasks as &$task) {
        if ($task['id'] === $id) {
            $task['title'] = $input['title'] ?? $task['title'];
            $task['completed'] = $input['completed'] ?? $task['completed'];
            $updated = true;
            break;
        }
    }
    if ($updated) {
        echo json_encode(['status' => 'success', 'message' => '任务更新成功']);
    } else {
        http_response_code(404);
        echo json_encode(['status' => 'error', 'message' => '任务未找到']);
    }
} elseif (preg_match('/^\/tasks\/(\d+)$/', $path, $matches) && $method === 'DELETE') {
    // 删除任务
    $id = (int)$matches[1];
    $tasks = array_filter($tasks, fn($t) => $t['id'] !== $id);
    echo json_encode(['status' => 'success', 'message' => '任务删除成功']);
} else {
    // 未匹配的请求
    http_response_code(404);
    echo json_encode(['status' => 'error', 'message' => '路径或方法不支持']);
}

这个例子虽然简单，但已经涵盖了 PHP RESTful 的关键点：

• 使用 parse_url 解析请求路径
• 通过 $_SERVER['REQUEST_METHOD'] 判断请求类型
• 用 json_decode 解析客户端传来的 JSON 数据
• 用 http_response_code 设置 HTTP 状态码
• 用 json_encode 返回结构化数据

HTTP 方法与状态码的正确使用

在 PHP RESTful 开发中，正确使用 HTTP 方法和状态码至关重要。它们是接口“语义”的体现，能让调用者快速理解请求结果。

举个例子：当你用 PUT /tasks/1 更新一个任务时，如果资源不存在，应该返回 404；如果更新成功，返回 200，并附带更新后的数据。

在实际项目中，我们常会使用 http_response_code() 函数来设置状态码。比如：

// 检查参数是否为空
if (empty($input['title'])) {
    http_response_code(400); // 客户端请求错误
    echo json_encode(['status' => 'error', 'message' => '标题不能为空']);
    exit;
}

这比直接返回 echo 更符合 RESTful 的规范。

实际项目中的最佳实践

当你的 PHP RESTful 接口开始走向生产环境，就需要考虑更多问题。以下是一些关键实践：

1. 使用路由类解耦逻辑

随着接口增多，index.php 会变得臃肿。建议使用路由类来管理请求分发。

<?php
// Router.php
class Router {
    private $routes = [];

    public function add($method, $path, $callback) {
        $this->routes[] = [
            'method' => $method,
            'path' => $path,
            'callback' => $callback
        ];
    }

    public function dispatch() {
        $method = $_SERVER['REQUEST_METHOD'];
        $path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

        foreach ($this->routes as $route) {
            if ($route['method'] !== $method) continue;
            if (!preg_match($route['path'], $path, $matches)) continue;
            array_shift($matches); // 移除匹配的整个字符串
            call_user_func_array($route['callback'], $matches);
            return;
        }

        http_response_code(404);
        echo json_encode(['status' => 'error', 'message' => '路由未找到']);
    }
}

然后在主文件中使用：

$router = new Router();
$router->add('GET', '/tasks', function() use ($tasks) {
    echo json_encode(['status' => 'success', 'data' => $tasks]);
});
$router->add('POST', '/tasks', function() use (&$tasks) {
    $input = json_decode(file_get_contents('php://input'), true);
    $newTask = [
        'id' => count($tasks) + 1,
        'title' => $input['title'] ?? '',
        'completed' => false
    ];
    $tasks[] = $newTask;
    http_response_code(201);
    echo json_encode(['status' => 'success', 'data' => $newTask]);
});
$router->dispatch();

2. 数据验证与错误处理

不要相信客户端传来的任何数据。每次接收到输入，都要进行验证。

function validateTask($data) {
    if (empty($data['title'])) {
        return ['valid' => false, 'message' => '标题不能为空'];
    }
    if (strlen($data['title']) > 100) {
        return ['valid' => false, 'message' => '标题不能超过 100 个字符'];
    }
    return ['valid' => true];
}

3. 安全性考虑

• 使用 HTTPS 传输数据
• 验证 Token 或 API Key
• 防止 SQL 注入（虽然这里用数组，但实际项目中必须注意）
• 限制请求频率

从学习到应用：PHP RESTful 的未来

掌握 PHP RESTful 接口开发，意味着你已经迈入了现代 Web 开发的大门。无论是为移动 App 提供数据，还是搭建微服务系统，RESTful 都是通用的语言。

它不像某些框架那样复杂，却足够强大。你不需要依赖 Laravel 或 Symfony 的全套生态，也能用原生 PHP 搭建稳定、高效的接口。

更重要的是，这种设计方式让你的代码更易维护、更易测试。当你看到一个 GET /users/123 请求，就能立刻知道它在做什么——这正是 RESTful 的魅力所在。

现在，是时候动手写一个属于自己的 PHP RESTful 接口了。从一个简单的“待办清单”开始，逐步扩展功能，你会发现，编程的乐趣，就藏在这些清晰的逻辑与结构之中。