PHP RESTful API 接口设计实战：从路由到安全部署的完整指南

做过后端接口开发的兄弟应该都有这种体验：前端同事拿着接口文档过来问你“这个接口为什么又返回 500 了”，你打开日志一看，错误信息是“Call to undefined function”，再往上翻，发现上一个版本明明还能用，结果这次重构把公共函数文件忘了引入。这种事多了以后，你大概率会意识到一件事——接口设计不能靠拍脑袋，得有一套公共的约定。RESTful API 就是目前最主流的这套约定，而 PHP 作为服务端语言，从原生写法到 Laravel、Slim 这类框架，都能把这套约定落地得很干净。

这篇文章我不打算写成教科书式的概念复读，而是直接以“我要在 PHP 里做一个符合 RESTful 风格的接口”为出发点，把设计思路、代码实现、部署调试、踩坑实录一次讲透。适合三类人看：刚接触接口开发、想搞明白 RESTful 到底是啥的后端新手；已经写了一阵子接口但对状态码、路由设计、安全处理没系统梳理过的 PHP 开发者；以及要接手别人 PHP 接口项目、急需搞懂约定与坑的全栈同学。看完你至少能独立设计一套接口规范，并且知道在原生 PHP 和框架两种场景下分别怎么实现。

1. 先搞清楚 RESTful 到底在解决什么问题

很多教程一上来就列 RESTful 的六个约束条件，什么客户端服务端分离、无状态、统一接口、可缓存、分层系统、按需代码，背完照样写不好接口。我不打算这么讲，我只问你一个问题：前后端对接时，最混乱的情况是什么？答案是各写各的。后端把“获取用户列表”叫 getUserList，前端问接口文档，文档写的是“GET /api/user/list”，结果发现同一个需求在不同项目里 URL 长得完全不一样，参数命名一个写 user_id 一个写 uid，甚至还有人用 POST /api/getUserList 这种把动词塞进 URL 的写法。RESTful 解决的就是这种混乱：它把“操作”这件事从 URL 里剥离出来，交给 HTTP 方法去表达，让 URL 只负责描述“资源”。

1.1 把 HTTP 动词用对，接口就成功了一半

RESTful 的核心思想是“万物皆资源”。用户、订单、文章、图片，都是资源；对这些资源的操作，用 HTTP 方法表达：

• GET：查询资源，只读，不能改数据。
• POST：新建资源，每一次执行都产生新资源，不属于幂等操作。
• PUT：整体更新资源，通常要求提交完整数据，幂等。
• PATCH：局部更新资源，只提交需要修改的字段，幂等（实际上实现时常有出入）。
• DELETE：删除资源。

注意上面说的“幂等”这个词，好多人栽在这。幂等的意思是“执行一次和执行十次，结果一样”。GET 查询一百次不会多一条数据，DELETE 删一个不存在的用户也不会把别的用户删了，这俩都是幂等；但 POST 你发十次就创建十个用户，所以新建用 POST，更新用 PUT 或 PATCH，别反了。我见过最典型的错误是把“更新用户信息”这个操作做成 POST /api/user/update?id=1，这叫动作式 URL，不是资源式 URL。正确写法是 PUT /api/users/1，看到这个 URL 和动词，谁都知道你在改 id 为 1 的用户，不需要任何额外说明。

1.2 URL 设计与状态码：一眼看懂接口的“地址”和“脸色”

URL 设计的核心原则是名词复数 + 层级关系。/api/users 表示用户集合，/api/users/1 表示用户集合里的某一项，/api/users/1/orders 表示该用户的订单列表。这套设计天然有层级，前端拿到 URL 就能猜出资源关系，不需要背文档。反过来看坏味道：/api/getUserOrders、/api/userInfo、/api/deleteUser，这些写法的问题在于动词进了 URL，服务端实现时很难做统一路由，前端也无法从 URL 判断这是查询还是修改，等于把接口的“自解释性”丢掉了。

