韩东晖做PHP做了十年，中间面试过的候选人没有五百也有三百。有个现象特别有意思：写了三五年PHP的开发者，你让他聊框架、聊语法、聊设计模式，他能跟你聊一下午；但你要是让他设计一个接口的返回结构，或者问问他"线上接口报错了怎么排查"，很多人会突然卡壳。这期是PHP后端十年系列的第七篇，我想认真聊聊一个常被忽视、但恰恰是区分"会写PHP"和"资深PHP后端"的分水岭——接口的数据契约、错误处理和前后端协作。
框架每年都在变，从早期的ThinkPHP 3.2.3到后来的Laravel、Hyperf，语法在变、写法在变，但有一件事十年都没变过：你的接口返回给前端的那份数据，决定了整个系统的稳定性、可维护性和团队协作效率。今天这篇不聊具体某个框架的用法，而是聊一套我在十年实战中总结出来的接口设计方法论。无论你用的是老牌的ThinkPHP，还是Laravel，亦或是自己写原生的PHP接口，这套东西都能直接套用。
本期内容适合谁？已经能独立写接口、但想往资深方向走的后端开发者；被前端频繁吐槽"接口又变了""字段又对不上"的PHP同学；以及项目里接口文档形同虚设、全靠口头沟通的团队。我会从数据契约、数组与对象的选择、序列化陷阱、错误处理体系、跨域协作、性能安全这六个维度展开，每一块都是实际项目中真金白银踩出来的经验。
1. 为什么十年PHP后端，最值钱的不是框架而是数据契约
先讲一个我亲身经历的项目。那是我职业生涯第三年接手的系统，用的是当年很流行的ThinkPHP 3.2.3，框架老旧，代码里甚至还有mysql_query的痕迹。但神奇的是，这个项目维护起来并不痛苦。为什么？因为它的接口层写得极其规范——每个接口返回什么结构、什么字段、什么类型，在一份wiki文档里写得清清楚楚，代码里的返回语句也严格遵循这个结构。
后来我又接触过一个用着最新框架的项目，技术栈光鲜亮丽，但接口返回乱七八糟。同一个"获取用户信息"的接口，有的地方返回user_id，有的地方返回uid，有的地方嵌套在data里，有的地方直接平铺。前端每联调一个页面就要来问一次"这个字段到底叫什么"。半年后这个项目就陷入了无尽的扯皮中，重构成本高到没人敢动。
这就是数据契约的意义。数据契约是接口层面的一组约定：返回数据的固定结构、字段命名规则、字段类型定义、错误码体系、分页格式、时间格式。它不是某个框架的专属概念，而是所有前后端协作场景下的底层共识。框架会过时，语言会更新，但一份清晰稳定的数据契约，五年后依然能指导新来的同事快速上手。
PHP里做数据契约为什么格外难？因为PHP是动态类型语言，关联数组太自由了。你在一个方法里return ["name" => "张三", "age" => 20]，另一个方法里return ['name' => '李四', 'age' => '20']。前者age是int，后者age是string，前端用JS做全等判断的时候就会莫名其妙出bug。动态类型给了开发者极大的自由度，但也让接口的"隐含约定"只能靠自觉去维持。这就是为什么PHP项目里接口返回来一个数据结构，前端解析时会出现各种诡异问题的根源。
所以，如果你想往资深方向走，第一件事不是去学什么新框架，而是建立你负责的每个接口的"数据契约意识"。每次写接口返回之前，先问自己三个问题：这个接口返回的结构是固定的吗？字段命名和项目里其他接口一致吗？字段类型是明确且稳定的吗？这三个问题想清楚了，你写的接口就已经超过一半的同行了。
1.1 一个接口返回结构的反面教材
先看一个我经常在面试中拿出来当反例的接口返回：
php复制// 反面示例：结构混乱、字段命名随意、类型不明确
public function getUserInfo()
{
$user = Db::name('user')->find($this->request->param('id'));
if ($user) {
return json([
'code' => 0,
'data' => [
'user_name' => $user['username'],
'uid' => $user['id'],
'age' => $user['age'], // 可能是字符串，可能是数字
'info' => $user['remark'] ?? '', // 有时有，有时没有
],
'msg' => 'success'
]);
} else {
return json([
'status' => -1,
'message' => '用户不存在'
]);
}
}
这个接口的问题一抓一大把：成功时字段叫code/data/msg，失败时字段叫status/message，前端要做两次判断；同一个用户标识有时叫uid有时叫user_id；age字段类型不确定；info字段时有时无。最致命的是成功和失败返回了完全不同的两层结构，前端必须用两个分支去解析。这种代码在项目里存活三年，就是在给团队持续制造bug和维护成本。
1.2 一套可以抄作业的标准返回结构
我在团队里推行了快七年的标准返回结构，简单到没有任何学习成本：
json复制{
"code": 0,
"message": "ok",
"data": {
"user_id": 1001,
"username": "zhangsan",
"age": 20
}
}
配套几条铁律：code为0时表示成功，非0表示业务失败；message是对code的人类可读描述，成功时为"ok"；data只存放业务数据，失败时可以是null或空对象；所有字段名统一使用下划线风格（后面会讲为什么）；所有固定字段类型明确，age一定是int，username一定是string，不存在就返回null而不是缺字段。
这套结构看起来简单，但能长期坚持下来非常不容易。尤其是在业务快速迭代时，很多开发者图省事，随手在data里塞一个临时字段，或者为了省一次查询把不需要的字段也返回了。这种"省事"短期看没什么，长期就是在腐蚀数据契约。我见过太多项目，接口返回结构从初始的清晰规范，慢慢变成一个没人敢动的巨型怪物。守住规范，比建立规范难十倍。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 从数组到对象：接口返回数据的结构设计与演变
说完了数据契约的整体框架，接下来聊一个更具体的问题：接口返回数据到底用关联数组还是对象？十年前PHP后端的主流做法是直接返回数组，现在越来越多的项目在回归对象（DTO，Data Transfer Object）。这不是谁比谁高级的问题，而是在项目复杂度上升后，数组的局限性会逐渐暴露，对象的优势会越来越明显。
2.1 数组的便利与隐患
数组是PHP的"舒适区"。写起来快，json_encode一把梭，读起来也直观。在小项目、临时脚本、快速迭代的场景下，数组完全够用，我没必要劝你非得上对象。
但数组的隐患在于"没有结构约束"。假设你有一个方法返回用户数据：
php复制return [
'id' => $user->id,
'name' => $user->name,
'email' => $user->email,
];
今天没问题。三个月后，另一个人在这个方法里加了一个字段'avatar' => $user->getAvatar()，但他把getAvatar()写错了，返回了null。由于数组没有类型约束，这个null会悄无声息地通过json_encode变成"avatar": null传给前端。前端拿到null后，有的页面做了判空，有的页面没做，于是线上出现一个时好时坏的bug。排查半天，最后发现是后端某个方法返回了null但没人发现。这种问题在动态类型语言里尤其隐蔽，因为它不会报错，只会让你的数据在你意想不到的地方变质。
另一个更隐蔽的问题是重构困难。如果你用IDE全局搜索一个数组键名，比如$data['name']，搜索结果会非常分散，因为数组键名只是一个字符串，不是代码结构的一部分。但如果你用的是对象属性$user->name，IDE可以精确地帮你找到所有引用这个属性的地方，重构时也能安全重命名。这个差异在代码量小的时候感觉不出来，项目到了几十万行的时候，就是天壤之别。
2.2 DTO：给接口数据穿上铠甲
DTO的核心思想很简单：接口返回什么结构，就用代码里一个明确的类来定义。比如：
php复制<?php
namespace App\DTO;
class UserDTO
{
public int $userId;
public string $username;
public ?string $avatar = null;
public int $age;
public static function fromArray(array $data): self
{
$dto = new self();
$dto->userId = (int)($data['user_id'] ?? 0);
$dto->username = (string)($data['username'] ?? '');
$dto->avatar = isset($data['avatar']) ? (string)$data['avatar'] : null;
$dto->age = (int)($data['age'] ?? 0);
return $dto;
}
public function toArray(): array
{
return [
'user_id' => $this->userId,
'username' => $this->username,
'avatar' => $this->avatar,
'age' => $this->age,
];
}
}
然后控制器里这样用：
php复制public function getUserInfo()
{
$user = User::find($this->request->param('id'));
if (!$user) {
return $this->error('用户不存在');
}
$dto = UserDTO::fromArray($user->toArray());
return $this->success($dto->toArray());
}
这样做的第一个好处是"类型可见"。UserDTO里声明了userId是int、username是string、avatar默认是null，谁打开这个类都能一眼看清楚接口返回的是什么数据类型。第二个好处是"边界清晰"。数据库表的字段可能叫user_id，前端需要的也是user_id，但内部业务逻辑里可能需要另一种称呼，DTO可以在fromArray和toArray之间做一次干净的转换，不让数据库结构直接渗透到接口层。第三个好处是"测试方便"。你可以直接new一个UserDTO塞入特定数据，然后断言toArray的返回结构是否符合预期，而不必去mock一整套数据库查询。
2.3 从数组到对象迁移的务实建议
我自己经历过一次老项目接口层从数组到DTO的渐进式迁移，这里分享几个避坑经验。
不要试图一次性把所有接口全部改成DTO。正确做法是"新接口直接上DTO，旧接口按需改造"。一个项目里真正高频使用的接口其实就那二三十个，优先改造这些，价值最大。
在DTO的fromArray里，一定要做显式类型转换。不要写成$dto->userId = $data['user_id'] ?? 0;，因为你不知道传入的数组里user_id到底是字符串"1001"还是数字1001。用(int)强行转换，能保证类型稳定。
注意兼容旧接口。如果旧接口曾经返回了字段nickname，你在新DTO里改成了username，那么所有已上线的App和Web端都会挂。我给团队定的原则是：字段只增不改不删。要加新字段直接加，但绝不能把已有的字段改名或删除。如果实在要改，必须走接口版本升级。关于版本升级这个事，后面有一节专门讲。
还有一个很多人忽略的点：DTO不要塞进Eloquent模型里。有的团队图省事，直接在User模型上写一个toResponseArray()方法，一开始很爽，但你会发现模型越来越臃肿，最后变成一个大杂烩。DTO的价值在于隔离，把模型和接口返回解耦，不要让模型的改动直接波及接口。
3. 序列化、编码与安全边界：接口数据在传输中容易踩的坑
数据契约和DTO搭好了框架，但真正让数据"安全"抵达前端的，是序列化这一环。PHP里做接口开发，绝大多数数据要经过json_encode变成JSON字符串，再由前端json_decode解析。这个过程中藏着几个特别容易踩的坑，每一个我都见过线上事故。
3.1 json_encode中文编码与特殊字符问题
最常见的坑是中文被转义。PHP的json_encode默认会把中文转成Unicode转义序列，比如"用户名"会变成"\u7528\u6237\u540d"。这本身没问题，因为前端会自动解码，但它有两个副作用：一是响应体积变大了（每个中文变成6个字符），二是在后端日志里看返回内容非常吃力。
解决方案很简单，加一个选项：
php复制json_encode($data, JSON_UNESCAPED_UNICODE);
我见过不少老项目因为没加这个参数，排查问题的时候要从日志里把一串Unicode转义复制到在线工具里解码才能看懂。加上JSON_UNESCAPED_UNICODE之后，日志可读性会好非常多。
还有一个更隐蔽的坑：当数据里含有特殊字符时，默认的json_encode可能会把整个JSON搞坏。比如某个字符串里有换行符，或者有未转义的双引号。虽然PHP的json_encode会自动处理大部分情况，但当你嵌套了多层对象、数组、字符串混合的结构时，我还是建议在返回前做一次json_last_error()检查：
php复制$json = json_encode($data, JSON_UNESCAPED_UNICODE);
if (json_last_error() !== JSON_ERROR_NONE) {
// 记录日志，返回一个通用的错误响应
Log::error('JSON encode failed: ' . json_last_error_msg());
return $this->error('数据格式错误');
}
这算是一个"防御性序列化"的写法，在数据量特别大、来源特别杂的接口里，能帮你挡掉很多线上事故。
3.2 类型失真：数字变字符串、浮点精度丢失
json_encode处理数字时有个历史遗留问题：如果数字太大（超过JS安全整数范围），前端解析后会丢失精度。比如某个接口返回了一个雪花ID，在PHP里是72057594037927936，但前端JS用Number类型解析，会变成72057594037927940，造成数据错乱。
解决方法是对于超长整数，统一用字符串返回。我在DTO里把所有ID字段都声明为string类型，就是这个原因。还有一个相关的问题：浮点数精度。PHP里0.1+0.2的结果是0.30000000000000004，直接json_encode出去，前端会一脸懵。做金额相关的接口时，统一以"分"为单位用int传输，不要直接传float。
这类问题不会让你接口报错，但会以"前端用着用着发现数据不对"的形式冒出来，极其难排查。我的经验是：在DTO层就完成类型修正，不要把原始数据类型直接漏出去。
3.3 对象序列化的信息泄露漏洞
这个坑尤其要命。假设你写了一个User类，里面有个password_hash字段或token之类的敏感属性，你一不小心把整个对象直接json_encode返回：
php复制return json_encode($user);
PHP会默认序列化对象的所有public属性。如果你的敏感字段恰好是public的，或者你的类里有__debugInfo()方法没写好，这些字段就会直接暴露给前端。这是实实在在的安全漏洞。
我的建议是：接口层永远不要直接json_encode一个Eloquent模型或Entity对象，必须经过DTO转换。DTO里明确声明了哪些字段会对外暴露，其余字段天然被隔离在结构之外。这比"小心不要把敏感字段设成public"要可靠得多，因为人的记性是不可靠的，但代码结构是可靠的。
4. 错误处理到底该怎么写：从try/catch到统一的异常体系
如果说数据契约是接口的高楼大厦，那错误处理就是这座楼的消防系统。平时的存在感很低，一出事就是大事。十年前写PHP，最常见的错误处理方式就是die('something went wrong')或者return false。现在做接口开发，再这么写就真的说不过去了。
4.1 try/catch的正确打开方式
很多人都知道用try/catch，但用法五花八门。最常见的问题是在catch里只写一句return $this->error('系统错误');，然后什么都日志都不打。这样做的后果是：线上出了问题，前端说弹了个"系统错误"，后端打开日志发现什么都查不到——因为真正的异常信息根本没被记录。
正确的写法是：catch里先记录完整异常信息，再返回给前端一个友好提示。
php复制try {
$user = User::findOrFail($id);
// 业务逻辑...
} catch (\Throwable $e) {
Log::error('获取用户信息失败', [
'id' => $id,
'exception' => $e->getMessage(),
'trace' => $e->getTraceAsString(),
]);
return $this->error('获取用户信息失败，请稍后重试');
}
注意我用的是\Throwable而不是\Exception。因为在PHP 7之后，Error和Exception都实现了Throwable接口。如果只catch Exception，一些TypeError、Error类的问题会漏掉。用Throwable可以一网打尽。
4.2 业务异常与系统异常分离
我在团队里推行了一套简单的异常分层，核心就两类：
一是业务异常（BusinessException），表示"这个操作不符合业务规则"。比如用户不存在、余额不足、权限不足。这类异常的特征是：错误信息可以直接展示给前端，不需要记录堆栈日志（因为不是代码bug，是业务逻辑的正常分支）。
二是系统异常（RuntimeException等），表示"代码出bug了或者外部服务挂了"。比如数据库连接失败、Redis超时、第三方API返回异常。这类异常必须记录完整日志，错误信息不能直接展示给前端，只能返回"系统繁忙，请稍后重试"。
php复制// 业务异常示例
if (!$user) {
throw new BusinessException('用户不存在', 1001);
}
// 系统异常示例
try {
$result = $httpClient->post(...);
} catch (\Throwable $e) {
Log::error('调用第三方服务失败', ['exception' => $e->getMessage()]);
throw new SystemException('外部服务异常');
}
然后你写一个全局异常处理器，统一捕获这两类异常并转换为标准响应结构：
php复制public function render($request, \Throwable $e)
{
if ($e instanceof BusinessException) {
return response()->json([
'code' => $e->getCode(),
'message' => $e->getMessage(),
'data' => null,
]);
}
if ($e instanceof SystemException) {
return response()->json([
'code' => 500,
'message' => '系统繁忙，请稍后重试',
'data' => null,
]);
}
// 未知异常：记录日志并返回通用错误
Log::error('Unhandled exception', [
'exception' => $e->getMessage(),
'trace' => $e->getTraceAsString(),
]);
return response()->json([
'code' => 500,
'message' => '系统繁忙，请稍后重试',
'data' => null,
]);
}
这套体系的价值在于：业务代码里你只需要写业务逻辑和抛出业务异常，不需要在每个方法里写一堆if-else判断错误的模板代码；全局异常处理器统一负责"错误信息如何展示给前端"和"错误细节如何记录到日志"这两件事。代码瞬间清爽很多。
4.3 HTTP状态码与业务码的关系
接口错误处理中还有一个高频争议：HTTP状态码到底用200还是用400/500？
我的实践是：HTTP状态码只表达"请求的传输层状态"，200代表请求到达了服务器并得到了业务处理结果，但具体业务成功与否看code字段。什么意思呢？就是说，即使用户余额不足，只要接口正常处理了这个"业务失败"的请求，HTTP状态码也应该是200。真正的HTTP 500只在代码崩了的时候出现。这样做的好处是：网关层和监控系统可以清晰地通过HTTP状态码判断"服务活着还是死了"，而不需要解析业务JSON。同时前端也只需要统一处理HTTP 200然后根据业务code做分支，不需要处理复杂的HTTP错误映射。
业务码的设计上，我用的是四段式数字码：前两位代表模块（比如10代表用户模块、20代表订单模块），后两位代表具体错误（01代表不存在、02代表无权限）。比如1001就是"用户模块-数据不存在"，2003就是"订单模块-状态不允许操作"。这种编码方式在错误码多起来之后，查问题非常高效，扫一眼错误码就知道大致是哪个模块的什么错误。
5. 前后端协作的实战细节：跨域、字段命名与协作流程
接口写完不是终点，前端能用、用得顺手才是终点。这节聊聊前后端协作中那些天天碰到、但很多人没系统梳理过的细节。
5.1 跨域问题的正确配置
PHP接口和前端页面不在同一个域名下是常态，跨域问题几乎每个项目都会遇到。十年前最好的方案是JSONP，但JSONP只支持GET请求，而且有安全隐患，现在只建议在老项目兼容时使用。新项目一律用CORS。
CORS在PHP里的配置看起来很简单：
php复制header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type, Authorization');
但这里有几个坑要注意。生产环境Access-Control-Allow-Origin不要用*，应该指定具体域名（或者按请求Origin动态返回），否则任何第三方站点都能通过浏览器直接调用你的API。带认证信息的请求（credentials），Access-Control-Allow-Origin必须指定具体域名，不能用*。另外，很多框架会帮你处理OPTIONS预检请求，但如果框架配置不对，前端就会遇到"请求能通但响应被浏览器拦截"的情况，排查方向先看响应头里的CORS字段。
我建议把CORS中间件独立做成一个全局中间件，不要在每个控制器里手动写header。这样也好维护，改动一处全局生效。不同环境（本地联调、测试、生产）用的允许域名清单可能不一样，设计的时候就把这个可配置性做进去。
5.2 字段命名：下划线还是驼峰？
这问题的答案很简单也很无奈：团队怎么约定就怎么来，最重要的是"统一"。如果团队合作比较紧密，后端的库表、前端的JS都采用相同的命名，这个事会更顺。
选择下划线的好处是PHP后端的习惯，数据库字段基本都是下划线命名，接口层直接从模型转换过来不需要额外处理。选择驼峰的好处是前端JS的"惯例"。如果你用DTO做一次转换，其实这两种都不难实现。
我的建议是：新项目统一用下划线，因为可以从数据库字段直出，减少转换层代码。但无论选哪种，都必须用DTO或Mapping这一层保证接口字段命名和内部数据结构分离。否则一旦库表字段改了名字，接口也跟着变，前端又要遭殃。
还有一个细节：接口返回的字段名不要出现大小写混合的"半吊子"写法，比如userName_zh，这会让前端和后端看代码时都想骂人。
5.3 文档先行与接口版本管理
文档的重要性，做过三年以上接口开发的人都深有体会。没有文档的接口协作，本质就是靠记忆力在维持，人一多、项目一久必出问题。我从2018年开始在团队里全面使用Apifox这类工具，核心流程是"先定义接口文档，再写后端代码，前端按文档mock联调"。
这个流程里最核心的一条：接口数据结构以文档为准，代码是实现文档的工具。每次要改接口，先去改文档，然后让文档的改动记录留下痕迹（Apifox有变更记录功能）。这样一旦出bug，谁改了什么一目了然，不会出现"前端和后端各自记了一个不同的数据版本"的惨剧。
接口版本管理同样重要。我见过最惨烈的线上事故之一，就是App发版后，后端把旧接口的一个字段改了格式，导致用户手里的老版本App直接血崩，当天连夜发版回滚。有了这个教训后，我给所有对外接口定了一条铁律：没有版本号保护的接口不许上线。
新接口从一开始就带上版本前缀：/api/v1/user/info、/api/v2/user/info。v1是线上稳定版，v2是新版开发中。同一个接口的字段要做不兼容变更时，必须升版本号，旧版本继续维护到确认没有旧客户端在用为止。听起来麻烦，但比起线上事故的代价，这点麻烦完全不值一提。
6. 接口性能与防御性编程：给后来者的几条实在建议
最后聊性能和安全。这两个话题展开讲各能写好几万字，这节只讲和接口设计关系最密切的几条实战建议，都是"普通PHP开发"和"资深PHP开发"在日常编码时真正拉开差距的地方。
6.1 先定位N+1查询问题
接口请求量一大，数据库压力就上来了。最常见的性能杀手是N+1查询。比如你要返回一个用户列表，每个用户带上他的最新订单，如果你是这么写的：
php复制// 例子：N+1查询
$users = User::where('status', 1)->get();
foreach ($users as $user) {
$orders = Order::where('user_id', $user->id)->latest()->first();
// ...
}
100个用户就有1次查询用户列表加上100次查询订单，总共101次数据库查询。这种写法一旦用户量上来，数据库直接被打爆。正确做法是用关联预加载或JOIN一次性把数据查出来：
php复制// 预加载
$users = User::with(['latestOrder'])->where('status', 1)->get();
这条铁律我重复了十年：循环里禁止查询数据库。一旦在for循环、foreach循环里看到SQL查询，就要立刻警觉，这大概率是N+1问题。
6.2 参数校验与幂等性
接口的输入参数校验，最忌讳的是"前端都校验过了，后端就不用再校验了"。真实的教训是：前端永远可以被绕过，黑客不会用你家的前端页面来调你的接口。所以后端必须对所有输入参数做完整校验，包括字段是否存在、类型是否正确、取值范围是否合法、枚举值是否在允许列表内。
在PHP里，用Laravel的Validation或ThinkPHP的Validate都可以，关键是"每一个接口都必须有参数校验规则"，这个不能省。我知道很多老项目里，开发者觉得写校验规则很烦，直接靠数据库查询时自动报错来兜底。但这样就意味着恶意请求可以带着脏数据一路穿透到数据库层，触发各种异常，甚至可能因为参数边界没控制好，造成越权或数据泄露。
幂等性设计也是后端高级工程师和普通工程师的分水岭。最典型的场景是支付回调、订单创建。一个请求因为网络超时被客户端重试了一次，如果后端没有幂等性处理，就可能创建出两个订单、重复扣款两次。最简单的做法是在接口层做唯一性校验或幂等键机制：客户端每次提交请求带一个幂等键，后端在分布式锁里判断这个键是否已经处理过，处理过的直接返回上一次结果。
6.3 安全红线：SQL注入、XSS、CSRF与文件上传
PHP安全是一个老生常谈但常谈常新的话题。在这十年的项目实践中，我总结出几条每次上线前都会检查的红线：
SQL注入方面，永远使用参数绑定或ORM的查询构造器，不要手动拼接SQL字符串。我知道有一个老项目，程序员图省事，把完整的字符串拼到SQL里，结果被黑客用一张十六进制的图片上传触发了一个存储型XSS，整个管理后台的用户session都被窃取了。这种案例网上一搜一大把，别心存侥幸。
XSS方面，接口返回的文本数据，前端展示时要做转义。后端在做内容校验时，要过滤掉script标签、javascript:协议等危险内容，尤其是用户可编辑的内容（昵称、评论、文章标题）。如果做的是富文本编辑器的内容，必须用严格的白名单过滤库（比如HTMLPurifier），不要自己写正则去匹配。
CSRF方面，涉及修改操作的接口（POST/PUT/DELETE），要校验CSRF Token或者验证请求来源。现在很多前后端分离项目用JWT做认证，CSRF的风险会小一些，但Cookie+Session模式的老项目一定要做好防护。
文件上传方面，上传接口要做文件类型白名单校验、大小限制、文件内容校验（不只检查扩展名，还要检查MIME类型和文件头），并且上传文件不要存储在执行目录下，避免被当作PHP脚本直接执行。这个坑几乎每年都有新项目中招，建议从项目第一天就立好规矩。
6.4 性能排查的基本姿势
线上接口变慢了，怎么排查？我给团队定的标准排查流程是：先看慢查询日志，确认为什么慢——查一下数据库慢日志里消耗时间最高的SQL，看有没有缺索引、有没有全表扫描。再看接口里有没有N+1查询——通过日志打印SQL执行次数，肉眼扫一遍循环。然后看Redis缓存命中率，热点数据有没有必要加缓存。最后才是加机器、调配置。
有一个性价比极高的性能优化动作，我做了十一年，屡试不爽：给所有高频接口的查询字段加上索引。就是这么简单粗暴。很多接口变慢的根本原因不是代码效率低，而是数据库索引没建好。一条SQL走了全表扫描和走了索引查询，性能相差几十上百倍。所以每次接口上线前，把涉及查询条件的字段都过一遍，该加索引的加索引，这个动作几乎是零成本。
另外一个建议是你如果做的是Swoole或Hyperf这类常驻内存模式，要注意PHP的"一次性请求"思维惯性要改掉。这时候静态变量、单例模式、连接池的管理方式都跟传统PHP-FPM不一样，稍不留神就会写出内存泄漏的代码。而且这类模式下进程不退出，日志、异常、请求上下文的处理逻辑都要比传统模式更仔细。我见过好几个从传统PHP转向Swoole的团队，前几个月都在为各种内存问题加班。这里没有捷径，先把手上的项目在FPM模式下做到接口稳定、日志清晰、数据契约明确，再考虑切换更复杂的运行模式，顺序不要反。
这一篇从数据契约、DTO、序列化陷阱、异常体系、前后端协作到性能安全，基本把我十年里在PHP接口开发上踩过的坑、总结出来的方法论都覆盖了。写到这儿特别想对刚入行三四年的PHP后端朋友说一句：框架可以随时换，但接口设计的数据契约意识、错误处理体系、前后端协作方法，是你跟着你走的硬功夫。这些能力不会因为哪天你转了Go或者Java就白费——数据契约、错误码设计、接口版本管理这些底层逻辑，放到任何语言任何技术栈里都成立。
我个人在实际项目里还有一个习惯，每年年初会把所有对外接口的返回结构、错误码定义、字段变更记录重新review一遍。这个动作看起来不起眼，但坚持几年下来，你对项目整体架构的掌控力会有质的变化。很多人觉得接口开发就是"把数据库查出来然后return json"，但真正做过十年的人会明白，稳定、可控、可维护的接口层，是一个后端项目能活过五年十年的地基。希望这一篇能帮你把这块地基打得比别人更扎实一些。