PHP与Vue混合开发时接口数据格式如何设计

先聊两句：接口格式确实该“较真”

做过几年 PHP 和 Vue 混搭开发的朋友，大概率都经历过这类场景：后端同事给你返回一个 `data`，打开一看，有时是数组，有时是对象，有时又悄悄把分页信息塞到了 `data` 里。前端拿到手，不得不花大功夫去 `Array.isArray` 判断、写兼容逻辑。时间一长，项目里到处是防御性代码，看着头大。

PHP 与 Vue 的混合开发模式，本质上是一个“后端给数据，前端消费数据”的协作关系，而这份关系的唯一契约，就是接口数据格式。格式设计得好，前后端开发效率翻倍；设计得随意，线上问题不断，互相甩锅也是常态。

先把底座打牢：统一响应结构

在讨论任何细节之前，第一个必须敲定的问题是：格式如何保持统一？ 我比较推荐一个被无数项目验证过的三层结构：

{
  "code": 0,
  "message": "success",
  "data": {}
}

别小看这套组合，其中有几个关键设计考量：

- `code` 必须是数字，且 0 代表成功。 很多人习惯用 HTTP 状态码来承载业务错误，但如 `401`、`500` 这类状态码语义太粗，无法描述“用户名已存在”或“库存不足”这类具体场景。用业务码可以让前后端用同一套字典沟通。
- `message` 是给人看的。 建议直接返回用户可读的提示语，前端做弹窗时免去二次翻译工作，也可方便调试排错。
- `data` 是数据本体。 如果请求失败，这个字段可以传 `null`，但一定要出现在响应中，不要缺席，结构保持恒定可以减少大量无效判断。

使用这套结构之后，前端 Vue 项目里封装 axios 拦截器就非常清爽：看到 `code === 0` 就直接把 `data` 抛给组件，其他情况直接弹出 `message`，只用做一次判断。

明确黄金准则：data 只放“一坨数据”

围绕 `data` 字段本身，最容易产生争议的问题就是：到底怎么定义它的内层结构？

我的经验是：`data` 内部不要塞与业务无关的信息，且格式必须与页面视图建立映射关系。

具体举个常见的反例：有的接口在分页列表场景下，返回长这样：

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [...]
  }
}

然后另一处获取详情：

{
  "code": 0,
  "message": "ok",
  "data": [...]
}

这就麻烦，前端每次拿到 `data` 都要想“这个接口返回的是数组还是对象”，很耗心神。

我建议的实践是：列表接口固定为 `data.list + data.total`

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [...],
    "total": 100
  }
}

后端不要嫌“用 `data.count` 更简单”而随意更换键名。前端拿到这种结构后，在 Vue 组件里初始化表格数据、计算页码就变成了一件机械操作，不需要额外的逻辑去猜结构。

针对详情类单条数据接口，则保持 `data` 传对象；无数据场景传 `{}` 而不是 `[]`，看似微小，却能让前端的默认值设定简单很多。规则一旦统一，跨项目的协作成本会骤降。

PHP 后端实现优雅响应：不裸奔、写工具类

既然是 PHP，广大开发者最常用的是 Laravel 或 ThinkPHP。建议在后端封装一个统一的响应辅助方法（或基类方法），而不是在控制器里手动拼数组。

下面是一个 Laravel 风格的最小参考实现。

class ApiResponse
{
    public static function success($data = null, string $message = 'success'): JsonResponse
    {
        return response()->json([
            'code'    => 0,
            'message' => $message,
            'data'    => $data,
        ]);
    }

    public static function error(int $code, string $message, $data = null): JsonResponse
    {
        return response()->json([
            'code'    => $code,
            'message' => $message,
            'data'    => $data,
        ]);
    }
}

不管未来前端需求怎么变，只要 Controller 层统一调用 `ApiResponse` 这个门面，返回体就不会出格，前端也就不用接一条改一次。

另外一个至关重要却又经常被忽略的点是：在给 Vue 传值之前，PHP 必须做好字段类型转换。 例如，MySQL 里 `id` 是 `bigint`，取出时在 PHP 中可能是字符串形式。如果不强制转成整型，前端拿到的 `id` 就可能变成 `"1"`，Vue 中做 `===` 严格比较时就会悄悄翻车。

// 常见技巧：用 map 处理列表字段类型
$list = collect($rawList)->map(function ($item) {
    return [
        'id'   => (int) $item['id'],
        'price' => (float) $item['price'],
    ];
});

这里建议通过数据库类型去匹配对应 PHP 的原生类型，前端最省事的类型规则就是：**整数给整型，小数给浮点（保留两位的给字符串亦可），逻辑布尔给布尔，不要默认丢字符串。**

兼容历史与非规范场景：保留一颗“弹性”的心

当然，纯粹的“理想型”在真实项目中很难一蹴而就，尤其是接手老项目或对接第三方接口时，限制不少。此时，后端可以把难以约束的字段放在 `data.extra` 或 `data.extend` 里，至少保证统一字段的语义不变。

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [...],
    "total": 88,
    "extra": {}
  }
}

额外数据不应该污染核心结构，这能在不影响核心列表渲染逻辑的前提下，给一些边缘能力留下足够的空间。

从 Vue 侧来看，配合 Axios 响应拦截器，实现一次全局解析：

service.interceptors.response.use(
  response => {
    const res = response.data
    if (res.code !== 0) {
      ElMessage.error(res.message)
      return Promise.reject(new Error(res.message))
    }
    return res.data
  }
)

这样做的好处是，组件中加载列表只需要这样写：

const { list, total } = await getGoodsList(params)

干净利落，不需要每个业务代码里都去磨响应判断，Vue 开发体验直线上升。

结语：格式设计定的是“协作的默契”

PHP 和 Vue 的混合开发，说到底是两种技术栈、多个角色之间的协同，最容易传递偏差的就是数据接口。与其依赖口头沟通约定，不如先定下一套简洁、可执行的响应格式。从层层的 `code/message/data` 到分页结构的统一，再到后端的类型转换、前端拦截器的配套实现，每一环都不是可有可无的细节，而是让架构变得“内聚而清爽”的砖石。

把格式定好，前后端少扯皮，多些精力写业务，这不正是我们做混合开发的初心吗？