PHP RESTful（手把手讲解）

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战(已更新的所有项目都能学习) / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

• 新开坑项目:《Spring AI 项目实战》 正在持续爆肝中，基于 Spring AI + Spring Boot 3.x + JDK 21...， 点击查看 ;
• 《从零手撸：仿小红书（微服务架构）》 已完结，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;演示链接： http://116.62.199.48:7070 ;
• 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 100w+ 字，讲解图 4013+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3700+ 小伙伴加入学习 ，欢迎点击围观

前言

随着互联网应用的快速发展，RESTful API 已成为前后端分离开发的核心技术之一。无论是构建移动应用、Web 应用还是微服务架构，掌握如何用 PHP 实现 RESTful API 都是一项关键技能。本文将从零开始，结合实例讲解 PHP RESTful API 的开发逻辑、设计原则和实战技巧，帮助开发者快速上手并理解其核心思想。

什么是 RESTful API？

RESTful API 是基于 REST（Representational State Transfer） 架构风格设计的接口规范。它的核心理念是通过 HTTP 协议 和 资源（Resource） 的概念，提供标准化的数据交互方式。

为什么选择 RESTful？

• 标准化：遵循 HTTP 方法（如 GET、POST）和状态码（如 200、404），降低沟通成本。
• 可扩展性：通过 URI 对资源进行统一标识，易于扩展新功能。
• 轻量级：通常使用 JSON 格式传输数据，减少传输开销。

类比：想象一个快递系统，每个包裹（资源）都有唯一的地址（URI），而 HTTP 方法对应操作：GET 是查询包裹信息，POST 是下单新包裹，PUT 是修改地址，DELETE 是取消订单。

PHP 实现 RESTful API 的核心步骤

1. 理解 HTTP 方法与资源设计

RESTful API 的设计围绕 HTTP 方法 和 资源路径 展开。以下是常见 HTTP 方法及其用途：

2. 路由设计：URI 的规范化

RESTful API 的 URI 需清晰表达资源路径，例如：

• GET /api/books：获取所有书籍
• POST /api/books：创建新书籍
• GET /api/books/1：获取书籍 ID 为 1 的详情

关键原则：

• 使用名词复数表示资源集合（如 /books）。
• 避免动词（如 /getBooks），优先用 HTTP 方法区分操作。

3. 处理 HTTP 请求与响应

步骤 1：接收请求

PHP 通过 $_SERVER['REQUEST_METHOD'] 和 $_SERVER['PATH_INFO'] 获取请求方法和路径。

// 获取请求方法
$method = $_SERVER['REQUEST_METHOD'];

// 获取 URI 路径（如 "/books/1"）
$uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

步骤 2：路由匹配与分发

通过路由表将 URI 和方法映射到处理函数：

$routes = [
    'GET /api/books' => 'handleGetBooks',
    'POST /api/books' => 'handlePostBook',
    // ...其他路由
];

// 匹配当前请求的 URI 和方法
$matchedRoute = null;
foreach ($routes as $route => $handler) {
    if (strpos($route, " ") === false) continue; // 格式错误
    list($httpMethod, $path) = explode(" ", $route);
    if ($httpMethod === $method && $path === $uri) {
        $matchedRoute = $handler;
        break;
    }
}

步骤 3：处理请求与生成响应

以 GET /api/books 为例，返回书籍列表：

function handleGetBooks() {
    // 模拟数据库查询
    $books = [
        ['id' => 1, 'title' => 'PHP进阶指南'],
        ['id' => 2, 'title' => 'RESTful设计模式']
    ];
    
    // 生成 JSON 响应
    header('Content-Type: application/json');
    echo json_encode(['data' => $books]);
}

4. 状态码与错误处理

HTTP 状态码是 RESTful API 的“沟通语言”，需规范使用：

示例：返回 400 错误

function handlePostBook() {
    if (empty($_POST['title'])) {
        http_response_code(400);
        echo json_encode(['error' => '标题不能为空']);
        exit;
    }
    // 继续处理...
}