状态码这块，很多 PHP 项目常年只有三种状态：200、500、以及“自己 code 字段里塞一堆业务码但 HTTP 状态码永远 200”。这不是不行，但对调用方不友好。理想状态是 HTTP 状态码表达“本次请求结果的性质”，业务码表达“具体业务状态”。常见的组合是：

这里强烈建议：业务层正常返回时统一走 200 或 201，参数相关错误按上表返回，真正没捕获到的异常才扔 500。千万别把所有业务错误都塞进 200，否则前端永远要“先解析 body 才知道这请求到底成没成”，时间长了必然有同事在联调时骂人。状态码是接口的“脸色”，body 是“说的话”，脸色都不对，话再好听也没人敢信。

2. PHP 实现 RESTful 接口的几种路子

环境确认这一步，新手容易卡。我建议直接用 PHP 8.3 起一个新项目，原因很简单：命名参数、构造器属性提升、enum、readonly 属性这些特性在 8.0 之后都成熟了，写接口代码会舒服很多。PHP 8.3 在性能上也有提升，联合类型、类常量类型这些新增语法写起来更严谨。如果你在用 PHP 7.x，强烈建议升一下，不单是性能问题，很多现代 PHP 框架和组件库已经逐步放弃对旧版本的支持了。

2.1 环境准备：PHP 8.3 + Composer 就够了

本机开发环境，我试过的几类方案里，最稳的还是“本地 PHP + Composer”，尽量别直接改系统自带的 PHP，容易版本混乱。Windows 下如果你用 PHPStorm，直接在 Settings 里配置 PHP 解释器路径和 CLI 解释器就行，VSCode 则装 PHP Intelephense 插件，NetBeans 也支持配置 PHP 8.3 解释器，本质都一样：让 IDE 认识你的 PHP 版本和自动加载规则。服务器环境如果是宝塔面板，在软件商店装 PHP 8.3 再切站点运行目录就行；如果要一致性更高的部署，用 Docker 打包 PHP 8.3 + Nginx 镜像，composer install 的时候在容器内跑，这是团队协作最省心的方式。

Composer 的安装不细说，装完以后在项目根目录建一个 composer.json，引入框架或者写 PSR-4 自动加载规则。哪怕你打算原生写 API，我也建议用 Composer 管理依赖，后面加个 redis 客户端、加个 JWT 库，都是 composer require 一行命令的事。

2.2 原生 PHP 实现：一套极简路由打天下

不想引入框架的时候，原生 PHP 做 RESTful 也不难，关键在于把所有请求统一打到一个入口文件里。假设你的入口是 public/index.php：

php复制<?php

require __DIR__ . '/../vendor/autoload.php';

$method = $_SERVER['REQUEST_METHOD'];
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$path = rtrim($path, '/') ?: '/';

// 简单路由映射：路由规则 => [HTTP方法, 控制器方法]
$routes = [
    'GET /api/users'    => ['UserController', 'index'],
    'POST /api/users'   => ['UserController', 'store'],
    'GET /api/users/{id}' => ['UserController', 'show'],
    'PUT /api/users/{id}' => ['UserController', 'update'],
    'DELETE /api/users/{id}' => ['UserController', 'destroy'],
];

// 匹配路由
$matched = null;
$params = [];
foreach ($routes as $pattern => $handler) {
    [$routeMethod, $routePath] = explode(' ', $pattern, 2);
    if ($routeMethod !== $method) {
        continue;
    }
    $regex = preg_replace('#\{[a-zA-Z_]+\}#', '([^/]+)', $routePath);
    $regex = '#^' . $regex . '$#';
    if (preg_match($regex, $path, $matches)) {
        $matched = $handler;
        array_shift($matches);
        $params = $matches;
        break;
    }
}

if (!$matched) {
    http_response_code(404);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode(['code' => 404, 'message' => 'Not Found']);
    exit;
}

[$controllerName, $action] = $matched;
$controller = new $controllerName();
$response = $controller->{$action}(...$params);

header('Content-Type: application/json; charset=utf-8');
echo json_encode($response, JSON_UNESCAPED_UNICODE);

