PHP 开发 API 接口完整教程

目录

1. 什么是 API？
2. 为什么选择 PHP 开发 API？
3. 核心概念：RESTful API
4. 开发环境准备
5. 从零开始：创建你的第一个 API
   • 1 项目结构
   • 2 数据库准备
   • 3 数据库连接 (config.php)
   • 4 数据模型 (User.php)
   • 5 API 路由和控制器 (api.php)
   • 6 启动并测试 API
6. 进阶：构建更健壮的 API
   • 1 统一 API 响应格式
   • 2 错误处理
   • 3 输入验证
   • 4 使用 JWT 进行身份认证
7. API 文档与测试工具
8. 部署与性能优化
9. 总结与最佳实践

什么是 API？

API (Application Programming Interface, 应用程序编程接口) 是一套预定义的规则和工具，允许不同的软件应用程序相互通信，你可以把它想象成餐厅里的服务员：

• 你：客户端应用程序 (如手机 App、网页)
• 厨房：服务器和数据库
• 菜单：API 规定了你可以“点”哪些“菜”（数据或功能）
• 服务员：API 接口，接收你的订单，去厨房取菜，再送回给你

最常见的 API 类型是 Web API，它通过 HTTP 请求在互联网上传输数据，通常使用 JSON 或 XML 格式。

为什么选择 PHP 开发 API？

• 成熟稳定：PHP 拥有超过 25 年的历史，被全球数百万网站使用，生态系统非常成熟。
• 学习成本低：对于 Web PHP 语法相对简单，易于上手。
• 框架丰富：有 Laravel、Symfony 等世界级框架，它们提供了强大的工具来快速构建健壮、可维护的 API。
• 社区庞大：遇到任何问题，你都能在 Stack Overflow、GitHub 等社区找到答案和帮助。
• 性能优异：随着 PHP 7/8 的发布，其性能得到了巨大提升，完全能满足大多数 API 的性能需求。

核心概念：RESTful API

REST (Representational State Transfer, 表述性状态转移) 是一种设计 Web API 的架构风格，它不是标准，而是一组原则，遵循 REST 风格的 API 称为 RESTful API，其核心原则包括：

• 资源：API 的核心是操作“资源”，资源通常用名词表示，/users, /products。
• 统一接口：
  • URI：通过唯一的 URI 来标识每个资源。
  • HTTP 方法：使用 HTTP 动词（方法）来对资源进行操作。
    • GET: 获取资源 (查询)
    • POST: 创建新资源 (创建)
    • PUT / PATCH: 更新现有资源 (更新)
    • DELETE: 删除资源 (删除)
  • 无状态：服务器不保存客户端的状态，每个请求都必须包含处理该请求所需的所有信息。
  • 使用 JSON/XML 作为数据格式：现代 API 普遍使用轻量级的 JSON。

开发环境准备

你需要一个本地服务器环境来运行 PHP，最简单的方式是安装集成环境包：

• XAMPP (Windows, macOS, Linux): 集成了 Apache, MySQL, PHP 和 Perl。
• WAMP (Windows): Windows 下的 Apache, MySQL, PHP 环境。
• MAMP (macOS): macOS 下的 Apache, MySQL, PHP 环境。

安装完成后,确保你的 Apache 和 MySQL 服务都已启动。

从零开始：创建你的第一个 API

我们将创建一个简单的用户管理 API，支持 GET 和 POST 方法。

1 项目结构

在你的 Web 服务器根目录（如 htdocs 或 www）下创建一个新项目，php-api-tutorial。

php-api-tutorial/
├── config.php       # 数据库配置
├── User.php         # 用户数据模型
├── api.php          # API 入口和路由
└── .htaccess        # URL 重写规则

2 数据库准备

使用 phpMyAdmin 或其他工具创建一个数据库和一张用户表。