实战案例：构建一个书籍管理 API

1. 定义资源与路由

假设我们需要管理书籍资源，设计如下接口：

2. 完整代码示例

<?php
// 定义路由表
$routes = [
    'GET /api/books' => 'handleGetBooks',
    'POST /api/books' => 'handlePostBook',
    'GET /api/books/{id}' => 'handleGetBookById',
    'PUT /api/books/{id}' => 'handlePutBook',
    'DELETE /api/books/{id}' => 'handleDeleteBook',
];

// 获取请求方法和路径
$method = $_SERVER['REQUEST_METHOD'];
$uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

// 处理 URI 参数（如 {id}）
if (strpos($uri, '/api/books/') === 0 && $uri != '/api/books') {
    $id = substr($uri, strlen('/api/books/') + 1);
    $uri = '/api/books/{id}';
}

// 匹配路由
$matchedRoute = null;
foreach ($routes as $route => $handler) {
    if (strpos($route, ' ') === false) continue;
    list($httpMethod, $path) = explode(' ', $route);
    if ($httpMethod === $method && preg_match('#^' . str_replace('{id}', '(\d+)', $path) . '$#', $uri)) {
        $matchedRoute = $handler;
        break;
    }
}

// 调用处理函数
if ($matchedRoute) {
    $response = $matchedRoute();
    header('Content-Type: application/json');
    echo json_encode($response);
} else {
    http_response_code(404);
    echo json_encode(['error' => '路由未找到']);
}

// 处理函数实现（简化版）
function handleGetBooks() {
    $books = [
        ['id' => 1, 'title' => 'PHP RESTful实战'],
        ['id' => 2, 'title' => 'API设计模式']
    ];
    return ['data' => $books];
}

function handlePostBook() {
    $title = $_POST['title'] ?? '';
    if (empty($title)) {
        http_response_code(400);
        return ['error' => '标题不能为空'];
    }
    // 模拟新增书籍
    $newBook = ['id' => 3, 'title' => $title];
    return ['data' => $newBook];
}

function handleGetBookById() {
    global $id;
    $books = [
        1 => ['id' => 1, 'title' => 'PHP RESTful实战'],
        2 => ['id' => 2, 'title' => 'API设计模式']
    ];
    if (!isset($books[$id])) {
        http_response_code(404);
        return ['error' => '书籍不存在'];
    }
    return ['data' => $books[$id]];
}

// 其他函数类似，根据逻辑实现

安全性与进阶优化

1. 防止常见攻击

• 输入验证：使用 filter_input 或第三方库（如 Respect\Validation）验证参数。
• CSRF 防护：在表单中添加令牌（Token），仅接受携带有效令牌的请求。
• HTTPS：强制使用加密协议传输数据，避免敏感信息泄露。

2. 分页与过滤

在返回大量数据时，添加分页参数：

// 接收分页参数
$page = $_GET['page'] ?? 1;
$pageSize = 10;

// 计算偏移量
$offset = ($page - 1) * $pageSize;
// 数据库查询时添加 LIMIT $offset, $pageSize

3. 使用框架提升效率

PHP 框架（如 Laravel 或 Slim Framework）内置 RESTful 路由和请求处理功能，大幅减少重复代码。例如，Laravel 的路由定义：

Route::apiResource('books', BookController::class);

结论

通过本文的讲解，开发者可以掌握 PHP RESTful API 的核心概念和实现方法。从基础的 HTTP 方法、路由设计到实战案例的完整流程，逐步构建了一个可扩展的 API 框架。在实际开发中，建议结合框架工具和最佳实践，进一步提升 API 的健壮性和安全性。

动手实践建议：

1. 尝试将代码示例部署到本地服务器，测试不同接口的响应。
2. 使用 Postman 或 curl 工具模拟 HTTP 请求。
3. 在现有项目中尝试重构接口为 RESTful 风格。

掌握 PHP RESTful API 的开发，不仅能提升代码的可维护性，还能为构建复杂的分布式系统打下坚实基础。