这段代码实现了最核心的“统一入口 + 方法分发 + 路由参数提取”。parse_url 是为了把 /api/users?page=1 里的查询字符串去掉，只留路径部分；rtrim($path, '/') 是为了让 /api/users/ 和 /api/users 被视为同一路由，避免前端多加一个斜杠就 404。匹配路由时用正则把 {id} 转成 ([^/]+)，这样 URL 里的动态参数就能被捕获并传给控制器。

2.3 用 Slim 框架：五分钟搭出一个规范接口

原生写法适合接口数量少的项目，接口多了以后路由分组、中间件、依赖注入都自己写会烦。Slim 4 是我在中小型 API 项目里用得比较顺手的框架，它轻量、专注做 HTTP 层，不绑定 ORM，你想用 PDO 还是 Eloquent 都行。安装很简单：

bash复制composer require slim/slim:"4.*"
composer require slim/psr7

然后入口 public/index.php：

php复制<?php

use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;

require __DIR__ . '/../vendor/autoload.php';

$app = AppFactory::create();

// 全局中间件：把异常转成 JSON 响应
$app->addErrorMiddleware(true, true, true);

// 用户资源路由组
$app->group('/api/users', function ($group) {
    $group->get('', UserController::class . ':index');
    $group->post('', UserController::class . ':store');
    $group->get('/{id}', UserController::class . ':show');
    $group->put('/{id}', UserController::class . ':update');
    $group->delete('/{id}', UserController::class . ':destroy');
});

$app->run();

这里 addErrorMiddleware 是调试阶段用的，会把异常详情输出为 JSON，生产环境请把前两个参数改成 false，避免把堆栈信息暴露给调用方。Slim 的路由分组能天然对应资源的层级关系，控制器类只需要实现 index、store、show、update、destroy 五个方法，就完美对应 1.1 里那五个 HTTP 动词，这就是 RESTful 风格带给代码结构的收益：约定统一，实现方式自然也跟着统一。

原生、微框架、重量级框架三条路线，我给出的选型建议非常直接：接口少于 10 个、你对 Composer 生态不熟，用原生方案先把接口跑通；接口 10 到 50 个、需要中间件处理 JWT 鉴权和日志，用 Slim；刚起步就是大项目、需要 ORM、迁移、队列、任务调度这些全套能力，直接用 Laravel，Laravel 的路由模型绑定能让你把 GET /api/users/{id} 直接绑定到 User 模型上，少写不少查找代码。选型没有对错，只有合不合适。

3. 核心细节：参数接收、响应结构、错误处理与安全

很多接口写着写着就乱，不是路由的问题，是细节没统一。这一节我把实操里最容易出问题的四个点逐个拆开讲。

3.1 参数接收的几个坑：$_POST 拿不到 JSON 是常态

我见过太多人调接口时发现 $_POST['name'] 是空的，第一反应是“前端没传”，其实问题出在 Content-Type。如果前端用 fetch 发 application/json，PHP 不会把 body 里的 JSON 自动解析进 $_POST，你得自己读 php://input 再 json_decode。原生写法：

php复制$rawBody = file_get_contents('php://input');
$data = json_decode($rawBody, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400);
    echo json_encode(['code' => 400, 'message' => 'Invalid JSON']);
    exit;
}

读取 php://input 之后，根据 Content-Type 判断解析方式：JSON 用 json_decode($rawBody, true)，普通表单用 parse_str($rawBody, $data)，这样 PUT、PATCH 和 DELETE 也能正确拿到请求体，而不是依赖 $_POST——$_POST 只在 application/x-www-form-urlencoded 或 multipart/form-data 时才有值，别让它成为你接口的参数唯一来源。

除了请求体解析，还有一个关于“参数来源”的设计建议：把查询参数、路径参数、请求体参数的来源分清楚。路径参数只能用于标识资源（比如 id），查询参数用于过滤、分页（比如 page、limit、keyword），请求体参数才用来承载要写入数据库的数据。三者混着用，前端调用时经常搞不清该把参数放 URL 还是放 body，这是接口设计细节上的失败。Slim 里三个来源分别对应 $request->getAttribute('routeArguments')、$request->getQueryParams()、$request->getParsedBody()，各取各的，非常清晰。

