早些年刚带团队的时候我遇到过一件印象特别深的事。后端同事把接口文档写得密密麻麻前端同事每接一个接口都要在代码里写一段特判这个接口返回 0 是成功那个接口返回 200 才是成功获取用户列表要 GET 一个 user_list 的地址删除用户却要 POST 一个 user_delete 的地址参数还得放在 FormData 里。到最后两个人当着我的面吵起来前端说你接口设计反人类后端说你连文档都不仔细看。我当时就意识到问题的根源不在文档写得够不够详细而是接口本身缺一套统一的设计语言。后来我把团队接口协议整体迁移到 RESTful 风格前后端沟通成本肉眼可见地降了下来。这篇文章我不打算写那种“五步教你搭建 RESTful API”的速食教程而是想结合多年后端开发经验把 RESTful API 的设计原理、PHP 实现时的路由分发、认证跨域、状态码处理这些关键环节以及实际项目中容易踩的坑、上线前要做的安全加固和性能优化全部拆开揉碎了讲一遍。不管你用的是原生 PHP 还是 Laravel、ThinkPHP只要理解了这套底层逻辑写出来的接口都差不到哪去。1. RESTful API 不是“URL 长得好不好看”的问题1.1 先从“资源”说起REST 的全称是 Representational State Transfer中文常译作“表现层状态转移”听起来很抽象但核心思想其实就一句话把系统里的所有事物都建模成“资源”URL 只是资源的定位符HTTP 方法才是对资源施加的动作。以用户系统为例。/users 代表“用户集合”这个资源/users/42 代表“ID 为 42 的用户”这个资源。你要“查询”就 GET“创建”就 POST“整体替换”就 PUT“局部修改”就 PATCH“删除”就 DELETE。URL 里面只出现名词不出现动词。对比一下我早年见过的那种 RPC 风格接口GET /user_list查询用户列表POST /user_delete删除用户POST /user_update更新用户这种设计最大的问题在于URL 描述的是动作资源身份被边缘化前端拿到接口列表只能一条条记忆。更麻烦的是方法只有 GET 和 POST有些团队甚至用 GET 干删除的活浏览器地址栏一访问就把数据删了。打个比方你就明白了把 URL 想象成仓库货架编号HTTP 方法就是“放货、取货、清点、报废”这些动作。编号只告诉你在哪个货架动作由指令来表达。如果每个动作都单独设计一个“编号”仓库管理必然乱套。1.2 幂等性REST 之所以靠谱的关键幂等性这个概念很多人听说过但没有真正重视起来。简单说同一个请求执行一次和执行十次资源最终状态一致这个请求就是幂等的。GET 查询十次和一次结果一致天然幂等。PUT 把订单状态改成“已发货”改几次都是“已发货”天然幂等。DELETE 删除 ID 为 1 的用户第一次返回 204第二次可能返回 404但资源最终状态都是“不存在”从资源状态看也是幂等的。POST 不幂等。点两次提交按钮可能产生两笔订单这就是非幂等操作最典型的风险。为什么幂等性在真实项目中这么重要因为网络重试、消息队列重投、前端按钮被用户点了两下这些都是实际会发生的场景。如果删除接口后退路是“删两次报两次错”那倒还好但扣款、下单这一类非幂等操作一旦被重复执行就是事故。所以 RUE 设计风格才会刻意把 PUT、DELETE 放在和 GET 一样的位置上因为它们在语义上天然安全。而 POST 因为不幂等必须靠幂等键、唯一索引、防重令牌等手段来兜底。1.3 无状态与服务端 Session 的冲突REST 强调无状态意思是每个请求都应该自包含服务端不保存客户端上下文。这在业界的落地方案就是 Token 认证比如 JWT 或者 API Key。这跟传统 PHP 开发者习惯的$_SESSION思路几乎是相反的。很多 PHPer 初次接触 REST 时总习惯性地把用户信息塞进 Session一上 REST 就发现“怎么会话丢了”其实不是丢了而是设计模式变了。身份信息应该由客户端在每次请求时通过 Authorization 头携带服务端只负责验签和鉴权。无状态带来的直接好处是横向扩展非常方便。服务器从 1 台扩到 10 台不需要同步 Session因为客户端自己带着身份信息。这一点在做负载均衡、容器化部署时体会尤其深。2. 用原生 PHP 搭建 RESTful API 的基座2.1 环境这一层就把基础打牢我现在的实践推荐是 PHP 8.0 以上Nginx PHP-FPM并且一定要开 OPcache。PHP 8 带来的 union types、match 表达式、构造器属性提升这些特性写接口响应逻辑时相当顺手。Nginx 配置里最关键的是 rewrite 规则。RESTful 接口的路径是/api/v1/users/123并不对应服务器上的真实文件必须让所有请求都进入 index.php 统一处理。我常用的配置是这样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_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_pass 127.0.0.1:9000; } }如果是 Apache 环境根目录的 .htaccess 这样写RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^ index.php [QSA,L]这一步的核心思路是“统一入口”。所有请求先进 index.php中间可以做全局的 CORS 头、请求日志、异常捕获。如果每个 PHP 文件都直接对外暴露安全性和统一性都很难保证。2.2 一个 60 行的手写 Router很多 PHPer 一上来就用框架路由是框架给的但底层原理反而不清楚。我建议至少手写一次路由分发你才能真正理解 URL 是怎么映射到处理函数的。下面这个 Router 类足够支撑一个小型 API 项目?php declare(strict_types1); final class Router { private array $routes []; public function add(string $method, string $pattern, callable $handler): void { $this-routes[] [ method strtoupper($method), pattern #^ . $pattern . $#, handler $handler, ]; } public function dispatch(string $method, string $uri): void { $path parse_url($uri, PHP_URL_PATH) ?: /; foreach ($this-routes as $route) { if ($route[method] ! $method) { continue; } if (preg_match($route[pattern], $path, $matches)) { array_shift($matches); call_user_func_array($route[handler], $matches); return; } } json_response([error Not Found], 404); } }注册路由的方式长这样$router new Router(); $router-add(GET, /api/v1/users, function () { // 查询用户列表 }); $router-add(GET, /api/v1/users/(\d), function (int $id) { // 查询单个用户 }); $router-add(POST, /api/v1/users, function () { // 创建用户 }); $router-add(DELETE, /api/v1/users/(\d), function (int $id) { // 删除用户 }); $router-dispatch( $_SERVER[REQUEST_METHOD] ?? GET, $_SERVER[REQUEST_URI] ?? / );路由规则里的(\d)是正则表达式只匹配数字 ID。这样/api/v1/users/abc就不会误入详情接口而是直接走 404。call_user_func_array的作用是把匹配到的参数按顺序传给闭包array_shift($matches)则是把第一个元素完整匹配到的字符串去掉。如果项目再复杂我建议直接用 Slim 或 Laravel但底层路由原理也是这么个思路。手写一遍是为了吃透它。2.3 统一响应封装把返给前端的“形状”先定死接口最容易出乱子的地方是不同接口返回的 JSON 结构五花八门。有的返回{code:0, data:[...]}有的直接返回[...]前端根本没法写通用处理逻辑。我给出的统一封装是这样function json_response(mixed $data, int $status 200): void { http_response_code($status); header(Content-Type: application/json; charsetutf-8); echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); exit; }这里有两个常量必须要说明。JSON_UNESCAPED_UNICODE不开的话中文会被编码成\u56fe\u7247这种形式。前端能解析但你在浏览器里直接看接口返回时排查问题会非常痛苦。JSON_UNESCAPED_SLASHES则是防止 URL 里的斜杠被转义成\/影响日志可读性。再讲一个和“php 接口数组对象”相关的经典坑json_encode对关联数组输出 JSON 对象对索引数组输出 JSON 数组。如果你查了一批用户外层包了[data $users]当$users为空时PHP 8 会输出{data:[]}这是对的。但某些老框架或某些代码习惯会把空数组强转成{}前端一写res.data.length就直接报错。我建议的约定是列表永远返回[]对象才返回{}。实现时小心(array)强转和json_encode的默认行为别在这种地方给前端埋雷。顺便说一句PHP 7.3 以后可以给json_encode传JSON_THROW_ON_ERROR配合 try-catch 处理编码异常避免 JSON 编码失败时返回空字符串这种诡异问题。这个小细节能省不少排查时间。3. 认证、跨域与错误码接口好用不好用的分水岭3.1 Token 认证用 Bearer Token 替代 SessionREST 接口的无状态特性决定了认证方式必须走“客户端自带凭证”的路子。目前最通用的方案就是 Bearer Token把 Token 放在 Authorization 请求头里。我常用的基础实现function get_bearer_token(): ?string { $header $_SERVER[HTTP_AUTHORIZATION] ?? ; if (preg_match(/Bearer\s(.)/i, $header, $matches)) { return trim($matches[1]); } return null; } function require_auth(): void { $token get_bearer_token(); if ($token null) { json_response([error Unauthorized], 401); } // 从 Redis / 数据库验证 token // 这里假设有一个 TokenStore 类 $userId TokenStore::verify($token); if ($userId null) { json_response([error Token 无效或已过期], 401); } // 把用户 ID 放到全局后续业务逻辑用 Container::set(current_user_id, $userId); }这里有一个 Nginx 环境下的坑必须提醒Nginx 默认不会把Authorization头传给 PHP-FPM很多 PHPer 发现$_SERVER[HTTP_AUTHORIZATION]一直取不到就是这个原因。需要在 Nginx 配置里加上location ~ \.php$ { fastcgi_param HTTP_AUTHORIZATION $http_authorization; ... }为什么用 Authorization 头而不是自定义的X-Token头因为 Authorization 是 HTTP 标准头网关、日志组件、第三方中间件都认识它。以后想无缝切换 JWT也是走同一个头改动成本很小。关于 JWT 多说一句结构上分成 header.payload.signature 三段用点分隔。PHP 里可以用 firebase/php-jwt 这个库也可以手写 base64url 编码加 HMAC 签名。但签名密钥必须放在环境变量里绝不能提交进 Git。我在实际项目中见过把 SECRET_KEY 写死在代码仓库里导致 Token 全部可伪造的事故这个教训真的要引以为戒。3.2 CORS 跨域别再给前端写 JSONP跨域问题的本质是浏览器同源策略。后端要做的是在响应头里明确“哪些来源可以访问我”。这就是 CORS跨域资源共享机制。一个安全、可用的响应头配置header(Access-Control-Allow-Origin: https://admin.example.com); header(Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS); header(Access-Control-Allow-Headers: Content-Type, Authorization); header(Access-Control-Max-Age: 86400);有三个注意点。第一如果不是公共接口别用*要写具体域名。否则等于告诉全世界随便哪个网页都能拿你的接口发起请求CSRF 风险直接被放大。第二带 Authorization 头的请求属于“非简单请求”浏览器会先发一个 OPTIONS 预检请求。如果服务端不处理 OPTIONS前端就会遇到“明明接口通但浏览器报跨域”的诡异情况。最稳的处理方式是在路由分发之前直接拦截if (($_SERVER[REQUEST_METHOD] ?? ) OPTIONS) { http_response_code(204); exit; }第三Access-Control-Max-Age可以让浏览器缓存预检结果减少 OPTIONS 请求的次数对接口性能有肉眼可见的改善。顺带说一句JSONP 是上古时代的方案只能走 GET还有 callback 参数注入风险。现在 CORS 已经覆盖所有现代浏览器能让 JSONP 退休就让它退休。3.3 错误码双轨制HTTP 状态码描述“结果类别”业务码描述“具体原因”很多团队的接口所有响应都返回 200Body 里再塞一个code0或code5000。看起来“前端好处理”实际上是把 HTTP 协议的能力废掉了。正确做法是双轨并行HTTP 状态码表达请求结果的类别业务错误码表达具体原因。我整理了一份最常用的状态码速查表HTTP 状态码语义典型场景200 OK查询成功GET 请求返回资源201 Created创建成功POST 请求创建了资源204 No Content删除/更新成功且无返回体DELETE、PUT400 Bad Request参数格式错误缺少必填字段或类型错误401 Unauthorized未认证没有 token 或 token 过期403 Forbidden无权限已认证但越权访问404 Not Found资源不存在查询用户但用户不存在405 Method Not Allowed方法不允许GET /users 可以但 DELETE /users 不允许409 Conflict资源冲突用户名已被占用422 Unprocessable Entity语义校验失败邮箱格式不对429 Too Many Requests触发限流请求太频繁500 Internal Server Error服务端异常PHP 抛了未捕获异常502 Bad Gateway网关异常PHP-FPM 挂了后 Nginx 报 502统一错误响应格式我建议固定成{ error: { code: ORDER_ALREADY_PAID, message: 订单已支付无法重复操作, field: order_id } }error 对象里的字段固定为 code、message、field 三个field 只在参数级错误时出现。前端拿到 4xx 加 code 就直接弹 message拿到 5xx 统一提示“服务器开小差了”不用为每种错误都写一套处理逻辑。这套约定一旦定下来前后端联调效率直接上一个台阶。4. 真实项目避坑指南这些细节决定接口质量4.1 别把 PUT 当成“升级版 POST”REST 里 PUT 表示对资源的整体替换PATCH 表示部分更新。很多团队混用这两个方法文档写 PUT 做部分更新这在语义上是错的调用方也会困惑。举个例子更新用户的昵称字段。用PUT /users/1时请求体应该携带完整的资源字段昵称、头像、邮箱等服务端把整个资源替换掉。用PATCH /users/1时请求体只需要携带{nickname: 新昵称}服务端只改这个字段。如果你不想在两种方法之间纠结一个折中方案是全量更新用 PUT部分更新用 PATCH接口文档里明确定义清楚。但绝对不要出现“文档写 PUT 干 PATCH 的活”这种自相矛盾的情况。4.2 接口会变版本号就是从 /api/v1 开始的良药接口上线之后字段改名、新增必填参数、删除旧字段……任何改动都可能破坏已上线的客户端。所以从第一个接口开始就应该把版本号放 URL 里/api/v1/users、/api/v2/users。版本策略的几个要点URL 里带主版本号路径中途不轻易改。v1 和 v2 可以长期并存老客户端继续用 v1新客户端用 v2。v1 接口的废弃周期要在文档里写明比如“v1 将于 2026 年 1 月下线”。向下兼容的改动只增加字段、新增接口不升版本会破坏现有调用的改动比如改字段名、改语义、删字段必须升版本。Header 里也可以放版本号比如Accept: application/vnd.myapp.v2json但那样调试和日志排查都不直观。我推荐 URL 方式简单直接。4.3 参数校验的分寸400、422 和 409 的边界我见过最经典的错误是用户注册接口邮箱格式不对返回 400用户名重复也返回 400密码太弱也返回 400。前端拿到 400 根本分不清到底哪里错了。我的习惯是严格区分三种情况400请求本身不可解析比如 JSON 语法错误、缺少 Body、类型不匹配。422参数能解析但语义不合法比如邮箱格式错误、密码长度不足。409和当前资源状态冲突比如用户名已被注册、订单已支付不能取消。配合之前说的统一错误格式里的field字段前端可以精确地在对应输入框下提示错误。这是把后端校验转化为前端体验的关键一步。4.4 分页、排序、过滤的命名要提前统一接口一多大家各写各的就乱套了。我建议在团队规范里固定一套统一约定分页page页码从 1 开始、limit每页条数最大 100排序sortcreated_at:desc,id:asc多个字段用逗号分隔过滤直接用查询参数名对应字段如statusactivetypepremium响应里返回分页元信息{ data: [...], pagination: { page: 1, limit: 20, total: 523, total_pages: 27 } }注意一点不要让调用方通过遍历页数来拿全量数据。大数据量场景直接考虑游标分页那又是另一个话题了但至少先从 page/limit 这类最基础的约定开始。5. 上线前必须过的安全与性能关5.1 预处理 SQL选择参数而不是拼接字符串SQL 注入在接口类项目里尤其危险因为接口是公开入口任何人都能构造请求。最稳妥的做法就是 PDO 预处理配合占位符$pdo new PDO($dsn, $user, $pass, [ PDO::ATTR_EMULATE_PREPARES false, PDO::ATTR_ERRMODE PDO::ERRMODE_EXCEPTION, ]); $stmt $pdo-prepare(SELECT * FROM users WHERE email ?); $stmt-execute([$email]); $user $stmt-fetch();这里有个很多人不知道的坑PDO 默认开着模拟预编译EMULATE_PREPAREStrue在不支持原生预编译的场景下会把参数转义后直接拼进 SQL 里逻辑上还是拼接字符串。在 PHP 8 加 MySQL 的环境下建议显式关闭模拟预编译让数据库真正的预处理接管。这个细节很便宜但能挡住大多数注入攻击。5.2 限流接口公开之后第一件事就是防刷接口上线之后面对的不仅是真实用户还有爬虫、刷接口的脚本、甚至竞争对手。限流是第一道防线。最简单可靠的方案是 Redis 计数器按 IP 每分钟限制 120 次$key rate: . $_SERVER[REMOTE_ADDR]; $count $redis-incr($key); if ($count 1) { $redis-expire($key, 60); } if ($count 120) { header(Retry-After: 30); json_response([error Too Many Requests], 429); }按 IP 限流是最基础的方案生产环境一般还要配上用户维度限流、接口维度限流、甚至基于滑动窗口的算法。但“先有 429 语义加计数器”比“裸奔上线”强一百倍。429 状态码本身就告诉客户端“你太快了去等等”客户端能正确处理重试逻辑。5.3 缓存 304让重复请求少消耗一次 PHP-FPM对于 GET 详情类接口响应头加 ETag 能大幅降低后端压力。ETag 就是资源的版本标识客户端下次请求时带上If-None-Match服务端发现没变就直接返回 304连业务逻辑都不用跑$etag md5(json_encode($data)); if (isset($_SERVER[HTTP_IF_NONE_MATCH]) $_SERVER[HTTP_IF_NONE_MATCH] $etag) { http_response_code(304); exit; } header(ETag: . $etag);这个方法尤其适合不常变化的字典数据、配置数据。第一次请求时后端正常返回 200 加全量数据浏览器会记住 ETag。第二次请求时浏览器带着 ETag 来问“资源变了吗”没变就回 304PHP 这边不用重新走完整业务逻辑省一次数据库查询。5.4 全局异常捕获与日志线上排障的最后一道保险在入口文件最外层套 try-catch把未捕获异常统一拦下来try { $router-dispatch( $_SERVER[REQUEST_METHOD] ?? GET, $_SERVER[REQUEST_URI] ?? / ); } catch (Throwable $e) { error_log($e-getMessage() . . $e-getTraceAsString()); json_response([error Internal Server Error], 500); }注意一个原则500 的时候不要把异常细节如 SQL 语句、堆栈信息返回给客户端。这些信息是给开发看的暴露出去等于帮攻击者做情报收集。日志里记录全量信息响应里只给一句“服务器开小差了”。日志方面我习惯每个请求记一条结构化日志时间、method、path、status、耗时、用户 ID、IP。不用太复杂文本日志按天切割就够后期要接入 ELK 也容易。还有 PHP 的error_log一定要配好php.ini里的log_errors和error_log路径确认无误线上排障最怕的就是“出错没日志”。做完这么多接口项目我最大的体会是RESTful API 真正解决的并不是 URL 好不好看这种表面问题而是让团队对“接口应该长什么样”有一个共同的默认值。前端不用每次看文档都像做阅读理解后端也不用因为接口设计被前端追着改而焦头烂额。如果你正在从零搭一套接口哪怕项目很小也建议把资源的命名、状态码双轨、版本化、统一响应结构这些规范先立起来。规范这东西越往后迁移成本越高。最后再分享一个小经验接口文档别等写完了再补每注册一个路由就顺手在文档里把 method、路径、参数、示例响应和错误码写上。让文档跟着代码走你会省下无数次“这个接口到底传什么参数”的来回沟通。 
长河君 · 2026/10/8 3:17:55 · 阅读 1.2k RESTful API设计原理与PHP实现：从路由到安全加固的完整指南
早些年刚带团队的时候我遇到过一件印象特别深的事。后端同事把接口文档写得密密麻麻前端同事每接一个接口都要在代码里写一段特判这个接口返回 0 是成功那个接口返回 200 才是成功获取用户列表要 GET 一个 user_list 的地址删除用户却要 POST 一个 user_delete 的地址参数还得放在 FormData 里。到最后两个人当着我的面吵起来前端说你接口设计反人类后端说你连文档都不仔细看。我当时就意识到问题的根源不在文档写得够不够详细而是接口本身缺一套统一的设计语言。后来我把团队接口协议整体迁移到 RESTful 风格前后端沟通成本肉眼可见地降了下来。这篇文章我不打算写那种“五步教你搭建 RESTful API”的速食教程而是想结合多年后端开发经验把 RESTful API 的设计原理、PHP 实现时的路由分发、认证跨域、状态码处理这些关键环节以及实际项目中容易踩的坑、上线前要做的安全加固和性能优化全部拆开揉碎了讲一遍。不管你用的是原生 PHP 还是 Laravel、ThinkPHP只要理解了这套底层逻辑写出来的接口都差不到哪去。1. RESTful API 不是“URL 长得好不好看”的问题1.1 先从“资源”说起REST 的全称是 Representational State Transfer中文常译作“表现层状态转移”听起来很抽象但核心思想其实就一句话把系统里的所有事物都建模成“资源”URL 只是资源的定位符HTTP 方法才是对资源施加的动作。以用户系统为例。/users 代表“用户集合”这个资源/users/42 代表“ID 为 42 的用户”这个资源。你要“查询”就 GET“创建”就 POST“整体替换”就 PUT“局部修改”就 PATCH“删除”就 DELETE。URL 里面只出现名词不出现动词。对比一下我早年见过的那种 RPC 风格接口GET /user_list查询用户列表POST /user_delete删除用户POST /user_update更新用户这种设计最大的问题在于URL 描述的是动作资源身份被边缘化前端拿到接口列表只能一条条记忆。更麻烦的是方法只有 GET 和 POST有些团队甚至用 GET 干删除的活浏览器地址栏一访问就把数据删了。打个比方你就明白了把 URL 想象成仓库货架编号HTTP 方法就是“放货、取货、清点、报废”这些动作。编号只告诉你在哪个货架动作由指令来表达。如果每个动作都单独设计一个“编号”仓库管理必然乱套。1.2 幂等性REST 之所以靠谱的关键幂等性这个概念很多人听说过但没有真正重视起来。简单说同一个请求执行一次和执行十次资源最终状态一致这个请求就是幂等的。GET 查询十次和一次结果一致天然幂等。PUT 把订单状态改成“已发货”改几次都是“已发货”天然幂等。DELETE 删除 ID 为 1 的用户第一次返回 204第二次可能返回 404但资源最终状态都是“不存在”从资源状态看也是幂等的。POST 不幂等。点两次提交按钮可能产生两笔订单这就是非幂等操作最典型的风险。为什么幂等性在真实项目中这么重要因为网络重试、消息队列重投、前端按钮被用户点了两下这些都是实际会发生的场景。如果删除接口后退路是“删两次报两次错”那倒还好但扣款、下单这一类非幂等操作一旦被重复执行就是事故。所以 RUE 设计风格才会刻意把 PUT、DELETE 放在和 GET 一样的位置上因为它们在语义上天然安全。而 POST 因为不幂等必须靠幂等键、唯一索引、防重令牌等手段来兜底。1.3 无状态与服务端 Session 的冲突REST 强调无状态意思是每个请求都应该自包含服务端不保存客户端上下文。这在业界的落地方案就是 Token 认证比如 JWT 或者 API Key。这跟传统 PHP 开发者习惯的$_SESSION思路几乎是相反的。很多 PHPer 初次接触 REST 时总习惯性地把用户信息塞进 Session一上 REST 就发现“怎么会话丢了”其实不是丢了而是设计模式变了。身份信息应该由客户端在每次请求时通过 Authorization 头携带服务端只负责验签和鉴权。无状态带来的直接好处是横向扩展非常方便。服务器从 1 台扩到 10 台不需要同步 Session因为客户端自己带着身份信息。这一点在做负载均衡、容器化部署时体会尤其深。2. 用原生 PHP 搭建 RESTful API 的基座2.1 环境这一层就把基础打牢我现在的实践推荐是 PHP 8.0 以上Nginx PHP-FPM并且一定要开 OPcache。PHP 8 带来的 union types、match 表达式、构造器属性提升这些特性写接口响应逻辑时相当顺手。Nginx 配置里最关键的是 rewrite 规则。RESTful 接口的路径是/api/v1/users/123并不对应服务器上的真实文件必须让所有请求都进入 index.php 统一处理。我常用的配置是这样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_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_pass 127.0.0.1:9000; } }如果是 Apache 环境根目录的 .htaccess 这样写RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^ index.php [QSA,L]这一步的核心思路是“统一入口”。所有请求先进 index.php中间可以做全局的 CORS 头、请求日志、异常捕获。如果每个 PHP 文件都直接对外暴露安全性和统一性都很难保证。2.2 一个 60 行的手写 Router很多 PHPer 一上来就用框架路由是框架给的但底层原理反而不清楚。我建议至少手写一次路由分发你才能真正理解 URL 是怎么映射到处理函数的。下面这个 Router 类足够支撑一个小型 API 项目?php declare(strict_types1); final class Router { private array $routes []; public function add(string $method, string $pattern, callable $handler): void { $this-routes[] [ method strtoupper($method), pattern #^ . $pattern . $#, handler $handler, ]; } public function dispatch(string $method, string $uri): void { $path parse_url($uri, PHP_URL_PATH) ?: /; foreach ($this-routes as $route) { if ($route[method] ! $method) { continue; } if (preg_match($route[pattern], $path, $matches)) { array_shift($matches); call_user_func_array($route[handler], $matches); return; } } json_response([error Not Found], 404); } }注册路由的方式长这样$router new Router(); $router-add(GET, /api/v1/users, function () { // 查询用户列表 }); $router-add(GET, /api/v1/users/(\d), function (int $id) { // 查询单个用户 }); $router-add(POST, /api/v1/users, function () { // 创建用户 }); $router-add(DELETE, /api/v1/users/(\d), function (int $id) { // 删除用户 }); $router-dispatch( $_SERVER[REQUEST_METHOD] ?? GET, $_SERVER[REQUEST_URI] ?? / );路由规则里的(\d)是正则表达式只匹配数字 ID。这样/api/v1/users/abc就不会误入详情接口而是直接走 404。call_user_func_array的作用是把匹配到的参数按顺序传给闭包array_shift($matches)则是把第一个元素完整匹配到的字符串去掉。如果项目再复杂我建议直接用 Slim 或 Laravel但底层路由原理也是这么个思路。手写一遍是为了吃透它。2.3 统一响应封装把返给前端的“形状”先定死接口最容易出乱子的地方是不同接口返回的 JSON 结构五花八门。有的返回{code:0, data:[...]}有的直接返回[...]前端根本没法写通用处理逻辑。我给出的统一封装是这样function json_response(mixed $data, int $status 200): void { http_response_code($status); header(Content-Type: application/json; charsetutf-8); echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); exit; }这里有两个常量必须要说明。JSON_UNESCAPED_UNICODE不开的话中文会被编码成\u56fe\u7247这种形式。前端能解析但你在浏览器里直接看接口返回时排查问题会非常痛苦。JSON_UNESCAPED_SLASHES则是防止 URL 里的斜杠被转义成\/影响日志可读性。再讲一个和“php 接口数组对象”相关的经典坑json_encode对关联数组输出 JSON 对象对索引数组输出 JSON 数组。如果你查了一批用户外层包了[data $users]当$users为空时PHP 8 会输出{data:[]}这是对的。但某些老框架或某些代码习惯会把空数组强转成{}前端一写res.data.length就直接报错。我建议的约定是列表永远返回[]对象才返回{}。实现时小心(array)强转和json_encode的默认行为别在这种地方给前端埋雷。顺便说一句PHP 7.3 以后可以给json_encode传JSON_THROW_ON_ERROR配合 try-catch 处理编码异常避免 JSON 编码失败时返回空字符串这种诡异问题。这个小细节能省不少排查时间。3. 认证、跨域与错误码接口好用不好用的分水岭3.1 Token 认证用 Bearer Token 替代 SessionREST 接口的无状态特性决定了认证方式必须走“客户端自带凭证”的路子。目前最通用的方案就是 Bearer Token把 Token 放在 Authorization 请求头里。我常用的基础实现function get_bearer_token(): ?string { $header $_SERVER[HTTP_AUTHORIZATION] ?? ; if (preg_match(/Bearer\s(.)/i, $header, $matches)) { return trim($matches[1]); } return null; } function require_auth(): void { $token get_bearer_token(); if ($token null) { json_response([error Unauthorized], 401); } // 从 Redis / 数据库验证 token // 这里假设有一个 TokenStore 类 $userId TokenStore::verify($token); if ($userId null) { json_response([error Token 无效或已过期], 401); } // 把用户 ID 放到全局后续业务逻辑用 Container::set(current_user_id, $userId); }这里有一个 Nginx 环境下的坑必须提醒Nginx 默认不会把Authorization头传给 PHP-FPM很多 PHPer 发现$_SERVER[HTTP_AUTHORIZATION]一直取不到就是这个原因。需要在 Nginx 配置里加上location ~ \.php$ { fastcgi_param HTTP_AUTHORIZATION $http_authorization; ... }为什么用 Authorization 头而不是自定义的X-Token头因为 Authorization 是 HTTP 标准头网关、日志组件、第三方中间件都认识它。以后想无缝切换 JWT也是走同一个头改动成本很小。关于 JWT 多说一句结构上分成 header.payload.signature 三段用点分隔。PHP 里可以用 firebase/php-jwt 这个库也可以手写 base64url 编码加 HMAC 签名。但签名密钥必须放在环境变量里绝不能提交进 Git。我在实际项目中见过把 SECRET_KEY 写死在代码仓库里导致 Token 全部可伪造的事故这个教训真的要引以为戒。3.2 CORS 跨域别再给前端写 JSONP跨域问题的本质是浏览器同源策略。后端要做的是在响应头里明确“哪些来源可以访问我”。这就是 CORS跨域资源共享机制。一个安全、可用的响应头配置header(Access-Control-Allow-Origin: https://admin.example.com); header(Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS); header(Access-Control-Allow-Headers: Content-Type, Authorization); header(Access-Control-Max-Age: 86400);有三个注意点。第一如果不是公共接口别用*要写具体域名。否则等于告诉全世界随便哪个网页都能拿你的接口发起请求CSRF 风险直接被放大。第二带 Authorization 头的请求属于“非简单请求”浏览器会先发一个 OPTIONS 预检请求。如果服务端不处理 OPTIONS前端就会遇到“明明接口通但浏览器报跨域”的诡异情况。最稳的处理方式是在路由分发之前直接拦截if (($_SERVER[REQUEST_METHOD] ?? ) OPTIONS) { http_response_code(204); exit; }第三Access-Control-Max-Age可以让浏览器缓存预检结果减少 OPTIONS 请求的次数对接口性能有肉眼可见的改善。顺带说一句JSONP 是上古时代的方案只能走 GET还有 callback 参数注入风险。现在 CORS 已经覆盖所有现代浏览器能让 JSONP 退休就让它退休。3.3 错误码双轨制HTTP 状态码描述“结果类别”业务码描述“具体原因”很多团队的接口所有响应都返回 200Body 里再塞一个code0或code5000。看起来“前端好处理”实际上是把 HTTP 协议的能力废掉了。正确做法是双轨并行HTTP 状态码表达请求结果的类别业务错误码表达具体原因。我整理了一份最常用的状态码速查表HTTP 状态码语义典型场景200 OK查询成功GET 请求返回资源201 Created创建成功POST 请求创建了资源204 No Content删除/更新成功且无返回体DELETE、PUT400 Bad Request参数格式错误缺少必填字段或类型错误401 Unauthorized未认证没有 token 或 token 过期403 Forbidden无权限已认证但越权访问404 Not Found资源不存在查询用户但用户不存在405 Method Not Allowed方法不允许GET /users 可以但 DELETE /users 不允许409 Conflict资源冲突用户名已被占用422 Unprocessable Entity语义校验失败邮箱格式不对429 Too Many Requests触发限流请求太频繁500 Internal Server Error服务端异常PHP 抛了未捕获异常502 Bad Gateway网关异常PHP-FPM 挂了后 Nginx 报 502统一错误响应格式我建议固定成{ error: { code: ORDER_ALREADY_PAID, message: 订单已支付无法重复操作, field: order_id } }error 对象里的字段固定为 code、message、field 三个field 只在参数级错误时出现。前端拿到 4xx 加 code 就直接弹 message拿到 5xx 统一提示“服务器开小差了”不用为每种错误都写一套处理逻辑。这套约定一旦定下来前后端联调效率直接上一个台阶。4. 真实项目避坑指南这些细节决定接口质量4.1 别把 PUT 当成“升级版 POST”REST 里 PUT 表示对资源的整体替换PATCH 表示部分更新。很多团队混用这两个方法文档写 PUT 做部分更新这在语义上是错的调用方也会困惑。举个例子更新用户的昵称字段。用PUT /users/1时请求体应该携带完整的资源字段昵称、头像、邮箱等服务端把整个资源替换掉。用PATCH /users/1时请求体只需要携带{nickname: 新昵称}服务端只改这个字段。如果你不想在两种方法之间纠结一个折中方案是全量更新用 PUT部分更新用 PATCH接口文档里明确定义清楚。但绝对不要出现“文档写 PUT 干 PATCH 的活”这种自相矛盾的情况。4.2 接口会变版本号就是从 /api/v1 开始的良药接口上线之后字段改名、新增必填参数、删除旧字段……任何改动都可能破坏已上线的客户端。所以从第一个接口开始就应该把版本号放 URL 里/api/v1/users、/api/v2/users。版本策略的几个要点URL 里带主版本号路径中途不轻易改。v1 和 v2 可以长期并存老客户端继续用 v1新客户端用 v2。v1 接口的废弃周期要在文档里写明比如“v1 将于 2026 年 1 月下线”。向下兼容的改动只增加字段、新增接口不升版本会破坏现有调用的改动比如改字段名、改语义、删字段必须升版本。Header 里也可以放版本号比如Accept: application/vnd.myapp.v2json但那样调试和日志排查都不直观。我推荐 URL 方式简单直接。4.3 参数校验的分寸400、422 和 409 的边界我见过最经典的错误是用户注册接口邮箱格式不对返回 400用户名重复也返回 400密码太弱也返回 400。前端拿到 400 根本分不清到底哪里错了。我的习惯是严格区分三种情况400请求本身不可解析比如 JSON 语法错误、缺少 Body、类型不匹配。422参数能解析但语义不合法比如邮箱格式错误、密码长度不足。409和当前资源状态冲突比如用户名已被注册、订单已支付不能取消。配合之前说的统一错误格式里的field字段前端可以精确地在对应输入框下提示错误。这是把后端校验转化为前端体验的关键一步。4.4 分页、排序、过滤的命名要提前统一接口一多大家各写各的就乱套了。我建议在团队规范里固定一套统一约定分页page页码从 1 开始、limit每页条数最大 100排序sortcreated_at:desc,id:asc多个字段用逗号分隔过滤直接用查询参数名对应字段如statusactivetypepremium响应里返回分页元信息{ data: [...], pagination: { page: 1, limit: 20, total: 523, total_pages: 27 } }注意一点不要让调用方通过遍历页数来拿全量数据。大数据量场景直接考虑游标分页那又是另一个话题了但至少先从 page/limit 这类最基础的约定开始。5. 上线前必须过的安全与性能关5.1 预处理 SQL选择参数而不是拼接字符串SQL 注入在接口类项目里尤其危险因为接口是公开入口任何人都能构造请求。最稳妥的做法就是 PDO 预处理配合占位符$pdo new PDO($dsn, $user, $pass, [ PDO::ATTR_EMULATE_PREPARES false, PDO::ATTR_ERRMODE PDO::ERRMODE_EXCEPTION, ]); $stmt $pdo-prepare(SELECT * FROM users WHERE email ?); $stmt-execute([$email]); $user $stmt-fetch();这里有个很多人不知道的坑PDO 默认开着模拟预编译EMULATE_PREPAREStrue在不支持原生预编译的场景下会把参数转义后直接拼进 SQL 里逻辑上还是拼接字符串。在 PHP 8 加 MySQL 的环境下建议显式关闭模拟预编译让数据库真正的预处理接管。这个细节很便宜但能挡住大多数注入攻击。5.2 限流接口公开之后第一件事就是防刷接口上线之后面对的不仅是真实用户还有爬虫、刷接口的脚本、甚至竞争对手。限流是第一道防线。最简单可靠的方案是 Redis 计数器按 IP 每分钟限制 120 次$key rate: . $_SERVER[REMOTE_ADDR]; $count $redis-incr($key); if ($count 1) { $redis-expire($key, 60); } if ($count 120) { header(Retry-After: 30); json_response([error Too Many Requests], 429); }按 IP 限流是最基础的方案生产环境一般还要配上用户维度限流、接口维度限流、甚至基于滑动窗口的算法。但“先有 429 语义加计数器”比“裸奔上线”强一百倍。429 状态码本身就告诉客户端“你太快了去等等”客户端能正确处理重试逻辑。5.3 缓存 304让重复请求少消耗一次 PHP-FPM对于 GET 详情类接口响应头加 ETag 能大幅降低后端压力。ETag 就是资源的版本标识客户端下次请求时带上If-None-Match服务端发现没变就直接返回 304连业务逻辑都不用跑$etag md5(json_encode($data)); if (isset($_SERVER[HTTP_IF_NONE_MATCH]) $_SERVER[HTTP_IF_NONE_MATCH] $etag) { http_response_code(304); exit; } header(ETag: . $etag);这个方法尤其适合不常变化的字典数据、配置数据。第一次请求时后端正常返回 200 加全量数据浏览器会记住 ETag。第二次请求时浏览器带着 ETag 来问“资源变了吗”没变就回 304PHP 这边不用重新走完整业务逻辑省一次数据库查询。5.4 全局异常捕获与日志线上排障的最后一道保险在入口文件最外层套 try-catch把未捕获异常统一拦下来try { $router-dispatch( $_SERVER[REQUEST_METHOD] ?? GET, $_SERVER[REQUEST_URI] ?? / ); } catch (Throwable $e) { error_log($e-getMessage() . . $e-getTraceAsString()); json_response([error Internal Server Error], 500); }注意一个原则500 的时候不要把异常细节如 SQL 语句、堆栈信息返回给客户端。这些信息是给开发看的暴露出去等于帮攻击者做情报收集。日志里记录全量信息响应里只给一句“服务器开小差了”。日志方面我习惯每个请求记一条结构化日志时间、method、path、status、耗时、用户 ID、IP。不用太复杂文本日志按天切割就够后期要接入 ELK 也容易。还有 PHP 的error_log一定要配好php.ini里的log_errors和error_log路径确认无误线上排障最怕的就是“出错没日志”。做完这么多接口项目我最大的体会是RESTful API 真正解决的并不是 URL 好不好看这种表面问题而是让团队对“接口应该长什么样”有一个共同的默认值。前端不用每次看文档都像做阅读理解后端也不用因为接口设计被前端追着改而焦头烂额。如果你正在从零搭一套接口哪怕项目很小也建议把资源的命名、状态码双轨、版本化、统一响应结构这些规范先立起来。规范这东西越往后迁移成本越高。最后再分享一个小经验接口文档别等写完了再补每注册一个路由就顺手在文档里把 method、路径、参数、示例响应和错误码写上。让文档跟着代码走你会省下无数次“这个接口到底传什么参数”的来回沟通。