PHP JSON 接口参数校验实战：统一入口、类型转换和错误响应

很多 PHP 项目一开始接口不多，参数判断直接写在控制器里也能跑。等接口变多以后，问题就出来了：有的地方漏判必填字段，有的地方把字符串当数字，有的地方错误响应格式不统一，前端联调也很难定位。

这篇文章用“创建订单”接口做例子，把 JSON 请求体读取、字段校验、类型转换、错误响应做成一条清晰的入口流程。它不是框架专属写法，原生 PHP 或轻量框架都能借鉴。

摘要

本文会先说明接口参数散落判断带来的风险，再实现一个小型校验器：统一解析 JSON，请求字段进入规则表，经过必填、类型、范围和格式检查，最后得到干净的数据数组或结构化错误响应。

适合人群

• 正在写 PHP JSON API，希望减少重复参数判断的开发者。
• 需要统一错误响应、方便前后端联调的后端同学。
• 熟悉基础 PHP 数组、函数和 HTTP 请求响应的读者。

目录

1. 为什么参数判断要放到统一入口
2. 定义接口规则表
3. 实现一个轻量校验函数
4. 在订单接口中使用
5. 常见坑和改进方向
6. 总结

一、为什么参数判断要放到统一入口

以订单接口为例，前端可能传来这样的 JSON：

{
  "user_id": "1001",
  "sku_id": "A-9527",
  "count": "2",
  "remark": "周末前发货"
}

这份数据看上去没问题，但后端真正需要的是：user_id 是整数，sku_id 是非空字符串，count 是 1 到 99 的整数，remark 是可选字符串。若每个控制器都自己写判断，就容易出现口径不一致。

二、定义接口规则表

先把字段要求写成规则表。这样业务代码不用到处翻判断条件，接口契约也更清楚。

 [
        'required' => true,
        'type' => 'int',
        'min' => 1,
    ],
    'sku_id' => [
        'required' => true,
        'type' => 'string',
        'pattern' => '/^[A-Z0-9-]{3,32}$/',
    ],
    'count' => [
        'required' => true,
        'type' => 'int',
        'min' => 1,
        'max' => 99,
    ],
    'remark' => [
        'required' => false,
        'type' => 'string',
        'max_length' => 120,
    ],
];

规则表越稳定，控制器越干净。后续想补充手机号、邮箱、枚举值，也是在这里加规则，而不是把判断散在多个接口里。

三、实现一个轻量校验函数

下面的函数只处理几个常见规则：必填、整数、字符串长度、正则格式和数值范围。真实项目里可以继续扩展，但入口结构基本类似。

 'body',
            'message' => '请求体必须是合法 JSON 对象',
        ]];
    }

    return [$data, null];
}

function validateInput(array $data, array $rules): array
{
    $clean = [];
    $errors = [];

    foreach ($rules as $field => $rule) {
        $exists = array_key_exists($field, $data);
        $value = $exists ? $data[$field] : null;

        if (($rule['required'] ?? false) && (!$exists || $value === '')) {
            $errors[] = [
                'field' => $field,
                'message' => '字段不能为空',
            ];
            continue;
        }

        if (!$exists || $value === '') {
            continue;
        }

        if (($rule['type'] ?? '') === 'int') {
            if (filter_var($value, FILTER_VALIDATE_INT) === false) {
                $errors[] = [
                    'field' => $field,
                    'message' => '必须是整数',
                ];
                continue;
            }

            $value = (int) $value;

            if (isset($rule['min']) && $value  $field,
                    'message' => '数值太小',
                ];
            }

            if (isset($rule['max']) && $value > $rule['max']) {
                $errors[] = [
                    'field' => $field,
                    'message' => '数值太大',
                ];
            }
        }

        if (($rule['type'] ?? '') === 'string') {
            $value = trim((string) $value);

            if (isset($rule['max_length']) && mb_strlen($value) > $rule['max_length']) {
                $errors[] = [
                    'field' => $field,
                    'message' => '文本太长',
                ];
            }

            if (isset($rule['pattern']) && !preg_match($rule['pattern'], $value)) {
                $errors[] = [
                    'field' => $field,
                    'message' => '格式不正确',
                ];
            }
        }

        $clean[$field] = $value;
    }

    return [$clean, $errors];
}

这里刻意让函数返回两个结果：干净数据和错误列表。业务层只关心“能不能继续下单”，不用再关心每个字段怎么判断。

四、在订单接口中使用

控制器入口只做三件事：读取 JSON、调用校验、根据结果返回响应。这样接口越多，收益越明显。

 400,
        'message' => '参数错误',
        'errors' => [$bodyError],
    ], JSON_UNESCAPED_UNICODE);
    return;
}

[$params, $errors] = validateInput($input, $rules);

if ($errors) {
    http_response_code(422);
    echo json_encode([
        'code' => 422,
        'message' => '参数校验未通过',
        'errors' => $errors,
    ], JSON_UNESCAPED_UNICODE);
    return;
}

echo json_encode([
    'code' => 0,
    'message' => 'ok',
    'data' => [
        'user_id' => $params['user_id'],
        'sku_id' => $params['sku_id'],
        'count' => $params['count'],
    ],
], JSON_UNESCAPED_UNICODE);

前端拿到的错误格式也会稳定很多，比如：

{
  "code": 422,
  "message": "参数校验未通过",
  "errors": [
    {
      "field": "count",
      "message": "必须是整数"
    }
  ]
}

五、常见坑和改进方向

1. 不要只判断字段是否存在

isset 和 array_key_exists 的语义不同。接口参数校验更常用 array_key_exists，因为传了字段但值为空，和完全没传字段，通常要给出不同提示。

2. 类型转换要发生在业务之前

如果 count 一会儿是字符串，一会儿是整数，后面计算库存、金额时就容易埋下问题。校验通过后再进入业务层的数据，应该已经完成基础类型转换。

3. 错误响应要稳定

建议固定返回 code、message、errors。前端可以直接把 field 映射到表单项，定位会快很多。

4. 规则表可以继续抽象

当规则越来越多时，可以把校验器封装成类，支持枚举、日期、手机号、数组列表、嵌套对象等场景。重点仍然是一个原则：入口统一，业务层拿到干净数据。

六、总结

PHP JSON 接口参数校验的核心不是写很多判断，而是把判断放在统一入口：请求体先被解析，字段按规则表逐个检查，类型在进入业务前完成转换，错误响应保持一致。

这套方式落地后，控制器会更清爽，前后端联调也更稳定。后续无论接入框架验证器，还是自己扩展规则，底层思路都一样：让每个接口先拿到可信、清晰、结构化的参数。