3.2 统一响应结构与错误处理：前端省心，后端省事

一个项目里如果有两套响应格式，比如 A 接口返回 {"code": 0, "data": [...]}，B 接口返回 {"success": true, "result": {...}}，前端写个统一的请求封装都无从下手。我建议所有接口使用统一信封结构：

json复制{
    "code": 0,
    "message": "success",
    "data": {},
    "meta": {
        "page": 1,
        "limit": 20,
        "total": 153
    }
}

• code：业务状态码，0 代表成功，非 0 代表具体的业务错误。
• message：人类可读的提示信息。
• data：业务数据主体，没有数据时返回 {} 或 null。
• meta：分页、耗时等信息，列表接口常用。

这个结构的价值在于，前端可以用同一个拦截器处理所有接口：先看 code，不是 0 就弹错误提示；是 0 再用 data。服务端实现时，建议写一个 ApiResponse 类统一构造这个信封，而不是在每个控制器里手写 json_encode。顺手把响应头里的 Content-Type: application/json; charset=utf-8 也在公共入口统一设置，避免中文字符串被浏览器按 ISO-8859-1 解析。

错误处理上，原生 PHP 有 set_exception_handler，建议把未捕获的异常统一转成 500 JSON 响应，并且记录完整堆栈到日志文件；Slim 直接使用 ErrorMiddleware，再配合自定义的 ErrorHandler 返回统一信封格式。这里有一个关键点：业务预期内的错误应该用 return 返回，业务预期外的错误才用 throw 抛出。比如用户传了一个不存在的 id，控制器应该返回 404 的 JSON，而不是 throw 一个异常然后让全局兜底——这两者虽然都会返回 404 响应，但日志里完全不同，前者是正常业务流，后者会被你当成系统故障排查半天。

3.3 认证与鉴权：不能让任何人都能调你的接口

RESTful 接口默认是无状态的，所以认证方案一般用 token 而不是 session。最简单的方案是每次请求带一个 Authorization: Bearer <token> 头，服务端解析 token，确定用户身份。PHP 里可以用 Firebase JWT：

bash复制composer require firebase/php-jwt

Slim 里的中间件写法：

php复制use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Http\Server\RequestHandlerInterface as Handler;

$app->add(function (Request $request, Handler $handler) {
    $authHeader = $request->getHeaderLine('Authorization');
    if (!preg_match('/Bearer\s+(.+)/i', $authHeader, $matches)) {
        $response = new \Slim\Psr7\Response();
        $response->getBody()->write(json_encode(['code' => 401, 'message' => '未登录']));
        return $response->withStatus(401)->withHeader('Content-Type', 'application/json; charset=utf-8');
    }

    try {
        $decoded = JWT::decode($matches[1], new Key('your-secret-key', 'HS256'));
        $request = $request->withAttribute('userId', $decoded->sub);
    } catch (\Exception $e) {
        $response = new \Slim\Psr7\Response();
        $response->getBody()->write(json_encode(['code' => 401, 'message' => 'token 无效或过期']));
        return $response->withStatus(401)->withHeader('Content-Type', 'application/json; charset=utf-8');
    }

    return $handler->handle($request);
});

这里把解码后的用户 ID 塞进请求属性里，后面的控制器直接用 $request->getAttribute('userId') 就能知道当前操作者是谁，不需要每个控制器里重复解析 token。鉴权只做到这步还不够，还有一个特别容易被忽视的问题是“越权”。比如用户 A 登录后，DELETE /api/orders/100 删掉了用户 B 的订单，如果你只校验“是否登录”不校验“资源是否属于当前用户”，这就是一个严重的水平越权漏洞。在控制器的 destroy 方法里，一定要把订单归属加上：WHERE id = ? AND user_id = ?，或者先查订单再比对 userId。RESTful 的资源路径设计天然暴露了资源标识，防越权责任就全在服务端了，这条路一步都不能省。