CREATE DATABASE my_api_db;
USE my_api_db;
CREATE TABLE `users` (
  `id` INT AUTO_INCREMENT PRIMARY KEY,
  `name` VARCHAR(100) NOT NULL,
  `email` VARCHAR(100) NOT NULL UNIQUE,
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

3 数据库连接 (config.php)

创建一个文件来管理数据库连接信息。

<?php
// config.php
define('DB_HOST', 'localhost');
define('DB_USER', 'root'); // 你的数据库用户名
define('DB_PASS', '');     // 你的数据库密码
define('DB_NAME', 'my_api_db');
try {
    $pdo = new PDO("mysql:host=" . DB_HOST . ";dbname=" . DB_NAME, DB_USER, DB_PASS);
    // 设置 PDO 错误模式为异常
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
} catch(PDOException $e) {
    // 如果连接失败，返回 500 错误
    http_response_code(500);
    echo json_encode(['message' => '数据库连接失败: ' . $e->getMessage()]);
    exit();
}

4 数据模型 (User.php)

这是一个简单的模型类,用于处理与 users 表相关的数据库操作。

<?php
// User.php
require_once 'config.php';
class User {
    private $pdo;
    public function __construct($pdo) {
        $this->pdo = $pdo;
    }
    // 获取所有用户
    public function getAllUsers() {
        $stmt = $this->pdo->query("SELECT id, name, email, created_at FROM users ORDER BY created_at DESC");
        return $stmt->fetchAll(PDO::FETCH_ASSOC);
    }
    // 创建一个新用户
    public function createUser($name, $email) {
        $sql = "INSERT INTO users (name, email) VALUES (:name, :email)";
        $stmt = $this->pdo->prepare($sql);
        $stmt->bindParam(':name', $name);
        $stmt->bindParam(':email', $email);
        if ($stmt->execute()) {
            // 返回新创建的用户信息
            $userId = $this->pdo->lastInsertId();
            return $this->getUserById($userId);
        }
        return false;
    }
    // 辅助方法：根据ID获取用户
    public function getUserById($id) {
        $stmt = $this->pdo->prepare("SELECT id, name, email, created_at FROM users WHERE id = :id");
        $stmt->bindParam(':id', $id, PDO::PARAM_INT);
        $stmt->execute();
        return $stmt->fetch(PDO::FETCH_ASSOC);
    }
}

5 API 入口和路由 (api.php)

这是我们 API 的核心，它将根据请求的 URL 和 HTTP 方法，调用相应的处理逻辑。

<?php
// api.php
header("Content-Type: application/json; charset=UTF-8");
header("Access-Control-Allow-Origin: *"); // 允许所有来源访问 (开发环境)，生产环境应指定具体域名
header("Access-Control-Allow-Methods: GET, POST"); // 允许的请求方法
header("Access-Control-Allow-Headers: Content-Type, Access-Control-Allow-Headers, Authorization, X-Requested-With");
// 引入文件
require_once 'config.php';
require_once 'User.php';
// 获取请求方法和 URI
$method = $_SERVER['REQUEST_METHOD'];
$request_uri = $_SERVER['REQUEST_URI'];
// 简单的路由逻辑
$uri_segments = explode('/', trim($request_uri, '/'));
// 确保我们的 API 路径是 /api/users
if ($uri_segments[count($uri_segments) - 2] !== 'api' || $uri_segments[count($uri_segments) - 1] !== 'users') {
    http_response_code(404);
    echo json_encode(['message' => 'Not Found']);
    exit();
}
// 实例化用户模型
$user = new User($pdo);
// 处理不同的请求
switch ($method) {
    case 'GET':
        // GET /api/users -> 获取所有用户
        $users = $user->getAllUsers();
        echo json_encode($users);
        break;
    case 'POST':
        // POST /api/users -> 创建新用户
        $data = json_decode(file_get_contents("php://input"));
        if (!empty($data->name) && !empty($data->email)) {
            $new_user = $user->createUser($data->name, $data->email);
            if ($new_user) {
                http_response_code(201); // Created
                echo json_encode($new_user);
            } else {
                http_response_code(500); // Internal Server Error
                echo json_encode(['message' => '创建用户失败']);
            }
        } else {
            http_response_code(400); // Bad Request
            echo json_encode(['message' => '缺少必要字段 (name, email)']);
        }
        break;
    default:
        // 不支持的请求方法
        http_response_code(405); // Method Not Allowed
        header("Allow: GET, POST");
        echo json_encode(['message' => 'Method Not Allowed']);
        break;
}

6 启动并测试 API

1. URL 重写：为了让 URL 更美观（如 http://localhost/php-api-tutorial/api/users 而不是 http://localhost/php-api-tutorial/api.php/users），我们需要 .htaccess 文件。

   # .htaccess
   RewriteEngine On
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteCond %{REQUEST_FILENAME} !-d
   RewriteRule ^api/(.*)$ api.php [L,QSA]

   确保 Apache 的 mod_rewrite 模块已启用。

2. 测试 GET 请求： 在浏览器地址栏输入 http://localhost/php-api-tutorial/api/users 或使用 Postman/Curl。

   Curl 命令:

   curl -X GET http://localhost/php-api-tutorial/api/users

   预期响应 (如果数据库为空):

   []

3. 测试 POST 请求： 使用 Postman 或 Curl 发送一个 POST 请求。

   Curl 命令:

   curl -X POST http://localhost/php-api-tutorial/api/users \
   -H "Content-Type: application/json" \
   -d '{"name": "John Doe", "email": "john.doe@example.com"}'

   预期响应:

   {
     "id": 1,
     "name": "John Doe",
     "email": "john.doe@example.com",
     "created_at": "2025-10-27T10:00:00.000Z"
   }

再次执行 GET 请求，你应该能看到新创建的用户。

进阶：构建更健壮的 API

上面的例子很简单,但真实世界的 API 需要更完善的结构。

1 统一 API 响应格式

无论成功还是失败,API 都应返回一个结构化的 JSON 响应。

// 成功响应
{
  "status": "success",
  "data": { ... }
}
// 错误响应
{
  "status": "error",
  "message": "错误描述信息"
}

你可以在 api.php 中创建辅助函数来处理这些响应。

2 错误处理

除了 HTTP 状态码，还要在响应体中提供清晰的错误信息，使用 try...catch 块捕获数据库操作等异常，并返回 500 错误。

3 输入验证

永远不要信任客户端输入！使用 PHP 内置函数或第三方库（如 Respect/Validation）来验证和清理所有输入数据。

// 在 POST 处理中增加验证
if (filter_var($data->email, FILTER_VALIDATE_EMAIL) === false) {
    http_response_code(400);
    echo json_encode(['status' => 'error', 'message' => '无效的邮箱格式']);
    exit();
}

4 使用 JWT 进行身份认证

对于需要保护的 API，你需要一种认证机制。JWT (JSON Web Token) 是目前最流行的方式。

1. 安装 JWT 库 (例如使用 Composer):

   composer firebase/php-jwt

2. 创建认证逻辑：
   • 登录端点 (/api/auth/login)：验证用户名和密码，如果正确，生成一个 JWT 并返回给客户端。
   • 中间件：创建一个中间件函数，在每个受保护的 API 请求前执行，它会检查请求头中是否包含有效的 JWT，如果无效则拒绝访问。

API 文档与测试工具

• API 文档：清晰、准确的文档是 API 成功的关键，可以使用 Swagger / OpenAPI 规范来编写文档，并使用工具（如 Swagger UI）生成交互式文档。
• 测试工具：
  • Postman：功能强大的 API 测试客户端，可以保存请求、编写测试脚本、自动化测试。
  • Insomnia：Postman 的一个优秀替代品。
  • curl：命令行工具，适合快速测试和脚本自动化。

部署与性能优化

• 部署：将你的 API 部署到云服务器上，如 AWS, Google Cloud, DigitalOcean 或国内的阿里云、腾讯云，可以使用 Docker 进行容器化部署，确保环境一致性。
• 性能优化：
  • 缓存：对不经常变化的数据使用缓存（如 Redis, Memcached）。
  • 数据库索引：确保查询字段上有正确的索引。
  • 代码优化：使用 OPcache 编译缓存 PHP 脚本。
  • 负载均衡：对于高流量应用，使用负载均衡器将请求分发到多个服务器。

总结与最佳实践

1. 使用框架：对于任何严肃的项目，都强烈建议使用 Laravel 或 Symfony，它们提供了路由、Eloquent ORM (更强大的数据库操作)、中间件、认证等开箱即用的功能，让你专注于业务逻辑。
2. 保持简洁：URL 设计要简洁明了。
3. 版本控制：在 URL 中包含 API 版本号，如 /api/v1/users，这样你可以在不破坏现有客户端的情况下进行迭代。
4. 安全性第一：始终验证输入、防止 SQL 注入、XSS 攻击，使用 HTTPS。
5. 提供良好的文档：让你的 API 对他人（包括未来的你）易于理解和使用。
6. 保持一致性：保持命名、响应格式、错误处理方式的一致性。

这份教程为你提供了从零开始用 PHP 开发 API 的完整路径，从最基础的实现开始，逐步引入了更高级和更专业的概念，祝你开发顺利！