输入校验和安全这块也顺带说一句：所有参数都不可信。原生 PHP 里注意 SQL 注入，PDO 预处理是底线；框架里则依赖 Validator 规则，比如 Slim 可以配 respect/validation，Laravel 自带 validate。字段长度、枚举值、数字范围都要校验，别指望前端帮你做。我见过一个真实事故：前端把 price 字段传成了负数，后端的优惠券计算逻辑没校验，结果用户下单后账户余额变成了负数，这种问题的根源就是后端校验缺失。RESTful 接口对外暴露了数据操作能力，输入校验就是你的第一道防线。

3.4 接口里的中文与数组对象：序列化别留隐患

PHP 的 json_encode 默认会对中文做 Unicode 转义，"张三" 会变成 "\u5f20\u4e09"。直接返回给前端虽然功能没错，但阅读接口文档的人会崩溃，抓包看也费劲。所以只要返回 JSON，统一加上 JSON_UNESCAPED_UNICODE：

php复制echo json_encode($data, JSON_UNESCAPED_UNICODE);

同理，json_encode 默认会把空数组序列化成 []，把关联数组序列化成 {}。如果你的业务里某个字段需要固定返回对象结构，比如 emptyObj 在客户端期望是 {}，你在 PHP 里应该写成 (object)[] 而不是 []，这是数组对象序列化经常被忽略的细节。接口文档里如果写明了响应结构，尽量保证字段类型稳定，null、[]、{} 三种形态之间随意变化会让前端的类型判断崩溃。

再补充一个关于编码的细节：响应头里已经声明了 charset=utf-8，数据库连接层面也要统一 utf8mb4。PHP 的 PDO 连接 MySQL 时，DSN 里可以指定 charset=utf8mb4，不要用默认的 utf8，否则表情符号或生僻字存进数据库就变成乱码，接口返回的时候再经 json_encode 一折腾，前端看到的就是一串诡异的字符。接口层面的“中文不乱码”这件事，十次有八次不是编码函数的问题，是链路源头就没统一。

4. 部署、调试与性能优化：接口能从本地跑到服务器

本地接口跑通了，部署到服务器上又是一堆幺蛾子。最典型的就是“404 了，但路由明明存在”，十次里有九次是 Web 服务器没配置好 URL 重写。PHP 内置服务器 php -S 会在路由匹配不到时直接返回 404，而正式环境用的 Nginx 或 Apache 需要把请求重写到入口文件。

4.1 Nginx 与 Apache 的 URL 重写配置

Nginx 下站点配置：

nginx复制server {
    listen 80;
    server_name api.example.com;
    root /var/www/api/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

核心就是 try_files $uri $uri/ /index.php?$query_string;。这条指令的意思是：先尝试按请求路径找真实文件，找不到就把请求交给 index.php 处理，查询字符串保留。没有这一行，/api/users 永远找不到对应的物理路径，直接 404。

Apache 下用 .htaccess：

apache复制RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [QSA,L]

逻辑一样：只有请求的文件或目录不存在时才走前端控制器，静态资源（图片、CSS、JS）直接由 Apache 返回，避免所有请求都进 PHP 拖慢速度。部署完配置后一定要 nginx -t 或重启服务，不然配置不生效，排查时把这个放在第一步。

4.2 跨域与 JSONP：前端调用接口的最后一公里

前端站点跑在 http://localhost:3000，接口跑在 http://localhost:8080，浏览器发请求时一定有跨域问题，因为端口不同就属于不同源。后端接口要允许跨域，最简单的办法是中间件给所有响应加三个头：

php复制header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type, Authorization');

注意预检请求。前端如果带了自定义头（比如 Authorization: Bearer xxx）或用 application/json，浏览器会先发一个 OPTIONS 请求探路，后端必须放行这个请求，直接返回 200，不然真正的业务请求根本发不出去。原生 PHP 里可以在入口文件最顶部判断：

php复制if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(200);
    exit;
}

还有 JSONP 这种老方案，热词里有人搜“php 跨域 jsonp”，说明老项目里还在用。JSONP 的原理是利用 <script> 标签不受跨域限制，服务端返回一段 JS 而不是 JSON。PHP 写法是把回调函数名包住数据：

php复制$callback = $_GET['callback'] ?? 'callback';
header('Content-Type: application/javascript; charset=utf-8');
echo $callback . '(' . json_encode($data, JSON_UNESCAPED_UNICODE) . ')';

但 JSONP 只支持 GET，不支持 POST，而且有 XSS 风险（回调名如果没过滤，可能执行恶意代码），新项目一律别用，直接 CORS。JSONP 只适合拿来兼容老系统，别让它在你的新接口里复活。

4.3 调试工具与日志：接口出问题时怎么快速定位

接口调试工具我推荐 Postman 或者 Apifox，后者对国内的协作场景更友好。调试 RESTful 接口的关键是：把请求方法和 Content-Type 设置对，再把环境变量配好，比如 {{baseUrl}} 指向本地或测试环境，切换环境时不用一个个改 URL。还有个技巧是用 Postman 的 Collection 管理接口用例，接口文档更新后，前端直接导入 Collection 就能调试，不用再手工对着文档敲请求。

日志这块，PHP 项目常见的问题是把 display_errors 开着运行在生产环境，导致接口报错时把 PHP 报错原文、文件路径甚至数据库连接信息直接输出到响应里。生产环境一定要把错误显示关掉，错误日志记录到文件：

php复制ini_set('display_errors', '0');
ini_set('log_errors', '1');
ini_set('error_log', __DIR__ . '/../logs/php-error.log');

中间件产生的异常、外部接口调用失败、认证失败这些业务日志，也建议单独记录，而不是都堆在 PHP error log 里。日志字段至少包含：时间、请求方法、URL、状态码、耗时、请求体摘要、响应体摘要（注意敏感信息脱敏）。有了这套日志，别人反馈“接口突然慢了”的时候，你直接看耗时最高的记录就行，不用靠猜。

4.4 性能优化：缓存、队列与耗时任务处理

RESTful API 里最常见的性能瓶颈是数据库查询。列表页每次请求都全表扫描，再大的机器也扛不住。优化顺序我建议是：先加数据库索引，再上 Redis 缓存，最后才考虑改架构。缓存维度可以从“接口级缓存”做起，也就是相同请求参数的结果缓存几分钟：

php复制$cacheKey = 'api_users_' . md5($queryString);
$data = $redis->get($cacheKey);
if ($data === false) {
    $data = $userModel->getList($page, $limit);
    $redis->setex($cacheKey, 60, json_encode($data));
}

这会带来一个一致性问题：用户改了自己的资料，缓存还是旧的。解决方案是在更新资源的操作里主动删除对应的缓存 key，或者缓存时间设短一点。接口的强一致性和性能本来就是一对矛盾，你需要根据业务场景选。

热词里有人搜“php 队列”，放在接口场景下最典型的用途是处理耗时任务。比如上传了一个 Excel 要批量导入用户，如果直接在请求里同步处理，前端会白等几十秒；正确做法是把任务 ID 返回给前端，后台用 Redis 队列或消息队列异步处理。PHP 生态里做队列可以用 Laravel Queue，或者独立的 beanstalkd、Redis + resque。接口设计上，这种异步任务一般走两步：第一步 POST 提交任务，返回 202 Accepted 和一个任务 ID；第二步前端用任务 ID 轮询或长轮询 GET /api/tasks/{id} 拿结果。注意这里的 202 状态码很少见但很准确，符合 RESTful“状态码表达请求结果性质”的原则。

5. 常见问题排查与避坑清单

写接口时间长了，你会发现坑来来回回就那么几个。我整理了一张“问题速查表”，每条都是我或者身边同事踩过的真实案例：

5.1 关于“200 永远成功”的执念

很多人写接口时有个错误执念：只要业务逻辑没崩溃，就返回 200。比如删除一个不存在的资源，明明应该返回 404，但他偏要返回 {"code": 1, "message": "记录不存在"} 加 200。这种做法的坏处是：HTTP 层无法感知业务异常，前端轮询接口健康状态、网关做限流和熔断时全都会误判。RESTful 的语义是把业务结果和 HTTP 状态码对齐，不是说绝不能返回业务错误，而是“错误必须用错误的状态码表达”。从今天开始，把“记录不存在”从 200 改成 404，把“参数校验失败”从 200 改成 422，你会少接很多前端同事的“这个接口为什么成功了却没数据”的质询电话。

5.2 别忽略 API 文档的维护

代码写得再规范，没有文档也是白搭。我见过太多项目接口文档在接口改了之后忘了同步，前端按旧文档调，后端按新代码返，两边对不上，最后都跑来问后端“你是不是改坏了”。解决方案有两个层面的：产出层面，可以用 Apifox 或 OpenAPI 规范来写文档，接口定义和文档尽量用同一份数据源；流程层面，接口变更必须在合并代码的同时更新文档，把这个动作写成团队约定，不更新文档不允许合并。文档里至少包含：URL、方法、请求头、请求参数（名称、类型、必填、说明）、响应示例、状态码对照。RESTful 的 URL 设计得再好，也没法替代一份清楚直白的文档。

5.3 从业务角度反推接口设计

这一条送给所有刚开始设计接口的同学：写接口之前，先回答三个问题——这个资源的生命周期是怎样的？谁会调用它？调用频率高吗？前面两个问题决定你的 URL 和权限设计，第三个问题决定你需不需要加缓存。举个例子，做“图书管理系统”的借阅功能时，你可能会本能的想写 POST /api/borrow 和 POST /api/return，但这两个动作本质上都是“操作借阅记录这个资源”：借书是新建一条借阅记录，还书是更新这条记录到已还状态。用 RESTful 的表达方式就是 POST /api/borrow-records 和 PUT /api/borrow-records/{id}。这样设计的好处是，借阅记录天生支持查询“谁借了什么书”“某本书被谁借走”，不需要额外的统计接口。把操作翻译成资源状态变化，是 RESTful 设计里最值得练习的思维方式。

5.4 一个老项目里“扫雷”式的接口改造经验

我去年接手过一个老系统，里面有几十个动作式接口，什么 getUserInfo、updateUserPassword、getOrderListByUser，前端调用时到处翻文档。我花了一周时间把核心接口按 RESTful 重写了一版：URL 全部换成资源式，状态码对齐语义，响应统一信封结构。改造过程里踩了一个大坑：老接口和新接口并行跑了一段时间，前端同事没注意切换 baseUrl，把新接口的响应格式按老的解析，导致页面白屏。所以接口重构务必注意三点：新旧接口并行时要有明确的时间窗口；响应结构变更一定要通知到所有调用方；灰度切换时用日志对比新旧接口的返回差异，而不是直接大版本切换。RESTful 改造不是把 URL 改个名字就完事，它是接口行为的一次重构，牵一发动全身，稳一点总没错。

到这儿，RESTful API 在 PHP 里的完整落地链路就梳理完了。从设计原则到状态码规范，从原生 PHP 到 Slim 框架，从参数解析、安全认证到部署调试、性能优化，再到斜率和避坑，每一环我都给出了能直接用起来的建议。我个人在实际项目里的体会是：RESTful 不是银弹，但它是一面很好的镜子，你设计接口时脑子越清楚，写出来的代码就越省心；反过来，接口改了三版还对不齐，多半不是工具问题，是资源边界没想明白。如果你正动手写自己的第一个 PHP 接口，建议先别急着上框架，用原生实现一版资源式路由，感受一下“动词交给 HTTP、URL 只描述资源”的思路；踩过几次坑之后，再切到 Slim 或 Laravel，你会明白每个设计约定背后的代价和收益。